From d96e2dea38dc83e32b1c49c6132363efb6e45d83 Mon Sep 17 00:00:00 2001 From: "Michael Kerrisk (man-pages)" Date: Wed, 4 Nov 2020 16:13:37 +0100 Subject: Add pages that were produced for the POSIX.1-2008 TC 1 release --- man-pages-posix-2013/Makefile | 59 + man-pages-posix-2013/POSIX-COPYRIGHT | 25 + man-pages-posix-2013/README | 22 + .../man-pages-posix-2013-a.Announce | 28 + man-pages-posix-2013/man-pages-posix-2013-a.lsm | 12 + man-pages-posix-2013/man0p/aio.h.0p | 174 + man-pages-posix-2013/man0p/arpa_inet.h.0p | 118 + man-pages-posix-2013/man0p/assert.h.0p | 82 + man-pages-posix-2013/man0p/complex.h.0p | 254 + man-pages-posix-2013/man0p/cpio.h.0p | 91 + man-pages-posix-2013/man0p/ctype.h.0p | 138 + man-pages-posix-2013/man0p/dirent.h.0p | 163 + man-pages-posix-2013/man0p/dlfcn.h.0p | 78 + man-pages-posix-2013/man0p/errno.h.0p | 333 + man-pages-posix-2013/man0p/fcntl.h.0p | 375 + man-pages-posix-2013/man0p/fenv.h.0p | 285 + man-pages-posix-2013/man0p/float.h.0p | 364 + man-pages-posix-2013/man0p/fmtmsg.h.0p | 129 + man-pages-posix-2013/man0p/fnmatch.h.0p | 80 + man-pages-posix-2013/man0p/ftw.h.0p | 131 + man-pages-posix-2013/man0p/glob.h.0p | 132 + man-pages-posix-2013/man0p/grp.h.0p | 93 + man-pages-posix-2013/man0p/iconv.h.0p | 71 + man-pages-posix-2013/man0p/inttypes.h.0p | 242 + man-pages-posix-2013/man0p/iso646.h.0p | 74 + man-pages-posix-2013/man0p/langinfo.h.0p | 195 + man-pages-posix-2013/man0p/libgen.h.0p | 57 + man-pages-posix-2013/man0p/limits.h.0p | 1179 +++ man-pages-posix-2013/man0p/locale.h.0p | 177 + man-pages-posix-2013/man0p/math.h.0p | 582 ++ man-pages-posix-2013/man0p/monetary.h.0p | 83 + man-pages-posix-2013/man0p/mqueue.h.0p | 140 + man-pages-posix-2013/man0p/ndbm.h.0p | 115 + man-pages-posix-2013/man0p/net_if.h.0p | 84 + man-pages-posix-2013/man0p/netdb.h.0p | 325 + man-pages-posix-2013/man0p/netinet_in.h.0p | 391 + man-pages-posix-2013/man0p/netinet_tcp.h.0p | 59 + man-pages-posix-2013/man0p/nl_types.h.0p | 109 + man-pages-posix-2013/man0p/poll.h.0p | 135 + man-pages-posix-2013/man0p/pthread.h.0p | 325 + man-pages-posix-2013/man0p/pwd.h.0p | 95 + man-pages-posix-2013/man0p/regex.h.0p | 209 + man-pages-posix-2013/man0p/sched.h.0p | 155 + man-pages-posix-2013/man0p/search.h.0p | 115 + man-pages-posix-2013/man0p/semaphore.h.0p | 100 + man-pages-posix-2013/man0p/setjmp.h.0p | 89 + man-pages-posix-2013/man0p/signal.h.0p | 582 ++ man-pages-posix-2013/man0p/spawn.h.0p | 168 + man-pages-posix-2013/man0p/stdarg.h.0p | 224 + man-pages-posix-2013/man0p/stdbool.h.0p | 65 + man-pages-posix-2013/man0p/stddef.h.0p | 104 + man-pages-posix-2013/man0p/stdint.h.0p | 644 ++ man-pages-posix-2013/man0p/stdio.h.0p | 327 + man-pages-posix-2013/man0p/stdlib.h.0p | 260 + man-pages-posix-2013/man0p/string.h.0p | 146 + man-pages-posix-2013/man0p/strings.h.0p | 78 + man-pages-posix-2013/man0p/stropts.h.0p | 433 + man-pages-posix-2013/man0p/sys_ipc.h.0p | 120 + man-pages-posix-2013/man0p/sys_mman.h.0p | 213 + man-pages-posix-2013/man0p/sys_msg.h.0p | 122 + man-pages-posix-2013/man0p/sys_resource.h.0p | 207 + man-pages-posix-2013/man0p/sys_select.h.0p | 144 + man-pages-posix-2013/man0p/sys_sem.h.0p | 162 + man-pages-posix-2013/man0p/sys_shm.h.0p | 120 + man-pages-posix-2013/man0p/sys_socket.h.0p | 563 ++ man-pages-posix-2013/man0p/sys_stat.h.0p | 406 + man-pages-posix-2013/man0p/sys_statvfs.h.0p | 104 + man-pages-posix-2013/man0p/sys_time.h.0p | 145 + man-pages-posix-2013/man0p/sys_times.h.0p | 83 + man-pages-posix-2013/man0p/sys_types.h.0p | 241 + man-pages-posix-2013/man0p/sys_uio.h.0p | 104 + man-pages-posix-2013/man0p/sys_un.h.0p | 89 + man-pages-posix-2013/man0p/sys_utsname.h.0p | 77 + man-pages-posix-2013/man0p/sys_wait.h.0p | 145 + man-pages-posix-2013/man0p/syslog.h.0p | 158 + man-pages-posix-2013/man0p/tar.h.0p | 102 + man-pages-posix-2013/man0p/termios.h.0p | 457 + man-pages-posix-2013/man0p/tgmath.h.0p | 396 + man-pages-posix-2013/man0p/time.h.0p | 331 + man-pages-posix-2013/man0p/trace.h.0p | 236 + man-pages-posix-2013/man0p/ulimit.h.0p | 68 + man-pages-posix-2013/man0p/unistd.h.0p | 1621 ++++ man-pages-posix-2013/man0p/utime.h.0p | 91 + man-pages-posix-2013/man0p/utmpx.h.0p | 128 + man-pages-posix-2013/man0p/wchar.h.0p | 353 + man-pages-posix-2013/man0p/wctype.h.0p | 178 + man-pages-posix-2013/man0p/wordexp.h.0p | 152 + man-pages-posix-2013/man1p/admin.1p | 510 ++ man-pages-posix-2013/man1p/alias.1p | 222 + man-pages-posix-2013/man1p/ar.1p | 727 ++ man-pages-posix-2013/man1p/asa.1p | 212 + man-pages-posix-2013/man1p/at.1p | 798 ++ man-pages-posix-2013/man1p/awk.1p | 3966 +++++++++ man-pages-posix-2013/man1p/basename.1p | 288 + man-pages-posix-2013/man1p/batch.1p | 275 + man-pages-posix-2013/man1p/bc.1p | 1615 ++++ man-pages-posix-2013/man1p/bg.1p | 222 + man-pages-posix-2013/man1p/break.1p | 134 + man-pages-posix-2013/man1p/c99.1p | 1152 +++ man-pages-posix-2013/man1p/cal.1p | 162 + man-pages-posix-2013/man1p/cat.1p | 325 + man-pages-posix-2013/man1p/cd.1p | 507 ++ man-pages-posix-2013/man1p/cflow.1p | 278 + man-pages-posix-2013/man1p/chgrp.1p | 235 + man-pages-posix-2013/man1p/chmod.1p | 679 ++ man-pages-posix-2013/man1p/chown.1p | 301 + man-pages-posix-2013/man1p/cksum.1p | 373 + man-pages-posix-2013/man1p/cmp.1p | 269 + man-pages-posix-2013/man1p/colon.1p | 104 + man-pages-posix-2013/man1p/comm.1p | 287 + man-pages-posix-2013/man1p/command.1p | 560 ++ man-pages-posix-2013/man1p/compress.1p | 258 + man-pages-posix-2013/man1p/continue.1p | 112 + man-pages-posix-2013/man1p/cp.1p | 806 ++ man-pages-posix-2013/man1p/crontab.1p | 360 + man-pages-posix-2013/man1p/csplit.1p | 315 + man-pages-posix-2013/man1p/ctags.1p | 477 ++ man-pages-posix-2013/man1p/cut.1p | 496 ++ man-pages-posix-2013/man1p/cxref.1p | 180 + man-pages-posix-2013/man1p/date.1p | 627 ++ man-pages-posix-2013/man1p/dd.1p | 769 ++ man-pages-posix-2013/man1p/delta.1p | 342 + man-pages-posix-2013/man1p/df.1p | 332 + man-pages-posix-2013/man1p/diff.1p | 1001 +++ man-pages-posix-2013/man1p/dirname.1p | 260 + man-pages-posix-2013/man1p/dot.1p | 116 + man-pages-posix-2013/man1p/du.1p | 279 + man-pages-posix-2013/man1p/echo.1p | 266 + man-pages-posix-2013/man1p/ed.1p | 2097 +++++ man-pages-posix-2013/man1p/env.1p | 330 + man-pages-posix-2013/man1p/eval.1p | 138 + man-pages-posix-2013/man1p/ex.1p | 9025 ++++++++++++++++++++ man-pages-posix-2013/man1p/exec.1p | 184 + man-pages-posix-2013/man1p/exit.1p | 129 + man-pages-posix-2013/man1p/expand.1p | 205 + man-pages-posix-2013/man1p/export.1p | 191 + man-pages-posix-2013/man1p/expr.1p | 440 + man-pages-posix-2013/man1p/false.1p | 75 + man-pages-posix-2013/man1p/fc.1p | 593 ++ man-pages-posix-2013/man1p/fg.1p | 162 + man-pages-posix-2013/man1p/file.1p | 829 ++ man-pages-posix-2013/man1p/find.1p | 1126 +++ man-pages-posix-2013/man1p/fold.1p | 280 + man-pages-posix-2013/man1p/fort77.1p | 581 ++ man-pages-posix-2013/man1p/fuser.1p | 247 + man-pages-posix-2013/man1p/gencat.1p | 289 + man-pages-posix-2013/man1p/get.1p | 848 ++ man-pages-posix-2013/man1p/getconf.1p | 443 + man-pages-posix-2013/man1p/getopts.1p | 445 + man-pages-posix-2013/man1p/grep.1p | 529 ++ man-pages-posix-2013/man1p/hash.1p | 189 + man-pages-posix-2013/man1p/head.1p | 207 + man-pages-posix-2013/man1p/iconv.1p | 288 + man-pages-posix-2013/man1p/id.1p | 351 + man-pages-posix-2013/man1p/ipcrm.1p | 150 + man-pages-posix-2013/man1p/ipcs.1p | 556 ++ man-pages-posix-2013/man1p/jobs.1p | 343 + man-pages-posix-2013/man1p/join.1p | 507 ++ man-pages-posix-2013/man1p/kill.1p | 460 + man-pages-posix-2013/man1p/lex.1p | 1374 +++ man-pages-posix-2013/man1p/link.1p | 122 + man-pages-posix-2013/man1p/ln.1p | 469 + man-pages-posix-2013/man1p/locale.1p | 560 ++ man-pages-posix-2013/man1p/localedef.1p | 327 + man-pages-posix-2013/man1p/logger.1p | 163 + man-pages-posix-2013/man1p/logname.1p | 132 + man-pages-posix-2013/man1p/lp.1p | 480 ++ man-pages-posix-2013/man1p/ls.1p | 1134 +++ man-pages-posix-2013/man1p/m4.1p | 841 ++ man-pages-posix-2013/man1p/mailx.1p | 3090 +++++++ man-pages-posix-2013/man1p/make.1p | 2487 ++++++ man-pages-posix-2013/man1p/man.1p | 267 + man-pages-posix-2013/man1p/mesg.1p | 167 + man-pages-posix-2013/man1p/mkdir.1p | 261 + man-pages-posix-2013/man1p/mkfifo.1p | 190 + man-pages-posix-2013/man1p/more.1p | 1382 +++ man-pages-posix-2013/man1p/mv.1p | 529 ++ man-pages-posix-2013/man1p/newgrp.1p | 296 + man-pages-posix-2013/man1p/nice.1p | 287 + man-pages-posix-2013/man1p/nl.1p | 312 + man-pages-posix-2013/man1p/nm.1p | 405 + man-pages-posix-2013/man1p/nohup.1p | 311 + man-pages-posix-2013/man1p/od.1p | 940 ++ man-pages-posix-2013/man1p/paste.1p | 365 + man-pages-posix-2013/man1p/patch.1p | 713 ++ man-pages-posix-2013/man1p/pathchk.1p | 426 + man-pages-posix-2013/man1p/pax.1p | 4153 +++++++++ man-pages-posix-2013/man1p/pr.1p | 569 ++ man-pages-posix-2013/man1p/printf.1p | 576 ++ man-pages-posix-2013/man1p/prs.1p | 445 + man-pages-posix-2013/man1p/ps.1p | 671 ++ man-pages-posix-2013/man1p/pwd.1p | 210 + man-pages-posix-2013/man1p/qalter.1p | 1093 +++ man-pages-posix-2013/man1p/qdel.1p | 208 + man-pages-posix-2013/man1p/qhold.1p | 270 + man-pages-posix-2013/man1p/qmove.1p | 187 + man-pages-posix-2013/man1p/qmsg.1p | 265 + man-pages-posix-2013/man1p/qrerun.1p | 163 + man-pages-posix-2013/man1p/qrls.1p | 279 + man-pages-posix-2013/man1p/qselect.1p | 918 ++ man-pages-posix-2013/man1p/qsig.1p | 235 + man-pages-posix-2013/man1p/qstat.1p | 404 + man-pages-posix-2013/man1p/qsub.1p | 1472 ++++ man-pages-posix-2013/man1p/read.1p | 272 + man-pages-posix-2013/man1p/readonly.1p | 164 + man-pages-posix-2013/man1p/renice.1p | 280 + man-pages-posix-2013/man1p/return.1p | 110 + man-pages-posix-2013/man1p/rm.1p | 447 + man-pages-posix-2013/man1p/rmdel.1p | 167 + man-pages-posix-2013/man1p/rmdir.1p | 195 + man-pages-posix-2013/man1p/sact.1p | 186 + man-pages-posix-2013/man1p/sccs.1p | 542 ++ man-pages-posix-2013/man1p/sed.1p | 1067 +++ man-pages-posix-2013/man1p/set.1p | 806 ++ man-pages-posix-2013/man1p/sh.1p | 1729 ++++ man-pages-posix-2013/man1p/shift.1p | 103 + man-pages-posix-2013/man1p/sleep.1p | 173 + man-pages-posix-2013/man1p/sort.1p | 776 ++ man-pages-posix-2013/man1p/split.1p | 318 + man-pages-posix-2013/man1p/strings.1p | 244 + man-pages-posix-2013/man1p/strip.1p | 153 + man-pages-posix-2013/man1p/stty.1p | 807 ++ man-pages-posix-2013/man1p/tabs.1p | 291 + man-pages-posix-2013/man1p/tail.1p | 348 + man-pages-posix-2013/man1p/talk.1p | 309 + man-pages-posix-2013/man1p/tee.1p | 196 + man-pages-posix-2013/man1p/test.1p | 1058 +++ man-pages-posix-2013/man1p/time.1p | 320 + man-pages-posix-2013/man1p/times.1p | 112 + man-pages-posix-2013/man1p/touch.1p | 646 ++ man-pages-posix-2013/man1p/tput.1p | 222 + man-pages-posix-2013/man1p/tr.1p | 699 ++ man-pages-posix-2013/man1p/trap.1p | 362 + man-pages-posix-2013/man1p/true.1p | 97 + man-pages-posix-2013/man1p/tsort.1p | 156 + man-pages-posix-2013/man1p/tty.1p | 145 + man-pages-posix-2013/man1p/type.1p | 133 + man-pages-posix-2013/man1p/ulimit.1p | 169 + man-pages-posix-2013/man1p/umask.1p | 372 + man-pages-posix-2013/man1p/unalias.1p | 150 + man-pages-posix-2013/man1p/uname.1p | 201 + man-pages-posix-2013/man1p/uncompress.1p | 186 + man-pages-posix-2013/man1p/unexpand.1p | 238 + man-pages-posix-2013/man1p/unget.1p | 189 + man-pages-posix-2013/man1p/uniq.1p | 355 + man-pages-posix-2013/man1p/unlink.1p | 121 + man-pages-posix-2013/man1p/unset.1p | 177 + man-pages-posix-2013/man1p/uucp.1p | 292 + man-pages-posix-2013/man1p/uudecode.1p | 215 + man-pages-posix-2013/man1p/uuencode.1p | 378 + man-pages-posix-2013/man1p/uustat.1p | 162 + man-pages-posix-2013/man1p/uux.1p | 361 + man-pages-posix-2013/man1p/val.1p | 248 + man-pages-posix-2013/man1p/vi.1p | 6469 ++++++++++++++ man-pages-posix-2013/man1p/wait.1p | 346 + man-pages-posix-2013/man1p/wc.1p | 264 + man-pages-posix-2013/man1p/what.1p | 193 + man-pages-posix-2013/man1p/who.1p | 315 + man-pages-posix-2013/man1p/write.1p | 232 + man-pages-posix-2013/man1p/xargs.1p | 749 ++ man-pages-posix-2013/man1p/yacc.1p | 1597 ++++ man-pages-posix-2013/man1p/zcat.1p | 127 + man-pages-posix-2013/man3p/FD_CLR.3p | 41 + man-pages-posix-2013/man3p/_Exit.3p | 451 + man-pages-posix-2013/man3p/_longjmp.3p | 130 + man-pages-posix-2013/man3p/_tolower.3p | 72 + man-pages-posix-2013/man3p/_toupper.3p | 72 + man-pages-posix-2013/man3p/a64l.3p | 159 + man-pages-posix-2013/man3p/abort.3p | 134 + man-pages-posix-2013/man3p/abs.3p | 70 + man-pages-posix-2013/man3p/accept.3p | 190 + man-pages-posix-2013/man3p/access.3p | 294 + man-pages-posix-2013/man3p/acos.3p | 120 + man-pages-posix-2013/man3p/acosh.3p | 118 + man-pages-posix-2013/man3p/acosl.3p | 38 + man-pages-posix-2013/man3p/aio_cancel.3p | 118 + man-pages-posix-2013/man3p/aio_error.3p | 117 + man-pages-posix-2013/man3p/aio_fsync.3p | 191 + man-pages-posix-2013/man3p/aio_read.3p | 208 + man-pages-posix-2013/man3p/aio_return.3p | 120 + man-pages-posix-2013/man3p/aio_suspend.3p | 132 + man-pages-posix-2013/man3p/aio_write.3p | 218 + man-pages-posix-2013/man3p/alarm.3p | 163 + man-pages-posix-2013/man3p/alphasort.3p | 266 + man-pages-posix-2013/man3p/asctime.3p | 197 + man-pages-posix-2013/man3p/asin.3p | 156 + man-pages-posix-2013/man3p/asinh.3p | 123 + man-pages-posix-2013/man3p/asinl.3p | 38 + man-pages-posix-2013/man3p/assert.3p | 92 + man-pages-posix-2013/man3p/atan.3p | 131 + man-pages-posix-2013/man3p/atan2.3p | 239 + man-pages-posix-2013/man3p/atanf.3p | 38 + man-pages-posix-2013/man3p/atanh.3p | 174 + man-pages-posix-2013/man3p/atanl.3p | 38 + man-pages-posix-2013/man3p/atexit.3p | 131 + man-pages-posix-2013/man3p/atof.3p | 85 + man-pages-posix-2013/man3p/atoi.3p | 108 + man-pages-posix-2013/man3p/atol.3p | 97 + man-pages-posix-2013/man3p/basename.3p | 144 + man-pages-posix-2013/man3p/bind.3p | 290 + man-pages-posix-2013/man3p/bsearch.3p | 193 + man-pages-posix-2013/man3p/btowc.3p | 79 + man-pages-posix-2013/man3p/cabs.3p | 64 + man-pages-posix-2013/man3p/cacos.3p | 69 + man-pages-posix-2013/man3p/cacosh.3p | 69 + man-pages-posix-2013/man3p/cacosl.3p | 38 + man-pages-posix-2013/man3p/calloc.3p | 104 + man-pages-posix-2013/man3p/carg.3p | 69 + man-pages-posix-2013/man3p/casin.3p | 69 + man-pages-posix-2013/man3p/casinh.3p | 70 + man-pages-posix-2013/man3p/casinl.3p | 38 + man-pages-posix-2013/man3p/catan.3p | 69 + man-pages-posix-2013/man3p/catanh.3p | 70 + man-pages-posix-2013/man3p/catanl.3p | 38 + man-pages-posix-2013/man3p/catclose.3p | 77 + man-pages-posix-2013/man3p/catgets.3p | 125 + man-pages-posix-2013/man3p/catopen.3p | 195 + man-pages-posix-2013/man3p/cbrt.3p | 81 + man-pages-posix-2013/man3p/ccos.3p | 65 + man-pages-posix-2013/man3p/ccosh.3p | 65 + man-pages-posix-2013/man3p/ccosl.3p | 38 + man-pages-posix-2013/man3p/ceil.3p | 101 + man-pages-posix-2013/man3p/cexp.3p | 67 + man-pages-posix-2013/man3p/cfgetispeed.3p | 126 + man-pages-posix-2013/man3p/cfgetospeed.3p | 75 + man-pages-posix-2013/man3p/cfsetispeed.3p | 94 + man-pages-posix-2013/man3p/cfsetospeed.3p | 94 + man-pages-posix-2013/man3p/chdir.3p | 131 + man-pages-posix-2013/man3p/chmod.3p | 365 + man-pages-posix-2013/man3p/chown.3p | 323 + man-pages-posix-2013/man3p/cimag.3p | 78 + man-pages-posix-2013/man3p/clearerr.3p | 73 + man-pages-posix-2013/man3p/clock.3p | 95 + man-pages-posix-2013/man3p/clock_getcpuclockid.3p | 98 + man-pages-posix-2013/man3p/clock_getres.3p | 284 + man-pages-posix-2013/man3p/clock_nanosleep.3p | 261 + man-pages-posix-2013/man3p/clock_settime.3p | 38 + man-pages-posix-2013/man3p/clog.3p | 71 + man-pages-posix-2013/man3p/close.3p | 329 + man-pages-posix-2013/man3p/closedir.3p | 108 + man-pages-posix-2013/man3p/closelog.3p | 291 + man-pages-posix-2013/man3p/confstr.3p | 278 + man-pages-posix-2013/man3p/conj.3p | 69 + man-pages-posix-2013/man3p/connect.3p | 301 + man-pages-posix-2013/man3p/copysign.3p | 74 + man-pages-posix-2013/man3p/cos.3p | 126 + man-pages-posix-2013/man3p/cosh.3p | 124 + man-pages-posix-2013/man3p/cosl.3p | 38 + man-pages-posix-2013/man3p/cpow.3p | 68 + man-pages-posix-2013/man3p/cproj.3p | 104 + man-pages-posix-2013/man3p/creal.3p | 79 + man-pages-posix-2013/man3p/creat.3p | 104 + man-pages-posix-2013/man3p/crypt.3p | 155 + man-pages-posix-2013/man3p/csin.3p | 65 + man-pages-posix-2013/man3p/csinh.3p | 65 + man-pages-posix-2013/man3p/csinl.3p | 38 + man-pages-posix-2013/man3p/csqrt.3p | 68 + man-pages-posix-2013/man3p/ctan.3p | 65 + man-pages-posix-2013/man3p/ctanh.3p | 65 + man-pages-posix-2013/man3p/ctanl.3p | 38 + man-pages-posix-2013/man3p/ctermid.3p | 144 + man-pages-posix-2013/man3p/ctime.3p | 173 + man-pages-posix-2013/man3p/daylight.3p | 38 + man-pages-posix-2013/man3p/dbm_clearerr.3p | 403 + man-pages-posix-2013/man3p/difftime.3p | 78 + man-pages-posix-2013/man3p/dirfd.3p | 130 + man-pages-posix-2013/man3p/dirname.3p | 162 + man-pages-posix-2013/man3p/div.3p | 88 + man-pages-posix-2013/man3p/dlclose.3p | 141 + man-pages-posix-2013/man3p/dlerror.3p | 109 + man-pages-posix-2013/man3p/dlopen.3p | 268 + man-pages-posix-2013/man3p/dlsym.3p | 190 + man-pages-posix-2013/man3p/dprintf.3p | 37 + man-pages-posix-2013/man3p/drand48.3p | 240 + man-pages-posix-2013/man3p/dup.3p | 262 + man-pages-posix-2013/man3p/duplocale.3p | 150 + man-pages-posix-2013/man3p/encrypt.3p | 118 + man-pages-posix-2013/man3p/endgrent.3p | 132 + man-pages-posix-2013/man3p/endhostent.3p | 109 + man-pages-posix-2013/man3p/endnetent.3p | 143 + man-pages-posix-2013/man3p/endprotoent.3p | 137 + man-pages-posix-2013/man3p/endpwent.3p | 165 + man-pages-posix-2013/man3p/endservent.3p | 169 + man-pages-posix-2013/man3p/endutxent.3p | 238 + man-pages-posix-2013/man3p/environ.3p | 38 + man-pages-posix-2013/man3p/erand48.3p | 38 + man-pages-posix-2013/man3p/erf.3p | 151 + man-pages-posix-2013/man3p/erfc.3p | 143 + man-pages-posix-2013/man3p/erff.3p | 40 + man-pages-posix-2013/man3p/errno.3p | 106 + man-pages-posix-2013/man3p/exec.3p | 1344 +++ man-pages-posix-2013/man3p/exit.3p | 101 + man-pages-posix-2013/man3p/exp.3p | 187 + man-pages-posix-2013/man3p/exp2.3p | 165 + man-pages-posix-2013/man3p/expm1.3p | 191 + man-pages-posix-2013/man3p/fabs.3p | 119 + man-pages-posix-2013/man3p/faccessat.3p | 39 + man-pages-posix-2013/man3p/fattach.3p | 234 + man-pages-posix-2013/man3p/fchdir.3p | 101 + man-pages-posix-2013/man3p/fchmod.3p | 159 + man-pages-posix-2013/man3p/fchmodat.3p | 38 + man-pages-posix-2013/man3p/fchown.3p | 138 + man-pages-posix-2013/man3p/fchownat.3p | 40 + man-pages-posix-2013/man3p/fclose.3p | 166 + man-pages-posix-2013/man3p/fcntl.3p | 690 ++ man-pages-posix-2013/man3p/fdatasync.3p | 98 + man-pages-posix-2013/man3p/fdetach.3p | 174 + man-pages-posix-2013/man3p/fdim.3p | 148 + man-pages-posix-2013/man3p/fdopen.3p | 194 + man-pages-posix-2013/man3p/fdopendir.3p | 314 + man-pages-posix-2013/man3p/feclearexcept.3p | 69 + man-pages-posix-2013/man3p/fegetenv.3p | 89 + man-pages-posix-2013/man3p/fegetexceptflag.3p | 94 + man-pages-posix-2013/man3p/fegetround.3p | 103 + man-pages-posix-2013/man3p/feholdexcept.3p | 76 + man-pages-posix-2013/man3p/feof.3p | 78 + man-pages-posix-2013/man3p/feraiseexcept.3p | 82 + man-pages-posix-2013/man3p/ferror.3p | 77 + man-pages-posix-2013/man3p/fesetenv.3p | 38 + man-pages-posix-2013/man3p/fesetexceptflag.3p | 38 + man-pages-posix-2013/man3p/fesetround.3p | 38 + man-pages-posix-2013/man3p/fetestexcept.3p | 95 + man-pages-posix-2013/man3p/feupdateenv.3p | 98 + man-pages-posix-2013/man3p/fexecve.3p | 37 + man-pages-posix-2013/man3p/fflush.3p | 214 + man-pages-posix-2013/man3p/ffs.3p | 66 + man-pages-posix-2013/man3p/fgetc.3p | 175 + man-pages-posix-2013/man3p/fgetpos.3p | 101 + man-pages-posix-2013/man3p/fgets.3p | 176 + man-pages-posix-2013/man3p/fgetwc.3p | 174 + man-pages-posix-2013/man3p/fgetws.3p | 121 + man-pages-posix-2013/man3p/fileno.3p | 88 + man-pages-posix-2013/man3p/flockfile.3p | 190 + man-pages-posix-2013/man3p/floor.3p | 97 + man-pages-posix-2013/man3p/fma.3p | 209 + man-pages-posix-2013/man3p/fmax.3p | 78 + man-pages-posix-2013/man3p/fmemopen.3p | 280 + man-pages-posix-2013/man3p/fmin.3p | 78 + man-pages-posix-2013/man3p/fmod.3p | 167 + man-pages-posix-2013/man3p/fmtmsg.3p | 247 + man-pages-posix-2013/man3p/fnmatch.3p | 196 + man-pages-posix-2013/man3p/fopen.3p | 354 + man-pages-posix-2013/man3p/fork.3p | 435 + man-pages-posix-2013/man3p/fpathconf.3p | 509 ++ man-pages-posix-2013/man3p/fpclassify.3p | 73 + man-pages-posix-2013/man3p/fprintf.3p | 1490 ++++ man-pages-posix-2013/man3p/fputc.3p | 157 + man-pages-posix-2013/man3p/fputs.3p | 154 + man-pages-posix-2013/man3p/fputwc.3p | 162 + man-pages-posix-2013/man3p/fputws.3p | 113 + man-pages-posix-2013/man3p/fread.3p | 190 + man-pages-posix-2013/man3p/free.3p | 84 + man-pages-posix-2013/man3p/freeaddrinfo.3p | 504 ++ man-pages-posix-2013/man3p/freelocale.3p | 102 + man-pages-posix-2013/man3p/freopen.3p | 361 + man-pages-posix-2013/man3p/frexp.3p | 97 + man-pages-posix-2013/man3p/fscanf.3p | 880 ++ man-pages-posix-2013/man3p/fseek.3p | 250 + man-pages-posix-2013/man3p/fsetpos.3p | 172 + man-pages-posix-2013/man3p/fstat.3p | 192 + man-pages-posix-2013/man3p/fstatat.3p | 493 ++ man-pages-posix-2013/man3p/fstatvfs.3p | 233 + man-pages-posix-2013/man3p/fsync.3p | 152 + man-pages-posix-2013/man3p/ftell.3p | 129 + man-pages-posix-2013/man3p/ftok.3p | 193 + man-pages-posix-2013/man3p/ftruncate.3p | 161 + man-pages-posix-2013/man3p/ftrylockfile.3p | 38 + man-pages-posix-2013/man3p/ftw.3p | 284 + man-pages-posix-2013/man3p/funlockfile.3p | 38 + man-pages-posix-2013/man3p/futimens.3p | 383 + man-pages-posix-2013/man3p/fwide.3p | 107 + man-pages-posix-2013/man3p/fwprintf.3p | 1040 +++ man-pages-posix-2013/man3p/fwrite.3p | 121 + man-pages-posix-2013/man3p/fwscanf.3p | 862 ++ man-pages-posix-2013/man3p/gai_strerror.3p | 96 + man-pages-posix-2013/man3p/getaddrinfo.3p | 42 + man-pages-posix-2013/man3p/getc.3p | 90 + man-pages-posix-2013/man3p/getc_unlocked.3p | 233 + man-pages-posix-2013/man3p/getchar.3p | 74 + man-pages-posix-2013/man3p/getchar_unlocked.3p | 38 + man-pages-posix-2013/man3p/getcwd.3p | 292 + man-pages-posix-2013/man3p/getdate.3p | 399 + man-pages-posix-2013/man3p/getdelim.3p | 221 + man-pages-posix-2013/man3p/getegid.3p | 70 + man-pages-posix-2013/man3p/getenv.3p | 220 + man-pages-posix-2013/man3p/geteuid.3p | 70 + man-pages-posix-2013/man3p/getgid.3p | 70 + man-pages-posix-2013/man3p/getgrent.3p | 38 + man-pages-posix-2013/man3p/getgrgid.3p | 235 + man-pages-posix-2013/man3p/getgrnam.3p | 210 + man-pages-posix-2013/man3p/getgroups.3p | 145 + man-pages-posix-2013/man3p/gethostent.3p | 38 + man-pages-posix-2013/man3p/gethostid.3p | 60 + man-pages-posix-2013/man3p/gethostname.3p | 73 + man-pages-posix-2013/man3p/getitimer.3p | 167 + man-pages-posix-2013/man3p/getline.3p | 40 + man-pages-posix-2013/man3p/getlogin.3p | 225 + man-pages-posix-2013/man3p/getmsg.3p | 410 + man-pages-posix-2013/man3p/getnameinfo.3p | 234 + man-pages-posix-2013/man3p/getnetbyaddr.3p | 42 + man-pages-posix-2013/man3p/getopt.3p | 445 + man-pages-posix-2013/man3p/getpeername.3p | 121 + man-pages-posix-2013/man3p/getpgid.3p | 98 + man-pages-posix-2013/man3p/getpgrp.3p | 80 + man-pages-posix-2013/man3p/getpid.3p | 69 + man-pages-posix-2013/man3p/getpmsg.3p | 40 + man-pages-posix-2013/man3p/getppid.3p | 69 + man-pages-posix-2013/man3p/getpriority.3p | 235 + man-pages-posix-2013/man3p/getprotobyname.3p | 42 + man-pages-posix-2013/man3p/getpwent.3p | 38 + man-pages-posix-2013/man3p/getpwnam.3p | 241 + man-pages-posix-2013/man3p/getpwuid.3p | 290 + man-pages-posix-2013/man3p/getrlimit.3p | 250 + man-pages-posix-2013/man3p/getrusage.3p | 110 + man-pages-posix-2013/man3p/gets.3p | 135 + man-pages-posix-2013/man3p/getservbyname.3p | 42 + man-pages-posix-2013/man3p/getsid.3p | 86 + man-pages-posix-2013/man3p/getsockname.3p | 121 + man-pages-posix-2013/man3p/getsockopt.3p | 144 + man-pages-posix-2013/man3p/getsubopt.3p | 296 + man-pages-posix-2013/man3p/gettimeofday.3p | 77 + man-pages-posix-2013/man3p/getuid.3p | 85 + man-pages-posix-2013/man3p/getutxent.3p | 42 + man-pages-posix-2013/man3p/getwc.3p | 80 + man-pages-posix-2013/man3p/getwchar.3p | 79 + man-pages-posix-2013/man3p/glob.3p | 448 + man-pages-posix-2013/man3p/gmtime.3p | 152 + man-pages-posix-2013/man3p/grantpt.3p | 93 + man-pages-posix-2013/man3p/hcreate.3p | 211 + man-pages-posix-2013/man3p/htonl.3p | 90 + man-pages-posix-2013/man3p/hypot.3p | 156 + man-pages-posix-2013/man3p/iconv.3p | 235 + man-pages-posix-2013/man3p/iconv_close.3p | 74 + man-pages-posix-2013/man3p/iconv_open.3p | 124 + man-pages-posix-2013/man3p/if_freenameindex.3p | 72 + man-pages-posix-2013/man3p/if_indextoname.3p | 82 + man-pages-posix-2013/man3p/if_nameindex.3p | 82 + man-pages-posix-2013/man3p/if_nametoindex.3p | 65 + man-pages-posix-2013/man3p/ilogb.3p | 193 + man-pages-posix-2013/man3p/imaxabs.3p | 67 + man-pages-posix-2013/man3p/imaxdiv.3p | 76 + man-pages-posix-2013/man3p/inet_addr.3p | 116 + man-pages-posix-2013/man3p/inet_ntop.3p | 200 + man-pages-posix-2013/man3p/initstate.3p | 189 + man-pages-posix-2013/man3p/insque.3p | 214 + man-pages-posix-2013/man3p/ioctl.3p | 1214 +++ man-pages-posix-2013/man3p/isalnum.3p | 116 + man-pages-posix-2013/man3p/isalpha.3p | 115 + man-pages-posix-2013/man3p/isascii.3p | 71 + man-pages-posix-2013/man3p/isastream.3p | 75 + man-pages-posix-2013/man3p/isatty.3p | 82 + man-pages-posix-2013/man3p/isblank.3p | 117 + man-pages-posix-2013/man3p/iscntrl.3p | 115 + man-pages-posix-2013/man3p/isdigit.3p | 113 + man-pages-posix-2013/man3p/isfinite.3p | 73 + man-pages-posix-2013/man3p/isgraph.3p | 116 + man-pages-posix-2013/man3p/isgreater.3p | 101 + man-pages-posix-2013/man3p/isgreaterequal.3p | 101 + man-pages-posix-2013/man3p/isinf.3p | 72 + man-pages-posix-2013/man3p/isless.3p | 101 + man-pages-posix-2013/man3p/islessequal.3p | 101 + man-pages-posix-2013/man3p/islessgreater.3p | 106 + man-pages-posix-2013/man3p/islower.3p | 169 + man-pages-posix-2013/man3p/isnan.3p | 72 + man-pages-posix-2013/man3p/isnormal.3p | 72 + man-pages-posix-2013/man3p/isprint.3p | 115 + man-pages-posix-2013/man3p/ispunct.3p | 115 + man-pages-posix-2013/man3p/isspace.3p | 114 + man-pages-posix-2013/man3p/isunordered.3p | 87 + man-pages-posix-2013/man3p/isupper.3p | 115 + man-pages-posix-2013/man3p/iswalnum.3p | 117 + man-pages-posix-2013/man3p/iswalpha.3p | 114 + man-pages-posix-2013/man3p/iswblank.3p | 115 + man-pages-posix-2013/man3p/iswcntrl.3p | 114 + man-pages-posix-2013/man3p/iswctype.3p | 188 + man-pages-posix-2013/man3p/iswdigit.3p | 114 + man-pages-posix-2013/man3p/iswgraph.3p | 115 + man-pages-posix-2013/man3p/iswlower.3p | 114 + man-pages-posix-2013/man3p/iswprint.3p | 114 + man-pages-posix-2013/man3p/iswpunct.3p | 114 + man-pages-posix-2013/man3p/iswspace.3p | 114 + man-pages-posix-2013/man3p/iswupper.3p | 114 + man-pages-posix-2013/man3p/iswxdigit.3p | 114 + man-pages-posix-2013/man3p/isxdigit.3p | 112 + man-pages-posix-2013/man3p/j0.3p | 112 + man-pages-posix-2013/man3p/jrand48.3p | 38 + man-pages-posix-2013/man3p/kill.3p | 287 + man-pages-posix-2013/man3p/killpg.3p | 95 + man-pages-posix-2013/man3p/l64a.3p | 38 + man-pages-posix-2013/man3p/labs.3p | 84 + man-pages-posix-2013/man3p/lchown.3p | 174 + man-pages-posix-2013/man3p/lcong48.3p | 39 + man-pages-posix-2013/man3p/ldexp.3p | 151 + man-pages-posix-2013/man3p/ldiv.3p | 108 + man-pages-posix-2013/man3p/lfind.3p | 39 + man-pages-posix-2013/man3p/lgamma.3p | 158 + man-pages-posix-2013/man3p/link.3p | 437 + man-pages-posix-2013/man3p/lio_listio.3p | 354 + man-pages-posix-2013/man3p/listen.3p | 153 + man-pages-posix-2013/man3p/llabs.3p | 38 + man-pages-posix-2013/man3p/lldiv.3p | 38 + man-pages-posix-2013/man3p/llrint.3p | 147 + man-pages-posix-2013/man3p/llround.3p | 149 + man-pages-posix-2013/man3p/localeconv.3p | 362 + man-pages-posix-2013/man3p/localtime.3p | 276 + man-pages-posix-2013/man3p/lockf.3p | 291 + man-pages-posix-2013/man3p/log.3p | 151 + man-pages-posix-2013/man3p/log10.3p | 149 + man-pages-posix-2013/man3p/log1p.3p | 177 + man-pages-posix-2013/man3p/log2.3p | 148 + man-pages-posix-2013/man3p/logb.3p | 163 + man-pages-posix-2013/man3p/logf.3p | 40 + man-pages-posix-2013/man3p/longjmp.3p | 146 + man-pages-posix-2013/man3p/lrand48.3p | 39 + man-pages-posix-2013/man3p/lrint.3p | 147 + man-pages-posix-2013/man3p/lround.3p | 149 + man-pages-posix-2013/man3p/lsearch.3p | 154 + man-pages-posix-2013/man3p/lseek.3p | 183 + man-pages-posix-2013/man3p/lstat.3p | 38 + man-pages-posix-2013/man3p/malloc.3p | 99 + man-pages-posix-2013/man3p/mblen.3p | 135 + man-pages-posix-2013/man3p/mbrlen.3p | 158 + man-pages-posix-2013/man3p/mbrtowc.3p | 180 + man-pages-posix-2013/man3p/mbsinit.3p | 101 + man-pages-posix-2013/man3p/mbsrtowcs.3p | 168 + man-pages-posix-2013/man3p/mbstowcs.3p | 119 + man-pages-posix-2013/man3p/mbtowc.3p | 139 + man-pages-posix-2013/man3p/memccpy.3p | 81 + man-pages-posix-2013/man3p/memchr.3p | 81 + man-pages-posix-2013/man3p/memcmp.3p | 82 + man-pages-posix-2013/man3p/memcpy.3p | 74 + man-pages-posix-2013/man3p/memmove.3p | 83 + man-pages-posix-2013/man3p/memset.3p | 71 + man-pages-posix-2013/man3p/mkdir.3p | 250 + man-pages-posix-2013/man3p/mkdtemp.3p | 215 + man-pages-posix-2013/man3p/mkfifo.3p | 273 + man-pages-posix-2013/man3p/mknod.3p | 336 + man-pages-posix-2013/man3p/mkstemp.3p | 38 + man-pages-posix-2013/man3p/mktime.3p | 175 + man-pages-posix-2013/man3p/mlock.3p | 168 + man-pages-posix-2013/man3p/mlockall.3p | 158 + man-pages-posix-2013/man3p/mmap.3p | 729 ++ man-pages-posix-2013/man3p/modf.3p | 107 + man-pages-posix-2013/man3p/mprotect.3p | 158 + man-pages-posix-2013/man3p/mq_close.3p | 90 + man-pages-posix-2013/man3p/mq_getattr.3p | 111 + man-pages-posix-2013/man3p/mq_notify.3p | 196 + man-pages-posix-2013/man3p/mq_open.3p | 317 + man-pages-posix-2013/man3p/mq_receive.3p | 201 + man-pages-posix-2013/man3p/mq_send.3p | 210 + man-pages-posix-2013/man3p/mq_setattr.3p | 112 + man-pages-posix-2013/man3p/mq_timedreceive.3p | 42 + man-pages-posix-2013/man3p/mq_timedsend.3p | 41 + man-pages-posix-2013/man3p/mq_unlink.3p | 127 + man-pages-posix-2013/man3p/mrand48.3p | 38 + man-pages-posix-2013/man3p/msgctl.3p | 188 + man-pages-posix-2013/man3p/msgget.3p | 164 + man-pages-posix-2013/man3p/msgrcv.3p | 272 + man-pages-posix-2013/man3p/msgsnd.3p | 239 + man-pages-posix-2013/man3p/msync.3p | 191 + man-pages-posix-2013/man3p/munlock.3p | 38 + man-pages-posix-2013/man3p/munlockall.3p | 38 + man-pages-posix-2013/man3p/munmap.3p | 143 + man-pages-posix-2013/man3p/nan.3p | 112 + man-pages-posix-2013/man3p/nanosleep.3p | 145 + man-pages-posix-2013/man3p/nearbyint.3p | 89 + man-pages-posix-2013/man3p/newlocale.3p | 267 + man-pages-posix-2013/man3p/nextafter.3p | 196 + man-pages-posix-2013/man3p/nftw.3p | 358 + man-pages-posix-2013/man3p/nice.3p | 122 + man-pages-posix-2013/man3p/nl_langinfo.3p | 205 + man-pages-posix-2013/man3p/nrand48.3p | 38 + man-pages-posix-2013/man3p/ntohl.3p | 40 + man-pages-posix-2013/man3p/open.3p | 779 ++ man-pages-posix-2013/man3p/open_memstream.3p | 189 + man-pages-posix-2013/man3p/openat.3p | 38 + man-pages-posix-2013/man3p/opendir.3p | 38 + man-pages-posix-2013/man3p/openlog.3p | 38 + man-pages-posix-2013/man3p/optarg.3p | 42 + man-pages-posix-2013/man3p/pathconf.3p | 38 + man-pages-posix-2013/man3p/pause.3p | 91 + man-pages-posix-2013/man3p/pclose.3p | 221 + man-pages-posix-2013/man3p/perror.3p | 156 + man-pages-posix-2013/man3p/pipe.3p | 169 + man-pages-posix-2013/man3p/poll.3p | 388 + man-pages-posix-2013/man3p/popen.3p | 312 + man-pages-posix-2013/man3p/posix_fadvise.3p | 133 + man-pages-posix-2013/man3p/posix_fallocate.3p | 160 + man-pages-posix-2013/man3p/posix_madvise.3p | 144 + man-pages-posix-2013/man3p/posix_mem_offset.3p | 125 + man-pages-posix-2013/man3p/posix_memalign.3p | 101 + man-pages-posix-2013/man3p/posix_openpt.3p | 172 + man-pages-posix-2013/man3p/posix_spawn.3p | 932 ++ .../man3p/posix_spawn_file_actions_addclose.3p | 328 + .../man3p/posix_spawn_file_actions_adddup2.3p | 135 + .../man3p/posix_spawn_file_actions_addopen.3p | 41 + .../man3p/posix_spawn_file_actions_destroy.3p | 109 + .../man3p/posix_spawnattr_destroy.3p | 151 + .../man3p/posix_spawnattr_getflags.3p | 129 + .../man3p/posix_spawnattr_getpgroup.3p | 114 + .../man3p/posix_spawnattr_getschedparam.3p | 119 + .../man3p/posix_spawnattr_getschedpolicy.3p | 118 + .../man3p/posix_spawnattr_getsigdefault.3p | 119 + .../man3p/posix_spawnattr_getsigmask.3p | 117 + man-pages-posix-2013/man3p/posix_spawnattr_init.3p | 39 + .../man3p/posix_spawnattr_setflags.3p | 39 + .../man3p/posix_spawnattr_setpgroup.3p | 39 + .../man3p/posix_spawnattr_setschedparam.3p | 41 + .../man3p/posix_spawnattr_setschedpolicy.3p | 41 + .../man3p/posix_spawnattr_setsigdefault.3p | 41 + .../man3p/posix_spawnattr_setsigmask.3p | 41 + man-pages-posix-2013/man3p/posix_spawnp.3p | 42 + .../man3p/posix_trace_attr_destroy.3p | 125 + .../man3p/posix_trace_attr_getclockres.3p | 190 + .../man3p/posix_trace_attr_getinherited.3p | 277 + .../man3p/posix_trace_attr_getlogsize.3p | 265 + .../man3p/posix_trace_attr_getname.3p | 40 + .../man3p/posix_trace_attr_getstreamfullpolicy.3p | 40 + .../man3p/posix_trace_attr_getstreamsize.3p | 41 + .../man3p/posix_trace_attr_init.3p | 39 + .../man3p/posix_trace_attr_setinherited.3p | 43 + .../man3p/posix_trace_attr_setlogsize.3p | 44 + .../man3p/posix_trace_attr_setname.3p | 40 + .../man3p/posix_trace_attr_setstreamfullpolicy.3p | 40 + .../man3p/posix_trace_attr_setstreamsize.3p | 41 + man-pages-posix-2013/man3p/posix_trace_clear.3p | 125 + man-pages-posix-2013/man3p/posix_trace_close.3p | 173 + man-pages-posix-2013/man3p/posix_trace_create.3p | 450 + man-pages-posix-2013/man3p/posix_trace_event.3p | 178 + .../man3p/posix_trace_eventid_equal.3p | 225 + .../man3p/posix_trace_eventid_open.3p | 41 + .../man3p/posix_trace_eventset_add.3p | 155 + .../man3p/posix_trace_eventtypelist_getnext_id.3p | 109 + man-pages-posix-2013/man3p/posix_trace_flush.3p | 40 + man-pages-posix-2013/man3p/posix_trace_get_attr.3p | 138 + .../man3p/posix_trace_get_filter.3p | 143 + .../man3p/posix_trace_get_status.3p | 40 + .../man3p/posix_trace_getnext_event.3p | 265 + man-pages-posix-2013/man3p/posix_trace_open.3p | 41 + .../man3p/posix_trace_set_filter.3p | 40 + man-pages-posix-2013/man3p/posix_trace_shutdown.3p | 40 + man-pages-posix-2013/man3p/posix_trace_start.3p | 103 + .../man3p/posix_trace_timedgetnext_event.3p | 44 + .../man3p/posix_trace_trid_eventid_open.3p | 41 + .../man3p/posix_trace_trygetnext_event.3p | 43 + .../man3p/posix_typed_mem_get_info.3p | 142 + man-pages-posix-2013/man3p/posix_typed_mem_open.3p | 275 + man-pages-posix-2013/man3p/pow.3p | 315 + man-pages-posix-2013/man3p/pread.3p | 38 + man-pages-posix-2013/man3p/printf.3p | 38 + man-pages-posix-2013/man3p/pselect.3p | 504 ++ man-pages-posix-2013/man3p/psiginfo.3p | 175 + man-pages-posix-2013/man3p/pthread_atfork.3p | 237 + man-pages-posix-2013/man3p/pthread_attr_destroy.3p | 237 + .../man3p/pthread_attr_getdetachstate.3p | 173 + .../man3p/pthread_attr_getguardsize.3p | 215 + .../man3p/pthread_attr_getinheritsched.3p | 159 + .../man3p/pthread_attr_getschedparam.3p | 150 + .../man3p/pthread_attr_getschedpolicy.3p | 133 + .../man3p/pthread_attr_getscope.3p | 132 + .../man3p/pthread_attr_getstack.3p | 201 + .../man3p/pthread_attr_getstacksize.3p | 119 + man-pages-posix-2013/man3p/pthread_attr_init.3p | 38 + .../man3p/pthread_attr_setdetachstate.3p | 38 + .../man3p/pthread_attr_setguardsize.3p | 39 + .../man3p/pthread_attr_setinheritsched.3p | 40 + .../man3p/pthread_attr_setschedparam.3p | 39 + .../man3p/pthread_attr_setschedpolicy.3p | 39 + .../man3p/pthread_attr_setscope.3p | 39 + .../man3p/pthread_attr_setstack.3p | 39 + .../man3p/pthread_attr_setstacksize.3p | 38 + .../man3p/pthread_barrier_destroy.3p | 168 + man-pages-posix-2013/man3p/pthread_barrier_wait.3p | 112 + .../man3p/pthread_barrierattr_destroy.3p | 113 + .../man3p/pthread_barrierattr_getpshared.3p | 141 + .../man3p/pthread_barrierattr_init.3p | 38 + .../man3p/pthread_barrierattr_setpshared.3p | 39 + man-pages-posix-2013/man3p/pthread_cancel.3p | 121 + man-pages-posix-2013/man3p/pthread_cleanup_pop.3p | 335 + .../man3p/pthread_cond_broadcast.3p | 238 + man-pages-posix-2013/man3p/pthread_cond_destroy.3p | 236 + man-pages-posix-2013/man3p/pthread_cond_signal.3p | 38 + .../man3p/pthread_cond_timedwait.3p | 459 + .../man3p/pthread_condattr_destroy.3p | 141 + .../man3p/pthread_condattr_getclock.3p | 133 + .../man3p/pthread_condattr_getpshared.3p | 132 + .../man3p/pthread_condattr_init.3p | 38 + .../man3p/pthread_condattr_setclock.3p | 39 + .../man3p/pthread_condattr_setpshared.3p | 39 + man-pages-posix-2013/man3p/pthread_create.3p | 234 + man-pages-posix-2013/man3p/pthread_detach.3p | 119 + man-pages-posix-2013/man3p/pthread_equal.3p | 86 + man-pages-posix-2013/man3p/pthread_exit.3p | 127 + .../man3p/pthread_getconcurrency.3p | 140 + .../man3p/pthread_getcpuclockid.3p | 78 + .../man3p/pthread_getschedparam.3p | 193 + man-pages-posix-2013/man3p/pthread_getspecific.3p | 151 + man-pages-posix-2013/man3p/pthread_join.3p | 230 + man-pages-posix-2013/man3p/pthread_key_create.3p | 261 + man-pages-posix-2013/man3p/pthread_key_delete.3p | 139 + man-pages-posix-2013/man3p/pthread_kill.3p | 97 + .../man3p/pthread_mutex_consistent.3p | 120 + .../man3p/pthread_mutex_destroy.3p | 455 + .../man3p/pthread_mutex_getprioceiling.3p | 151 + man-pages-posix-2013/man3p/pthread_mutex_init.3p | 40 + man-pages-posix-2013/man3p/pthread_mutex_lock.3p | 309 + .../man3p/pthread_mutex_setprioceiling.3p | 40 + .../man3p/pthread_mutex_timedlock.3p | 195 + .../man3p/pthread_mutex_trylock.3p | 40 + .../man3p/pthread_mutexattr_destroy.3p | 364 + .../man3p/pthread_mutexattr_getprioceiling.3p | 123 + .../man3p/pthread_mutexattr_getprotocol.3p | 197 + .../man3p/pthread_mutexattr_getpshared.3p | 130 + .../man3p/pthread_mutexattr_getrobust.3p | 160 + .../man3p/pthread_mutexattr_gettype.3p | 135 + .../man3p/pthread_mutexattr_init.3p | 38 + .../man3p/pthread_mutexattr_setprioceiling.3p | 40 + .../man3p/pthread_mutexattr_setprotocol.3p | 40 + .../man3p/pthread_mutexattr_setpshared.3p | 39 + .../man3p/pthread_mutexattr_setrobust.3p | 39 + .../man3p/pthread_mutexattr_settype.3p | 38 + man-pages-posix-2013/man3p/pthread_once.3p | 175 + .../man3p/pthread_rwlock_destroy.3p | 195 + .../man3p/pthread_rwlock_rdlock.3p | 182 + .../man3p/pthread_rwlock_timedrdlock.3p | 148 + .../man3p/pthread_rwlock_timedwrlock.3p | 141 + .../man3p/pthread_rwlock_tryrdlock.3p | 38 + .../man3p/pthread_rwlock_trywrlock.3p | 133 + .../man3p/pthread_rwlock_unlock.3p | 119 + .../man3p/pthread_rwlock_wrlock.3p | 38 + .../man3p/pthread_rwlockattr_destroy.3p | 115 + .../man3p/pthread_rwlockattr_getpshared.3p | 124 + .../man3p/pthread_rwlockattr_init.3p | 38 + .../man3p/pthread_rwlockattr_setpshared.3p | 40 + man-pages-posix-2013/man3p/pthread_self.3p | 67 + .../man3p/pthread_setcancelstate.3p | 153 + .../man3p/pthread_setconcurrency.3p | 38 + .../man3p/pthread_setschedparam.3p | 40 + man-pages-posix-2013/man3p/pthread_setschedprio.3p | 115 + man-pages-posix-2013/man3p/pthread_setspecific.3p | 38 + man-pages-posix-2013/man3p/pthread_sigmask.3p | 248 + man-pages-posix-2013/man3p/pthread_spin_destroy.3p | 155 + man-pages-posix-2013/man3p/pthread_spin_lock.3p | 114 + man-pages-posix-2013/man3p/pthread_spin_unlock.3p | 98 + man-pages-posix-2013/man3p/pthread_testcancel.3p | 38 + man-pages-posix-2013/man3p/ptsname.3p | 86 + man-pages-posix-2013/man3p/putc.3p | 78 + man-pages-posix-2013/man3p/putc_unlocked.3p | 38 + man-pages-posix-2013/man3p/putchar.3p | 65 + man-pages-posix-2013/man3p/putchar_unlocked.3p | 38 + man-pages-posix-2013/man3p/putenv.3p | 159 + man-pages-posix-2013/man3p/putmsg.3p | 361 + man-pages-posix-2013/man3p/puts.3p | 145 + man-pages-posix-2013/man3p/pututxline.3p | 38 + man-pages-posix-2013/man3p/putwc.3p | 80 + man-pages-posix-2013/man3p/putwchar.3p | 66 + man-pages-posix-2013/man3p/pwrite.3p | 39 + man-pages-posix-2013/man3p/qsort.3p | 113 + man-pages-posix-2013/man3p/raise.3p | 93 + man-pages-posix-2013/man3p/rand.3p | 225 + man-pages-posix-2013/man3p/random.3p | 38 + man-pages-posix-2013/man3p/read.3p | 626 ++ man-pages-posix-2013/man3p/readdir.3p | 373 + man-pages-posix-2013/man3p/readlink.3p | 255 + man-pages-posix-2013/man3p/readv.3p | 150 + man-pages-posix-2013/man3p/realloc.3p | 176 + man-pages-posix-2013/man3p/realpath.3p | 254 + man-pages-posix-2013/man3p/recv.3p | 220 + man-pages-posix-2013/man3p/recvfrom.3p | 243 + man-pages-posix-2013/man3p/recvmsg.3p | 278 + man-pages-posix-2013/man3p/regcomp.3p | 873 ++ man-pages-posix-2013/man3p/remainder.3p | 145 + man-pages-posix-2013/man3p/remove.3p | 97 + man-pages-posix-2013/man3p/remque.3p | 38 + man-pages-posix-2013/man3p/remquo.3p | 161 + man-pages-posix-2013/man3p/rename.3p | 549 ++ man-pages-posix-2013/man3p/rewind.3p | 100 + man-pages-posix-2013/man3p/rewinddir.3p | 91 + man-pages-posix-2013/man3p/rint.3p | 130 + man-pages-posix-2013/man3p/rmdir.3p | 267 + man-pages-posix-2013/man3p/round.3p | 88 + man-pages-posix-2013/man3p/scalbln.3p | 172 + man-pages-posix-2013/man3p/scandir.3p | 40 + man-pages-posix-2013/man3p/scanf.3p | 38 + .../man3p/sched_get_priority_max.3p | 93 + man-pages-posix-2013/man3p/sched_getparam.3p | 98 + man-pages-posix-2013/man3p/sched_getscheduler.3p | 98 + .../man3p/sched_rr_get_interval.3p | 86 + man-pages-posix-2013/man3p/sched_setparam.3p | 157 + man-pages-posix-2013/man3p/sched_setscheduler.3p | 182 + man-pages-posix-2013/man3p/sched_yield.3p | 67 + man-pages-posix-2013/man3p/seed48.3p | 39 + man-pages-posix-2013/man3p/seekdir.3p | 117 + man-pages-posix-2013/man3p/select.3p | 40 + man-pages-posix-2013/man3p/sem_close.3p | 102 + man-pages-posix-2013/man3p/sem_destroy.3p | 93 + man-pages-posix-2013/man3p/sem_getvalue.3p | 90 + man-pages-posix-2013/man3p/sem_init.3p | 146 + man-pages-posix-2013/man3p/sem_open.3p | 296 + man-pages-posix-2013/man3p/sem_post.3p | 104 + man-pages-posix-2013/man3p/sem_timedwait.3p | 231 + man-pages-posix-2013/man3p/sem_trywait.3p | 127 + man-pages-posix-2013/man3p/sem_unlink.3p | 133 + man-pages-posix-2013/man3p/sem_wait.3p | 38 + man-pages-posix-2013/man3p/semctl.3p | 336 + man-pages-posix-2013/man3p/semget.3p | 196 + man-pages-posix-2013/man3p/semop.3p | 480 ++ man-pages-posix-2013/man3p/send.3p | 224 + man-pages-posix-2013/man3p/sendmsg.3p | 323 + man-pages-posix-2013/man3p/sendto.3p | 314 + man-pages-posix-2013/man3p/setbuf.3p | 121 + man-pages-posix-2013/man3p/setegid.3p | 94 + man-pages-posix-2013/man3p/setenv.3p | 167 + man-pages-posix-2013/man3p/seteuid.3p | 93 + man-pages-posix-2013/man3p/setgid.3p | 101 + man-pages-posix-2013/man3p/setgrent.3p | 38 + man-pages-posix-2013/man3p/sethostent.3p | 38 + man-pages-posix-2013/man3p/setitimer.3p | 39 + man-pages-posix-2013/man3p/setjmp.3p | 104 + man-pages-posix-2013/man3p/setkey.3p | 98 + man-pages-posix-2013/man3p/setlocale.3p | 441 + man-pages-posix-2013/man3p/setlogmask.3p | 38 + man-pages-posix-2013/man3p/setnetent.3p | 37 + man-pages-posix-2013/man3p/setpgid.3p | 201 + man-pages-posix-2013/man3p/setpgrp.3p | 85 + man-pages-posix-2013/man3p/setpriority.3p | 38 + man-pages-posix-2013/man3p/setprotoent.3p | 38 + man-pages-posix-2013/man3p/setpwent.3p | 38 + man-pages-posix-2013/man3p/setregid.3p | 135 + man-pages-posix-2013/man3p/setreuid.3p | 141 + man-pages-posix-2013/man3p/setrlimit.3p | 38 + man-pages-posix-2013/man3p/setservent.3p | 38 + man-pages-posix-2013/man3p/setsid.3p | 111 + man-pages-posix-2013/man3p/setsockopt.3p | 165 + man-pages-posix-2013/man3p/setstate.3p | 38 + man-pages-posix-2013/man3p/setuid.3p | 255 + man-pages-posix-2013/man3p/setutxent.3p | 38 + man-pages-posix-2013/man3p/setvbuf.3p | 124 + man-pages-posix-2013/man3p/shm_open.3p | 400 + man-pages-posix-2013/man3p/shm_unlink.3p | 139 + man-pages-posix-2013/man3p/shmat.3p | 152 + man-pages-posix-2013/man3p/shmctl.3p | 190 + man-pages-posix-2013/man3p/shmdt.3p | 105 + man-pages-posix-2013/man3p/shmget.3p | 183 + man-pages-posix-2013/man3p/shutdown.3p | 126 + man-pages-posix-2013/man3p/sigaction.3p | 676 ++ man-pages-posix-2013/man3p/sigaddset.3p | 103 + man-pages-posix-2013/man3p/sigaltstack.3p | 181 + man-pages-posix-2013/man3p/sigdelset.3p | 104 + man-pages-posix-2013/man3p/sigemptyset.3p | 118 + man-pages-posix-2013/man3p/sigfillset.3p | 73 + man-pages-posix-2013/man3p/sighold.3p | 255 + man-pages-posix-2013/man3p/siginterrupt.3p | 99 + man-pages-posix-2013/man3p/sigismember.3p | 105 + man-pages-posix-2013/man3p/siglongjmp.3p | 106 + man-pages-posix-2013/man3p/signal.3p | 218 + man-pages-posix-2013/man3p/signbit.3p | 70 + man-pages-posix-2013/man3p/signgam.3p | 38 + man-pages-posix-2013/man3p/sigpause.3p | 38 + man-pages-posix-2013/man3p/sigpending.3p | 72 + man-pages-posix-2013/man3p/sigprocmask.3p | 39 + man-pages-posix-2013/man3p/sigqueue.3p | 188 + man-pages-posix-2013/man3p/sigrelse.3p | 40 + man-pages-posix-2013/man3p/sigsetjmp.3p | 155 + man-pages-posix-2013/man3p/sigsuspend.3p | 128 + man-pages-posix-2013/man3p/sigtimedwait.3p | 366 + man-pages-posix-2013/man3p/sigwait.3p | 145 + man-pages-posix-2013/man3p/sigwaitinfo.3p | 38 + man-pages-posix-2013/man3p/sin.3p | 160 + man-pages-posix-2013/man3p/sinh.3p | 145 + man-pages-posix-2013/man3p/sinl.3p | 38 + man-pages-posix-2013/man3p/sleep.3p | 224 + man-pages-posix-2013/man3p/snprintf.3p | 39 + man-pages-posix-2013/man3p/sockatmark.3p | 149 + man-pages-posix-2013/man3p/socket.3p | 182 + man-pages-posix-2013/man3p/socketpair.3p | 170 + man-pages-posix-2013/man3p/sprintf.3p | 38 + man-pages-posix-2013/man3p/sqrt.3p | 136 + man-pages-posix-2013/man3p/srand.3p | 38 + man-pages-posix-2013/man3p/srand48.3p | 39 + man-pages-posix-2013/man3p/srandom.3p | 38 + man-pages-posix-2013/man3p/sscanf.3p | 38 + man-pages-posix-2013/man3p/stat.3p | 38 + man-pages-posix-2013/man3p/statvfs.3p | 38 + man-pages-posix-2013/man3p/stdin.3p | 129 + man-pages-posix-2013/man3p/stpcpy.3p | 38 + man-pages-posix-2013/man3p/stpncpy.3p | 38 + man-pages-posix-2013/man3p/strcasecmp.3p | 135 + man-pages-posix-2013/man3p/strcat.3p | 78 + man-pages-posix-2013/man3p/strchr.3p | 71 + man-pages-posix-2013/man3p/strcmp.3p | 125 + man-pages-posix-2013/man3p/strcoll.3p | 170 + man-pages-posix-2013/man3p/strcpy.3p | 178 + man-pages-posix-2013/man3p/strcspn.3p | 73 + man-pages-posix-2013/man3p/strdup.3p | 119 + man-pages-posix-2013/man3p/strerror.3p | 307 + man-pages-posix-2013/man3p/strfmon.3p | 326 + man-pages-posix-2013/man3p/strftime.3p | 996 +++ man-pages-posix-2013/man3p/strlen.3p | 125 + man-pages-posix-2013/man3p/strncasecmp.3p | 41 + man-pages-posix-2013/man3p/strncat.3p | 78 + man-pages-posix-2013/man3p/strncmp.3p | 82 + man-pages-posix-2013/man3p/strncpy.3p | 116 + man-pages-posix-2013/man3p/strndup.3p | 38 + man-pages-posix-2013/man3p/strnlen.3p | 38 + man-pages-posix-2013/man3p/strpbrk.3p | 71 + man-pages-posix-2013/man3p/strptime.3p | 442 + man-pages-posix-2013/man3p/strrchr.3p | 97 + man-pages-posix-2013/man3p/strsignal.3p | 104 + man-pages-posix-2013/man3p/strspn.3p | 69 + man-pages-posix-2013/man3p/strstr.3p | 74 + man-pages-posix-2013/man3p/strtod.3p | 341 + man-pages-posix-2013/man3p/strtoimax.3p | 123 + man-pages-posix-2013/man3p/strtok.3p | 241 + man-pages-posix-2013/man3p/strtol.3p | 244 + man-pages-posix-2013/man3p/strtold.3p | 38 + man-pages-posix-2013/man3p/strtoll.3p | 39 + man-pages-posix-2013/man3p/strtoul.3p | 240 + man-pages-posix-2013/man3p/strtoumax.3p | 39 + man-pages-posix-2013/man3p/strxfrm.3p | 154 + man-pages-posix-2013/man3p/swab.3p | 77 + man-pages-posix-2013/man3p/swprintf.3p | 40 + man-pages-posix-2013/man3p/swscanf.3p | 40 + man-pages-posix-2013/man3p/symlink.3p | 264 + man-pages-posix-2013/man3p/sync.3p | 65 + man-pages-posix-2013/man3p/sysconf.3p | 358 + man-pages-posix-2013/man3p/syslog.3p | 38 + man-pages-posix-2013/man3p/system.3p | 459 + man-pages-posix-2013/man3p/tan.3p | 206 + man-pages-posix-2013/man3p/tanh.3p | 129 + man-pages-posix-2013/man3p/tanl.3p | 38 + man-pages-posix-2013/man3p/tcdrain.3p | 97 + man-pages-posix-2013/man3p/tcflow.3p | 133 + man-pages-posix-2013/man3p/tcflush.3p | 110 + man-pages-posix-2013/man3p/tcgetattr.3p | 146 + man-pages-posix-2013/man3p/tcgetpgrp.3p | 90 + man-pages-posix-2013/man3p/tcgetsid.3p | 76 + man-pages-posix-2013/man3p/tcsendbreak.3p | 103 + man-pages-posix-2013/man3p/tcsetattr.3p | 240 + man-pages-posix-2013/man3p/tcsetpgrp.3p | 109 + man-pages-posix-2013/man3p/tdelete.3p | 319 + man-pages-posix-2013/man3p/telldir.3p | 73 + man-pages-posix-2013/man3p/tempnam.3p | 148 + man-pages-posix-2013/man3p/tfind.3p | 39 + man-pages-posix-2013/man3p/tgamma.3p | 244 + man-pages-posix-2013/man3p/time.3p | 207 + man-pages-posix-2013/man3p/timer_create.3p | 263 + man-pages-posix-2013/man3p/timer_delete.3p | 78 + man-pages-posix-2013/man3p/timer_getoverrun.3p | 256 + man-pages-posix-2013/man3p/times.3p | 206 + man-pages-posix-2013/man3p/timezone.3p | 38 + man-pages-posix-2013/man3p/tmpfile.3p | 150 + man-pages-posix-2013/man3p/tmpnam.3p | 146 + man-pages-posix-2013/man3p/toascii.3p | 64 + man-pages-posix-2013/man3p/tolower.3p | 100 + man-pages-posix-2013/man3p/toupper.3p | 103 + man-pages-posix-2013/man3p/towctrans.3p | 155 + man-pages-posix-2013/man3p/towlower.3p | 103 + man-pages-posix-2013/man3p/towupper.3p | 103 + man-pages-posix-2013/man3p/trunc.3p | 85 + man-pages-posix-2013/man3p/truncate.3p | 167 + man-pages-posix-2013/man3p/truncf.3p | 40 + man-pages-posix-2013/man3p/tsearch.3p | 39 + man-pages-posix-2013/man3p/ttyname.3p | 130 + man-pages-posix-2013/man3p/twalk.3p | 39 + man-pages-posix-2013/man3p/tzset.3p | 128 + man-pages-posix-2013/man3p/ulimit.3p | 132 + man-pages-posix-2013/man3p/umask.3p | 116 + man-pages-posix-2013/man3p/uname.3p | 122 + man-pages-posix-2013/man3p/ungetc.3p | 118 + man-pages-posix-2013/man3p/ungetwc.3p | 126 + man-pages-posix-2013/man3p/unlink.3p | 449 + man-pages-posix-2013/man3p/unlockpt.3p | 85 + man-pages-posix-2013/man3p/unsetenv.3p | 92 + man-pages-posix-2013/man3p/uselocale.3p | 126 + man-pages-posix-2013/man3p/utime.3p | 202 + man-pages-posix-2013/man3p/utimensat.3p | 44 + man-pages-posix-2013/man3p/va_arg.3p | 44 + man-pages-posix-2013/man3p/vfprintf.3p | 101 + man-pages-posix-2013/man3p/vfscanf.3p | 94 + man-pages-posix-2013/man3p/vfwprintf.3p | 95 + man-pages-posix-2013/man3p/vfwscanf.3p | 96 + man-pages-posix-2013/man3p/vprintf.3p | 39 + man-pages-posix-2013/man3p/vscanf.3p | 39 + man-pages-posix-2013/man3p/vsnprintf.3p | 43 + man-pages-posix-2013/man3p/vsscanf.3p | 40 + man-pages-posix-2013/man3p/vswprintf.3p | 41 + man-pages-posix-2013/man3p/vswscanf.3p | 41 + man-pages-posix-2013/man3p/vwprintf.3p | 40 + man-pages-posix-2013/man3p/vwscanf.3p | 40 + man-pages-posix-2013/man3p/wait.3p | 892 ++ man-pages-posix-2013/man3p/waitid.3p | 212 + man-pages-posix-2013/man3p/waitpid.3p | 38 + man-pages-posix-2013/man3p/wcpcpy.3p | 38 + man-pages-posix-2013/man3p/wcpncpy.3p | 40 + man-pages-posix-2013/man3p/wcrtomb.3p | 151 + man-pages-posix-2013/man3p/wcscasecmp.3p | 158 + man-pages-posix-2013/man3p/wcscat.3p | 76 + man-pages-posix-2013/man3p/wcschr.3p | 75 + man-pages-posix-2013/man3p/wcscmp.3p | 78 + man-pages-posix-2013/man3p/wcscoll.3p | 135 + man-pages-posix-2013/man3p/wcscpy.3p | 99 + man-pages-posix-2013/man3p/wcscspn.3p | 72 + man-pages-posix-2013/man3p/wcsdup.3p | 91 + man-pages-posix-2013/man3p/wcsftime.3p | 94 + man-pages-posix-2013/man3p/wcslen.3p | 96 + man-pages-posix-2013/man3p/wcsncasecmp.3p | 41 + man-pages-posix-2013/man3p/wcsncat.3p | 80 + man-pages-posix-2013/man3p/wcsncmp.3p | 81 + man-pages-posix-2013/man3p/wcsncpy.3p | 106 + man-pages-posix-2013/man3p/wcsnlen.3p | 38 + man-pages-posix-2013/man3p/wcsnrtombs.3p | 39 + man-pages-posix-2013/man3p/wcspbrk.3p | 73 + man-pages-posix-2013/man3p/wcsrchr.3p | 76 + man-pages-posix-2013/man3p/wcsrtombs.3p | 165 + man-pages-posix-2013/man3p/wcsspn.3p | 71 + man-pages-posix-2013/man3p/wcsstr.3p | 77 + man-pages-posix-2013/man3p/wcstod.3p | 267 + man-pages-posix-2013/man3p/wcstoimax.3p | 103 + man-pages-posix-2013/man3p/wcstok.3p | 122 + man-pages-posix-2013/man3p/wcstol.3p | 229 + man-pages-posix-2013/man3p/wcstold.3p | 39 + man-pages-posix-2013/man3p/wcstoll.3p | 39 + man-pages-posix-2013/man3p/wcstombs.3p | 111 + man-pages-posix-2013/man3p/wcstoul.3p | 231 + man-pages-posix-2013/man3p/wcstoumax.3p | 40 + man-pages-posix-2013/man3p/wcswidth.3p | 79 + man-pages-posix-2013/man3p/wcsxfrm.3p | 161 + man-pages-posix-2013/man3p/wctob.3p | 80 + man-pages-posix-2013/man3p/wctomb.3p | 127 + man-pages-posix-2013/man3p/wctrans.3p | 139 + man-pages-posix-2013/man3p/wctype.3p | 166 + man-pages-posix-2013/man3p/wcwidth.3p | 76 + man-pages-posix-2013/man3p/wmemchr.3p | 88 + man-pages-posix-2013/man3p/wmemcmp.3p | 93 + man-pages-posix-2013/man3p/wmemcpy.3p | 88 + man-pages-posix-2013/man3p/wmemmove.3p | 103 + man-pages-posix-2013/man3p/wmemset.3p | 85 + man-pages-posix-2013/man3p/wordexp.3p | 489 ++ man-pages-posix-2013/man3p/wprintf.3p | 39 + man-pages-posix-2013/man3p/write.3p | 735 ++ man-pages-posix-2013/man3p/writev.3p | 169 + man-pages-posix-2013/man3p/wscanf.3p | 39 + man-pages-posix-2013/man3p/y0.3p | 162 + 1144 files changed, 249303 insertions(+) create mode 100644 man-pages-posix-2013/Makefile create mode 100644 man-pages-posix-2013/POSIX-COPYRIGHT create mode 100644 man-pages-posix-2013/README create mode 100644 man-pages-posix-2013/man-pages-posix-2013-a.Announce create mode 100644 man-pages-posix-2013/man-pages-posix-2013-a.lsm create mode 100644 man-pages-posix-2013/man0p/aio.h.0p create mode 100644 man-pages-posix-2013/man0p/arpa_inet.h.0p create mode 100644 man-pages-posix-2013/man0p/assert.h.0p create mode 100644 man-pages-posix-2013/man0p/complex.h.0p create mode 100644 man-pages-posix-2013/man0p/cpio.h.0p create mode 100644 man-pages-posix-2013/man0p/ctype.h.0p create mode 100644 man-pages-posix-2013/man0p/dirent.h.0p create mode 100644 man-pages-posix-2013/man0p/dlfcn.h.0p create mode 100644 man-pages-posix-2013/man0p/errno.h.0p create mode 100644 man-pages-posix-2013/man0p/fcntl.h.0p create mode 100644 man-pages-posix-2013/man0p/fenv.h.0p create mode 100644 man-pages-posix-2013/man0p/float.h.0p create mode 100644 man-pages-posix-2013/man0p/fmtmsg.h.0p create mode 100644 man-pages-posix-2013/man0p/fnmatch.h.0p create mode 100644 man-pages-posix-2013/man0p/ftw.h.0p create mode 100644 man-pages-posix-2013/man0p/glob.h.0p create mode 100644 man-pages-posix-2013/man0p/grp.h.0p create mode 100644 man-pages-posix-2013/man0p/iconv.h.0p create mode 100644 man-pages-posix-2013/man0p/inttypes.h.0p create mode 100644 man-pages-posix-2013/man0p/iso646.h.0p create mode 100644 man-pages-posix-2013/man0p/langinfo.h.0p create mode 100644 man-pages-posix-2013/man0p/libgen.h.0p create mode 100644 man-pages-posix-2013/man0p/limits.h.0p create mode 100644 man-pages-posix-2013/man0p/locale.h.0p create mode 100644 man-pages-posix-2013/man0p/math.h.0p create mode 100644 man-pages-posix-2013/man0p/monetary.h.0p create mode 100644 man-pages-posix-2013/man0p/mqueue.h.0p create mode 100644 man-pages-posix-2013/man0p/ndbm.h.0p create mode 100644 man-pages-posix-2013/man0p/net_if.h.0p create mode 100644 man-pages-posix-2013/man0p/netdb.h.0p create mode 100644 man-pages-posix-2013/man0p/netinet_in.h.0p create mode 100644 man-pages-posix-2013/man0p/netinet_tcp.h.0p create mode 100644 man-pages-posix-2013/man0p/nl_types.h.0p create mode 100644 man-pages-posix-2013/man0p/poll.h.0p create mode 100644 man-pages-posix-2013/man0p/pthread.h.0p create mode 100644 man-pages-posix-2013/man0p/pwd.h.0p create mode 100644 man-pages-posix-2013/man0p/regex.h.0p create mode 100644 man-pages-posix-2013/man0p/sched.h.0p create mode 100644 man-pages-posix-2013/man0p/search.h.0p create mode 100644 man-pages-posix-2013/man0p/semaphore.h.0p create mode 100644 man-pages-posix-2013/man0p/setjmp.h.0p create mode 100644 man-pages-posix-2013/man0p/signal.h.0p create mode 100644 man-pages-posix-2013/man0p/spawn.h.0p create mode 100644 man-pages-posix-2013/man0p/stdarg.h.0p create mode 100644 man-pages-posix-2013/man0p/stdbool.h.0p create mode 100644 man-pages-posix-2013/man0p/stddef.h.0p create mode 100644 man-pages-posix-2013/man0p/stdint.h.0p create mode 100644 man-pages-posix-2013/man0p/stdio.h.0p create mode 100644 man-pages-posix-2013/man0p/stdlib.h.0p create mode 100644 man-pages-posix-2013/man0p/string.h.0p create mode 100644 man-pages-posix-2013/man0p/strings.h.0p create mode 100644 man-pages-posix-2013/man0p/stropts.h.0p create mode 100644 man-pages-posix-2013/man0p/sys_ipc.h.0p create mode 100644 man-pages-posix-2013/man0p/sys_mman.h.0p create mode 100644 man-pages-posix-2013/man0p/sys_msg.h.0p create mode 100644 man-pages-posix-2013/man0p/sys_resource.h.0p create mode 100644 man-pages-posix-2013/man0p/sys_select.h.0p create mode 100644 man-pages-posix-2013/man0p/sys_sem.h.0p create mode 100644 man-pages-posix-2013/man0p/sys_shm.h.0p create mode 100644 man-pages-posix-2013/man0p/sys_socket.h.0p create mode 100644 man-pages-posix-2013/man0p/sys_stat.h.0p create mode 100644 man-pages-posix-2013/man0p/sys_statvfs.h.0p create mode 100644 man-pages-posix-2013/man0p/sys_time.h.0p create mode 100644 man-pages-posix-2013/man0p/sys_times.h.0p create mode 100644 man-pages-posix-2013/man0p/sys_types.h.0p create mode 100644 man-pages-posix-2013/man0p/sys_uio.h.0p create mode 100644 man-pages-posix-2013/man0p/sys_un.h.0p create mode 100644 man-pages-posix-2013/man0p/sys_utsname.h.0p create mode 100644 man-pages-posix-2013/man0p/sys_wait.h.0p create mode 100644 man-pages-posix-2013/man0p/syslog.h.0p create mode 100644 man-pages-posix-2013/man0p/tar.h.0p create mode 100644 man-pages-posix-2013/man0p/termios.h.0p create mode 100644 man-pages-posix-2013/man0p/tgmath.h.0p create mode 100644 man-pages-posix-2013/man0p/time.h.0p create mode 100644 man-pages-posix-2013/man0p/trace.h.0p create mode 100644 man-pages-posix-2013/man0p/ulimit.h.0p create mode 100644 man-pages-posix-2013/man0p/unistd.h.0p create mode 100644 man-pages-posix-2013/man0p/utime.h.0p create mode 100644 man-pages-posix-2013/man0p/utmpx.h.0p create mode 100644 man-pages-posix-2013/man0p/wchar.h.0p create mode 100644 man-pages-posix-2013/man0p/wctype.h.0p create mode 100644 man-pages-posix-2013/man0p/wordexp.h.0p create mode 100644 man-pages-posix-2013/man1p/admin.1p create mode 100644 man-pages-posix-2013/man1p/alias.1p create mode 100644 man-pages-posix-2013/man1p/ar.1p create mode 100644 man-pages-posix-2013/man1p/asa.1p create mode 100644 man-pages-posix-2013/man1p/at.1p create mode 100644 man-pages-posix-2013/man1p/awk.1p create mode 100644 man-pages-posix-2013/man1p/basename.1p create mode 100644 man-pages-posix-2013/man1p/batch.1p create mode 100644 man-pages-posix-2013/man1p/bc.1p create mode 100644 man-pages-posix-2013/man1p/bg.1p create mode 100644 man-pages-posix-2013/man1p/break.1p create mode 100644 man-pages-posix-2013/man1p/c99.1p create mode 100644 man-pages-posix-2013/man1p/cal.1p create mode 100644 man-pages-posix-2013/man1p/cat.1p create mode 100644 man-pages-posix-2013/man1p/cd.1p create mode 100644 man-pages-posix-2013/man1p/cflow.1p create mode 100644 man-pages-posix-2013/man1p/chgrp.1p create mode 100644 man-pages-posix-2013/man1p/chmod.1p create mode 100644 man-pages-posix-2013/man1p/chown.1p create mode 100644 man-pages-posix-2013/man1p/cksum.1p create mode 100644 man-pages-posix-2013/man1p/cmp.1p create mode 100644 man-pages-posix-2013/man1p/colon.1p create mode 100644 man-pages-posix-2013/man1p/comm.1p create mode 100644 man-pages-posix-2013/man1p/command.1p create mode 100644 man-pages-posix-2013/man1p/compress.1p create mode 100644 man-pages-posix-2013/man1p/continue.1p create mode 100644 man-pages-posix-2013/man1p/cp.1p create mode 100644 man-pages-posix-2013/man1p/crontab.1p create mode 100644 man-pages-posix-2013/man1p/csplit.1p create mode 100644 man-pages-posix-2013/man1p/ctags.1p create mode 100644 man-pages-posix-2013/man1p/cut.1p create mode 100644 man-pages-posix-2013/man1p/cxref.1p create mode 100644 man-pages-posix-2013/man1p/date.1p create mode 100644 man-pages-posix-2013/man1p/dd.1p create mode 100644 man-pages-posix-2013/man1p/delta.1p create mode 100644 man-pages-posix-2013/man1p/df.1p create mode 100644 man-pages-posix-2013/man1p/diff.1p create mode 100644 man-pages-posix-2013/man1p/dirname.1p create mode 100644 man-pages-posix-2013/man1p/dot.1p create mode 100644 man-pages-posix-2013/man1p/du.1p create mode 100644 man-pages-posix-2013/man1p/echo.1p create mode 100644 man-pages-posix-2013/man1p/ed.1p create mode 100644 man-pages-posix-2013/man1p/env.1p create mode 100644 man-pages-posix-2013/man1p/eval.1p create mode 100644 man-pages-posix-2013/man1p/ex.1p create mode 100644 man-pages-posix-2013/man1p/exec.1p create mode 100644 man-pages-posix-2013/man1p/exit.1p create mode 100644 man-pages-posix-2013/man1p/expand.1p create mode 100644 man-pages-posix-2013/man1p/export.1p create mode 100644 man-pages-posix-2013/man1p/expr.1p create mode 100644 man-pages-posix-2013/man1p/false.1p create mode 100644 man-pages-posix-2013/man1p/fc.1p create mode 100644 man-pages-posix-2013/man1p/fg.1p create mode 100644 man-pages-posix-2013/man1p/file.1p create mode 100644 man-pages-posix-2013/man1p/find.1p create mode 100644 man-pages-posix-2013/man1p/fold.1p create mode 100644 man-pages-posix-2013/man1p/fort77.1p create mode 100644 man-pages-posix-2013/man1p/fuser.1p create mode 100644 man-pages-posix-2013/man1p/gencat.1p create mode 100644 man-pages-posix-2013/man1p/get.1p create mode 100644 man-pages-posix-2013/man1p/getconf.1p create mode 100644 man-pages-posix-2013/man1p/getopts.1p create mode 100644 man-pages-posix-2013/man1p/grep.1p create mode 100644 man-pages-posix-2013/man1p/hash.1p create mode 100644 man-pages-posix-2013/man1p/head.1p create mode 100644 man-pages-posix-2013/man1p/iconv.1p create mode 100644 man-pages-posix-2013/man1p/id.1p create mode 100644 man-pages-posix-2013/man1p/ipcrm.1p create mode 100644 man-pages-posix-2013/man1p/ipcs.1p create mode 100644 man-pages-posix-2013/man1p/jobs.1p create mode 100644 man-pages-posix-2013/man1p/join.1p create mode 100644 man-pages-posix-2013/man1p/kill.1p create mode 100644 man-pages-posix-2013/man1p/lex.1p create mode 100644 man-pages-posix-2013/man1p/link.1p create mode 100644 man-pages-posix-2013/man1p/ln.1p create mode 100644 man-pages-posix-2013/man1p/locale.1p create mode 100644 man-pages-posix-2013/man1p/localedef.1p create mode 100644 man-pages-posix-2013/man1p/logger.1p create mode 100644 man-pages-posix-2013/man1p/logname.1p create mode 100644 man-pages-posix-2013/man1p/lp.1p create mode 100644 man-pages-posix-2013/man1p/ls.1p create mode 100644 man-pages-posix-2013/man1p/m4.1p create mode 100644 man-pages-posix-2013/man1p/mailx.1p create mode 100644 man-pages-posix-2013/man1p/make.1p create mode 100644 man-pages-posix-2013/man1p/man.1p create mode 100644 man-pages-posix-2013/man1p/mesg.1p create mode 100644 man-pages-posix-2013/man1p/mkdir.1p create mode 100644 man-pages-posix-2013/man1p/mkfifo.1p create mode 100644 man-pages-posix-2013/man1p/more.1p create mode 100644 man-pages-posix-2013/man1p/mv.1p create mode 100644 man-pages-posix-2013/man1p/newgrp.1p create mode 100644 man-pages-posix-2013/man1p/nice.1p create mode 100644 man-pages-posix-2013/man1p/nl.1p create mode 100644 man-pages-posix-2013/man1p/nm.1p create mode 100644 man-pages-posix-2013/man1p/nohup.1p create mode 100644 man-pages-posix-2013/man1p/od.1p create mode 100644 man-pages-posix-2013/man1p/paste.1p create mode 100644 man-pages-posix-2013/man1p/patch.1p create mode 100644 man-pages-posix-2013/man1p/pathchk.1p create mode 100644 man-pages-posix-2013/man1p/pax.1p create mode 100644 man-pages-posix-2013/man1p/pr.1p create mode 100644 man-pages-posix-2013/man1p/printf.1p create mode 100644 man-pages-posix-2013/man1p/prs.1p create mode 100644 man-pages-posix-2013/man1p/ps.1p create mode 100644 man-pages-posix-2013/man1p/pwd.1p create mode 100644 man-pages-posix-2013/man1p/qalter.1p create mode 100644 man-pages-posix-2013/man1p/qdel.1p create mode 100644 man-pages-posix-2013/man1p/qhold.1p create mode 100644 man-pages-posix-2013/man1p/qmove.1p create mode 100644 man-pages-posix-2013/man1p/qmsg.1p create mode 100644 man-pages-posix-2013/man1p/qrerun.1p create mode 100644 man-pages-posix-2013/man1p/qrls.1p create mode 100644 man-pages-posix-2013/man1p/qselect.1p create mode 100644 man-pages-posix-2013/man1p/qsig.1p create mode 100644 man-pages-posix-2013/man1p/qstat.1p create mode 100644 man-pages-posix-2013/man1p/qsub.1p create mode 100644 man-pages-posix-2013/man1p/read.1p create mode 100644 man-pages-posix-2013/man1p/readonly.1p create mode 100644 man-pages-posix-2013/man1p/renice.1p create mode 100644 man-pages-posix-2013/man1p/return.1p create mode 100644 man-pages-posix-2013/man1p/rm.1p create mode 100644 man-pages-posix-2013/man1p/rmdel.1p create mode 100644 man-pages-posix-2013/man1p/rmdir.1p create mode 100644 man-pages-posix-2013/man1p/sact.1p create mode 100644 man-pages-posix-2013/man1p/sccs.1p create mode 100644 man-pages-posix-2013/man1p/sed.1p create mode 100644 man-pages-posix-2013/man1p/set.1p create mode 100644 man-pages-posix-2013/man1p/sh.1p create mode 100644 man-pages-posix-2013/man1p/shift.1p create mode 100644 man-pages-posix-2013/man1p/sleep.1p create mode 100644 man-pages-posix-2013/man1p/sort.1p create mode 100644 man-pages-posix-2013/man1p/split.1p create mode 100644 man-pages-posix-2013/man1p/strings.1p create mode 100644 man-pages-posix-2013/man1p/strip.1p create mode 100644 man-pages-posix-2013/man1p/stty.1p create mode 100644 man-pages-posix-2013/man1p/tabs.1p create mode 100644 man-pages-posix-2013/man1p/tail.1p create mode 100644 man-pages-posix-2013/man1p/talk.1p create mode 100644 man-pages-posix-2013/man1p/tee.1p create mode 100644 man-pages-posix-2013/man1p/test.1p create mode 100644 man-pages-posix-2013/man1p/time.1p create mode 100644 man-pages-posix-2013/man1p/times.1p create mode 100644 man-pages-posix-2013/man1p/touch.1p create mode 100644 man-pages-posix-2013/man1p/tput.1p create mode 100644 man-pages-posix-2013/man1p/tr.1p create mode 100644 man-pages-posix-2013/man1p/trap.1p create mode 100644 man-pages-posix-2013/man1p/true.1p create mode 100644 man-pages-posix-2013/man1p/tsort.1p create mode 100644 man-pages-posix-2013/man1p/tty.1p create mode 100644 man-pages-posix-2013/man1p/type.1p create mode 100644 man-pages-posix-2013/man1p/ulimit.1p create mode 100644 man-pages-posix-2013/man1p/umask.1p create mode 100644 man-pages-posix-2013/man1p/unalias.1p create mode 100644 man-pages-posix-2013/man1p/uname.1p create mode 100644 man-pages-posix-2013/man1p/uncompress.1p create mode 100644 man-pages-posix-2013/man1p/unexpand.1p create mode 100644 man-pages-posix-2013/man1p/unget.1p create mode 100644 man-pages-posix-2013/man1p/uniq.1p create mode 100644 man-pages-posix-2013/man1p/unlink.1p create mode 100644 man-pages-posix-2013/man1p/unset.1p create mode 100644 man-pages-posix-2013/man1p/uucp.1p create mode 100644 man-pages-posix-2013/man1p/uudecode.1p create mode 100644 man-pages-posix-2013/man1p/uuencode.1p create mode 100644 man-pages-posix-2013/man1p/uustat.1p create mode 100644 man-pages-posix-2013/man1p/uux.1p create mode 100644 man-pages-posix-2013/man1p/val.1p create mode 100644 man-pages-posix-2013/man1p/vi.1p create mode 100644 man-pages-posix-2013/man1p/wait.1p create mode 100644 man-pages-posix-2013/man1p/wc.1p create mode 100644 man-pages-posix-2013/man1p/what.1p create mode 100644 man-pages-posix-2013/man1p/who.1p create mode 100644 man-pages-posix-2013/man1p/write.1p create mode 100644 man-pages-posix-2013/man1p/xargs.1p create mode 100644 man-pages-posix-2013/man1p/yacc.1p create mode 100644 man-pages-posix-2013/man1p/zcat.1p create mode 100644 man-pages-posix-2013/man3p/FD_CLR.3p create mode 100644 man-pages-posix-2013/man3p/_Exit.3p create mode 100644 man-pages-posix-2013/man3p/_longjmp.3p create mode 100644 man-pages-posix-2013/man3p/_tolower.3p create mode 100644 man-pages-posix-2013/man3p/_toupper.3p create mode 100644 man-pages-posix-2013/man3p/a64l.3p create mode 100644 man-pages-posix-2013/man3p/abort.3p create mode 100644 man-pages-posix-2013/man3p/abs.3p create mode 100644 man-pages-posix-2013/man3p/accept.3p create mode 100644 man-pages-posix-2013/man3p/access.3p create mode 100644 man-pages-posix-2013/man3p/acos.3p create mode 100644 man-pages-posix-2013/man3p/acosh.3p create mode 100644 man-pages-posix-2013/man3p/acosl.3p create mode 100644 man-pages-posix-2013/man3p/aio_cancel.3p create mode 100644 man-pages-posix-2013/man3p/aio_error.3p create mode 100644 man-pages-posix-2013/man3p/aio_fsync.3p create mode 100644 man-pages-posix-2013/man3p/aio_read.3p create mode 100644 man-pages-posix-2013/man3p/aio_return.3p create mode 100644 man-pages-posix-2013/man3p/aio_suspend.3p create mode 100644 man-pages-posix-2013/man3p/aio_write.3p create mode 100644 man-pages-posix-2013/man3p/alarm.3p create mode 100644 man-pages-posix-2013/man3p/alphasort.3p create mode 100644 man-pages-posix-2013/man3p/asctime.3p create mode 100644 man-pages-posix-2013/man3p/asin.3p create mode 100644 man-pages-posix-2013/man3p/asinh.3p create mode 100644 man-pages-posix-2013/man3p/asinl.3p create mode 100644 man-pages-posix-2013/man3p/assert.3p create mode 100644 man-pages-posix-2013/man3p/atan.3p create mode 100644 man-pages-posix-2013/man3p/atan2.3p create mode 100644 man-pages-posix-2013/man3p/atanf.3p create mode 100644 man-pages-posix-2013/man3p/atanh.3p create mode 100644 man-pages-posix-2013/man3p/atanl.3p create mode 100644 man-pages-posix-2013/man3p/atexit.3p create mode 100644 man-pages-posix-2013/man3p/atof.3p create mode 100644 man-pages-posix-2013/man3p/atoi.3p create mode 100644 man-pages-posix-2013/man3p/atol.3p create mode 100644 man-pages-posix-2013/man3p/basename.3p create mode 100644 man-pages-posix-2013/man3p/bind.3p create mode 100644 man-pages-posix-2013/man3p/bsearch.3p create mode 100644 man-pages-posix-2013/man3p/btowc.3p create mode 100644 man-pages-posix-2013/man3p/cabs.3p create mode 100644 man-pages-posix-2013/man3p/cacos.3p create mode 100644 man-pages-posix-2013/man3p/cacosh.3p create mode 100644 man-pages-posix-2013/man3p/cacosl.3p create mode 100644 man-pages-posix-2013/man3p/calloc.3p create mode 100644 man-pages-posix-2013/man3p/carg.3p create mode 100644 man-pages-posix-2013/man3p/casin.3p create mode 100644 man-pages-posix-2013/man3p/casinh.3p create mode 100644 man-pages-posix-2013/man3p/casinl.3p create mode 100644 man-pages-posix-2013/man3p/catan.3p create mode 100644 man-pages-posix-2013/man3p/catanh.3p create mode 100644 man-pages-posix-2013/man3p/catanl.3p create mode 100644 man-pages-posix-2013/man3p/catclose.3p create mode 100644 man-pages-posix-2013/man3p/catgets.3p create mode 100644 man-pages-posix-2013/man3p/catopen.3p create mode 100644 man-pages-posix-2013/man3p/cbrt.3p create mode 100644 man-pages-posix-2013/man3p/ccos.3p create mode 100644 man-pages-posix-2013/man3p/ccosh.3p create mode 100644 man-pages-posix-2013/man3p/ccosl.3p create mode 100644 man-pages-posix-2013/man3p/ceil.3p create mode 100644 man-pages-posix-2013/man3p/cexp.3p create mode 100644 man-pages-posix-2013/man3p/cfgetispeed.3p create mode 100644 man-pages-posix-2013/man3p/cfgetospeed.3p create mode 100644 man-pages-posix-2013/man3p/cfsetispeed.3p create mode 100644 man-pages-posix-2013/man3p/cfsetospeed.3p create mode 100644 man-pages-posix-2013/man3p/chdir.3p create mode 100644 man-pages-posix-2013/man3p/chmod.3p create mode 100644 man-pages-posix-2013/man3p/chown.3p create mode 100644 man-pages-posix-2013/man3p/cimag.3p create mode 100644 man-pages-posix-2013/man3p/clearerr.3p create mode 100644 man-pages-posix-2013/man3p/clock.3p create mode 100644 man-pages-posix-2013/man3p/clock_getcpuclockid.3p create mode 100644 man-pages-posix-2013/man3p/clock_getres.3p create mode 100644 man-pages-posix-2013/man3p/clock_nanosleep.3p create mode 100644 man-pages-posix-2013/man3p/clock_settime.3p create mode 100644 man-pages-posix-2013/man3p/clog.3p create mode 100644 man-pages-posix-2013/man3p/close.3p create mode 100644 man-pages-posix-2013/man3p/closedir.3p create mode 100644 man-pages-posix-2013/man3p/closelog.3p create mode 100644 man-pages-posix-2013/man3p/confstr.3p create mode 100644 man-pages-posix-2013/man3p/conj.3p create mode 100644 man-pages-posix-2013/man3p/connect.3p create mode 100644 man-pages-posix-2013/man3p/copysign.3p create mode 100644 man-pages-posix-2013/man3p/cos.3p create mode 100644 man-pages-posix-2013/man3p/cosh.3p create mode 100644 man-pages-posix-2013/man3p/cosl.3p create mode 100644 man-pages-posix-2013/man3p/cpow.3p create mode 100644 man-pages-posix-2013/man3p/cproj.3p create mode 100644 man-pages-posix-2013/man3p/creal.3p create mode 100644 man-pages-posix-2013/man3p/creat.3p create mode 100644 man-pages-posix-2013/man3p/crypt.3p create mode 100644 man-pages-posix-2013/man3p/csin.3p create mode 100644 man-pages-posix-2013/man3p/csinh.3p create mode 100644 man-pages-posix-2013/man3p/csinl.3p create mode 100644 man-pages-posix-2013/man3p/csqrt.3p create mode 100644 man-pages-posix-2013/man3p/ctan.3p create mode 100644 man-pages-posix-2013/man3p/ctanh.3p create mode 100644 man-pages-posix-2013/man3p/ctanl.3p create mode 100644 man-pages-posix-2013/man3p/ctermid.3p create mode 100644 man-pages-posix-2013/man3p/ctime.3p create mode 100644 man-pages-posix-2013/man3p/daylight.3p create mode 100644 man-pages-posix-2013/man3p/dbm_clearerr.3p create mode 100644 man-pages-posix-2013/man3p/difftime.3p create mode 100644 man-pages-posix-2013/man3p/dirfd.3p create mode 100644 man-pages-posix-2013/man3p/dirname.3p create mode 100644 man-pages-posix-2013/man3p/div.3p create mode 100644 man-pages-posix-2013/man3p/dlclose.3p create mode 100644 man-pages-posix-2013/man3p/dlerror.3p create mode 100644 man-pages-posix-2013/man3p/dlopen.3p create mode 100644 man-pages-posix-2013/man3p/dlsym.3p create mode 100644 man-pages-posix-2013/man3p/dprintf.3p create mode 100644 man-pages-posix-2013/man3p/drand48.3p create mode 100644 man-pages-posix-2013/man3p/dup.3p create mode 100644 man-pages-posix-2013/man3p/duplocale.3p create mode 100644 man-pages-posix-2013/man3p/encrypt.3p create mode 100644 man-pages-posix-2013/man3p/endgrent.3p create mode 100644 man-pages-posix-2013/man3p/endhostent.3p create mode 100644 man-pages-posix-2013/man3p/endnetent.3p create mode 100644 man-pages-posix-2013/man3p/endprotoent.3p create mode 100644 man-pages-posix-2013/man3p/endpwent.3p create mode 100644 man-pages-posix-2013/man3p/endservent.3p create mode 100644 man-pages-posix-2013/man3p/endutxent.3p create mode 100644 man-pages-posix-2013/man3p/environ.3p create mode 100644 man-pages-posix-2013/man3p/erand48.3p create mode 100644 man-pages-posix-2013/man3p/erf.3p create mode 100644 man-pages-posix-2013/man3p/erfc.3p create mode 100644 man-pages-posix-2013/man3p/erff.3p create mode 100644 man-pages-posix-2013/man3p/errno.3p create mode 100644 man-pages-posix-2013/man3p/exec.3p create mode 100644 man-pages-posix-2013/man3p/exit.3p create mode 100644 man-pages-posix-2013/man3p/exp.3p create mode 100644 man-pages-posix-2013/man3p/exp2.3p create mode 100644 man-pages-posix-2013/man3p/expm1.3p create mode 100644 man-pages-posix-2013/man3p/fabs.3p create mode 100644 man-pages-posix-2013/man3p/faccessat.3p create mode 100644 man-pages-posix-2013/man3p/fattach.3p create mode 100644 man-pages-posix-2013/man3p/fchdir.3p create mode 100644 man-pages-posix-2013/man3p/fchmod.3p create mode 100644 man-pages-posix-2013/man3p/fchmodat.3p create mode 100644 man-pages-posix-2013/man3p/fchown.3p create mode 100644 man-pages-posix-2013/man3p/fchownat.3p create mode 100644 man-pages-posix-2013/man3p/fclose.3p create mode 100644 man-pages-posix-2013/man3p/fcntl.3p create mode 100644 man-pages-posix-2013/man3p/fdatasync.3p create mode 100644 man-pages-posix-2013/man3p/fdetach.3p create mode 100644 man-pages-posix-2013/man3p/fdim.3p create mode 100644 man-pages-posix-2013/man3p/fdopen.3p create mode 100644 man-pages-posix-2013/man3p/fdopendir.3p create mode 100644 man-pages-posix-2013/man3p/feclearexcept.3p create mode 100644 man-pages-posix-2013/man3p/fegetenv.3p create mode 100644 man-pages-posix-2013/man3p/fegetexceptflag.3p create mode 100644 man-pages-posix-2013/man3p/fegetround.3p create mode 100644 man-pages-posix-2013/man3p/feholdexcept.3p create mode 100644 man-pages-posix-2013/man3p/feof.3p create mode 100644 man-pages-posix-2013/man3p/feraiseexcept.3p create mode 100644 man-pages-posix-2013/man3p/ferror.3p create mode 100644 man-pages-posix-2013/man3p/fesetenv.3p create mode 100644 man-pages-posix-2013/man3p/fesetexceptflag.3p create mode 100644 man-pages-posix-2013/man3p/fesetround.3p create mode 100644 man-pages-posix-2013/man3p/fetestexcept.3p create mode 100644 man-pages-posix-2013/man3p/feupdateenv.3p create mode 100644 man-pages-posix-2013/man3p/fexecve.3p create mode 100644 man-pages-posix-2013/man3p/fflush.3p create mode 100644 man-pages-posix-2013/man3p/ffs.3p create mode 100644 man-pages-posix-2013/man3p/fgetc.3p create mode 100644 man-pages-posix-2013/man3p/fgetpos.3p create mode 100644 man-pages-posix-2013/man3p/fgets.3p create mode 100644 man-pages-posix-2013/man3p/fgetwc.3p create mode 100644 man-pages-posix-2013/man3p/fgetws.3p create mode 100644 man-pages-posix-2013/man3p/fileno.3p create mode 100644 man-pages-posix-2013/man3p/flockfile.3p create mode 100644 man-pages-posix-2013/man3p/floor.3p create mode 100644 man-pages-posix-2013/man3p/fma.3p create mode 100644 man-pages-posix-2013/man3p/fmax.3p create mode 100644 man-pages-posix-2013/man3p/fmemopen.3p create mode 100644 man-pages-posix-2013/man3p/fmin.3p create mode 100644 man-pages-posix-2013/man3p/fmod.3p create mode 100644 man-pages-posix-2013/man3p/fmtmsg.3p create mode 100644 man-pages-posix-2013/man3p/fnmatch.3p create mode 100644 man-pages-posix-2013/man3p/fopen.3p create mode 100644 man-pages-posix-2013/man3p/fork.3p create mode 100644 man-pages-posix-2013/man3p/fpathconf.3p create mode 100644 man-pages-posix-2013/man3p/fpclassify.3p create mode 100644 man-pages-posix-2013/man3p/fprintf.3p create mode 100644 man-pages-posix-2013/man3p/fputc.3p create mode 100644 man-pages-posix-2013/man3p/fputs.3p create mode 100644 man-pages-posix-2013/man3p/fputwc.3p create mode 100644 man-pages-posix-2013/man3p/fputws.3p create mode 100644 man-pages-posix-2013/man3p/fread.3p create mode 100644 man-pages-posix-2013/man3p/free.3p create mode 100644 man-pages-posix-2013/man3p/freeaddrinfo.3p create mode 100644 man-pages-posix-2013/man3p/freelocale.3p create mode 100644 man-pages-posix-2013/man3p/freopen.3p create mode 100644 man-pages-posix-2013/man3p/frexp.3p create mode 100644 man-pages-posix-2013/man3p/fscanf.3p create mode 100644 man-pages-posix-2013/man3p/fseek.3p create mode 100644 man-pages-posix-2013/man3p/fsetpos.3p create mode 100644 man-pages-posix-2013/man3p/fstat.3p create mode 100644 man-pages-posix-2013/man3p/fstatat.3p create mode 100644 man-pages-posix-2013/man3p/fstatvfs.3p create mode 100644 man-pages-posix-2013/man3p/fsync.3p create mode 100644 man-pages-posix-2013/man3p/ftell.3p create mode 100644 man-pages-posix-2013/man3p/ftok.3p create mode 100644 man-pages-posix-2013/man3p/ftruncate.3p create mode 100644 man-pages-posix-2013/man3p/ftrylockfile.3p create mode 100644 man-pages-posix-2013/man3p/ftw.3p create mode 100644 man-pages-posix-2013/man3p/funlockfile.3p create mode 100644 man-pages-posix-2013/man3p/futimens.3p create mode 100644 man-pages-posix-2013/man3p/fwide.3p create mode 100644 man-pages-posix-2013/man3p/fwprintf.3p create mode 100644 man-pages-posix-2013/man3p/fwrite.3p create mode 100644 man-pages-posix-2013/man3p/fwscanf.3p create mode 100644 man-pages-posix-2013/man3p/gai_strerror.3p create mode 100644 man-pages-posix-2013/man3p/getaddrinfo.3p create mode 100644 man-pages-posix-2013/man3p/getc.3p create mode 100644 man-pages-posix-2013/man3p/getc_unlocked.3p create mode 100644 man-pages-posix-2013/man3p/getchar.3p create mode 100644 man-pages-posix-2013/man3p/getchar_unlocked.3p create mode 100644 man-pages-posix-2013/man3p/getcwd.3p create mode 100644 man-pages-posix-2013/man3p/getdate.3p create mode 100644 man-pages-posix-2013/man3p/getdelim.3p create mode 100644 man-pages-posix-2013/man3p/getegid.3p create mode 100644 man-pages-posix-2013/man3p/getenv.3p create mode 100644 man-pages-posix-2013/man3p/geteuid.3p create mode 100644 man-pages-posix-2013/man3p/getgid.3p create mode 100644 man-pages-posix-2013/man3p/getgrent.3p create mode 100644 man-pages-posix-2013/man3p/getgrgid.3p create mode 100644 man-pages-posix-2013/man3p/getgrnam.3p create mode 100644 man-pages-posix-2013/man3p/getgroups.3p create mode 100644 man-pages-posix-2013/man3p/gethostent.3p create mode 100644 man-pages-posix-2013/man3p/gethostid.3p create mode 100644 man-pages-posix-2013/man3p/gethostname.3p create mode 100644 man-pages-posix-2013/man3p/getitimer.3p create mode 100644 man-pages-posix-2013/man3p/getline.3p create mode 100644 man-pages-posix-2013/man3p/getlogin.3p create mode 100644 man-pages-posix-2013/man3p/getmsg.3p create mode 100644 man-pages-posix-2013/man3p/getnameinfo.3p create mode 100644 man-pages-posix-2013/man3p/getnetbyaddr.3p create mode 100644 man-pages-posix-2013/man3p/getopt.3p create mode 100644 man-pages-posix-2013/man3p/getpeername.3p create mode 100644 man-pages-posix-2013/man3p/getpgid.3p create mode 100644 man-pages-posix-2013/man3p/getpgrp.3p create mode 100644 man-pages-posix-2013/man3p/getpid.3p create mode 100644 man-pages-posix-2013/man3p/getpmsg.3p create mode 100644 man-pages-posix-2013/man3p/getppid.3p create mode 100644 man-pages-posix-2013/man3p/getpriority.3p create mode 100644 man-pages-posix-2013/man3p/getprotobyname.3p create mode 100644 man-pages-posix-2013/man3p/getpwent.3p create mode 100644 man-pages-posix-2013/man3p/getpwnam.3p create mode 100644 man-pages-posix-2013/man3p/getpwuid.3p create mode 100644 man-pages-posix-2013/man3p/getrlimit.3p create mode 100644 man-pages-posix-2013/man3p/getrusage.3p create mode 100644 man-pages-posix-2013/man3p/gets.3p create mode 100644 man-pages-posix-2013/man3p/getservbyname.3p create mode 100644 man-pages-posix-2013/man3p/getsid.3p create mode 100644 man-pages-posix-2013/man3p/getsockname.3p create mode 100644 man-pages-posix-2013/man3p/getsockopt.3p create mode 100644 man-pages-posix-2013/man3p/getsubopt.3p create mode 100644 man-pages-posix-2013/man3p/gettimeofday.3p create mode 100644 man-pages-posix-2013/man3p/getuid.3p create mode 100644 man-pages-posix-2013/man3p/getutxent.3p create mode 100644 man-pages-posix-2013/man3p/getwc.3p create mode 100644 man-pages-posix-2013/man3p/getwchar.3p create mode 100644 man-pages-posix-2013/man3p/glob.3p create mode 100644 man-pages-posix-2013/man3p/gmtime.3p create mode 100644 man-pages-posix-2013/man3p/grantpt.3p create mode 100644 man-pages-posix-2013/man3p/hcreate.3p create mode 100644 man-pages-posix-2013/man3p/htonl.3p create mode 100644 man-pages-posix-2013/man3p/hypot.3p create mode 100644 man-pages-posix-2013/man3p/iconv.3p create mode 100644 man-pages-posix-2013/man3p/iconv_close.3p create mode 100644 man-pages-posix-2013/man3p/iconv_open.3p create mode 100644 man-pages-posix-2013/man3p/if_freenameindex.3p create mode 100644 man-pages-posix-2013/man3p/if_indextoname.3p create mode 100644 man-pages-posix-2013/man3p/if_nameindex.3p create mode 100644 man-pages-posix-2013/man3p/if_nametoindex.3p create mode 100644 man-pages-posix-2013/man3p/ilogb.3p create mode 100644 man-pages-posix-2013/man3p/imaxabs.3p create mode 100644 man-pages-posix-2013/man3p/imaxdiv.3p create mode 100644 man-pages-posix-2013/man3p/inet_addr.3p create mode 100644 man-pages-posix-2013/man3p/inet_ntop.3p create mode 100644 man-pages-posix-2013/man3p/initstate.3p create mode 100644 man-pages-posix-2013/man3p/insque.3p create mode 100644 man-pages-posix-2013/man3p/ioctl.3p create mode 100644 man-pages-posix-2013/man3p/isalnum.3p create mode 100644 man-pages-posix-2013/man3p/isalpha.3p create mode 100644 man-pages-posix-2013/man3p/isascii.3p create mode 100644 man-pages-posix-2013/man3p/isastream.3p create mode 100644 man-pages-posix-2013/man3p/isatty.3p create mode 100644 man-pages-posix-2013/man3p/isblank.3p create mode 100644 man-pages-posix-2013/man3p/iscntrl.3p create mode 100644 man-pages-posix-2013/man3p/isdigit.3p create mode 100644 man-pages-posix-2013/man3p/isfinite.3p create mode 100644 man-pages-posix-2013/man3p/isgraph.3p create mode 100644 man-pages-posix-2013/man3p/isgreater.3p create mode 100644 man-pages-posix-2013/man3p/isgreaterequal.3p create mode 100644 man-pages-posix-2013/man3p/isinf.3p create mode 100644 man-pages-posix-2013/man3p/isless.3p create mode 100644 man-pages-posix-2013/man3p/islessequal.3p create mode 100644 man-pages-posix-2013/man3p/islessgreater.3p create mode 100644 man-pages-posix-2013/man3p/islower.3p create mode 100644 man-pages-posix-2013/man3p/isnan.3p create mode 100644 man-pages-posix-2013/man3p/isnormal.3p create mode 100644 man-pages-posix-2013/man3p/isprint.3p create mode 100644 man-pages-posix-2013/man3p/ispunct.3p create mode 100644 man-pages-posix-2013/man3p/isspace.3p create mode 100644 man-pages-posix-2013/man3p/isunordered.3p create mode 100644 man-pages-posix-2013/man3p/isupper.3p create mode 100644 man-pages-posix-2013/man3p/iswalnum.3p create mode 100644 man-pages-posix-2013/man3p/iswalpha.3p create mode 100644 man-pages-posix-2013/man3p/iswblank.3p create mode 100644 man-pages-posix-2013/man3p/iswcntrl.3p create mode 100644 man-pages-posix-2013/man3p/iswctype.3p create mode 100644 man-pages-posix-2013/man3p/iswdigit.3p create mode 100644 man-pages-posix-2013/man3p/iswgraph.3p create mode 100644 man-pages-posix-2013/man3p/iswlower.3p create mode 100644 man-pages-posix-2013/man3p/iswprint.3p create mode 100644 man-pages-posix-2013/man3p/iswpunct.3p create mode 100644 man-pages-posix-2013/man3p/iswspace.3p create mode 100644 man-pages-posix-2013/man3p/iswupper.3p create mode 100644 man-pages-posix-2013/man3p/iswxdigit.3p create mode 100644 man-pages-posix-2013/man3p/isxdigit.3p create mode 100644 man-pages-posix-2013/man3p/j0.3p create mode 100644 man-pages-posix-2013/man3p/jrand48.3p create mode 100644 man-pages-posix-2013/man3p/kill.3p create mode 100644 man-pages-posix-2013/man3p/killpg.3p create mode 100644 man-pages-posix-2013/man3p/l64a.3p create mode 100644 man-pages-posix-2013/man3p/labs.3p create mode 100644 man-pages-posix-2013/man3p/lchown.3p create mode 100644 man-pages-posix-2013/man3p/lcong48.3p create mode 100644 man-pages-posix-2013/man3p/ldexp.3p create mode 100644 man-pages-posix-2013/man3p/ldiv.3p create mode 100644 man-pages-posix-2013/man3p/lfind.3p create mode 100644 man-pages-posix-2013/man3p/lgamma.3p create mode 100644 man-pages-posix-2013/man3p/link.3p create mode 100644 man-pages-posix-2013/man3p/lio_listio.3p create mode 100644 man-pages-posix-2013/man3p/listen.3p create mode 100644 man-pages-posix-2013/man3p/llabs.3p create mode 100644 man-pages-posix-2013/man3p/lldiv.3p create mode 100644 man-pages-posix-2013/man3p/llrint.3p create mode 100644 man-pages-posix-2013/man3p/llround.3p create mode 100644 man-pages-posix-2013/man3p/localeconv.3p create mode 100644 man-pages-posix-2013/man3p/localtime.3p create mode 100644 man-pages-posix-2013/man3p/lockf.3p create mode 100644 man-pages-posix-2013/man3p/log.3p create mode 100644 man-pages-posix-2013/man3p/log10.3p create mode 100644 man-pages-posix-2013/man3p/log1p.3p create mode 100644 man-pages-posix-2013/man3p/log2.3p create mode 100644 man-pages-posix-2013/man3p/logb.3p create mode 100644 man-pages-posix-2013/man3p/logf.3p create mode 100644 man-pages-posix-2013/man3p/longjmp.3p create mode 100644 man-pages-posix-2013/man3p/lrand48.3p create mode 100644 man-pages-posix-2013/man3p/lrint.3p create mode 100644 man-pages-posix-2013/man3p/lround.3p create mode 100644 man-pages-posix-2013/man3p/lsearch.3p create mode 100644 man-pages-posix-2013/man3p/lseek.3p create mode 100644 man-pages-posix-2013/man3p/lstat.3p create mode 100644 man-pages-posix-2013/man3p/malloc.3p create mode 100644 man-pages-posix-2013/man3p/mblen.3p create mode 100644 man-pages-posix-2013/man3p/mbrlen.3p create mode 100644 man-pages-posix-2013/man3p/mbrtowc.3p create mode 100644 man-pages-posix-2013/man3p/mbsinit.3p create mode 100644 man-pages-posix-2013/man3p/mbsrtowcs.3p create mode 100644 man-pages-posix-2013/man3p/mbstowcs.3p create mode 100644 man-pages-posix-2013/man3p/mbtowc.3p create mode 100644 man-pages-posix-2013/man3p/memccpy.3p create mode 100644 man-pages-posix-2013/man3p/memchr.3p create mode 100644 man-pages-posix-2013/man3p/memcmp.3p create mode 100644 man-pages-posix-2013/man3p/memcpy.3p create mode 100644 man-pages-posix-2013/man3p/memmove.3p create mode 100644 man-pages-posix-2013/man3p/memset.3p create mode 100644 man-pages-posix-2013/man3p/mkdir.3p create mode 100644 man-pages-posix-2013/man3p/mkdtemp.3p create mode 100644 man-pages-posix-2013/man3p/mkfifo.3p create mode 100644 man-pages-posix-2013/man3p/mknod.3p create mode 100644 man-pages-posix-2013/man3p/mkstemp.3p create mode 100644 man-pages-posix-2013/man3p/mktime.3p create mode 100644 man-pages-posix-2013/man3p/mlock.3p create mode 100644 man-pages-posix-2013/man3p/mlockall.3p create mode 100644 man-pages-posix-2013/man3p/mmap.3p create mode 100644 man-pages-posix-2013/man3p/modf.3p create mode 100644 man-pages-posix-2013/man3p/mprotect.3p create mode 100644 man-pages-posix-2013/man3p/mq_close.3p create mode 100644 man-pages-posix-2013/man3p/mq_getattr.3p create mode 100644 man-pages-posix-2013/man3p/mq_notify.3p create mode 100644 man-pages-posix-2013/man3p/mq_open.3p create mode 100644 man-pages-posix-2013/man3p/mq_receive.3p create mode 100644 man-pages-posix-2013/man3p/mq_send.3p create mode 100644 man-pages-posix-2013/man3p/mq_setattr.3p create mode 100644 man-pages-posix-2013/man3p/mq_timedreceive.3p create mode 100644 man-pages-posix-2013/man3p/mq_timedsend.3p create mode 100644 man-pages-posix-2013/man3p/mq_unlink.3p create mode 100644 man-pages-posix-2013/man3p/mrand48.3p create mode 100644 man-pages-posix-2013/man3p/msgctl.3p create mode 100644 man-pages-posix-2013/man3p/msgget.3p create mode 100644 man-pages-posix-2013/man3p/msgrcv.3p create mode 100644 man-pages-posix-2013/man3p/msgsnd.3p create mode 100644 man-pages-posix-2013/man3p/msync.3p create mode 100644 man-pages-posix-2013/man3p/munlock.3p create mode 100644 man-pages-posix-2013/man3p/munlockall.3p create mode 100644 man-pages-posix-2013/man3p/munmap.3p create mode 100644 man-pages-posix-2013/man3p/nan.3p create mode 100644 man-pages-posix-2013/man3p/nanosleep.3p create mode 100644 man-pages-posix-2013/man3p/nearbyint.3p create mode 100644 man-pages-posix-2013/man3p/newlocale.3p create mode 100644 man-pages-posix-2013/man3p/nextafter.3p create mode 100644 man-pages-posix-2013/man3p/nftw.3p create mode 100644 man-pages-posix-2013/man3p/nice.3p create mode 100644 man-pages-posix-2013/man3p/nl_langinfo.3p create mode 100644 man-pages-posix-2013/man3p/nrand48.3p create mode 100644 man-pages-posix-2013/man3p/ntohl.3p create mode 100644 man-pages-posix-2013/man3p/open.3p create mode 100644 man-pages-posix-2013/man3p/open_memstream.3p create mode 100644 man-pages-posix-2013/man3p/openat.3p create mode 100644 man-pages-posix-2013/man3p/opendir.3p create mode 100644 man-pages-posix-2013/man3p/openlog.3p create mode 100644 man-pages-posix-2013/man3p/optarg.3p create mode 100644 man-pages-posix-2013/man3p/pathconf.3p create mode 100644 man-pages-posix-2013/man3p/pause.3p create mode 100644 man-pages-posix-2013/man3p/pclose.3p create mode 100644 man-pages-posix-2013/man3p/perror.3p create mode 100644 man-pages-posix-2013/man3p/pipe.3p create mode 100644 man-pages-posix-2013/man3p/poll.3p create mode 100644 man-pages-posix-2013/man3p/popen.3p create mode 100644 man-pages-posix-2013/man3p/posix_fadvise.3p create mode 100644 man-pages-posix-2013/man3p/posix_fallocate.3p create mode 100644 man-pages-posix-2013/man3p/posix_madvise.3p create mode 100644 man-pages-posix-2013/man3p/posix_mem_offset.3p create mode 100644 man-pages-posix-2013/man3p/posix_memalign.3p create mode 100644 man-pages-posix-2013/man3p/posix_openpt.3p create mode 100644 man-pages-posix-2013/man3p/posix_spawn.3p create mode 100644 man-pages-posix-2013/man3p/posix_spawn_file_actions_addclose.3p create mode 100644 man-pages-posix-2013/man3p/posix_spawn_file_actions_adddup2.3p create mode 100644 man-pages-posix-2013/man3p/posix_spawn_file_actions_addopen.3p create mode 100644 man-pages-posix-2013/man3p/posix_spawn_file_actions_destroy.3p create mode 100644 man-pages-posix-2013/man3p/posix_spawnattr_destroy.3p create mode 100644 man-pages-posix-2013/man3p/posix_spawnattr_getflags.3p create mode 100644 man-pages-posix-2013/man3p/posix_spawnattr_getpgroup.3p create mode 100644 man-pages-posix-2013/man3p/posix_spawnattr_getschedparam.3p create mode 100644 man-pages-posix-2013/man3p/posix_spawnattr_getschedpolicy.3p create mode 100644 man-pages-posix-2013/man3p/posix_spawnattr_getsigdefault.3p create mode 100644 man-pages-posix-2013/man3p/posix_spawnattr_getsigmask.3p create mode 100644 man-pages-posix-2013/man3p/posix_spawnattr_init.3p create mode 100644 man-pages-posix-2013/man3p/posix_spawnattr_setflags.3p create mode 100644 man-pages-posix-2013/man3p/posix_spawnattr_setpgroup.3p create mode 100644 man-pages-posix-2013/man3p/posix_spawnattr_setschedparam.3p create mode 100644 man-pages-posix-2013/man3p/posix_spawnattr_setschedpolicy.3p create mode 100644 man-pages-posix-2013/man3p/posix_spawnattr_setsigdefault.3p create mode 100644 man-pages-posix-2013/man3p/posix_spawnattr_setsigmask.3p create mode 100644 man-pages-posix-2013/man3p/posix_spawnp.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_attr_destroy.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_attr_getclockres.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_attr_getinherited.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_attr_getlogsize.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_attr_getname.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_attr_getstreamfullpolicy.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_attr_getstreamsize.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_attr_init.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_attr_setinherited.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_attr_setlogsize.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_attr_setname.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_attr_setstreamfullpolicy.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_attr_setstreamsize.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_clear.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_close.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_create.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_event.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_eventid_equal.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_eventid_open.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_eventset_add.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_eventtypelist_getnext_id.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_flush.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_get_attr.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_get_filter.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_get_status.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_getnext_event.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_open.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_set_filter.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_shutdown.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_start.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_timedgetnext_event.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_trid_eventid_open.3p create mode 100644 man-pages-posix-2013/man3p/posix_trace_trygetnext_event.3p create mode 100644 man-pages-posix-2013/man3p/posix_typed_mem_get_info.3p create mode 100644 man-pages-posix-2013/man3p/posix_typed_mem_open.3p create mode 100644 man-pages-posix-2013/man3p/pow.3p create mode 100644 man-pages-posix-2013/man3p/pread.3p create mode 100644 man-pages-posix-2013/man3p/printf.3p create mode 100644 man-pages-posix-2013/man3p/pselect.3p create mode 100644 man-pages-posix-2013/man3p/psiginfo.3p create mode 100644 man-pages-posix-2013/man3p/pthread_atfork.3p create mode 100644 man-pages-posix-2013/man3p/pthread_attr_destroy.3p create mode 100644 man-pages-posix-2013/man3p/pthread_attr_getdetachstate.3p create mode 100644 man-pages-posix-2013/man3p/pthread_attr_getguardsize.3p create mode 100644 man-pages-posix-2013/man3p/pthread_attr_getinheritsched.3p create mode 100644 man-pages-posix-2013/man3p/pthread_attr_getschedparam.3p create mode 100644 man-pages-posix-2013/man3p/pthread_attr_getschedpolicy.3p create mode 100644 man-pages-posix-2013/man3p/pthread_attr_getscope.3p create mode 100644 man-pages-posix-2013/man3p/pthread_attr_getstack.3p create mode 100644 man-pages-posix-2013/man3p/pthread_attr_getstacksize.3p create mode 100644 man-pages-posix-2013/man3p/pthread_attr_init.3p create mode 100644 man-pages-posix-2013/man3p/pthread_attr_setdetachstate.3p create mode 100644 man-pages-posix-2013/man3p/pthread_attr_setguardsize.3p create mode 100644 man-pages-posix-2013/man3p/pthread_attr_setinheritsched.3p create mode 100644 man-pages-posix-2013/man3p/pthread_attr_setschedparam.3p create mode 100644 man-pages-posix-2013/man3p/pthread_attr_setschedpolicy.3p create mode 100644 man-pages-posix-2013/man3p/pthread_attr_setscope.3p create mode 100644 man-pages-posix-2013/man3p/pthread_attr_setstack.3p create mode 100644 man-pages-posix-2013/man3p/pthread_attr_setstacksize.3p create mode 100644 man-pages-posix-2013/man3p/pthread_barrier_destroy.3p create mode 100644 man-pages-posix-2013/man3p/pthread_barrier_wait.3p create mode 100644 man-pages-posix-2013/man3p/pthread_barrierattr_destroy.3p create mode 100644 man-pages-posix-2013/man3p/pthread_barrierattr_getpshared.3p create mode 100644 man-pages-posix-2013/man3p/pthread_barrierattr_init.3p create mode 100644 man-pages-posix-2013/man3p/pthread_barrierattr_setpshared.3p create mode 100644 man-pages-posix-2013/man3p/pthread_cancel.3p create mode 100644 man-pages-posix-2013/man3p/pthread_cleanup_pop.3p create mode 100644 man-pages-posix-2013/man3p/pthread_cond_broadcast.3p create mode 100644 man-pages-posix-2013/man3p/pthread_cond_destroy.3p create mode 100644 man-pages-posix-2013/man3p/pthread_cond_signal.3p create mode 100644 man-pages-posix-2013/man3p/pthread_cond_timedwait.3p create mode 100644 man-pages-posix-2013/man3p/pthread_condattr_destroy.3p create mode 100644 man-pages-posix-2013/man3p/pthread_condattr_getclock.3p create mode 100644 man-pages-posix-2013/man3p/pthread_condattr_getpshared.3p create mode 100644 man-pages-posix-2013/man3p/pthread_condattr_init.3p create mode 100644 man-pages-posix-2013/man3p/pthread_condattr_setclock.3p create mode 100644 man-pages-posix-2013/man3p/pthread_condattr_setpshared.3p create mode 100644 man-pages-posix-2013/man3p/pthread_create.3p create mode 100644 man-pages-posix-2013/man3p/pthread_detach.3p create mode 100644 man-pages-posix-2013/man3p/pthread_equal.3p create mode 100644 man-pages-posix-2013/man3p/pthread_exit.3p create mode 100644 man-pages-posix-2013/man3p/pthread_getconcurrency.3p create mode 100644 man-pages-posix-2013/man3p/pthread_getcpuclockid.3p create mode 100644 man-pages-posix-2013/man3p/pthread_getschedparam.3p create mode 100644 man-pages-posix-2013/man3p/pthread_getspecific.3p create mode 100644 man-pages-posix-2013/man3p/pthread_join.3p create mode 100644 man-pages-posix-2013/man3p/pthread_key_create.3p create mode 100644 man-pages-posix-2013/man3p/pthread_key_delete.3p create mode 100644 man-pages-posix-2013/man3p/pthread_kill.3p create mode 100644 man-pages-posix-2013/man3p/pthread_mutex_consistent.3p create mode 100644 man-pages-posix-2013/man3p/pthread_mutex_destroy.3p create mode 100644 man-pages-posix-2013/man3p/pthread_mutex_getprioceiling.3p create mode 100644 man-pages-posix-2013/man3p/pthread_mutex_init.3p create mode 100644 man-pages-posix-2013/man3p/pthread_mutex_lock.3p create mode 100644 man-pages-posix-2013/man3p/pthread_mutex_setprioceiling.3p create mode 100644 man-pages-posix-2013/man3p/pthread_mutex_timedlock.3p create mode 100644 man-pages-posix-2013/man3p/pthread_mutex_trylock.3p create mode 100644 man-pages-posix-2013/man3p/pthread_mutexattr_destroy.3p create mode 100644 man-pages-posix-2013/man3p/pthread_mutexattr_getprioceiling.3p create mode 100644 man-pages-posix-2013/man3p/pthread_mutexattr_getprotocol.3p create mode 100644 man-pages-posix-2013/man3p/pthread_mutexattr_getpshared.3p create mode 100644 man-pages-posix-2013/man3p/pthread_mutexattr_getrobust.3p create mode 100644 man-pages-posix-2013/man3p/pthread_mutexattr_gettype.3p create mode 100644 man-pages-posix-2013/man3p/pthread_mutexattr_init.3p create mode 100644 man-pages-posix-2013/man3p/pthread_mutexattr_setprioceiling.3p create mode 100644 man-pages-posix-2013/man3p/pthread_mutexattr_setprotocol.3p create mode 100644 man-pages-posix-2013/man3p/pthread_mutexattr_setpshared.3p create mode 100644 man-pages-posix-2013/man3p/pthread_mutexattr_setrobust.3p create mode 100644 man-pages-posix-2013/man3p/pthread_mutexattr_settype.3p create mode 100644 man-pages-posix-2013/man3p/pthread_once.3p create mode 100644 man-pages-posix-2013/man3p/pthread_rwlock_destroy.3p create mode 100644 man-pages-posix-2013/man3p/pthread_rwlock_rdlock.3p create mode 100644 man-pages-posix-2013/man3p/pthread_rwlock_timedrdlock.3p create mode 100644 man-pages-posix-2013/man3p/pthread_rwlock_timedwrlock.3p create mode 100644 man-pages-posix-2013/man3p/pthread_rwlock_tryrdlock.3p create mode 100644 man-pages-posix-2013/man3p/pthread_rwlock_trywrlock.3p create mode 100644 man-pages-posix-2013/man3p/pthread_rwlock_unlock.3p create mode 100644 man-pages-posix-2013/man3p/pthread_rwlock_wrlock.3p create mode 100644 man-pages-posix-2013/man3p/pthread_rwlockattr_destroy.3p create mode 100644 man-pages-posix-2013/man3p/pthread_rwlockattr_getpshared.3p create mode 100644 man-pages-posix-2013/man3p/pthread_rwlockattr_init.3p create mode 100644 man-pages-posix-2013/man3p/pthread_rwlockattr_setpshared.3p create mode 100644 man-pages-posix-2013/man3p/pthread_self.3p create mode 100644 man-pages-posix-2013/man3p/pthread_setcancelstate.3p create mode 100644 man-pages-posix-2013/man3p/pthread_setconcurrency.3p create mode 100644 man-pages-posix-2013/man3p/pthread_setschedparam.3p create mode 100644 man-pages-posix-2013/man3p/pthread_setschedprio.3p create mode 100644 man-pages-posix-2013/man3p/pthread_setspecific.3p create mode 100644 man-pages-posix-2013/man3p/pthread_sigmask.3p create mode 100644 man-pages-posix-2013/man3p/pthread_spin_destroy.3p create mode 100644 man-pages-posix-2013/man3p/pthread_spin_lock.3p create mode 100644 man-pages-posix-2013/man3p/pthread_spin_unlock.3p create mode 100644 man-pages-posix-2013/man3p/pthread_testcancel.3p create mode 100644 man-pages-posix-2013/man3p/ptsname.3p create mode 100644 man-pages-posix-2013/man3p/putc.3p create mode 100644 man-pages-posix-2013/man3p/putc_unlocked.3p create mode 100644 man-pages-posix-2013/man3p/putchar.3p create mode 100644 man-pages-posix-2013/man3p/putchar_unlocked.3p create mode 100644 man-pages-posix-2013/man3p/putenv.3p create mode 100644 man-pages-posix-2013/man3p/putmsg.3p create mode 100644 man-pages-posix-2013/man3p/puts.3p create mode 100644 man-pages-posix-2013/man3p/pututxline.3p create mode 100644 man-pages-posix-2013/man3p/putwc.3p create mode 100644 man-pages-posix-2013/man3p/putwchar.3p create mode 100644 man-pages-posix-2013/man3p/pwrite.3p create mode 100644 man-pages-posix-2013/man3p/qsort.3p create mode 100644 man-pages-posix-2013/man3p/raise.3p create mode 100644 man-pages-posix-2013/man3p/rand.3p create mode 100644 man-pages-posix-2013/man3p/random.3p create mode 100644 man-pages-posix-2013/man3p/read.3p create mode 100644 man-pages-posix-2013/man3p/readdir.3p create mode 100644 man-pages-posix-2013/man3p/readlink.3p create mode 100644 man-pages-posix-2013/man3p/readv.3p create mode 100644 man-pages-posix-2013/man3p/realloc.3p create mode 100644 man-pages-posix-2013/man3p/realpath.3p create mode 100644 man-pages-posix-2013/man3p/recv.3p create mode 100644 man-pages-posix-2013/man3p/recvfrom.3p create mode 100644 man-pages-posix-2013/man3p/recvmsg.3p create mode 100644 man-pages-posix-2013/man3p/regcomp.3p create mode 100644 man-pages-posix-2013/man3p/remainder.3p create mode 100644 man-pages-posix-2013/man3p/remove.3p create mode 100644 man-pages-posix-2013/man3p/remque.3p create mode 100644 man-pages-posix-2013/man3p/remquo.3p create mode 100644 man-pages-posix-2013/man3p/rename.3p create mode 100644 man-pages-posix-2013/man3p/rewind.3p create mode 100644 man-pages-posix-2013/man3p/rewinddir.3p create mode 100644 man-pages-posix-2013/man3p/rint.3p create mode 100644 man-pages-posix-2013/man3p/rmdir.3p create mode 100644 man-pages-posix-2013/man3p/round.3p create mode 100644 man-pages-posix-2013/man3p/scalbln.3p create mode 100644 man-pages-posix-2013/man3p/scandir.3p create mode 100644 man-pages-posix-2013/man3p/scanf.3p create mode 100644 man-pages-posix-2013/man3p/sched_get_priority_max.3p create mode 100644 man-pages-posix-2013/man3p/sched_getparam.3p create mode 100644 man-pages-posix-2013/man3p/sched_getscheduler.3p create mode 100644 man-pages-posix-2013/man3p/sched_rr_get_interval.3p create mode 100644 man-pages-posix-2013/man3p/sched_setparam.3p create mode 100644 man-pages-posix-2013/man3p/sched_setscheduler.3p create mode 100644 man-pages-posix-2013/man3p/sched_yield.3p create mode 100644 man-pages-posix-2013/man3p/seed48.3p create mode 100644 man-pages-posix-2013/man3p/seekdir.3p create mode 100644 man-pages-posix-2013/man3p/select.3p create mode 100644 man-pages-posix-2013/man3p/sem_close.3p create mode 100644 man-pages-posix-2013/man3p/sem_destroy.3p create mode 100644 man-pages-posix-2013/man3p/sem_getvalue.3p create mode 100644 man-pages-posix-2013/man3p/sem_init.3p create mode 100644 man-pages-posix-2013/man3p/sem_open.3p create mode 100644 man-pages-posix-2013/man3p/sem_post.3p create mode 100644 man-pages-posix-2013/man3p/sem_timedwait.3p create mode 100644 man-pages-posix-2013/man3p/sem_trywait.3p create mode 100644 man-pages-posix-2013/man3p/sem_unlink.3p create mode 100644 man-pages-posix-2013/man3p/sem_wait.3p create mode 100644 man-pages-posix-2013/man3p/semctl.3p create mode 100644 man-pages-posix-2013/man3p/semget.3p create mode 100644 man-pages-posix-2013/man3p/semop.3p create mode 100644 man-pages-posix-2013/man3p/send.3p create mode 100644 man-pages-posix-2013/man3p/sendmsg.3p create mode 100644 man-pages-posix-2013/man3p/sendto.3p create mode 100644 man-pages-posix-2013/man3p/setbuf.3p create mode 100644 man-pages-posix-2013/man3p/setegid.3p create mode 100644 man-pages-posix-2013/man3p/setenv.3p create mode 100644 man-pages-posix-2013/man3p/seteuid.3p create mode 100644 man-pages-posix-2013/man3p/setgid.3p create mode 100644 man-pages-posix-2013/man3p/setgrent.3p create mode 100644 man-pages-posix-2013/man3p/sethostent.3p create mode 100644 man-pages-posix-2013/man3p/setitimer.3p create mode 100644 man-pages-posix-2013/man3p/setjmp.3p create mode 100644 man-pages-posix-2013/man3p/setkey.3p create mode 100644 man-pages-posix-2013/man3p/setlocale.3p create mode 100644 man-pages-posix-2013/man3p/setlogmask.3p create mode 100644 man-pages-posix-2013/man3p/setnetent.3p create mode 100644 man-pages-posix-2013/man3p/setpgid.3p create mode 100644 man-pages-posix-2013/man3p/setpgrp.3p create mode 100644 man-pages-posix-2013/man3p/setpriority.3p create mode 100644 man-pages-posix-2013/man3p/setprotoent.3p create mode 100644 man-pages-posix-2013/man3p/setpwent.3p create mode 100644 man-pages-posix-2013/man3p/setregid.3p create mode 100644 man-pages-posix-2013/man3p/setreuid.3p create mode 100644 man-pages-posix-2013/man3p/setrlimit.3p create mode 100644 man-pages-posix-2013/man3p/setservent.3p create mode 100644 man-pages-posix-2013/man3p/setsid.3p create mode 100644 man-pages-posix-2013/man3p/setsockopt.3p create mode 100644 man-pages-posix-2013/man3p/setstate.3p create mode 100644 man-pages-posix-2013/man3p/setuid.3p create mode 100644 man-pages-posix-2013/man3p/setutxent.3p create mode 100644 man-pages-posix-2013/man3p/setvbuf.3p create mode 100644 man-pages-posix-2013/man3p/shm_open.3p create mode 100644 man-pages-posix-2013/man3p/shm_unlink.3p create mode 100644 man-pages-posix-2013/man3p/shmat.3p create mode 100644 man-pages-posix-2013/man3p/shmctl.3p create mode 100644 man-pages-posix-2013/man3p/shmdt.3p create mode 100644 man-pages-posix-2013/man3p/shmget.3p create mode 100644 man-pages-posix-2013/man3p/shutdown.3p create mode 100644 man-pages-posix-2013/man3p/sigaction.3p create mode 100644 man-pages-posix-2013/man3p/sigaddset.3p create mode 100644 man-pages-posix-2013/man3p/sigaltstack.3p create mode 100644 man-pages-posix-2013/man3p/sigdelset.3p create mode 100644 man-pages-posix-2013/man3p/sigemptyset.3p create mode 100644 man-pages-posix-2013/man3p/sigfillset.3p create mode 100644 man-pages-posix-2013/man3p/sighold.3p create mode 100644 man-pages-posix-2013/man3p/siginterrupt.3p create mode 100644 man-pages-posix-2013/man3p/sigismember.3p create mode 100644 man-pages-posix-2013/man3p/siglongjmp.3p create mode 100644 man-pages-posix-2013/man3p/signal.3p create mode 100644 man-pages-posix-2013/man3p/signbit.3p create mode 100644 man-pages-posix-2013/man3p/signgam.3p create mode 100644 man-pages-posix-2013/man3p/sigpause.3p create mode 100644 man-pages-posix-2013/man3p/sigpending.3p create mode 100644 man-pages-posix-2013/man3p/sigprocmask.3p create mode 100644 man-pages-posix-2013/man3p/sigqueue.3p create mode 100644 man-pages-posix-2013/man3p/sigrelse.3p create mode 100644 man-pages-posix-2013/man3p/sigsetjmp.3p create mode 100644 man-pages-posix-2013/man3p/sigsuspend.3p create mode 100644 man-pages-posix-2013/man3p/sigtimedwait.3p create mode 100644 man-pages-posix-2013/man3p/sigwait.3p create mode 100644 man-pages-posix-2013/man3p/sigwaitinfo.3p create mode 100644 man-pages-posix-2013/man3p/sin.3p create mode 100644 man-pages-posix-2013/man3p/sinh.3p create mode 100644 man-pages-posix-2013/man3p/sinl.3p create mode 100644 man-pages-posix-2013/man3p/sleep.3p create mode 100644 man-pages-posix-2013/man3p/snprintf.3p create mode 100644 man-pages-posix-2013/man3p/sockatmark.3p create mode 100644 man-pages-posix-2013/man3p/socket.3p create mode 100644 man-pages-posix-2013/man3p/socketpair.3p create mode 100644 man-pages-posix-2013/man3p/sprintf.3p create mode 100644 man-pages-posix-2013/man3p/sqrt.3p create mode 100644 man-pages-posix-2013/man3p/srand.3p create mode 100644 man-pages-posix-2013/man3p/srand48.3p create mode 100644 man-pages-posix-2013/man3p/srandom.3p create mode 100644 man-pages-posix-2013/man3p/sscanf.3p create mode 100644 man-pages-posix-2013/man3p/stat.3p create mode 100644 man-pages-posix-2013/man3p/statvfs.3p create mode 100644 man-pages-posix-2013/man3p/stdin.3p create mode 100644 man-pages-posix-2013/man3p/stpcpy.3p create mode 100644 man-pages-posix-2013/man3p/stpncpy.3p create mode 100644 man-pages-posix-2013/man3p/strcasecmp.3p create mode 100644 man-pages-posix-2013/man3p/strcat.3p create mode 100644 man-pages-posix-2013/man3p/strchr.3p create mode 100644 man-pages-posix-2013/man3p/strcmp.3p create mode 100644 man-pages-posix-2013/man3p/strcoll.3p create mode 100644 man-pages-posix-2013/man3p/strcpy.3p create mode 100644 man-pages-posix-2013/man3p/strcspn.3p create mode 100644 man-pages-posix-2013/man3p/strdup.3p create mode 100644 man-pages-posix-2013/man3p/strerror.3p create mode 100644 man-pages-posix-2013/man3p/strfmon.3p create mode 100644 man-pages-posix-2013/man3p/strftime.3p create mode 100644 man-pages-posix-2013/man3p/strlen.3p create mode 100644 man-pages-posix-2013/man3p/strncasecmp.3p create mode 100644 man-pages-posix-2013/man3p/strncat.3p create mode 100644 man-pages-posix-2013/man3p/strncmp.3p create mode 100644 man-pages-posix-2013/man3p/strncpy.3p create mode 100644 man-pages-posix-2013/man3p/strndup.3p create mode 100644 man-pages-posix-2013/man3p/strnlen.3p create mode 100644 man-pages-posix-2013/man3p/strpbrk.3p create mode 100644 man-pages-posix-2013/man3p/strptime.3p create mode 100644 man-pages-posix-2013/man3p/strrchr.3p create mode 100644 man-pages-posix-2013/man3p/strsignal.3p create mode 100644 man-pages-posix-2013/man3p/strspn.3p create mode 100644 man-pages-posix-2013/man3p/strstr.3p create mode 100644 man-pages-posix-2013/man3p/strtod.3p create mode 100644 man-pages-posix-2013/man3p/strtoimax.3p create mode 100644 man-pages-posix-2013/man3p/strtok.3p create mode 100644 man-pages-posix-2013/man3p/strtol.3p create mode 100644 man-pages-posix-2013/man3p/strtold.3p create mode 100644 man-pages-posix-2013/man3p/strtoll.3p create mode 100644 man-pages-posix-2013/man3p/strtoul.3p create mode 100644 man-pages-posix-2013/man3p/strtoumax.3p create mode 100644 man-pages-posix-2013/man3p/strxfrm.3p create mode 100644 man-pages-posix-2013/man3p/swab.3p create mode 100644 man-pages-posix-2013/man3p/swprintf.3p create mode 100644 man-pages-posix-2013/man3p/swscanf.3p create mode 100644 man-pages-posix-2013/man3p/symlink.3p create mode 100644 man-pages-posix-2013/man3p/sync.3p create mode 100644 man-pages-posix-2013/man3p/sysconf.3p create mode 100644 man-pages-posix-2013/man3p/syslog.3p create mode 100644 man-pages-posix-2013/man3p/system.3p create mode 100644 man-pages-posix-2013/man3p/tan.3p create mode 100644 man-pages-posix-2013/man3p/tanh.3p create mode 100644 man-pages-posix-2013/man3p/tanl.3p create mode 100644 man-pages-posix-2013/man3p/tcdrain.3p create mode 100644 man-pages-posix-2013/man3p/tcflow.3p create mode 100644 man-pages-posix-2013/man3p/tcflush.3p create mode 100644 man-pages-posix-2013/man3p/tcgetattr.3p create mode 100644 man-pages-posix-2013/man3p/tcgetpgrp.3p create mode 100644 man-pages-posix-2013/man3p/tcgetsid.3p create mode 100644 man-pages-posix-2013/man3p/tcsendbreak.3p create mode 100644 man-pages-posix-2013/man3p/tcsetattr.3p create mode 100644 man-pages-posix-2013/man3p/tcsetpgrp.3p create mode 100644 man-pages-posix-2013/man3p/tdelete.3p create mode 100644 man-pages-posix-2013/man3p/telldir.3p create mode 100644 man-pages-posix-2013/man3p/tempnam.3p create mode 100644 man-pages-posix-2013/man3p/tfind.3p create mode 100644 man-pages-posix-2013/man3p/tgamma.3p create mode 100644 man-pages-posix-2013/man3p/time.3p create mode 100644 man-pages-posix-2013/man3p/timer_create.3p create mode 100644 man-pages-posix-2013/man3p/timer_delete.3p create mode 100644 man-pages-posix-2013/man3p/timer_getoverrun.3p create mode 100644 man-pages-posix-2013/man3p/times.3p create mode 100644 man-pages-posix-2013/man3p/timezone.3p create mode 100644 man-pages-posix-2013/man3p/tmpfile.3p create mode 100644 man-pages-posix-2013/man3p/tmpnam.3p create mode 100644 man-pages-posix-2013/man3p/toascii.3p create mode 100644 man-pages-posix-2013/man3p/tolower.3p create mode 100644 man-pages-posix-2013/man3p/toupper.3p create mode 100644 man-pages-posix-2013/man3p/towctrans.3p create mode 100644 man-pages-posix-2013/man3p/towlower.3p create mode 100644 man-pages-posix-2013/man3p/towupper.3p create mode 100644 man-pages-posix-2013/man3p/trunc.3p create mode 100644 man-pages-posix-2013/man3p/truncate.3p create mode 100644 man-pages-posix-2013/man3p/truncf.3p create mode 100644 man-pages-posix-2013/man3p/tsearch.3p create mode 100644 man-pages-posix-2013/man3p/ttyname.3p create mode 100644 man-pages-posix-2013/man3p/twalk.3p create mode 100644 man-pages-posix-2013/man3p/tzset.3p create mode 100644 man-pages-posix-2013/man3p/ulimit.3p create mode 100644 man-pages-posix-2013/man3p/umask.3p create mode 100644 man-pages-posix-2013/man3p/uname.3p create mode 100644 man-pages-posix-2013/man3p/ungetc.3p create mode 100644 man-pages-posix-2013/man3p/ungetwc.3p create mode 100644 man-pages-posix-2013/man3p/unlink.3p create mode 100644 man-pages-posix-2013/man3p/unlockpt.3p create mode 100644 man-pages-posix-2013/man3p/unsetenv.3p create mode 100644 man-pages-posix-2013/man3p/uselocale.3p create mode 100644 man-pages-posix-2013/man3p/utime.3p create mode 100644 man-pages-posix-2013/man3p/utimensat.3p create mode 100644 man-pages-posix-2013/man3p/va_arg.3p create mode 100644 man-pages-posix-2013/man3p/vfprintf.3p create mode 100644 man-pages-posix-2013/man3p/vfscanf.3p create mode 100644 man-pages-posix-2013/man3p/vfwprintf.3p create mode 100644 man-pages-posix-2013/man3p/vfwscanf.3p create mode 100644 man-pages-posix-2013/man3p/vprintf.3p create mode 100644 man-pages-posix-2013/man3p/vscanf.3p create mode 100644 man-pages-posix-2013/man3p/vsnprintf.3p create mode 100644 man-pages-posix-2013/man3p/vsscanf.3p create mode 100644 man-pages-posix-2013/man3p/vswprintf.3p create mode 100644 man-pages-posix-2013/man3p/vswscanf.3p create mode 100644 man-pages-posix-2013/man3p/vwprintf.3p create mode 100644 man-pages-posix-2013/man3p/vwscanf.3p create mode 100644 man-pages-posix-2013/man3p/wait.3p create mode 100644 man-pages-posix-2013/man3p/waitid.3p create mode 100644 man-pages-posix-2013/man3p/waitpid.3p create mode 100644 man-pages-posix-2013/man3p/wcpcpy.3p create mode 100644 man-pages-posix-2013/man3p/wcpncpy.3p create mode 100644 man-pages-posix-2013/man3p/wcrtomb.3p create mode 100644 man-pages-posix-2013/man3p/wcscasecmp.3p create mode 100644 man-pages-posix-2013/man3p/wcscat.3p create mode 100644 man-pages-posix-2013/man3p/wcschr.3p create mode 100644 man-pages-posix-2013/man3p/wcscmp.3p create mode 100644 man-pages-posix-2013/man3p/wcscoll.3p create mode 100644 man-pages-posix-2013/man3p/wcscpy.3p create mode 100644 man-pages-posix-2013/man3p/wcscspn.3p create mode 100644 man-pages-posix-2013/man3p/wcsdup.3p create mode 100644 man-pages-posix-2013/man3p/wcsftime.3p create mode 100644 man-pages-posix-2013/man3p/wcslen.3p create mode 100644 man-pages-posix-2013/man3p/wcsncasecmp.3p create mode 100644 man-pages-posix-2013/man3p/wcsncat.3p create mode 100644 man-pages-posix-2013/man3p/wcsncmp.3p create mode 100644 man-pages-posix-2013/man3p/wcsncpy.3p create mode 100644 man-pages-posix-2013/man3p/wcsnlen.3p create mode 100644 man-pages-posix-2013/man3p/wcsnrtombs.3p create mode 100644 man-pages-posix-2013/man3p/wcspbrk.3p create mode 100644 man-pages-posix-2013/man3p/wcsrchr.3p create mode 100644 man-pages-posix-2013/man3p/wcsrtombs.3p create mode 100644 man-pages-posix-2013/man3p/wcsspn.3p create mode 100644 man-pages-posix-2013/man3p/wcsstr.3p create mode 100644 man-pages-posix-2013/man3p/wcstod.3p create mode 100644 man-pages-posix-2013/man3p/wcstoimax.3p create mode 100644 man-pages-posix-2013/man3p/wcstok.3p create mode 100644 man-pages-posix-2013/man3p/wcstol.3p create mode 100644 man-pages-posix-2013/man3p/wcstold.3p create mode 100644 man-pages-posix-2013/man3p/wcstoll.3p create mode 100644 man-pages-posix-2013/man3p/wcstombs.3p create mode 100644 man-pages-posix-2013/man3p/wcstoul.3p create mode 100644 man-pages-posix-2013/man3p/wcstoumax.3p create mode 100644 man-pages-posix-2013/man3p/wcswidth.3p create mode 100644 man-pages-posix-2013/man3p/wcsxfrm.3p create mode 100644 man-pages-posix-2013/man3p/wctob.3p create mode 100644 man-pages-posix-2013/man3p/wctomb.3p create mode 100644 man-pages-posix-2013/man3p/wctrans.3p create mode 100644 man-pages-posix-2013/man3p/wctype.3p create mode 100644 man-pages-posix-2013/man3p/wcwidth.3p create mode 100644 man-pages-posix-2013/man3p/wmemchr.3p create mode 100644 man-pages-posix-2013/man3p/wmemcmp.3p create mode 100644 man-pages-posix-2013/man3p/wmemcpy.3p create mode 100644 man-pages-posix-2013/man3p/wmemmove.3p create mode 100644 man-pages-posix-2013/man3p/wmemset.3p create mode 100644 man-pages-posix-2013/man3p/wordexp.3p create mode 100644 man-pages-posix-2013/man3p/wprintf.3p create mode 100644 man-pages-posix-2013/man3p/write.3p create mode 100644 man-pages-posix-2013/man3p/writev.3p create mode 100644 man-pages-posix-2013/man3p/wscanf.3p create mode 100644 man-pages-posix-2013/man3p/y0.3p diff --git a/man-pages-posix-2013/Makefile b/man-pages-posix-2013/Makefile new file mode 100644 index 0000000..7e71ec0 --- /dev/null +++ b/man-pages-posix-2013/Makefile @@ -0,0 +1,59 @@ +# Do "make screen" first, if you want to protect already installed, +# more up-to-date manual pages than the ones included in this package. +# Do "make install" to copy the pages to their destination. +# Do "make gz" or "make bz2" first if you use compressed source pages. + +DESTDIR= +prefix?=/usr +MANDIR=$(prefix)/share/man + +GZIP=gzip -9 +BZIP2=bzip2 -9 + +all: screen remove install + +allgz: gz all + +allbz: bz2 all + +screen: + -mkdir not_installed + for i in man?p/*; do \ + if [ $(MANDIR)/"$$i" -nt "$$i" ]; then \ + cmp -s $(MANDIR)/"$$i" "$$i" > /dev/null 2>&1; \ + if [ "$$?" != 0 ]; then mv "$$i" not_installed; fi; \ + fi; \ + done + +remove: + for i in man?p/*; do \ + rm -f $(MANDIR)/"$$i" $(MANDIR)/"$$i".gz $(MANDIR)/"$$i".bz2; \ + done + +gz: + for i in man?p; do $(GZIP) "$$i"/*; done + +bz2: + for i in man?p; do $(BZIP2) "$$i"/*; done + +# Use with +# make HTDIR=/some/dir HTOPTS=whatever html +# The sed removes the lines "Content-type: text/html\n\n" +html: + @if [ x$(HTDIR) = x ]; then echo "You must set HTDIR."; else \ + for i in man?p; do \ + [ -d $(HTDIR)/"$$i" ] || mkdir -p $(HTDIR)/"$$i"; \ + find "$$i/" -type f | while read f; do \ + (cd "$$i"; man2html $(HTOPTS) `basename $$f`) | \ + sed -e '1,2d' > $(HTDIR)/"$$i"/`basename $$f`.html; \ + done; \ + done; fi + +install: + for i in man?p; do \ + install -d -m 755 $(DESTDIR)$(MANDIR)/"$$i" || exit $$?; \ + install -m 644 "$$i"/* $(DESTDIR)$(MANDIR)/"$$i" || exit $$?; \ + done; \ + +# someone might also want to look at /var/catman/cat2 or so ... +# a problem is that the location of cat pages varies a lot diff --git a/man-pages-posix-2013/POSIX-COPYRIGHT b/man-pages-posix-2013/POSIX-COPYRIGHT new file mode 100644 index 0000000..3097301 --- /dev/null +++ b/man-pages-posix-2013/POSIX-COPYRIGHT @@ -0,0 +1,25 @@ +The Institute of Electrical and Electronics Engineers (IEEE) and +The Open Group, have given us permission to reprint portions of +their documentation. + +In the following statement, the phrase ``this text'' refers to +portions of the system documentation. + +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri- +cal and Electronics Engineers, Inc and The Open Group. (This is +POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online +at http://www.unix.org/online.html . + +This notice shall appear on any product containing this material. + +Redistribution of this material is permitted so long as this notice and +the corresponding notices within each POSIX manual page are retained on +any distribution, and the nroff source is included. Modifications to +the text are permitted so long as any conflicts with the standard +are clearly marked as such in the text. diff --git a/man-pages-posix-2013/README b/man-pages-posix-2013/README new file mode 100644 index 0000000..8e1ccb8 --- /dev/null +++ b/man-pages-posix-2013/README @@ -0,0 +1,22 @@ +These are pages from POSIX.1-2008, Technical Corrigendum 1. +Since TC1 appeared in 2013, it is also known as POSIX.1-2013. + +This package contains the POSIX man pages (pages in sections +except 0p, 1p, and 3p). Some more information is given in the +`Announce' file. Some background on UNIX standards, including +POSIX, can be found in the standards(7) page provide as part +of the separate Linux man-pages package. + +Install by copying to your favourite location. +"make install" will just copy them to /usr/share/man/man[013]p. +"make" will move the pages from this package that are older than +the already installed ones to a subdirectory `not_installed', +then remove old versions (compressed or not), +compress the pages, and copy them to /usr/share/man/man[013]p. + +Note that you may have to remove preformatted pages. + +Copyrights: see the file POSIX-COPYRIGHT. + +If you have corrections and additions to suggest, then visit +https://www.kernel.org/doc/man-pages/reporting_bugs.html diff --git a/man-pages-posix-2013/man-pages-posix-2013-a.Announce b/man-pages-posix-2013/man-pages-posix-2013-a.Announce new file mode 100644 index 0000000..6b16e78 --- /dev/null +++ b/man-pages-posix-2013/man-pages-posix-2013-a.Announce @@ -0,0 +1,28 @@ +RELEASE +The Linux man-pages maintainer proudly announces. . . + + man-pages-posix-2013-a.tar.gz - POSIX man pages + +For further information, visit http://www.kernel.org/doc/man-pages/ + +POSIX +This release contains a copy of the POSIX 1003.1-2013 man pages. +The directories man0p, man1p, man3p contain descriptions of the +headers, the utilities, and the functions documented in that standard. +For the copyright notice, see the file POSIX-COPYRIGHT. + +In order to use this, put in {/usr/share/misc/}man.conf{ig} or so +your favourite order of looking at these pages, for example, +MANSECT 1p:1:8:0p:3p:2:3:4:5:6:7:9:tcl:n:l:p:o +or set the MANSECT environment variable. + +Here is a breakdown of what this distribution contains: + + Section 0p = POSIX headers + Section 1p = POSIX utilities + Section 3p = POSIX functions + +Copyright information: + + For the POSIX pages permission to distribute was given by IEEE + and the Open Group, see POSIX-COPYRIGHT. diff --git a/man-pages-posix-2013/man-pages-posix-2013-a.lsm b/man-pages-posix-2013/man-pages-posix-2013-a.lsm new file mode 100644 index 0000000..d9bfaa6 --- /dev/null +++ b/man-pages-posix-2013/man-pages-posix-2013-a.lsm @@ -0,0 +1,12 @@ +Begin3 +Title: Section 0p, 1p, and 3p man pages (the POSIX.1-2013 man-pages) for Linux +Version: 2013-a +Entered-date: 2014-01-19 +Description: POSIX manual pages +Keywords: man pages +Author: The Open Group +Maintained-by: Michael Kerrisk +Primary-site: https://www.kernel.org/pub/linux/docs/man-pages/man-pages-posix/ + 1499k man-pages-posix-2013-a.tar.gz +Copying-policy: See the file POSIX-COPYRIGHT; +End diff --git a/man-pages-posix-2013/man0p/aio.h.0p b/man-pages-posix-2013/man0p/aio.h.0p new file mode 100644 index 0000000..0a5c829 --- /dev/null +++ b/man-pages-posix-2013/man0p/aio.h.0p @@ -0,0 +1,174 @@ +'\" et +.TH aio.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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.h +\(em asynchronous input and output +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR aiocb +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +int aio_fildes \fRFile descriptor.\fR +off_t aio_offset \fRFile offset.\fR +volatile void *aio_buf \fRLocation of buffer.\fR +size_t aio_nbytes \fRLength of transfer.\fR +int aio_reqprio \fRRequest priority offset.\fR +struct sigevent aio_sigevent \fRSignal number and value.\fR +int aio_lio_opcode \fROperation to be performed.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR off_t , +.BR pthread_attr_t , +.BR size_t , +and +.BR ssize_t +types as described in +.IR . +.P +The +.IR +header shall define the +.BR "struct timespec" +structure as described in +.IR . +.P +The tag +.BR sigevent +shall be declared as naming an incomplete structure type, the contents +of which are described in the +.IR +header. +.P +The +.IR +header shall define the following symbolic constants: +.IP AIO_ALLDONE 14 +A return value indicating that none of the requested operations could +be canceled since they are already complete. +.IP AIO_CANCELED 14 +A return value indicating that all requested operations have been +canceled. +.IP AIO_NOTCANCELED 14 +.br +A return value indicating that some of the requested operations could +not be canceled since they are in progress. +.IP LIO_NOP 14 +A +\fIlio_listio\fR() +element operation option indicating that no transfer is requested. +.IP LIO_NOWAIT 14 +A +\fIlio_listio\fR() +synchronization operation indicating that the calling thread is to +continue execution while the +\fIlio_listio\fR() +operation is being performed, and no notification is given when the +operation is complete. +.IP LIO_READ 14 +A +\fIlio_listio\fR() +element operation option requesting a read. +.IP LIO_WAIT 14 +A +\fIlio_listio\fR() +synchronization operation indicating that the calling thread is to +suspend until the +\fIlio_listio\fR() +operation is complete. +.IP LIO_WRITE 14 +A +\fIlio_listio\fR() +element operation option requesting a write. +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int aio_cancel(int, struct aiocb *); +int aio_error(const struct aiocb *); +int aio_fsync(int, struct aiocb *); +int aio_read(struct aiocb *); +ssize_t aio_return(struct aiocb *); +int aio_suspend(const struct aiocb *const [], int, + const struct timespec *); +int aio_write(struct aiocb *); +int lio_listio(int, struct aiocb *restrict const [restrict], int, + struct sigevent *restrict); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may make visible symbols defined in the headers +.IR , +.IR , +and +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIaio_cancel\fR\^(\|)", +.IR "\fIaio_error\fR\^(\|)", +.IR "\fIaio_fsync\fR\^(\|)", +.IR "\fIaio_read\fR\^(\|)", +.IR "\fIaio_return\fR\^(\|)", +.IR "\fIaio_suspend\fR\^(\|)", +.IR "\fIaio_write\fR\^(\|)", +.IR "\fIfsync\fR\^(\|)", +.IR "\fIlio_listio\fR\^(\|)", +.IR "\fIlseek\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/arpa_inet.h.0p b/man-pages-posix-2013/man0p/arpa_inet.h.0p new file mode 100644 index 0000000..6c4bdbe --- /dev/null +++ b/man-pages-posix-2013/man0p/arpa_inet.h.0p @@ -0,0 +1,118 @@ +'\" et +.TH arpa_inet.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +arpa/inet.h +\(em definitions for internet operations +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR in_port_t +and +.BR in_addr_t +types as described in +.IR . +.P +The +.IR +header shall define the +.BR in_addr +structure as described in +.IR . +.P +The +.IR +header shall define the INET_ADDRSTRLEN +and INET6_ADDRSTRLEN +macros as described in +.IR . +.P +The following shall be declared as functions, or defined as macros, +or both. If functions are declared, function prototypes shall be +provided. +.sp +.RS 4 +.nf +\fB +uint32_t htonl(uint32_t); +uint16_t htons(uint16_t); +uint32_t ntohl(uint32_t); +uint16_t ntohs(uint16_t); +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR uint32_t +and +.BR uint16_t +types as described in +.IR . +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +in_addr_t inet_addr(const char *); +char *inet_ntoa(struct in_addr); +const char *inet_ntop(int, const void *restrict, char *restrict, + socklen_t); +int inet_pton(int, const char *restrict, void *restrict); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may also make visible all symbols from +.IR +and +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIhtonl\fR\^(\|)", +.IR "\fIinet_addr\fR\^(\|)", +.IR "\fIinet_ntop\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/assert.h.0p b/man-pages-posix-2013/man0p/assert.h.0p new file mode 100644 index 0000000..2957f9b --- /dev/null +++ b/man-pages-posix-2013/man0p/assert.h.0p @@ -0,0 +1,82 @@ +'\" et +.TH assert.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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.h +\(em verify program assertion +.SH SYNOPSIS +.LP +.nf +#include +.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\(hy2008 defers to the ISO\ C standard. +.P +The +.IR +header shall define the +\fIassert\fR() +macro. It refers to the macro NDEBUG +which is not defined in the header. If NDEBUG is defined as a macro +name before the inclusion of this header, the +\fIassert\fR() +macro shall be defined simply as: +.sp +.RS 4 +.nf +\fB +#define assert(ignore)((void) 0) +.fi \fR +.P +.RE +.P +Otherwise, the macro behaves as described in +\fIassert\fR(). +.P +The +\fIassert\fR() +macro shall be redefined according to the current state of NDEBUG each +time +.IR +is included. +.P +The +\fIassert\fR() +macro shall be implemented as a macro, not as a function. If the macro +definition is suppressed in order to access an actual function, the +behavior is undefined. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIassert\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/complex.h.0p b/man-pages-posix-2013/man0p/complex.h.0p new file mode 100644 index 0000000..517ecf4 --- /dev/null +++ b/man-pages-posix-2013/man0p/complex.h.0p @@ -0,0 +1,254 @@ +'\" et +.TH complex.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +complex.h +\(em complex arithmetic +.SH SYNOPSIS +.LP +.nf +#include +.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\(hy2008 defers to the ISO\ C standard. +.P +The +.IR +header shall define the following macros: +.IP complex 12 +Expands to +.BR _Complex . +.IP _Complex_I 12 +Expands to a constant expression of type +.BR "const float _Complex" , +with the value of the imaginary unit (that is, a number +.IR i +such that \fIi\fR\s-3\u2\d\s+3=\(mi1). +.IP imaginary 12 +Expands to +.BR _Imaginary . +.IP _Imaginary_I 12 +Expands to a constant expression of type +.BR "const float _Imaginary" +with the value of the imaginary unit. +.IP I 12 +Expands to either _Imaginary_I or _Complex_I. If _Imaginary_I is not +defined, I expands to _Complex_I. +.P +The macros imaginary and _Imaginary_I shall be defined if and only if +the implementation supports imaginary types. +.P +An application may undefine and then, perhaps, redefine the complex, +imaginary, and I macros. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +double cabs(double complex); +float cabsf(float complex); +long double cabsl(long double complex); +double complex cacos(double complex); +float complex cacosf(float complex); +double complex cacosh(double complex); +float complex cacoshf(float complex); +long double complex cacoshl(long double complex); +long double complex cacosl(long double complex); +double carg(double complex); +float cargf(float complex); +long double cargl(long double complex); +double complex casin(double complex); +float complex casinf(float complex); +double complex casinh(double complex); +float complex casinhf(float complex); +long double complex casinhl(long double complex); +long double complex casinl(long double complex); +double complex catan(double complex); +float complex catanf(float complex); +double complex catanh(double complex); +float complex catanhf(float complex); +long double complex catanhl(long double complex); +long double complex catanl(long double complex); +double complex ccos(double complex); +float complex ccosf(float complex); +double complex ccosh(double complex); +float complex ccoshf(float complex); +long double complex ccoshl(long double complex); +long double complex ccosl(long double complex); +double complex cexp(double complex); +float complex cexpf(float complex); +long double complex cexpl(long double complex); +double cimag(double complex); +float cimagf(float complex); +long double cimagl(long double complex); +double complex clog(double complex); +float complex clogf(float complex); +long double complex clogl(long double complex); +double complex conj(double complex); +float complex conjf(float complex); +long double complex conjl(long double complex); +double complex cpow(double complex, double complex); +float complex cpowf(float complex, float complex); +long double complex cpowl(long double complex, long double complex); +double complex cproj(double complex); +float complex cprojf(float complex); +long double complex cprojl(long double complex); +double creal(double complex); +float crealf(float complex); +long double creall(long double complex); +double complex csin(double complex); +float complex csinf(float complex); +double complex csinh(double complex); +float complex csinhf(float complex); +long double complex csinhl(long double complex); +long double complex csinl(long double complex); +double complex csqrt(double complex); +float complex csqrtf(float complex); +long double complex csqrtl(long double complex); +double complex ctan(double complex); +float complex ctanf(float complex); +double complex ctanh(double complex); +float complex ctanhf(float complex); +long double complex ctanhl(long double complex); +long double complex ctanl(long double complex); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Values are interpreted as radians, not degrees. +.SH RATIONALE +The choice of +.IR I +instead of +.IR i +for the imaginary unit concedes to the widespread use of the identifier +.IR i +for other purposes. The application can use a different identifier, say +.IR j , +for the imaginary unit by following the inclusion of the +.IR +header with: +.sp +.RS 4 +.nf +\fB +#undef I +#define j _Imaginary_I +.fi \fR +.P +.RE +.P +An +.IR I +suffix to designate imaginary constants is not required, as +multiplication by +.IR I +provides a sufficiently convenient and more generally useful notation +for imaginary terms. The corresponding real type for the imaginary unit +is +.BR float , +so that use of +.IR I +for algorithmic or notational convenience will not result in +widening types. +.P +On systems with imaginary types, the application has the ability to +control whether use of the macro I introduces an imaginary type, by +explicitly defining I to be _Imaginary_I or _Complex_I. Disallowing +imaginary types is useful for some applications intended to run on +implementations without support for such types. +.P +The macro _Imaginary_I provides a test for whether imaginary types are +supported. +.P +The +\fIcis\fR() +function (\fIcos\fR(\fIx\fR) + \fII\fR*\fIsin\fR(\fIx\fR)) was +considered but rejected because its implementation is easy and +straightforward, even though some implementations could compute sine +and cosine more efficiently in tandem. +.SH "FUTURE DIRECTIONS" +The following function names and the same names suffixed with +.IR f +or +.IR l +are reserved for future use, and may be added to the declarations +in the +.IR +header. +.sp +.RS +.TS +tab(!); +l l l. +T{ +.nf +\fIcerf\fR() +\fIcerfc\fR() +\fIcexp2\fR() +T}!T{ +.nf +\fIcexpm1\fR() +\fIclog10\fR() +\fIclog1p\fR() +T}!T{ +.nf +\fIclog2\fR() +\fIclgamma\fR() +\fIctgamma\fR() +.fi +T} +.TE +.RE +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIcabs\fR\^(\|)", +.IR "\fIcacos\fR\^(\|)", +.IR "\fIcacosh\fR\^(\|)", +.IR "\fIcarg\fR\^(\|)", +.IR "\fIcasin\fR\^(\|)", +.IR "\fIcasinh\fR\^(\|)", +.IR "\fIcatan\fR\^(\|)", +.IR "\fIcatanh\fR\^(\|)", +.IR "\fIccos\fR\^(\|)", +.IR "\fIccosh\fR\^(\|)", +.IR "\fIcexp\fR\^(\|)", +.IR "\fIcimag\fR\^(\|)", +.IR "\fIclog\fR\^(\|)", +.IR "\fIconj\fR\^(\|)", +.IR "\fIcpow\fR\^(\|)", +.IR "\fIcproj\fR\^(\|)", +.IR "\fIcreal\fR\^(\|)", +.IR "\fIcsin\fR\^(\|)", +.IR "\fIcsinh\fR\^(\|)", +.IR "\fIcsqrt\fR\^(\|)", +.IR "\fIctan\fR\^(\|)", +.IR "\fIctanh\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/cpio.h.0p b/man-pages-posix-2013/man0p/cpio.h.0p new file mode 100644 index 0000000..f3727ac --- /dev/null +++ b/man-pages-posix-2013/man0p/cpio.h.0p @@ -0,0 +1,91 @@ +'\" et +.TH cpio.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cpio.h +\(em cpio archive values +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the symbolic constants needed by the +.IR c_mode +field of the +.IR cpio +archive format, with the names and values given in the following table: +.TS +box center tab(@); +cB| cB |cB +l| l |c. +Name@Description@Value (Octal) +_ +C_IRUSR@Read by owner.@0000400 +C_IWUSR@Write by owner.@0000200 +C_IXUSR@Execute by owner.@0000100 +C_IRGRP@Read by group.@0000040 +C_IWGRP@Write by group.@0000020 +C_IXGRP@Execute by group.@0000010 +C_IROTH@Read by others.@0000004 +C_IWOTH@Write by others.@0000002 +C_IXOTH@Execute by others.@0000001 +C_ISUID@Set user ID.@0004000 +C_ISGID@Set group ID.@0002000 +C_ISVTX@On directories, restricted deletion flag.@0001000 +C_ISDIR@Directory.@0040000 +C_ISFIFO@FIFO.@0010000 +C_ISREG@Regular file.@0100000 +C_ISBLK@Block special.@0060000 +C_ISCHR@Character special.@0020000 +C_ISCTG@Reserved.@0110000 +C_ISLNK@Symbolic link.@0120000 +C_ISSOCK@Socket.@0140000 +.TE +.P +The +.IR +header shall define the following symbolic constant as a string: +.sp +.RS 4 +.nf +\fB +MAGIC "070707" +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIpax\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/ctype.h.0p b/man-pages-posix-2013/man0p/ctype.h.0p new file mode 100644 index 0000000..a85b241 --- /dev/null +++ b/man-pages-posix-2013/man0p/ctype.h.0p @@ -0,0 +1,138 @@ +'\" et +.TH ctype.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ctype.h +\(em character types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends the +ISO\ C standard. Applications shall define the appropriate feature test macro +(see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment") +to enable the visibility of these symbols in this header. +.P +The +.IR +header shall define the +.BR locale_t +type as described in +.IR , +representing a locale object. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided for use with ISO\ C standard +compilers. +.sp +.RS 4 +.nf +\fB +int isalnum(int); +int isalnum_l(int, locale_t); +int isalpha(int); +int isalpha_l(int, locale_t); +int isascii(int); +int isblank(int); +int isblank_l(int, locale_t); +int iscntrl(int); +int iscntrl_l(int, locale_t); +int isdigit(int); +int isdigit_l(int, locale_t); +int isgraph(int); +int isgraph_l(int, locale_t); +int islower(int); +int islower_l(int, locale_t); +int isprint(int); +int isprint_l(int, locale_t); +int ispunct(int); +int ispunct_l(int, locale_t); +int isspace(int); +int isspace_l(int, locale_t); +int isupper(int); +int isupper_l(int, locale_t); +int isxdigit(int); +int isxdigit_l(int, locale_t); +int toascii(int); +int tolower(int); +int tolower_l(int, locale_t); +int toupper(int); +int toupper_l(int, locale_t); +.fi \fR +.P +.RE +.P +The +.IR +header shall define the following as macros: +.sp +.RS 4 +.nf +\fB +int _toupper(int); +int _tolower(int); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment", +.IR "\fIisalnum\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIisascii\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 "\fImblen\fR\^(\|)", +.IR "\fImbstowcs\fR\^(\|)", +.IR "\fImbtowc\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fItoascii\fR\^(\|)", +.IR "\fItolower\fR\^(\|)", +.IR "\fI_tolower\fR\^(\|)", +.IR "\fItoupper\fR\^(\|)", +.IR "\fI_toupper\fR\^(\|)", +.IR "\fIwcstombs\fR\^(\|)", +.IR "\fIwctomb\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/dirent.h.0p b/man-pages-posix-2013/man0p/dirent.h.0p new file mode 100644 index 0000000..3df87ce --- /dev/null +++ b/man-pages-posix-2013/man0p/dirent.h.0p @@ -0,0 +1,163 @@ +'\" et +.TH dirent.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +dirent.h +\(em format of directory entries +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The internal format of directories is unspecified. +.P +The +.IR +header shall define the following type: +.IP "\fBDIR\fR" 8 +A type representing a directory stream. The +.BR DIR +type may be an incomplete type. +.P +It shall also define the structure +.BR dirent +which shall include the following members: +.sp +.RS 4 +.nf +\fB +ino_t d_ino \fRFile serial number.\fR +char d_name[] \fRFilename string of entry.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR ino_t +type as described in +.IR . +.P +The array +.IR d_name +is of unspecified size, but shall contain a filename of at most +{NAME_MAX} +bytes followed by a terminating null byte. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int alphasort(const struct dirent **, const struct dirent **); +int closedir(DIR *); +int dirfd(DIR *); +DIR *fdopendir(int); +DIR *opendir(const char *); +struct dirent *readdir(DIR *); +int readdir_r(DIR *restrict, struct dirent *restrict, + struct dirent **restrict); +void rewinddir(DIR *); +int scandir(const char *, struct dirent ***, + int (*)(const struct dirent *), + int (*)(const struct dirent **, + const struct dirent **)); +void seekdir(DIR *, long); +long telldir(DIR *); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Information similar to that in the +.IR +header is contained in a file +.IR +in 4.2 BSD and 4.3 BSD. The equivalent in these implementations of +.BR "struct dirent" +from this volume of POSIX.1\(hy2008 is +.BR "struct direct" . +The filename was changed because the name +.IR +was also used in earlier implementations to refer to definitions +related to the older access method; this produced name conflicts. The +name of the structure was changed because this volume of POSIX.1\(hy2008 does not completely +define what is in the structure, so it could be different on some +implementations from +.BR "struct direct" . +.P +The name of an array of +.BR char +of an unspecified size should not be used as an lvalue. Use of: +.sp +.RS 4 +.nf +\fB +sizeof(d_name) +.fi \fR +.P +.RE +.P +is incorrect; use: +.sp +.RS 4 +.nf +\fB +strlen(d_name) +.fi \fR +.P +.RE +.P +instead. +.P +The array of +.BR char +.IR d_name +is not a fixed size. Implementations may need to declare +.BR "struct dirent" +with an array size for +.IR d_name +of 1, but the actual number of bytes provided matches (or only slightly +exceeds) the length of the filename string. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIalphasort\fR\^(\|)", +.IR "\fIclosedir\fR\^(\|)", +.IR "\fIdirfd\fR\^(\|)", +.IR "\fIfdopendir\fR\^(\|)", +.IR "\fIreaddir\fR\^(\|)", +.IR "\fIrewinddir\fR\^(\|)", +.IR "\fIseekdir\fR\^(\|)", +.IR "\fItelldir\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/dlfcn.h.0p b/man-pages-posix-2013/man0p/dlfcn.h.0p new file mode 100644 index 0000000..a33c254 --- /dev/null +++ b/man-pages-posix-2013/man0p/dlfcn.h.0p @@ -0,0 +1,78 @@ +'\" et +.TH dlfcn.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +dlfcn.h +\(em dynamic linking +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define at least the following symbolic constants for use +in the construction of a +\fIdlopen\fR() +.IR mode +argument: +.IP RTLD_LAZY 14 +Relocations are performed at an implementation-defined time. +.IP RTLD_NOW 14 +Relocations are performed when the object is loaded. +.IP RTLD_GLOBAL 14 +All symbols are available for relocation processing of other modules. +.IP RTLD_LOCAL 14 +All symbols are not made available for relocation processing by other +modules. +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int dlclose(void *); +char *dlerror(void); +void *dlopen(const char *, int); +void *dlsym(void *restrict, const char *restrict); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIdlclose\fR\^(\|)", +.IR "\fIdlerror\fR\^(\|)", +.IR "\fIdlopen\fR\^(\|)", +.IR "\fIdlsym\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/errno.h.0p b/man-pages-posix-2013/man0p/errno.h.0p new file mode 100644 index 0000000..856ae5e --- /dev/null +++ b/man-pages-posix-2013/man0p/errno.h.0p @@ -0,0 +1,333 @@ +'\" et +.TH errno.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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.h +\(em system error numbers +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends +the ISO\ C standard. Any conflict between the requirements described here +and the ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard. +.P +The ISO\ C standard only requires the symbols +.BR [EDOM] , +.BR [EILSEQ] , +and +.BR [ERANGE] +to be defined. +.P +The +.IR +header shall provide a declaration or definition for +.IR errno . +The symbol +.IR errno +shall expand to a modifiable lvalue of type +.BR int . +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 +.IR +header shall define the following macros which shall expand to +integer constant expressions with type +.BR int , +distinct positive values (except as noted below), and which shall be +suitable for use in +.BR #if +preprocessing directives: +.TP +.BR E2BIG +Argument list too long. +.TP +.BR EACCES +Permission denied. +.TP +.BR EADDRINUSE +Address in use. +.TP +.BR EADDRNOTAVAIL +Address not available. +.TP +.BR EAFNOSUPPORT +Address family not supported. +.TP +.BR EAGAIN +Resource unavailable, try again (may be the same value as +.BR [EWOULDBLOCK] ). +.TP +.BR EALREADY +Connection already in progress. +.TP +.BR EBADF +Bad file descriptor. +.TP +.BR EBADMSG +Bad message. +.TP +.BR EBUSY +Device or resource busy. +.TP +.BR ECANCELED +Operation canceled. +.TP +.BR ECHILD +No child processes. +.TP +.BR ECONNABORTED +Connection aborted. +.TP +.BR ECONNREFUSED +Connection refused. +.TP +.BR ECONNRESET +Connection reset. +.TP +.BR EDEADLK +Resource deadlock would occur. +.TP +.BR EDESTADDRREQ +Destination address required. +.TP +.BR EDOM +Mathematics argument out of domain of function. +.TP +.BR EDQUOT +Reserved. +.TP +.BR EEXIST +File exists. +.TP +.BR EFAULT +Bad address. +.TP +.BR EFBIG +File too large. +.TP +.BR EHOSTUNREACH +Host is unreachable. +.TP +.BR EIDRM +Identifier removed. +.TP +.BR EILSEQ +Illegal byte sequence. +.TP +.BR EINPROGRESS +Operation in progress. +.TP +.BR EINTR +Interrupted function. +.TP +.BR EINVAL +Invalid argument. +.TP +.BR EIO +I/O error. +.TP +.BR EISCONN +Socket is connected. +.TP +.BR EISDIR +Is a directory. +.TP +.BR ELOOP +Too many levels of symbolic links. +.TP +.BR EMFILE +File descriptor value too large. +.TP +.BR EMLINK +Too many links. +.TP +.BR EMSGSIZE +Message too large. +.TP +.BR EMULTIHOP +Reserved. +.TP +.BR ENAMETOOLONG +Filename too long. +.TP +.BR ENETDOWN +Network is down. +.TP +.BR ENETRESET +Connection aborted by network. +.TP +.BR ENETUNREACH +Network unreachable. +.TP +.BR ENFILE +Too many files open in system. +.TP +.BR ENOBUFS +No buffer space available. +.TP +.BR ENODATA +No message is available on the STREAM head read queue. +.TP +.BR ENODEV +No such device. +.TP +.BR ENOENT +No such file or directory. +.TP +.BR ENOEXEC +Executable file format error. +.TP +.BR ENOLCK +No locks available. +.TP +.BR ENOLINK +Reserved. +.TP +.BR ENOMEM +Not enough space. +.TP +.BR ENOMSG +No message of the desired type. +.TP +.BR ENOPROTOOPT +Protocol not available. +.TP +.BR ENOSPC +No space left on device. +.TP +.BR ENOSR +No STREAM resources. +.TP +.BR ENOSTR +Not a STREAM. +.TP +.BR ENOSYS +Function not supported. +.TP +.BR ENOTCONN +The socket is not connected. +.TP +.BR ENOTDIR +Not a directory or a symbolic link to a directory. +.TP +.BR ENOTEMPTY +Directory not empty. +.TP +.BR ENOTRECOVERABLE +.br +State not recoverable. +.TP +.BR ENOTSOCK +Not a socket. +.TP +.BR ENOTSUP +Not supported (may be the same value as +.BR [EOPNOTSUPP] ). +.TP +.BR ENOTTY +Inappropriate I/O control operation. +.TP +.BR ENXIO +No such device or address. +.TP +.BR EOPNOTSUPP +Operation not supported on socket (may be the same value as +.BR [ENOTSUP] ). +.TP +.BR EOVERFLOW +Value too large to be stored in data type. +.TP +.BR EOWNERDEAD +Previous owner died. +.TP +.BR EPERM +Operation not permitted. +.TP +.BR EPIPE +Broken pipe. +.TP +.BR EPROTO +Protocol error. +.TP +.BR EPROTONOSUPPORT +.br +Protocol not supported. +.TP +.BR EPROTOTYPE +Protocol wrong type for socket. +.TP +.BR ERANGE +Result too large. +.TP +.BR EROFS +Read-only file system. +.TP +.BR ESPIPE +Invalid seek. +.TP +.BR ESRCH +No such process. +.TP +.BR ESTALE +Reserved. +.TP +.BR ETIME +Stream +\fIioctl\fR() +timeout. +.TP +.BR ETIMEDOUT +Connection timed out. +.TP +.BR ETXTBSY +Text file busy. +.TP +.BR EWOULDBLOCK +Operation would block (may be the same value as +.BR [EAGAIN] ). +.TP +.BR EXDEV +Cross-device link. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Additional error numbers may be defined on conforming systems; see +the System Interfaces volume of POSIX.1\(hy2008. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.3" ", " "Error Numbers" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/fcntl.h.0p b/man-pages-posix-2013/man0p/fcntl.h.0p new file mode 100644 index 0000000..6848144 --- /dev/null +++ b/man-pages-posix-2013/man0p/fcntl.h.0p @@ -0,0 +1,375 @@ +'\" et +.TH fcntl.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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.h +\(em file control options +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following symbolic constants for the +.IR cmd +argument used by +\fIfcntl\fR(). +The values shall be unique and shall be suitable for use in +.BR #if +preprocessing directives. +.IP F_DUPFD 12 +Duplicate file descriptor. +.IP F_DUPFD_CLOEXEC 12 +.br +Duplicate file descriptor with the close-on-\c +.IR exec +flag FD_CLOEXEC set. +.IP F_GETFD 12 +Get file descriptor flags. +.IP F_SETFD 12 +Set file descriptor flags. +.IP F_GETFL 12 +Get file status flags and file access modes. +.IP F_SETFL 12 +Set file status flags. +.IP F_GETLK 12 +Get record locking information. +.IP F_SETLK 12 +Set record locking information. +.IP F_SETLKW 12 +Set record locking information; wait if blocked. +.IP F_GETOWN 12 +Get process or process group ID to receive SIGURG signals. +.IP F_SETOWN 12 +Set process or process group ID to receive SIGURG signals. +.P +The +.IR +header shall define the following symbolic constant used for the +\fIfcntl\fR() +file descriptor flags, which shall be suitable for use in +.BR #if +preprocessing directives. +.IP FD_CLOEXEC 12 +Close the file descriptor upon execution of an +.IR exec +family function. +.P +The +.IR +header shall also define the following symbolic constants for the +.IR l_type +argument used for record locking with +\fIfcntl\fR(). +The values shall be unique and shall be suitable for use in +.BR #if +preprocessing directives. +.IP F_RDLCK 12 +Shared or read lock. +.IP F_UNLCK 12 +Unlock. +.IP F_WRLCK 12 +Exclusive or write lock. +.P +The +.IR +header shall define the values used for +.IR l_whence , +SEEK_SET, SEEK_CUR, and SEEK_END +as described in +.IR . +.P +The +.IR +header shall define the following symbolic constants as file creation +flags for use in the +.IR oflag +value to +\fIopen\fR() +and +\fIopenat\fR(). +The values shall be bitwise-distinct and shall be suitable for use in +.BR #if +preprocessing directives. +.IP O_CLOEXEC 12 +The FD_CLOEXEC flag associated with the new descriptor shall be +set to close the file descriptor upon execution of an +.IR exec +family function. +.IP O_CREAT 12 +Create file if it does not exist. +.IP O_DIRECTORY 12 +Fail if not a directory. +.IP O_EXCL 12 +Exclusive use flag. +.IP O_NOCTTY 12 +Do not assign controlling terminal. +.IP O_NOFOLLOW 12 +Do not follow symbolic links. +.IP O_TRUNC 12 +Truncate flag. +.IP O_TTY_INIT 12 +Set the +.BR termios +structure terminal parameters to a state that provides conforming +behavior; see +.IR "Section 11.2" ", " "Parameters that Can be Set". +.P +The O_TTY_INIT flag can have the value zero and in this case it need +not be bitwise-distinct from the other flags. +.P +The +.IR +header shall define the following symbolic constants for use as +file status flags for +\fIopen\fR(), +\fIopenat\fR(), +and +\fIfcntl\fR(). +The values shall be suitable for use in +.BR #if +preprocessing directives. +.IP O_APPEND 12 +Set append mode. +.IP O_DSYNC 12 +Write according to synchronized I/O data integrity completion. +.IP O_NONBLOCK 12 +Non-blocking mode. +.IP O_RSYNC 12 +Synchronized read I/O operations. +.IP O_SYNC 12 +Write according to synchronized I/O file integrity completion. +.P +The +.IR +header shall define the following symbolic constant for use as the mask +for file access modes. The value shall be suitable for use in +.BR #if +preprocessing directives. +.IP O_ACCMODE 12 +Mask for file access modes. +.P +The +.IR +header shall define the following symbolic constants for use as +the file access modes for +\fIopen\fR(), +\fIopenat\fR(), +and +\fIfcntl\fR(). +The values shall be unique, except that O_EXEC and O_SEARCH may have +equal values. The values shall be suitable for use in +.BR #if +preprocessing directives. +.IP O_EXEC 12 +Open for execute only (non-directory files). The result is unspecified +if this flag is applied to a directory. +.IP O_RDONLY 12 +Open for reading only. +.IP O_RDWR 12 +Open for reading and writing. +.IP O_SEARCH 12 +Open directory for search only. The result is unspecified if this flag +is applied to a non-directory file. +.IP O_WRONLY 12 +Open for writing only. +.P +The +.IR +header shall define the symbolic constants for file modes for use as +values of +.BR mode_t +as described in +.IR . +.P +The +.IR +header shall define the following symbolic constant as a special value +used in place of a file descriptor for the +.IR *at (\|) +functions which take a directory file descriptor as a parameter: +.IP AT_FDCWD 12 +Use the current working directory to determine the target of relative +file paths. +.P +The +.IR +header shall define the following symbolic constant as a value for the +.IR flag +used by +\fIfaccessat\fR(): +.IP AT_EACCESS 12 +Check access using effective user and group ID. +.P +The +.IR +header shall define the following symbolic constant as a value for the +.IR flag +used by +\fIfstatat\fR(), +\fIfchmodat\fR(), +\fIfchownat\fR(), +and +\fIutimensat\fR(): +.IP AT_SYMLINK_NOFOLLOW 12 +.br +Do not follow symbolic links. +.P +The +.IR +header shall define the following symbolic constant as a value for +the flag used by +\fIlinkat\fR(): +.IP AT_SYMLINK_FOLLOW 12 +.br +Follow symbolic link. +.br +.P +The +.IR +header shall define the following symbolic constant as a value +for the flag used by +\fIunlinkat\fR(): +.IP AT_REMOVEDIR 12 +.br +Remove directory instead of file. +.P +The +.IR +header shall define the following symbolic constants for the +.IR advice +argument used by +\fIposix_fadvise\fR(): +.IP POSIX_FADV_DONTNEED 6 +.br +The application expects that it will not access the specified data in +the near future. +.IP POSIX_FADV_NOREUSE 6 +.br +The application expects to access the specified data once and then not +reuse it thereafter. +.IP POSIX_FADV_NORMAL 6 +.br +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_RANDOM 6 +.br +The application expects to access the specified data in a random +order. +.IP POSIX_FADV_SEQUENTIAL 6 +.br +The application expects to access the specified data sequentially from +lower offsets to higher offsets. +.IP POSIX_FADV_WILLNEED 6 +.br +The application expects to access the specified data in the near +future. +.P +The +.IR +header shall define the +.BR flock +structure describing a file lock. It shall include the following members: +.sp +.RS 4 +.nf +\fB +short l_type \fRType of lock; F_RDLCK, F_WRLCK, F_UNLCK.\fR +short l_whence \fRFlag for starting offset.\fR +off_t l_start \fRRelative offset in bytes.\fR +off_t l_len \fRSize; if 0 then until EOF.\fR +pid_t l_pid \fRProcess ID of the process holding the lock; returned with F_GETLK.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR mode_t , +.BR off_t , +and +.BR pid_t +types as described in +.IR . +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int creat(const char *, mode_t); +int fcntl(int, int, ...); +int open(const char *, int, ...); +int openat(int, const char *, int, ...); +int posix_fadvise(int, off_t, off_t, int); +int posix_fallocate(int, off_t, off_t); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may also make visible all symbols from +.IR +and +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Although no existing implementation defines AT_SYMLINK_FOLLOW and +AT_SYMLINK_NOFOLLOW as the same numeric value, POSIX.1\(hy2008 does not prohibit +that as the two constants are not used with the same interfaces. +.SH RATIONALE +While many of the symbolic constants introduced in the +.IR +header do not strictly need to be used in +.BR #if +preprocessor directives, widespread historic practice has defined +them as macros that are usable in such constructs, and examination +of existing applications has shown that they are occasionally used in +such a way. Therefore it was decided to retain this requirement on an +implementation in POSIX.1\(hy2008. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIcreat\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIfutimens\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIposix_fadvise\fR\^(\|)", +.IR "\fIposix_fallocate\fR\^(\|)", +.IR "\fIposix_madvise\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/fenv.h.0p b/man-pages-posix-2013/man0p/fenv.h.0p new file mode 100644 index 0000000..b0b014d --- /dev/null +++ b/man-pages-posix-2013/man0p/fenv.h.0p @@ -0,0 +1,285 @@ +'\" et +.TH fenv.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fenv.h +\(em floating-point environment +.SH SYNOPSIS +.LP +.nf +#include +.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\(hy2008 defers to the ISO\ C standard. +.P +The +.IR +header shall define the following data types through +.BR typedef : +.IP "\fBfenv_t\fR" 10 +Represents the entire floating-point environment. The floating-point +environment refers collectively to any floating-point status flags and +control modes supported by the implementation. +.IP "\fBfexcept_t\fR" 10 +Represents the floating-point status flags collectively, including any +status the implementation associates with the flags. A floating-point +status flag is a system variable whose value is set (but never cleared) +when a floating-point exception is raised, which occurs as a side-effect +of exceptional floating-point arithmetic to provide auxiliary +information. A floating-point control mode is a system variable whose +value may be set by the user to affect the subsequent behavior of +floating-point arithmetic. +.P +The +.IR +header shall define each of the following macros if and only if the +implementation supports the floating-point exception by means of the +floating-point functions +\fIfeclearexcept\fR(), +\fIfegetexceptflag\fR(), +\fIferaiseexcept\fR(), +\fIfesetexceptflag\fR(), +and +\fIfetestexcept\fR(). +The defined macros shall expand to integer constant expressions with +values that are bitwise-distinct. +.sp +.RS +FE_DIVBYZERO +FE_INEXACT +FE_INVALID +FE_OVERFLOW +FE_UNDERFLOW +.RE +.P +If the implementation supports the IEC 60559 Floating-Point option, all +five macros shall be defined. +Additional implementation-defined floating-point exceptions with +macros beginning with FE_ and an uppercase letter may also be +specified by the implementation. +.P +The +.IR +header shall define the macro FE_ALL_EXCEPT as the bitwise-inclusive +OR of all floating-point exception macros defined by the +implementation, if any. If no such macros are defined, then the +macro FE_ALL_EXCEPT shall be defined as zero. +.P +The +.IR +header shall define each of the following macros if and only if the +implementation supports getting and setting the represented rounding +direction by means of the +\fIfegetround\fR() +and +\fIfesetround\fR() +functions. The defined macros shall expand to integer constant +expressions whose values are distinct non-negative values. +.sp +.RS +FE_DOWNWARD +FE_TONEAREST +FE_TOWARDZERO +FE_UPWARD +.RE +.P +If the implementation supports the IEC 60559 Floating-Point option, all +four macros shall be defined. +Additional implementation-defined rounding directions with macros +beginning with FE_ and an uppercase letter may also be specified by the +implementation. +.P +The +.IR +header shall define the following macro, which represents the +default floating-point environment (that is, the one installed at +program startup) and has type pointer to const-qualified +.BR fenv_t . +It can be used as an argument to the functions within the +.IR +header that manage the floating-point environment. +.sp +.RS +FE_DFL_ENV +.RE +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int feclearexcept(int); +int fegetenv(fenv_t *); +int fegetexceptflag(fexcept_t *, int); +int fegetround(void); +int feholdexcept(fenv_t *); +int feraiseexcept(int); +int fesetenv(const fenv_t *); +int fesetexceptflag(const fexcept_t *, int); +int fesetround(int); +int fetestexcept(int); +int feupdateenv(const fenv_t *); +.fi \fR +.P +.RE +.P +The FENV_ACCESS pragma provides a means to inform the implementation +when an application might access the floating-point environment to test +floating-point status flags or run under non-default floating-point +control modes. The pragma shall occur either outside external +declarations or preceding all explicit declarations and statements +inside a compound statement. When outside external declarations, the +pragma takes effect from its occurrence until another FENV_ACCESS +pragma is encountered, or until the end of the translation unit. When +inside a compound statement, the pragma takes effect from its +occurrence until another FENV_ACCESS pragma is encountered (including +within a nested compound statement), or until the end of the compound +statement; at the end of a compound statement the state for the pragma +is restored to its condition just before the compound statement. If +this pragma is used in any other context, the behavior is undefined. If +part of an application tests floating-point status flags, sets +floating-point control modes, or runs under non-default mode settings, +but was translated with the state for the FENV_ACCESS pragma off, the +behavior is undefined. The default state (on or off) for the pragma is +implementation-defined. (When execution passes from a part of the +application translated with FENV_ACCESS off to a part translated with +FENV_ACCESS on, the state of the floating-point status flags is +unspecified and the floating-point control modes have their default +settings.) +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +This header is designed to support the floating-point exception status +flags and directed-rounding control modes required by the IEC\ 60559:\|1989 standard, and +other similar floating-point state information. Also it is designed to +facilitate code portability among all systems. +.P +Certain application programming conventions support the intended model +of use for the floating-point environment: +.IP " *" 4 +A function call does not alter its caller's floating-point control +modes, clear its caller's floating-point status flags, nor depend on +the state of its caller's floating-point status flags unless the +function is so documented. +.IP " *" 4 +A function call is assumed to require default floating-point control +modes, unless its documentation promises otherwise. +.IP " *" 4 +A function call is assumed to have the potential for raising +floating-point exceptions, unless its documentation promises otherwise. +.P +With these conventions, an application can safely assume default +floating-point control modes (or be unaware of them). The +responsibilities associated with accessing the floating-point +environment fall on the application that does so explicitly. +.P +Even though the rounding direction macros may expand to constants +corresponding to the values of FLT_ROUNDS, they are not required to do +so. +.P +For example: +.sp +.RS 4 +.nf +\fB +#include +void f(double x) +{ + #pragma STDC FENV_ACCESS ON + void g(double); + void h(double); + /* ... */ + g(x + 1); + h(x + 1); + /* ... */ +} +.fi \fR +.P +.RE +.P +If the function +\fIg\fR() +might depend on status flags set as a side-effect of the first +.IR x +1, +or if the second +.IR x +1 +might depend on control modes set as a side-effect of the call to +function +\fIg\fR(), +then the application shall contain an appropriately placed invocation +as follows: +.sp +.RS 4 +.nf +\fB +#pragma STDC FENV_ACCESS ON +.fi \fR +.P +.RE +.SH RATIONALE +.SS "The fexcept_t Type" +.P +.BR fexcept_t +does not have to be an integer type. Its values must be obtained by a +call to +\fIfegetexceptflag\fR(), +and cannot be created by logical operations from the exception macros. +An implementation might simply implement +.BR fexcept_t +as an +.BR int +and use the representations reflected by the exception macros, but is +not required to; other representations might contain extra information +about the exceptions. +.BR fexcept_t +might be a +.BR struct +with a member for each exception (that might hold the address of the +first or last floating-point instruction that caused that exception). +The ISO/IEC\ 9899:\|1999 standard makes no claims about the internals of an +.BR fexcept_t , +and so the user cannot inspect it. +.SS "Exception and Rounding Macros" +.P +Macros corresponding to unsupported modes and rounding directions are +not defined by the implementation and must not be defined by the +application. An application might use +.BR #ifdef +to test for this. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfegetenv\fR\^(\|)", +.IR "\fIfegetexceptflag\fR\^(\|)", +.IR "\fIfegetround\fR\^(\|)", +.IR "\fIfeholdexcept\fR\^(\|)", +.IR "\fIferaiseexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIfeupdateenv\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/float.h.0p b/man-pages-posix-2013/man0p/float.h.0p new file mode 100644 index 0000000..f63b661 --- /dev/null +++ b/man-pages-posix-2013/man0p/float.h.0p @@ -0,0 +1,364 @@ +'\" et +.TH float.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of 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 +float.h +\(em floating types +.SH SYNOPSIS +.LP +.nf +#include +.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\(hy2008 defers to the ISO\ C standard. +.P +The characteristics of floating types are defined in terms of a model +that describes a representation of floating-point numbers and values +that provide information about an implementation's floating-point +arithmetic. +.P +The following parameters are used to define the model for each +floating-point type: +.IP "\fIs\fP" 6 +Sign (\(+-1). +.IP "\fIb\fP" 6 +Base or radix of exponent representation (an integer >1). +.IP "\fIe\fP" 6 +Exponent (an integer between a minimum $e_ min$ and a maximum +$e_ max$). +.IP "\fIp\fP" 6 +Precision (the number of base\(mi\fIb\fP digits in the significand). +.IP "$f_ k$" 6 +Non-negative integers less than +.IR b +(the significand digits). +.P +A floating-point number +.IR x +is defined by the following model: +.P +.EQ +x " " = " " sb"^" e" " " " sum from k=1 to p^ " " f_ k" " " " b"^" " "-k , + " " e_ min" " " " <= " " e " " <= " " e_ max" " +.EN +.P +In addition to normalized floating-point numbers ($f_ 1$>0 if +.IR x \(!=0), +floating types may be able to contain other kinds of floating-point +numbers, such as subnormal floating-point numbers (\c +.IR x \(!=0, +.IR e =\c +$e_ min$, $f_ 1$=0) and unnormalized floating-point numbers (\c +.IR x \(!=0, +.IR e >\c +$e_ min$, $f_ 1$=0), and values that are not floating-point +numbers, such as infinities and NaNs. A +.IR NaN +is an encoding signifying Not-a-Number. A +.IR "quiet NaN" +propagates through almost every arithmetic operation without raising a +floating-point exception; a +.IR "signaling NaN" +generally raises a floating-point exception when occurring as an +arithmetic operand. +.P +An implementation may give zero and non-numeric values, such as +infinities and NaNs, a sign, or may leave them unsigned. Wherever such +values are unsigned, any requirement in POSIX.1\(hy2008 to retrieve the +sign shall produce an unspecified sign and any requirement to set the +sign shall be ignored. +.P +The accuracy of the floating-point operations (\c +.BR '+' , +.BR '\(mi' , +.BR '*' , +.BR '/' ) +and of the functions in +.IR +and +.IR +that return floating-point results is implementation-defined, as is the +accuracy of the conversion between floating-point internal +representations and string representations performed by the functions +in +.IR , +.IR , +and +.IR . +The implementation may state that the accuracy is unknown. +.P +All integer values in the +.IR +header, except FLT_ROUNDS, shall be constant expressions suitable for +use in +.BR #if +preprocessing directives; all floating values shall be constant +expressions. All except DECIMAL_DIG, FLT_EVAL_METHOD, FLT_RADIX, and +FLT_ROUNDS have separate names for all three floating-point types. The +floating-point model representation is provided for all values except +FLT_EVAL_METHOD and FLT_ROUNDS. +.P +The rounding mode for floating-point addition is characterized by the +implementation-defined value of FLT_ROUNDS: +.IP "\(mi1" 6 +Indeterminable. +.IP "\00" 6 +Toward zero. +.IP "\01" 6 +To nearest. +.IP "\02" 6 +Toward positive infinity. +.IP "\03" 6 +Toward negative infinity. +.P +All other values for FLT_ROUNDS characterize implementation-defined +rounding behavior. +.P +The values of operations with floating operands and values subject to +the usual arithmetic conversions and of floating constants are +evaluated to a format whose range and precision may be greater than +required by the type. The use of evaluation formats is characterized by +the implementation-defined value of FLT_EVAL_METHOD: +.IP "\(mi1" 6 +Indeterminable. +.IP "\00" 6 +Evaluate all operations and constants just to the range and +precision of the type. +.IP "\01" 6 +Evaluate operations and constants of type +.BR float +and +.BR double +to the range and precision of the +.BR double +type; evaluate +.BR "long double" +operations and constants to the range and precision of the +.BR "long double" +type. +.IP "\02" 6 +Evaluate all operations and constants to the range and precision of the +.BR "long double" +type. +.P +All other negative values for FLT_EVAL_METHOD characterize +implementation-defined behavior. +.P +The +.IR +header shall define the following values as constant expressions with +implementation-defined values that are greater or equal in magnitude +(absolute value) to those shown, with the same sign. +.IP " *" 4 +Radix of exponent representation, +.IR b . +.RS 4 +.IP FLT_RADIX 14 +2 +.RE +.IP " *" 4 +Number of base-FLT_RADIX digits in the floating-point significand, +.IR p . +.RS 4 +.IP FLT_MANT_DIG 14 +.IP DBL_MANT_DIG 14 +.IP LDBL_MANT_DIG 14 +.RE +.IP " *" 4 +Number of decimal digits, +.IR n , +such that any floating-point number in the widest supported floating +type with $p_ max$ radix +.IR b +digits can be rounded to a floating-point number with +.IR n +decimal digits and back again without change to the value. +.RS 4 +.P +.EQ +lpile { p_ max" " " " log_ 10" " " " b above +left ceiling " " 1 " " + " " p_ max" " " " log_ 10" " " " b right ceiling } + " " " " lpile {if " " b " " is " " a " " power " " of " " 10 above otherwise} +.EN +.IP DECIMAL_DIG 14 +10 +.RE +.br +.RE +.IP " *" 4 +Number of decimal digits, +.IR q , +such that any floating-point number with +.IR q +decimal digits can be rounded into a floating-point number with +.IR p +radix +.IR b +digits and back again without change to the +.IR q +decimal digits. +.RS 4 +.P +.EQ +lpile { p " " log_ 10" " " " b above +left floor " " (p " " - " " 1) " " log_ 10" " " " b " " right floor } + " " " " lpile {if " " b " " is " " a " " power " " of " " 10 above otherwise} +.EN +.IP FLT_DIG 14 +6 +.IP DBL_DIG 14 +10 +.IP LDBL_DIG 14 +10 +.RE +.IP " *" 4 +Minimum negative integer such that FLT_RADIX raised to that power +minus 1 is a normalized floating-point number, $e_ min$. +.RS 4 +.IP FLT_MIN_EXP 14 +.IP DBL_MIN_EXP 14 +.IP LDBL_MIN_EXP 14 +.RE +.IP " *" 4 +Minimum negative integer such that 10 raised to that power is in +the range of normalized floating-point numbers. +.RS 4 +.P +.EQ +left ceiling " " log_ 10" " " " b"^" " "{ e_ min" " " " "^" " "-1 } ^ " " right ceiling +.EN +.IP FLT_MIN_10_EXP 14 +\(mi37 +.IP DBL_MIN_10_EXP 14 +\(mi37 +.IP LDBL_MIN_10_EXP 14 +\(mi37 +.RE +.IP " *" 4 +Maximum integer such that FLT_RADIX raised to that power +minus 1 is a representable finite floating-point number, $e_ max$. +.RS 4 +.IP FLT_MAX_EXP 14 +.IP DBL_MAX_EXP 14 +.IP LDBL_MAX_EXP 14 +.P +Additionally, FLT_MAX_EXP shall be at least as large as FLT_MANT_DIG, +DBL_MAX_EXP shall be at least as large as DBL_MANT_DIG, and LDBL_MAX_EXP +shall be at least as large as LDBL_MANT_DIG; which has the effect that +FLT_MAX, DBL_MAX, and LDBL_MAX are integral. +.RE +.IP " *" 4 +Maximum integer such that 10 raised to that power is in the range +of representable finite floating-point numbers. +.RS 4 +.P +.EQ +left floor " " log_ 10" " ( ( 1 " " - " " b"^" " "-p ) " " + b"^" e" "_ max" "^ ) " " right floor +.EN +.IP FLT_MAX_10_EXP 14 ++37 +.IP DBL_MAX_10_EXP 14 ++37 +.IP LDBL_MAX_10_EXP 14 ++37 +.RE +.P +The +.IR +header shall define the following values as constant expressions with +implementation-defined values that are greater than or equal to those +shown: +.IP " *" 4 +Maximum representable finite floating-point number. +.RS 4 +.P +.EQ +(1 " " - " " b"^" " "-p^) " " b"^" e" "_ max" " +.EN +.IP FLT_MAX 14 +1E+37 +.IP DBL_MAX 14 +1E+37 +.IP LDBL_MAX 14 +1E+37 +.RE +.P +The +.IR +header shall define the following values as constant expressions with +implementation-defined (positive) values that are less than or equal to +those shown: +.IP " *" 4 +The difference between 1 and the least value greater than 1 +that is representable in the given floating-point type, $b"^" " "{1 " " - " " p}$. +.RS 4 +.IP FLT_EPSILON 14 +1E\(mi5 +.IP DBL_EPSILON 14 +1E\(mi9 +.IP LDBL_EPSILON 14 +1E\(mi9 +.RE +.IP " *" 4 +Minimum normalized positive floating-point number, +$b"^" " "{ e_ min" " " " "^" " "-1 }$. +.RS 4 +.IP FLT_MIN 14 +1E\(mi37 +.IP DBL_MIN 14 +1E\(mi37 +.IP LDBL_MIN 14 +1E\(mi37 +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +All known hardware floating-point formats satisfy the property that the +exponent range is larger than the number of mantissa digits. The ISO\ C standard +permits a floating-point format where this property is not true, such that +the largest finite value would not be integral; however, it is unlikely +that there will ever be hardware support for such a floating-point format, +and it introduces boundary cases that portable programs should not have +to be concerned with (for example, a non-integral DBL_MAX means that +\fIceil\fR() +would have to worry about overflow). Therefore, this standard imposes +an additional requirement that the largest representable finite value +is integral. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/fmtmsg.h.0p b/man-pages-posix-2013/man0p/fmtmsg.h.0p new file mode 100644 index 0000000..396e812 --- /dev/null +++ b/man-pages-posix-2013/man0p/fmtmsg.h.0p @@ -0,0 +1,129 @@ +'\" et +.TH fmtmsg.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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.h +\(em message display structures +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following symbolic constants: +.IP MM_HARD 14 +Source of the condition is hardware. +.IP MM_SOFT 14 +Source of the condition is software. +.IP MM_FIRM 14 +Source of the condition is firmware. +.IP MM_APPL 14 +Condition detected by application. +.IP MM_UTIL 14 +Condition detected by utility. +.IP MM_OPSYS 14 +Condition detected by operating system. +.IP MM_RECOVER 14 +Recoverable error. +.IP MM_NRECOV 14 +Non-recoverable error. +.IP MM_HALT 14 +Error causing application to halt. +.IP MM_ERROR 14 +Application has encountered a non-fatal fault. +.IP MM_WARNING 14 +Application has detected unusual non-error condition. +.IP MM_INFO 14 +Informative message. +.IP MM_NOSEV 14 +No severity level provided for the message. +.IP MM_PRINT 14 +Display message on standard error. +.IP MM_CONSOLE 14 +Display message on system console. +.P +The table below indicates the null values and identifiers for +\fIfmtmsg\fR() +arguments. The +.IR +header shall define the symbolic constants in the +.BR Identifier +column, which shall have the type indicated in the +.BR Type +column: +.TS +box tab(!) center; +cB | cB | cB | cB +lI | lB | l | l. +Argument!Type!Null-Value!Identifier +_ +label!char *!(\fBchar\fR*)0!MM_NULLLBL +severity!int!0!MM_NULLSEV +class!long!\fB0L\fR!MM_NULLMC +text!char *!(\fBchar\fR*)0!MM_NULLTXT +action!char *!(\fBchar\fR*)0!MM_NULLACT +tag!char *!(\fBchar\fR*)0!MM_NULLTAG +.TE +.P +The +.IR +header shall also define the following symbolic constants for use +as return values for +\fIfmtmsg\fR(): +.IP MM_OK 14 +The function succeeded. +.IP MM_NOTOK 14 +The function failed completely. +.IP MM_NOMSG 14 +The function was unable to generate a message on standard error, but +otherwise succeeded. +.IP MM_NOCON 14 +The function was unable to generate a console message, but otherwise +succeeded. +.P +The following shall be declared as a function and may also be defined +as a macro. A function prototype shall be provided. +.sp +.RS 4 +.nf +\fB +int fmtmsg(long, const char *, int, + const char *, const char *, const char *); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIfmtmsg\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/fnmatch.h.0p b/man-pages-posix-2013/man0p/fnmatch.h.0p new file mode 100644 index 0000000..793945e --- /dev/null +++ b/man-pages-posix-2013/man0p/fnmatch.h.0p @@ -0,0 +1,80 @@ +'\" et +.TH fnmatch.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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.h +\(em filename-matching types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following symbolic constants: +.IP FNM_NOMATCH 14 +The string does not match the specified pattern. +.IP FNM_PATHNAME 14 + +in +.IR string +only matches + +in +.IR pattern . +.IP FNM_PERIOD 14 +Leading + +in +.IR string +must be exactly matched by + +in +.IR pattern . +.IP FNM_NOESCAPE 14 +Disable backslash escaping. +.P +The following shall be declared as a function and may also be defined +as a macro. A function prototype shall be provided. +.sp +.RS 4 +.nf +\fB +int fnmatch(const char *, const char *, int); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIfnmatch\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/ftw.h.0p b/man-pages-posix-2013/man0p/ftw.h.0p new file mode 100644 index 0000000..ecd9c88 --- /dev/null +++ b/man-pages-posix-2013/man0p/ftw.h.0p @@ -0,0 +1,131 @@ +'\" et +.TH ftw.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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.h +\(em file tree traversal +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR FTW +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +int base +int level +.fi \fR +.P +.RE +.P +The +.IR +header shall define the following symbolic constants for use as values +of the third argument to the application-supplied function that is +passed as the second argument to +\fIftw\fR() +and +\fInftw\fR(): +.IP FTW_F 14 +Non-directory file. +.IP FTW_D 14 +Directory. +.IP FTW_DNR 14 +Directory without read permission. +.IP FTW_DP 14 +Directory with subdirectories visited. +.IP FTW_NS 14 +Unknown type; +\fIstat\fR() +failed. +.IP FTW_SL 14 +Symbolic link. +.IP FTW_SLN 14 +Symbolic link that names a nonexistent file. +.P +The +.IR +header shall define the following symbolic constants for use as +values of the fourth argument to +\fInftw\fR(): +.IP FTW_PHYS 14 +Physical walk, does not follow symbolic links. Otherwise, +\fInftw\fR() +follows links but does not walk down any path that crosses itself. +.IP FTW_MOUNT 14 +The walk does not cross a mount point. +.IP FTW_DEPTH 14 +All subdirectories are visited before the directory itself. +.IP FTW_CHDIR 14 +The walk changes to each directory before reading it. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int ftw(const char *, int (*)(const char *, const struct stat *, + int), int); +int nftw(const char *, int (*)(const char *, const struct stat *, + int, struct FTW *), int, int); +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR stat +structure and the symbolic names for +.IR st_mode +and the file type test macros as described in +.IR . +.P +Inclusion of the +.IR +header may also make visible all symbols from +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIftw\fR\^(\|)", +.IR "\fInftw\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/glob.h.0p b/man-pages-posix-2013/man0p/glob.h.0p new file mode 100644 index 0000000..c6eac83 --- /dev/null +++ b/man-pages-posix-2013/man0p/glob.h.0p @@ -0,0 +1,132 @@ +'\" et +.TH glob.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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.h +\(em pathname pattern-matching types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the structures and symbolic constants used by the +\fIglob\fR() +function. +.P +The +.IR +header shall define the +.BR glob_t +structure type, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +size_t gl_pathc \fRCount of paths matched by \fIpattern.\fR +char **gl_pathv \fRPointer to a list of matched pathnames.\fR +size_t gl_offs \fRSlots to reserve at the beginning of \fIgl_pathv.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR size_t +type as described in +.IR . +.P +The +.IR +header shall define the following symbolic constants as values for the +.IR flags +argument: +.IP GLOB_APPEND 14 +Append generated pathnames to those previously obtained. +.IP GLOB_DOOFFS 14 +Specify how many null pointers to add to the beginning of +.IR gl_pathv . +.IP GLOB_ERR 14 +Cause +\fIglob\fR() +to return on error. +.IP GLOB_MARK 14 +Each pathname that is a directory that matches +.IR pattern +has a + +appended. +.IP GLOB_NOCHECK 14 +If +.IR pattern +does not match any pathname, then return a list consisting of only +.IR pattern . +.IP GLOB_NOESCAPE 14 +Disable backslash escaping. +.IP GLOB_NOSORT 14 +Do not sort the pathnames returned. +.P +The +.IR +header shall define the following symbolic constants as error +return values: +.IP GLOB_ABORTED 14 +The scan was stopped because GLOB_ERR was set or (*\fIerrfunc\fP)(\|) +returned non-zero. +.IP GLOB_NOMATCH 14 +The pattern does not match any existing pathname, and GLOB_NOCHECK was +not set in +.IR flags . +.IP GLOB_NOSPACE 14 +An attempt to allocate memory failed. +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int glob(const char *restrict, int, int(*)(const char *, int), + glob_t *restrict); +void globfree(glob_t *); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIglob\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/grp.h.0p b/man-pages-posix-2013/man0p/grp.h.0p new file mode 100644 index 0000000..02033ff --- /dev/null +++ b/man-pages-posix-2013/man0p/grp.h.0p @@ -0,0 +1,93 @@ +'\" et +.TH grp.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +grp.h +\(em group structure +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall declare the +.BR group +structure, which shall include the following members: +.sp +.RS 4 +.nf +\fB +char *gr_name \fRThe name of the group.\fR +gid_t gr_gid \fRNumerical group ID.\fR +char **gr_mem \fRPointer to a null-terminated array of character\fR + \fRpointers to member names.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR gid_t +and +.BR size_t +types as described in +.IR . +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +void endgrent(void); +struct group *getgrent(void); +struct group *getgrgid(gid_t); +int getgrgid_r(gid_t, struct group *, char *, + size_t, struct group **); +struct group *getgrnam(const char *); +int getgrnam_r(const char *, struct group *, char *, + size_t , struct group **); +void setgrent(void); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIendgrent\fR\^(\|)", +.IR "\fIgetgrgid\fR\^(\|)", +.IR "\fIgetgrnam\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/iconv.h.0p b/man-pages-posix-2013/man0p/iconv.h.0p new file mode 100644 index 0000000..0552017 --- /dev/null +++ b/man-pages-posix-2013/man0p/iconv.h.0p @@ -0,0 +1,71 @@ +'\" et +.TH iconv.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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.h +\(em codeset conversion facility +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following types: +.IP "\fBiconv_t\fP" 12 +Identifies the conversion from one codeset to another. +.IP "\fBsize_t\fP" 12 +As described in +.IR . +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +size_t iconv(iconv_t, char **restrict, size_t *restrict, + char **restrict, size_t *restrict); +int iconv_close(iconv_t); +iconv_t iconv_open(const char *, const char *); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIiconv\fR\^(\|)", +.IR "\fIiconv_close\fR\^(\|)", +.IR "\fIiconv_open\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/inttypes.h.0p b/man-pages-posix-2013/man0p/inttypes.h.0p new file mode 100644 index 0000000..4c8ab75 --- /dev/null +++ b/man-pages-posix-2013/man0p/inttypes.h.0p @@ -0,0 +1,242 @@ +'\" et +.TH inttypes.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +inttypes.h +\(em fixed size integer types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends the +ISO\ C standard. Applications shall define the appropriate feature test macro +(see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment") +to enable the visibility of these symbols in this header. +.P +The +.IR +header shall include the +.IR +header. +.P +The +.IR +header shall define at least the following types: +.IP "\fBimaxdiv_t\fR" 12 +Structure type that is the type of the value returned by the +\fIimaxdiv\fR() +function. +.IP "\fBwchar_t\fR" 12 +As described in +.IR . +.P +The +.IR +header shall define the following macros. Each expands to a +character string literal containing a conversion specifier, possibly +modified by a length modifier, suitable for use within the +.IR format +argument of a formatted input/output function when converting the +corresponding integer type. These macros have the general form of +PRI (character string literals for the +\fIfprintf\fR() +and +\fIfwprintf\fR() +family of functions) or SCN (character string literals for the +\fIfscanf\fR() +and +\fIfwscanf\fR() +family of functions), followed by the conversion specifier, followed by +a name corresponding to a similar type name in +.IR . +In these names, +.IR N +represents the width of the type as described in +.IR . +For example, +.IR PRIdFAST32 +can be used in a format string to print the value of an integer of type +.BR int_fast32_t . +.P +The +\fIfprintf\fR() +macros for signed integers are: +.sp +.RS +.TS +tab(!); +le le le le le. +PRId\fIN\fR!PRIdLEAST\fIN\fR!PRIdFAST\fIN\fR!PRIdMAX!PRIdPTR +PRIi\fIN\fR!PRIiLEAST\fIN\fR!PRIiFAST\fIN\fR!PRIiMAX!PRIiPTR +.TE +.RE +.P +The +\fIfprintf\fR() +macros for unsigned integers are: +.sp +.RS +.TS +tab(!); +le le le le le. +PRIo\fIN\fR!PRIoLEAST\fIN\fR!PRIoFAST\fIN\fR!PRIoMAX!PRIoPTR +PRIu\fIN\fR!PRIuLEAST\fIN\fR!PRIuFAST\fIN\fR!PRIuMAX!PRIuPTR +PRIx\fIN\fR!PRIxLEAST\fIN\fR!PRIxFAST\fIN\fR!PRIxMAX!PRIxPTR +PRIX\fIN\fR!PRIXLEAST\fIN\fR!PRIXFAST\fIN\fR!PRIXMAX!PRIXPTR +.TE +.RE +.P +The +\fIfscanf\fR() +macros for signed integers are: +.sp +.RS +.TS +tab(!); +le le le le le. +SCNd\fIN\fR!SCNdLEAST\fIN\fR!SCNdFAST\fIN\fR!SCNdMAX!SCNdPTR +SCNi\fIN\fR!SCNiLEAST\fIN\fR!SCNiFAST\fIN\fR!SCNiMAX!SCNiPTR +.TE +.RE +.P +The +\fIfscanf\fR() +macros for unsigned integers are: +.sp +.RS +.TS +tab(!); +le le le le le. +SCNo\fIN\fR!SCNoLEAST\fIN\fR!SCNoFAST\fIN\fR!SCNoMAX!SCNoPTR +SCNu\fIN\fR!SCNuLEAST\fIN\fR!SCNuFAST\fIN\fR!SCNuMAX!SCNuPTR +SCNx\fIN\fR!SCNxLEAST\fIN\fR!SCNxFAST\fIN\fR!SCNxMAX!SCNxPTR +.TE +.RE +.P +For each type that the implementation provides in +.IR , +the corresponding +\fIfprintf\fR() +and +\fIfwprintf\fR() +macros shall be defined and the corresponding +\fIfscanf\fR() +and +\fIfwscanf\fR() +macros shall be defined unless the implementation does not have a +suitable modifier for the type. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +intmax_t imaxabs(intmax_t); +imaxdiv_t imaxdiv(intmax_t, intmax_t); +intmax_t strtoimax(const char *restrict, char **restrict, int); +uintmax_t strtoumax(const char *restrict, char **restrict, int); +intmax_t wcstoimax(const wchar_t *restrict, wchar_t **restrict, int); +uintmax_t wcstoumax(const wchar_t *restrict, wchar_t **restrict, int); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +.LP +.nf +#include +#include +int main(void) +{ + uintmax_t i = UINTMAX_MAX; // This type always exists. + wprintf(L"The largest integer value is %020" + PRIxMAX "\en", i); + return 0; +} +.fi +.SH "APPLICATION USAGE" +The purpose of +.IR +is to provide a set of integer types whose definitions are consistent +across machines and independent of operating systems and other +implementation idiosyncrasies. It defines, through +.BR typedef , +integer types of various sizes. Implementations are free to +.BR typedef +them as ISO\ C standard integer types or extensions that they support. Consistent +use of this header will greatly increase the portability of applications +across platforms. +.SH RATIONALE +The ISO/IEC\ 9899:\|1990 standard specified that the language should support four signed and +unsigned integer data types\(em\c +.BR char , +.BR short , +.BR int , +and +.BR long \(em\c +but placed very little requirement on their size other than that +.BR int +and +.BR short +be at least 16 bits and +.BR long +be at least as long as +.BR int +and not smaller than 32 bits. For 16-bit systems, most implementations +assigned 8, 16, 16, and 32 bits to +.BR char , +.BR short , +.BR int , +and +.BR long , +respectively. For 32-bit systems, the common practice has been to +assign 8, 16, 32, and 32 bits to these types. This difference in +.BR int +size can create some problems for users who migrate from one system to +another which assigns different sizes to integer types, because the +ISO\ C standard integer promotion rule can produce silent changes unexpectedly. +The need for defining an extended integer type increased with the +introduction of 64-bit systems. +.SH "FUTURE DIRECTIONS" +Macro names beginning with PRI or SCN followed by any lowercase letter +or +.BR 'X' +may be added to the macros defined in the +.IR +header. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment", +.IR "\fIimaxabs\fR\^(\|)", +.IR "\fIimaxdiv\fR\^(\|)", +.IR "\fIstrtoimax\fR\^(\|)", +.IR "\fIwcstoimax\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/iso646.h.0p b/man-pages-posix-2013/man0p/iso646.h.0p new file mode 100644 index 0000000..63d1006 --- /dev/null +++ b/man-pages-posix-2013/man0p/iso646.h.0p @@ -0,0 +1,74 @@ +'\" et +.TH iso646.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +iso646.h +\(em alternative spellings +.SH SYNOPSIS +.LP +.nf +#include +.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\(hy2008 defers to the ISO\ C standard. +.P +The +.IR +header shall define the following eleven macros (on the left) that +expand to the corresponding tokens (on the right): +.IP and 10 +\&\fR&&\fR +.IP and_eq 10 +\&\fR&=\fR +.IP bitand 10 +\&\fR&\fR +.IP bitor 10 +\&\fR|\fR +.IP compl 10 +\&\fR~\fR +.IP not 10 +\&\fR!\fR +.IP not_eq 10 +\&\fR!=\fR +.IP or 10 +\&\fR||\fR +.IP or_eq 10 +\&\fR|=\fR +.IP xor 10 +\&\fR^\fR +.IP xor_eq 10 +\&\fR^=\fR +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +None. +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/langinfo.h.0p b/man-pages-posix-2013/man0p/langinfo.h.0p new file mode 100644 index 0000000..aaf2461 --- /dev/null +++ b/man-pages-posix-2013/man0p/langinfo.h.0p @@ -0,0 +1,195 @@ +'\" et +.TH langinfo.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +langinfo.h +\(em language information constants +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the symbolic constants used to identify items of +.IR langinfo +data (see +\fInl_langinfo\fR()). +.P +The +.IR +header shall define the +.BR locale_t +type as described in +.IR . +.P +The +.IR +header shall define the +.BR nl_item +type as described in +.IR . +.P +The +.IR +header shall define the following symbolic constants with type +.BR nl_item . +The entries under +.BR Category +indicate in which +\fIsetlocale\fR() +category each item is defined. +.TS +box center tab(!); +cB | cB | cB +l1 | lI1 | l. +Constant!Category!Meaning +_ +CODESET!LC_CTYPE!Codeset name. +D_T_FMT!LC_TIME!String for formatting date and time. +D_FMT!LC_TIME!Date format string. +T_FMT!LC_TIME!Time format string. +T_FMT_AMPM!LC_TIME!a.m. or p.m. time format string. +AM_STR!LC_TIME!Ante-meridiem affix. +PM_STR!LC_TIME!Post-meridiem affix. +DAY_1!LC_TIME!Name of the first day of the week (for example, Sunday). +DAY_2!LC_TIME!Name of the second day of the week (for example, Monday). +DAY_3!LC_TIME!Name of the third day of the week (for example, Tuesday). +DAY_4!LC_TIME!Name of the fourth day of the week + !!(for example, Wednesday). +DAY_5!LC_TIME!Name of the fifth day of the week (for example, Thursday). +DAY_6!LC_TIME!Name of the sixth day of the week (for example, Friday). +DAY_7!LC_TIME!Name of the seventh day of the week + !!(for example, Saturday). +ABDAY_1!LC_TIME!Abbreviated name of the first day of the week. +ABDAY_2!LC_TIME!Abbreviated name of the second day of the week. +ABDAY_3!LC_TIME!Abbreviated name of the third day of the week. +ABDAY_4!LC_TIME!Abbreviated name of the fourth day of the week. +ABDAY_5!LC_TIME!Abbreviated name of the fifth day of the week. +ABDAY_6!LC_TIME!Abbreviated name of the sixth day of the week. +ABDAY_7!LC_TIME!Abbreviated name of the seventh day of the week. +MON_1!LC_TIME!Name of the first month of the year. +MON_2!LC_TIME!Name of the second month. +MON_3!LC_TIME!Name of the third month. +MON_4!LC_TIME!Name of the fourth month. +MON_5!LC_TIME!Name of the fifth month. +MON_6!LC_TIME!Name of the sixth month. +MON_7!LC_TIME!Name of the seventh month. +MON_8!LC_TIME!Name of the eighth month. +MON_9!LC_TIME!Name of the ninth month. +MON_10!LC_TIME!Name of the tenth month. +MON_11!LC_TIME!Name of the eleventh month. +MON_12!LC_TIME!Name of the twelfth month. +ABMON_1!LC_TIME!Abbreviated name of the first month. +ABMON_2!LC_TIME!Abbreviated name of the second month. +ABMON_3!LC_TIME!Abbreviated name of the third month. +ABMON_4!LC_TIME!Abbreviated name of the fourth month. +ABMON_5!LC_TIME!Abbreviated name of the fifth month. +ABMON_6!LC_TIME!Abbreviated name of the sixth month. +ABMON_7!LC_TIME!Abbreviated name of the seventh month. +ABMON_8!LC_TIME!Abbreviated name of the eighth month. +ABMON_9!LC_TIME!Abbreviated name of the ninth month. +ABMON_10!LC_TIME!Abbreviated name of the tenth month. +ABMON_11!LC_TIME!Abbreviated name of the eleventh month. +ABMON_12!LC_TIME!Abbreviated name of the twelfth month. +ERA!LC_TIME!Era description segments. +ERA_D_FMT!LC_TIME!Era date format string. +ERA_D_T_FMT!LC_TIME!Era date and time format string. +ERA_T_FMT!LC_TIME!Era time format string. +ALT_DIGITS!LC_TIME!Alternative symbols for digits. +RADIXCHAR!LC_NUMERIC!Radix character. +THOUSEP!LC_NUMERIC!Separator for thousands. +YESEXPR!LC_MESSAGES!Affirmative response expression. +NOEXPR!LC_MESSAGES!Negative response expression. +CRNCYSTR!LC_MONETARY!T{ +Local currency symbol, preceded by +.BR '\(mi' +if the symbol should appear before the value, +.BR '+' +if the symbol should appear after the value, or +.BR '.' +if the symbol should replace the radix character. If the local +currency symbol is the empty string, implementations may return +the empty string (\c +.BR \(dq\&\(dq ). +T} +.TE +.P +If the locale's values for +.BR p_cs_precedes +and +.BR n_cs_precedes +do not match, the value of +.IR nl_langinfo (CRNCYSTR) +and +.IR nl_langinfo_l (CRNCYSTR,loc) +is unspecified. +.P +The following shall be declared as a function and may also be defined +as a macro. A function prototype shall be provided. +.sp +.RS 4 +.nf +\fB +char *nl_langinfo(nl_item); +char *nl_langinfo_l(nl_item, locale_t); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may also make visible all symbols from +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Wherever possible, users are advised to use functions compatible with +those in the ISO\ C standard to access items of +.IR langinfo +data. In particular, the +\fIstrftime\fR() +function should be used to access date and time information defined in +category +.IR LC_TIME . +The +\fIlocaleconv\fR() +function should be used to access information corresponding to +RADIXCHAR, THOUSEP, and CRNCYSTR. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fInl_langinfo\fR\^(\|)", +.IR "\fIlocaleconv\fR\^(\|)", +.IR "\fIstrfmon\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/libgen.h.0p b/man-pages-posix-2013/man0p/libgen.h.0p new file mode 100644 index 0000000..43a020c --- /dev/null +++ b/man-pages-posix-2013/man0p/libgen.h.0p @@ -0,0 +1,57 @@ +'\" et +.TH libgen.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +libgen.h +\(em definitions for pattern matching functions +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +char *basename(char *); +char *dirname(char *); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIbasename\fR\^(\|)", +.IR "\fIdirname\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/limits.h.0p b/man-pages-posix-2013/man0p/limits.h.0p new file mode 100644 index 0000000..6f126d5 --- /dev/null +++ b/man-pages-posix-2013/man0p/limits.h.0p @@ -0,0 +1,1179 @@ +'\" et +.TH limits.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +limits.h +\(em implementation-defined constants +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends the +ISO\ C standard. Applications shall define the appropriate feature test macro +(see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment") +to enable the visibility of these symbols in this header. +.P +Many of the symbols listed here are not defined by the ISO/IEC\ 9899:\|1999 standard. Such symbols +are not shown as CX shaded, except under the heading ``Numerical Limits''. +.P +The +.IR +header shall define macros and symbolic constants for various limits. +Different categories of limits are described below, representing various +limits on resources that the implementation imposes on applications. +All macros and symbolic constants defined in this header shall be +suitable for use in +.BR #if +preprocessing directives. +.P +Implementations may choose any appropriate value for each limit, +provided it is not more restrictive than the Minimum Acceptable Values +listed below. Symbolic constant names beginning with _POSIX may be +found in +.IR . +.P +Applications should not assume any particular value for a limit. To +achieve maximum portability, an application should not require more +resource than the Minimum Acceptable Value quantity. However, an +application wishing to avail itself of the full amount of a resource +available on an implementation may make use of the value given in +.IR +on that particular implementation, by using the macros and symbolic +constants listed below. It should be noted, however, that many of the +listed limits are not invariant, and at runtime, the value of the limit +may differ from those given in this header, for the following reasons: +.IP " *" 4 +The limit is pathname-dependent. +.IP " *" 4 +The limit differs between the compile and runtime machines. +.P +For these reasons, an application may use the +\fIfpathconf\fR(), +\fIpathconf\fR(), +and +\fIsysconf\fR() +functions to determine the actual value of a limit at runtime. +.P +The items in the list ending in _MIN give the most negative values that +the mathematical types are guaranteed to be capable of representing. +Numbers of a more negative value may be supported on some +implementations, as indicated by the +.IR +header on the implementation, but applications requiring such numbers +are not guaranteed to be portable to all implementations. For positive +constants ending in _MIN, this indicates the minimum acceptable value. +.SS "Runtime Invariant Values (Possibly Indeterminate)" +.P +A definition of one of the symbolic constants in the following list +shall be omitted from +.IR +on specific implementations where the corresponding value is equal to +or greater than the stated minimum, but is unspecified. +.P +This indetermination might depend on the amount of available memory +space on a specific instance of a specific implementation. The actual +value supported by a specific instance shall be provided by the +\fIsysconf\fR() +function. +.IP {AIO_LISTIO_MAX} 6 +.br +Maximum number of I/O operations in a single list I/O call supported by +the implementation. +.br +Minimum Acceptable Value: +{_POSIX_AIO_LISTIO_MAX} +.IP {AIO_MAX} 6 +.br +Maximum number of outstanding asynchronous I/O operations supported by +the implementation. +.br +Minimum Acceptable Value: +{_POSIX_AIO_MAX} +.IP {AIO_PRIO_DELTA_MAX} 6 +.br +The maximum amount by which a process can decrease its asynchronous I/O +priority level from its own scheduling priority. +.br +Minimum Acceptable Value: 0 +.IP {ARG_MAX} 6 +.br +Maximum length of argument to the +.IR exec +functions including environment data. +.br +Minimum Acceptable Value: +{_POSIX_ARG_MAX} +.IP {ATEXIT_MAX} 6 +.br +Maximum number of functions that may be registered with +\fIatexit\fR(). +.br +Minimum Acceptable Value: 32 +.IP {CHILD_MAX} 6 +.br +Maximum number of simultaneous processes per real user ID. +.br +Minimum Acceptable Value: +{_POSIX_CHILD_MAX} +.IP {DELAYTIMER_MAX} 6 +.br +Maximum number of timer expiration overruns. +.br +Minimum Acceptable Value: +{_POSIX_DELAYTIMER_MAX} +.IP {HOST_NAME_MAX} 6 +.br +Maximum length of a host name (not including the terminating null) +as returned from the +\fIgethostname\fR() +function. +.br +Minimum Acceptable Value: +{_POSIX_HOST_NAME_MAX} +.IP {IOV_MAX} 6 +.br +Maximum number of +.BR iovec +structures that one process has available for use with +\fIreadv\fR() +or +\fIwritev\fR(). +.br +Minimum Acceptable Value: +{_XOPEN_IOV_MAX} +.IP {LOGIN_NAME_MAX} 6 +.br +Maximum length of a login name. +.br +Minimum Acceptable Value: +{_POSIX_LOGIN_NAME_MAX} +.IP {MQ_OPEN_MAX} 6 +.br +The maximum number of open message queue descriptors a process may +hold. +.br +Minimum Acceptable Value: +{_POSIX_MQ_OPEN_MAX} +.IP {MQ_PRIO_MAX} 6 +.br +The maximum number of message priorities supported by the implementation. +.br +Minimum Acceptable Value: +{_POSIX_MQ_PRIO_MAX} +.IP {OPEN_MAX} 6 +.br +A value one greater than the maximum value that the system may +assign to a newly-created file descriptor. +.br +Minimum Acceptable Value: +{_POSIX_OPEN_MAX} +.IP {PAGESIZE} 6 +.br +Size in bytes of a page. +.br +Minimum Acceptable Value: 1 +.IP {PAGE_SIZE} 6 +.br +Equivalent to +{PAGESIZE}. +If either +{PAGESIZE} +or +{PAGE_SIZE} +is defined, the other is defined with the same value. +.IP {PTHREAD_DESTRUCTOR_ITERATIONS} 6 +.br +Maximum number of attempts made to destroy a thread's thread-specific +data values on thread exit. +.br +Minimum Acceptable Value: +{_POSIX_THREAD_DESTRUCTOR_ITERATIONS} +.IP {PTHREAD_KEYS_MAX} 6 +.br +Maximum number of data keys that can be created by a process. +.br +Minimum Acceptable Value: +{_POSIX_THREAD_KEYS_MAX} +.IP {PTHREAD_STACK_MIN} 6 +.br +Minimum size in bytes of thread stack storage. +.br +Minimum Acceptable Value: 0 +.IP {PTHREAD_THREADS_MAX} 6 +.br +Maximum number of threads that can be created per process. +.br +Minimum Acceptable Value: +{_POSIX_THREAD_THREADS_MAX} +.IP {RE_DUP_MAX} 6 +.br +Maximum number of repeated occurrences of a BRE or ERE interval +expression; see +.IR "Section 9.3.6" ", " "BREs Matching Multiple Characters" +and +.IR "Section 9.4.6" ", " "EREs Matching Multiple Characters". +.br +Minimum Acceptable Value: +{_POSIX2_RE_DUP_MAX} +.IP {RTSIG_MAX} 6 +.br +Maximum number of realtime signals reserved for application use in this +implementation. +.br +Minimum Acceptable Value: +{_POSIX_RTSIG_MAX} +.IP {SEM_NSEMS_MAX} 6 +.br +Maximum number of semaphores that a process may have. +.br +Minimum Acceptable Value: +{_POSIX_SEM_NSEMS_MAX} +.IP {SEM_VALUE_MAX} 6 +.br +The maximum value a semaphore may have. +.br +Minimum Acceptable Value: +{_POSIX_SEM_VALUE_MAX} +.IP {SIGQUEUE_MAX} 6 +.br +Maximum number of queued signals that a process may send and have +pending at the receiver(s) at any time. +.br +Minimum Acceptable Value: +{_POSIX_SIGQUEUE_MAX} +.IP {SS_REPL_MAX} 6 +.br +The maximum number of replenishment operations that may be simultaneously +pending for a particular sporadic server scheduler. +.br +Minimum Acceptable Value: +{_POSIX_SS_REPL_MAX} +.IP {STREAM_MAX} 6 +.br +Maximum number of streams that one process can have open at one time. +If defined, it has the same value as +{FOPEN_MAX} +(see +.IR ). +.br +Minimum Acceptable Value: +{_POSIX_STREAM_MAX} +.IP {SYMLOOP_MAX} 6 +.br +Maximum number of symbolic links that can be reliably traversed in the +resolution of a pathname in the absence of a loop. +.br +Minimum Acceptable Value: +{_POSIX_SYMLOOP_MAX} +.IP {TIMER_MAX} 6 +.br +Maximum number of timers per process supported by the implementation. +.br +Minimum Acceptable Value: +{_POSIX_TIMER_MAX} +.IP {TRACE_EVENT_NAME_MAX} 6 +.br +Maximum length of the trace event name (not including the terminating null). +.br +Minimum Acceptable Value: +{_POSIX_TRACE_EVENT_NAME_MAX} +.IP {TRACE_NAME_MAX} 6 +.br +Maximum length of the trace generation version string or of the +trace stream name (not including the terminating null). +.br +Minimum Acceptable Value: +{_POSIX_TRACE_NAME_MAX} +.IP {TRACE_SYS_MAX} 6 +.br +Maximum number of trace streams that may simultaneously exist in +the system. +.br +Minimum Acceptable Value: +{_POSIX_TRACE_SYS_MAX} +.IP {TRACE_USER_EVENT_MAX} 6 +.br +Maximum number of user trace event type identifiers that may +simultaneously exist in a traced process, including the predefined +user trace event POSIX_TRACE_UNNAMED_USER_EVENT. +.br +Minimum Acceptable Value: +{_POSIX_TRACE_USER_EVENT_MAX} +.IP {TTY_NAME_MAX} 6 +.br +Maximum length of terminal device name. +.br +Minimum Acceptable Value: +{_POSIX_TTY_NAME_MAX} +.IP {TZNAME_MAX} 6 +.br +Maximum number of bytes supported for the name of a timezone (not of +the +.IR TZ +variable). +.br +Minimum Acceptable Value: +{_POSIX_TZNAME_MAX} +.TP 10 +.BR Note: +The length given by +{TZNAME_MAX} +does not include the quoting characters mentioned in +.IR "Section 8.3" ", " "Other Environment Variables". +.P +.SS "Pathname Variable Values" +.P +The values in the following list may be constants within an +implementation or may vary from one pathname to another. For example, +file systems or directories may have different characteristics. +.P +A definition of one of the symbolic constants in the following list +shall be omitted from the +.IR +header on specific implementations where the corresponding value is +equal to or greater than the stated minimum, but where the value can +vary depending on the file to which it is applied. The actual value +supported for a specific pathname shall be provided by the +\fIpathconf\fR() +function. +.IP {FILESIZEBITS} 6 +.br +Minimum number of bits needed to represent, as a signed integer value, +the maximum size of a regular file allowed in the specified directory. +.br +Minimum Acceptable Value: 32 +.IP {LINK_MAX} 6 +.br +Maximum number of links to a single file. +.br +Minimum Acceptable Value: +{_POSIX_LINK_MAX} +.IP {MAX_CANON} 6 +.br +Maximum number of bytes in a terminal canonical input line. +.br +Minimum Acceptable Value: +{_POSIX_MAX_CANON} +.IP {MAX_INPUT} 6 +.br +Minimum number of bytes for which space is available in a terminal +input queue; therefore, the maximum number of bytes a conforming +application may require to be typed as input before reading them. +.br +Minimum Acceptable Value: +{_POSIX_MAX_INPUT} +.IP {NAME_MAX} 6 +.br +Maximum number of bytes in a filename (not including the terminating +null of a filename string). +.br +Minimum Acceptable Value: +{_POSIX_NAME_MAX} +.br +Minimum Acceptable Value: +{_XOPEN_NAME_MAX} +.IP {PATH_MAX} 6 +.br +Maximum number of bytes the implementation will store as a pathname in +a user-supplied buffer of unspecified size, including the terminating +null character. Minimum number the implementation will accept as the +maximum number of bytes in a pathname. +.br +Minimum Acceptable Value: +{_POSIX_PATH_MAX} +.br +Minimum Acceptable Value: +{_XOPEN_PATH_MAX} +.IP {PIPE_BUF} 6 +.br +Maximum number of bytes that is guaranteed to be atomic when writing to +a pipe. +.br +Minimum Acceptable Value: +{_POSIX_PIPE_BUF} +.IP {POSIX_ALLOC_SIZE_MIN} 6 +.br +Minimum number of bytes of storage actually allocated for any portion +of a file. +.br +Minimum Acceptable Value: Not specified. +.IP {POSIX_REC_INCR_XFER_SIZE} 6 +.br +Recommended increment for file transfer sizes between the +{POSIX_REC_MIN_XFER_SIZE} +and +{POSIX_REC_MAX_XFER_SIZE} +values. +.br +Minimum Acceptable Value: Not specified. +.IP {POSIX_REC_MAX_XFER_SIZE} 6 +.br +Maximum recommended file transfer size. +.br +Minimum Acceptable Value: Not specified. +.IP {POSIX_REC_MIN_XFER_SIZE} 6 +.br +Minimum recommended file transfer size. +.br +Minimum Acceptable Value: Not specified. +.IP {POSIX_REC_XFER_ALIGN} 6 +.br +Recommended file transfer buffer alignment. +.br +Minimum Acceptable Value: Not specified. +.IP {SYMLINK_MAX} 6 +.br +Maximum number of bytes in a symbolic link. +.br +Minimum Acceptable Value: +{_POSIX_SYMLINK_MAX} +.SS "Runtime Increasable Values" +.P +The magnitude limitations in the following list shall be fixed by +specific implementations. An application should assume that the value +of the symbolic constant defined by +.IR +in a specific implementation is the minimum that pertains whenever the +application is run under that implementation. A specific instance of a +specific implementation may increase the value relative to that +supplied by +.IR +for that implementation. The actual value supported by a specific +instance shall be provided by the +\fIsysconf\fR() +function. +.IP {BC_BASE_MAX} 6 +.br +Maximum +.IR obase +values allowed by the +.IR bc +utility. +.br +Minimum Acceptable Value: +{_POSIX2_BC_BASE_MAX} +.IP {BC_DIM_MAX} 6 +.br +Maximum number of elements permitted in an array by the +.IR bc +utility. +.br +Minimum Acceptable Value: +{_POSIX2_BC_DIM_MAX} +.IP {BC_SCALE_MAX} 6 +.br +Maximum +.IR scale +value allowed by the +.IR bc +utility. +.br +Minimum Acceptable Value: +{_POSIX2_BC_SCALE_MAX} +.IP {BC_STRING_MAX} 6 +.br +Maximum length of a string constant accepted by the +.IR bc +utility. +.br +Minimum Acceptable Value: +{_POSIX2_BC_STRING_MAX} +.IP {CHARCLASS_NAME_MAX} 6 +.br +Maximum number of bytes in a character class name. +.br +Minimum Acceptable Value: +{_POSIX2_CHARCLASS_NAME_MAX} +.IP {COLL_WEIGHTS_MAX} 6 +.br +Maximum number of weights that can be assigned to an entry of the +.IR LC_COLLATE +.BR order +keyword in the locale definition file; see +.IR "Chapter 7" ", " "Locale". +.br +Minimum Acceptable Value: +{_POSIX2_COLL_WEIGHTS_MAX} +.IP {EXPR_NEST_MAX} 6 +.br +Maximum number of expressions that can be nested within parentheses by +the +.IR expr +utility. +.br +Minimum Acceptable Value: +{_POSIX2_EXPR_NEST_MAX} +.IP {LINE_MAX} 6 +.br +Unless otherwise noted, the maximum length, in bytes, of a utility's +input line (either standard input or another file), when the utility is +described as processing text files. The length includes room for the +trailing +. +.br +Minimum Acceptable Value: +{_POSIX2_LINE_MAX} +.IP {NGROUPS_MAX} 6 +.br +Maximum number of simultaneous supplementary group IDs per process. +.br +Minimum Acceptable Value: +{_POSIX_NGROUPS_MAX} +.IP {RE_DUP_MAX} 6 +.br +Maximum number of repeated occurrences of a regular expression +permitted when using the interval notation \e{\fIm\fP,\fIn\fP\e}; see +.IR "Chapter 9" ", " "Regular Expressions". +.br +Minimum Acceptable Value: +{_POSIX2_RE_DUP_MAX} +.SS "Maximum Values" +.P +The +.IR +header shall define the following symbolic constants with the values +shown. These are the most restrictive values for certain features on +an implementation. A conforming implementation shall provide values no +larger than these values. A conforming application must not require a +smaller value for correct operation. +.IP {_POSIX_CLOCKRES_MIN} 6 +.br +The resolution of the CLOCK_REALTIME clock, in nanoseconds. +.br +Value: 20 000 000 +.RS 6 +.P +If the Monotonic Clock option is supported, the resolution of the +CLOCK_MONOTONIC clock, in nanoseconds, is represented by +{_POSIX_CLOCKRES_MIN}. +.RE +.SS "Minimum Values" +.P +The +.IR +header shall define the following symbolic constants with the values +shown. These are the most restrictive values for certain features on +an implementation conforming to this volume of POSIX.1\(hy2008. Related symbolic constants are +defined elsewhere in this volume of POSIX.1\(hy2008 which reflect the actual implementation and +which need not be as restrictive. For each of these limits, a conforming +implementation shall provide a value at least this large or shall have +no limit. A strictly conforming application must not require a larger +value for correct operation. +.IP {_POSIX_AIO_LISTIO_MAX} 6 +.br +The number of I/O operations that can be specified in a list I/O call. +.br +Value: 2 +.IP {_POSIX_AIO_MAX} 6 +.br +The number of outstanding asynchronous I/O operations. +.br +Value: 1 +.IP {_POSIX_ARG_MAX} 6 +.br +Maximum length of argument to the +.IR exec +functions including environment data. +.br +Value: 4 096 +.IP {_POSIX_CHILD_MAX} 6 +.br +Maximum number of simultaneous processes per real user ID. +.br +Value: 25 +.IP {_POSIX_DELAYTIMER_MAX} 6 +.br +The number of timer expiration overruns. +.br +Value: 32 +.IP {_POSIX_HOST_NAME_MAX} 6 +.br +Maximum length of a host name (not including the terminating null) +as returned from the +\fIgethostname\fR() +function. +.br +Value: 255 +.IP {_POSIX_LINK_MAX} 6 +.br +Maximum number of links to a single file. +.br +Value: 8 +.IP {_POSIX_LOGIN_NAME_MAX} 6 +.br +The size of the storage required for a login name, in bytes +(including the terminating null). +.br +Value: 9 +.IP {_POSIX_MAX_CANON} 6 +.br +Maximum number of bytes in a terminal canonical input queue. +.br +Value: 255 +.IP {_POSIX_MAX_INPUT} 6 +.br +Maximum number of bytes allowed in a terminal input queue. +.br +Value: 255 +.IP {_POSIX_MQ_OPEN_MAX} 6 +.br +The number of message queues that can be open for a single process. +.br +Value: 8 +.IP {_POSIX_MQ_PRIO_MAX} 6 +.br +The maximum number of message priorities supported by the implementation. +.br +Value: 32 +.IP {_POSIX_NAME_MAX} 6 +.br +Maximum number of bytes in a filename (not including the terminating +null of a filename string). +.br +Value: 14 +.IP {_POSIX_NGROUPS_MAX} 6 +.br +Maximum number of simultaneous supplementary group IDs per process. +.br +Value: 8 +.IP {_POSIX_OPEN_MAX} 6 +.br +A value one greater than the maximum value that the system may assign +to a newly-created file descriptor. +.br +Value: 20 +.IP {_POSIX_PATH_MAX} 6 +.br +Minimum number the implementation will accept as the maximum number of +bytes in a pathname. +.br +Value: 256 +.IP {_POSIX_PIPE_BUF} 6 +.br +Maximum number of bytes that is guaranteed to be atomic when writing to +a pipe. +.br +Value: 512 +.IP {_POSIX_RE_DUP_MAX} 6 +.br +The number of repeated occurrences of a BRE permitted by the +\fIregexec\fR() +and +\fIregcomp\fR() +functions when using the interval notation {\e(\fIm\fR,\fIn\fR\e}; see +.IR "Section 9.3.6" ", " "BREs Matching Multiple Characters". +.br +Value: 255 +.IP {_POSIX_RTSIG_MAX} 6 +.br +The number of realtime signal numbers reserved for application use. +.br +Value: 8 +.IP {_POSIX_SEM_NSEMS_MAX} 6 +.br +The number of semaphores that a process may have. +.br +Value: 256 +.IP {_POSIX_SEM_VALUE_MAX} 6 +.br +The maximum value a semaphore may have. +.br +Value: 32 767 +.IP {_POSIX_SIGQUEUE_MAX} 6 +.br +The number of queued signals that a process may send and have pending +at the receiver(s) at any time. +.br +Value: 32 +.IP {_POSIX_SSIZE_MAX} 6 +.br +The value that can be stored in an object of type +.BR ssize_t . +.br +Value: 32 767 +.IP {_POSIX_SS_REPL_MAX} 6 +.br +The number of replenishment operations that may be simultaneously +pending for a particular sporadic server scheduler. +.br +Value: 4 +.IP {_POSIX_STREAM_MAX} 6 +.br +The number of streams that one process can have open at one time. +.br +Value: 8 +.IP {_POSIX_SYMLINK_MAX} 6 +.br +The number of bytes in a symbolic link. +.br +Value: 255 +.IP {_POSIX_SYMLOOP_MAX} 6 +.br +The number of symbolic links that can be traversed in the resolution of +a pathname in the absence of a loop. +.br +Value: 8 +.IP {_POSIX_THREAD_DESTRUCTOR_ITERATIONS} 6 +.br +The number of attempts made to destroy a thread's thread-specific data +values on thread exit. +.br +Value: 4 +.IP {_POSIX_THREAD_KEYS_MAX} 6 +.br +The number of data keys per process. +.br +Value: 128 +.IP {_POSIX_THREAD_THREADS_MAX} 6 +.br +The number of threads per process. +.br +Value: 64 +.IP {_POSIX_TIMER_MAX} 6 +.br +The per-process number of timers. +.br +Value: 32 +.IP {_POSIX_TRACE_EVENT_NAME_MAX} 6 +.br +The length in bytes of a trace event name (not including the terminating null). +.br +Value: 30 +.IP {_POSIX_TRACE_NAME_MAX} 6 +.br +The length in bytes of a trace generation version string or a trace +stream name (not including the terminating null). +.br +Value: 8 +.IP {_POSIX_TRACE_SYS_MAX} 6 +.br +The number of trace streams that may simultaneously exist in the system. +.br +Value: 8 +.IP {_POSIX_TRACE_USER_EVENT_MAX} 6 +.br +The number of user trace event type identifiers that may simultaneously +exist in a traced process, including the predefined user trace event +POSIX_TRACE_UNNAMED_USER_EVENT. +.br +Value: 32 +.IP {_POSIX_TTY_NAME_MAX} 6 +.br +The size of the storage required for a terminal device name, in bytes +(including the terminating null). +.br +Value: 9 +.IP {_POSIX_TZNAME_MAX} 6 +.br +Maximum number of bytes supported for the name of a timezone (not of +the +.IR TZ +variable). +.br +Value: 6 +.RS 6 +.TP 10 +.BR Note: +The length given by +{_POSIX_TZNAME_MAX} +does not include the quoting characters mentioned in +.IR "Section 8.3" ", " "Other Environment Variables". +.P +.RE +.IP {_POSIX2_BC_BASE_MAX} 6 +.br +Maximum +.IR obase +values allowed by the +.IR bc +utility. +.br +Value: 99 +.IP {_POSIX2_BC_DIM_MAX} 6 +.br +Maximum number of elements permitted in an array by the +.IR bc +utility. +.br +Value: 2 048 +.IP {_POSIX2_BC_SCALE_MAX} 6 +.br +Maximum +.IR scale +value allowed by the +.IR bc +utility. +.br +Value: 99 +.IP {_POSIX2_BC_STRING_MAX} 6 +.br +Maximum length of a string constant accepted by the +.IR bc +utility. +.br +Value: 1 000 +.IP {_POSIX2_CHARCLASS_NAME_MAX} 6 +.br +Maximum number of bytes in a character class name. +.br +Value: 14 +.IP {_POSIX2_COLL_WEIGHTS_MAX} 6 +.br +Maximum number of weights that can be assigned to an entry of the +.IR LC_COLLATE +.BR order +keyword in the locale definition file; see +.IR "Chapter 7" ", " "Locale". +.br +Value: 2 +.IP {_POSIX2_EXPR_NEST_MAX} 6 +.br +Maximum number of expressions that can be nested within parentheses by +the +.IR expr +utility. +.br +Value: 32 +.IP {_POSIX2_LINE_MAX} 6 +.br +Unless otherwise noted, the maximum length, in bytes, of a utility's +input line (either standard input or another file), when the utility is +described as processing text files. The length includes room for the +trailing +. +.br +Value: 2 048 +.IP {_POSIX2_RE_DUP_MAX} 6 +.br +Maximum number of repeated occurrences of a regular expression +permitted when using the interval notation \e{\fIm\fP,\fIn\fP\e}; see +.IR "Chapter 9" ", " "Regular Expressions". +.br +Value: 255 +.IP {_XOPEN_IOV_MAX} 6 +.br +Maximum number of +.BR iovec +structures that one process has available for use with +\fIreadv\fR() +or +\fIwritev\fR(). +.br +Value: 16 +.IP {_XOPEN_NAME_MAX} 6 +.br +Maximum number of bytes in a filename (not including the terminating +null of a filename string). +.br +Value: 255 +.IP {_XOPEN_PATH_MAX} 6 +.br +Minimum number the implementation will accept as the maximum number of +bytes in a pathname. +.br +Value: 1\|024 +.SS "Numerical Limits" +.P +The +.IR +header shall define the following macros and, except for +{CHAR_BIT}, +{LONG_BIT}, +{MB_LEN_MAX}, +and +{WORD_BIT}, +they shall be replaced by expressions that have the same type as +would an expression that is an object of the corresponding type +converted according to the integer promotions. +.P +If the value of an object of type +.BR char +is treated as a signed integer when used in an expression, the value of +{CHAR_MIN} +is the same as that of +{SCHAR_MIN} +and the value of +{CHAR_MAX} +is the same as that of +{SCHAR_MAX}. +Otherwise, the value of +{CHAR_MIN} +is 0 and the value of +{CHAR_MAX} +is the same as that of +{UCHAR_MAX}. +.IP {CHAR_BIT} 6 +.br +Number of bits in a type +.BR char . +.br +Value: 8 +.IP {CHAR_MAX} 6 +.br +Maximum value for an object of type +.BR char . +.br +Value: +{UCHAR_MAX} +or +{SCHAR_MAX} +.IP {CHAR_MIN} 6 +.br +Minimum value for an object of type +.BR char . +.br +Value: +{SCHAR_MIN} +or 0 +.IP {INT_MAX} 6 +.br +Maximum value for an object of type +.BR int . +.br +Minimum Acceptable Value: 2 147 483 647 +.IP {INT_MIN} 6 +.br +Minimum value for an object of type +.BR int . +.br +Maximum Acceptable Value: \(mi2 147 483 647 +.IP {LLONG_MAX} 6 +.br +Maximum value for an object of type +.BR "long long" . +.br +Minimum Acceptable Value: +9\|223\|372\|036\|854\|775\|807 +.IP {LLONG_MIN} 6 +.br +Minimum value for an object of type +.BR "long long" . +.br +Maximum Acceptable Value: \(mi9\|223\|372\|036\|854\|775\|807 +.IP {LONG_BIT} 6 +.br +Number of bits in an object of type +.BR long . +.br +Minimum Acceptable Value: 32 +.IP {LONG_MAX} 6 +.br +Maximum value for an object of type +.BR long . +.br +Minimum Acceptable Value: +2 147 483 647 +.IP {LONG_MIN} 6 +.br +Minimum value for an object of type +.BR long . +.br +Maximum Acceptable Value: \(mi2 147 483 647 +.IP {MB_LEN_MAX} 6 +.br +Maximum number of bytes in a character, for any supported locale. +.br +Minimum Acceptable Value: 1 +.IP {SCHAR_MAX} 6 +.br +Maximum value for an object of type +.BR "signed char" . +.br +Value: +127 +.IP {SCHAR_MIN} 6 +.br +Minimum value for an object of type +.BR "signed char" . +.br +Value: \(mi128 +.IP {SHRT_MAX} 6 +.br +Maximum value for an object of type +.BR short . +.br +Minimum Acceptable Value: +32 767 +.IP {SHRT_MIN} 6 +.br +Minimum value for an object of type +.BR short . +.br +Maximum Acceptable Value: \(mi32 767 +.IP {SSIZE_MAX} 6 +.br +Maximum value for an object of type +.BR ssize_t . +.br +Minimum Acceptable Value: +{_POSIX_SSIZE_MAX} +.IP {UCHAR_MAX} 6 +.br +Maximum value for an object of type +.BR "unsigned char" . +.br +Value: 255 +.IP {UINT_MAX} 6 +.br +Maximum value for an object of type +.BR unsigned . +.br +Minimum Acceptable Value: 4 294 967 295 +.IP {ULLONG_MAX} 6 +.br +Maximum value for an object of type +.BR "unsigned long long" . +.br +Minimum Acceptable Value: 18\|446\|744\|073\|709\|551\|615 +.IP {ULONG_MAX} 6 +.br +Maximum value for an object of type +.BR "unsigned long" . +.br +Minimum Acceptable Value: 4 294 967 295 +.IP {USHRT_MAX} 6 +.br +Maximum value for an object of type +.BR "unsigned short" . +.br +Minimum Acceptable Value: 65 535 +.IP {WORD_BIT} 6 +.br +Number of bits in an object of type +.BR int . +.br +Minimum Acceptable Value: 32 +.SS "Other Invariant Values" +.P +The +.IR +header shall define the following symbolic constants: +.IP {NL_ARGMAX} 6 +.br +Maximum value of +.IR n +in conversion specifications using the \fR"%\fIn\fR$"\fR +sequence in calls to the +\fIprintf\fR() +and +\fIscanf\fR() +families of functions. +.br +Minimum Acceptable Value: 9 +.IP {NL_LANGMAX} 6 +.br +Maximum number of bytes in a +.IR LANG +name. +.br +Minimum Acceptable Value: 14 +.IP {NL_MSGMAX} 6 +.br +Maximum message number. +.br +Minimum Acceptable Value: 32 767 +.IP {NL_SETMAX} 6 +.br +Maximum set number. +.br +Minimum Acceptable Value: 255 +.IP {NL_TEXTMAX} 6 +.br +Maximum number of bytes in a message string. +.br +Minimum Acceptable Value: +{_POSIX2_LINE_MAX} +.IP {NZERO} 6 +.br +Default process priority. +.br +Minimum Acceptable Value: 20 +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +A request was made to reduce the value of +{_POSIX_LINK_MAX} +from the value of 8 specified for it in the POSIX.1\(hy1990 standard to 2. The +standard developers decided to deny this request for several reasons: +.IP " *" 4 +They wanted to avoid making any changes to the standard that could +break conforming applications, and the requested change could have that +effect. +.IP " *" 4 +The use of multiple hard links to a file cannot always be replaced with +use of symbolic links. Symbolic links are semantically different from +hard links in that they associate a pathname with another pathname +rather than a pathname with a file. This has implications for access +control, file permanence, and transparency. +.IP " *" 4 +The original standard developers had considered the issue of allowing +for implementations that did not in general support hard links, and +decided that this would reduce consensus on the standard. +.P +Systems that support historical versions of the development option of +the ISO\ POSIX\(hy2 standard retain the name +{_POSIX2_RE_DUP_MAX} +as an alias for +{_POSIX_RE_DUP_MAX}. +.IP {PATH_MAX} 6 +.br +IEEE PASC Interpretation 1003.1 #15 addressed the inconsistency in the +standard with the definition of pathname and the description of +{PATH_MAX}, +allowing application developers to allocate either +{PATH_MAX} +or +{PATH_MAX}+1 +bytes. The inconsistency has been removed by correction to the +{PATH_MAX} +definition to include the null character. With this change, +applications that previously allocated +{PATH_MAX} +bytes will continue to succeed. +.IP {SYMLINK_MAX} 6 +.br +This symbol refers to space for data that is stored in the file system, +as opposed to +{PATH_MAX} +which is the length of a name that can be passed to a function. In some +existing implementations, the pathnames pointed to by symbolic links +are stored in the +.IR inode s +of the links, so it is important that +{SYMLINK_MAX} +not be constrained to be as large as +{PATH_MAX}. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment", +.IR "\fIfpathconf\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/locale.h.0p b/man-pages-posix-2013/man0p/locale.h.0p new file mode 100644 index 0000000..202a878 --- /dev/null +++ b/man-pages-posix-2013/man0p/locale.h.0p @@ -0,0 +1,177 @@ +'\" et +.TH locale.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +locale.h +\(em category macros +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends the +ISO\ C standard. Applications shall define the appropriate feature test macro +(see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment") +to enable the visibility of these symbols in this header. +.P +The +.IR +header shall define the +.BR lconv +structure, which shall include at least the following members. +(See the definitions of +.IR LC_MONETARY +in +.IR "Section 7.3.3" ", " "LC_MONETARY" +and +.IR "Section 7.3.4" ", " "LC_NUMERIC".) +.sp +.RS 4 +.nf +\fB +char *currency_symbol +char *decimal_point +char frac_digits +char *grouping +char *int_curr_symbol +char int_frac_digits +char int_n_cs_precedes +char int_n_sep_by_space +char int_n_sign_posn +char int_p_cs_precedes +char int_p_sep_by_space +char int_p_sign_posn +char *mon_decimal_point +char *mon_grouping +char *mon_thousands_sep +char *negative_sign +char n_cs_precedes +char n_sep_by_space +char n_sign_posn +char *positive_sign +char p_cs_precedes +char p_sep_by_space +char p_sign_posn +char *thousands_sep +.fi \fR +.P +.RE +.P +The +.IR +header shall define NULL (as described in +.IR ) +and at least the following as macros: +.P +.nf +LC_ALL +LC_COLLATE +LC_CTYPE +LC_MESSAGES +LC_MONETARY +LC_NUMERIC +LC_TIME +.fi +.P +which shall expand to integer constant expressions with distinct +values for use as the first argument to the +\fIsetlocale\fR() +function. +.P +Implementations may add additional masks using the form +.IR LC_* +and an uppercase letter. +.P +The +.IR +header shall contain at least the following macros representing +bitmasks for use with the +\fInewlocale\fR() +function for each supported locale category: +LC_COLLATE_MASK +LC_CTYPE_MASK +LC_MESSAGES_MASK +LC_MONETARY_MASK +LC_NUMERIC_MASK +LC_TIME_MASK +.P +Implementations may add additional masks using the form LC_*_MASK. +.P +In addition, a macro to set the bits for all categories set shall be +defined: +LC_ALL_MASK +.P +The +.IR +header shall define LC_GLOBAL_LOCALE, a special locale object descriptor +used by the +\fIduplocale\fR() +and +\fIuselocale\fR() +functions. +.P +The +.IR +header shall define the +.BR locale_t +type, representing a locale object. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided for use with ISO\ C standard +compilers. +.sp +.RS 4 +.nf +\fB +locale_t duplocale(locale_t); +void freelocale(locale_t); +struct lconv *localeconv(void); +locale_t newlocale(int, const char *, locale_t); +char *setlocale(int, const char *); +locale_t uselocale (locale_t); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 8" ", " "Environment Variables", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIduplocale\fR\^(\|)", +.IR "\fIfreelocale\fR\^(\|)", +.IR "\fIlocaleconv\fR\^(\|)", +.IR "\fInewlocale\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/math.h.0p b/man-pages-posix-2013/man0p/math.h.0p new file mode 100644 index 0000000..c8cf2cd --- /dev/null +++ b/man-pages-posix-2013/man0p/math.h.0p @@ -0,0 +1,582 @@ +'\" et +.TH math.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of 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 +math.h +\(em mathematical declarations +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends the +ISO\ C standard. Applications shall define the appropriate feature test macro +(see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment") +to enable the visibility of these symbols in this header. +.P +The +.IR +header shall define at least the following types: +.IP "\fBfloat_t\fR" 12 +A real-floating type at least as wide as +.BR float . +.IP "\fBdouble_t\fR" 12 +A real-floating type at least as wide as +.BR double , +and at least as wide as +.BR float_t . +.P +If FLT_EVAL_METHOD equals 0, +.BR float_t +and +.BR double_t +shall be +.BR float +and +.BR double , +respectively; if FLT_EVAL_METHOD equals 1, they shall both be +.BR double ; +if FLT_EVAL_METHOD equals 2, they shall both be +.BR "long double" ; +for other values of FLT_EVAL_METHOD, they are otherwise +implementation-defined. +.P +The +.IR +header shall define the following macros, where real-floating indicates +that the argument shall be an expression of real-floating type: +.sp +.RS 4 +.nf +\fB +int fpclassify(real-floating x); +int isfinite(real-floating x); +int isgreater(real-floating x, real-floating y); +int isgreaterequal(real-floating x, real-floating y); +int isinf(real-floating x); +int isless(real-floating x, real-floating y); +int islessequal(real-floating x, real-floating y); +int islessgreater(real-floating x, real-floating y); +int isnan(real-floating x); +int isnormal(real-floating x); +int isunordered(real-floating x, real-floating y); +int signbit(real-floating x); +.fi \fR +.P +.RE +.P +The +.IR +header shall define the following symbolic constants. The values +shall have type +.BR double +and shall be accurate within the precision of the +.BR double +type. +.IP M_E 12 +Value of $e$ +.IP M_LOG2E 12 +Value of $log_ 2" " e$ +.IP M_LOG10E 12 +Value of $log_ 10" " e$ +.IP M_LN2 12 +Value of $log_ e" " 2$ +.IP M_LN10 12 +Value of $log_ e" " 10$ +.IP M_PI 12 +Value of $pi$ +.IP M_PI_2 12 +Value of $pi /2$ +.IP M_PI_4 12 +Value of $pi /4$ +.IP M_1_PI 12 +Value of $1/ pi$ +.IP M_2_PI 12 +Value of $2/ pi$ +.IP M_2_SQRTPI 12 +Value of $2/ sqrt pi$ +.IP M_SQRT2 12 +Value of $sqrt 2$ +.IP M_SQRT1_2 12 +Value of $1/ sqrt 2$ +.P +The +.IR +header shall define the following symbolic constant: +.IP MAXFLOAT 12 +Same value as FLT_MAX in +.IR . +.P +The +.IR +header shall define the following macros: +.IP HUGE_VAL 12 +A positive +.BR double +constant expression, not necessarily representable as a +.BR float . +Used as an error value returned by the mathematics library. HUGE_VAL +evaluates to +infinity on systems supporting IEEE\ Std\ 754\(hy1985. +.IP HUGE_VALF 12 +A positive +.BR float +constant expression. Used as an error value returned by the mathematics +library. HUGE_VALF evaluates to +infinity on systems supporting IEEE\ Std\ 754\(hy1985. +.IP HUGE_VALL 12 +A positive +.BR "long double" +constant expression. Used as an error value returned by the mathematics +library. HUGE_VALL evaluates to +infinity on systems supporting IEEE\ Std\ 754\(hy1985. +.IP INFINITY 12 +A constant expression of type +.BR float +representing positive or unsigned infinity, if available; else a +positive constant of type +.BR float +that overflows at translation time. +.IP NAN 12 +A constant expression of type +.BR float +representing a quiet NaN. This macro is only defined if the +implementation supports quiet NaNs for the +.BR float +type. +.P +The following macros shall be defined for number classification. They +represent the mutually-exclusive kinds of floating-point values. They +expand to integer constant expressions with distinct values. Additional +implementation-defined floating-point classifications, with macro +definitions beginning with FP_ and an uppercase letter, may also be +specified by the implementation. +.sp +.RS +FP_INFINITE +FP_NAN +FP_NORMAL +FP_SUBNORMAL +FP_ZERO +.RE +.P +The following optional macros indicate whether the +\fIfma\fR() +family of functions are fast compared with direct code: +.sp +.RS +FP_FAST_FMA +FP_FAST_FMAF +FP_FAST_FMAL +.RE +.P +If defined, the FP_FAST_FMA macro shall expand to the integer constant +1 and shall indicate that the +\fIfma\fR() +function generally executes about as fast as, or faster than, a +multiply and an add of +.BR double +operands. If undefined, the speed of execution is unspecified. The +other macros have the equivalent meaning for the +.BR float +and +.BR "long double" +versions. +.P +The following macros shall expand to integer constant expressions whose +values are returned by +.IR ilogb (\c +.IR x ) +if +.IR x +is zero or NaN, respectively. The value of FP_ILOGB0 shall be either +{INT_MIN} +or \(mi\c +{INT_MAX}. +The value of FP_ILOGBNAN shall be either +{INT_MAX} +or +{INT_MIN}. +.sp +.RS +FP_ILOGB0 +FP_ILOGBNAN +.RE +.P +The following macros shall expand to the integer constants 1 and 2, +respectively; +.sp +.RS +MATH_ERRNO +MATH_ERREXCEPT +.RE +.P +The following macro shall expand to an expression that has type +.BR int +and the value MATH_ERRNO, MATH_ERREXCEPT, or the bitwise-inclusive OR +of both: +.sp +.RS +math_errhandling +.RE +.P +The value of math_errhandling is constant for the duration of the +program. It is unspecified whether math_errhandling is a macro or an +identifier with external linkage. If a macro definition is suppressed +or a program defines an identifier with the name math_errhandling , the +behavior is undefined. If the expression (math_errhandling & +MATH_ERREXCEPT) can be non-zero, the implementation shall define the +macros FE_DIVBYZERO, FE_INVALID, and FE_OVERFLOW in +.IR . +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +double acos(double); +float acosf(float); +double acosh(double); +float acoshf(float); +long double acoshl(long double); +long double acosl(long double); +double asin(double); +float asinf(float); +double asinh(double); +float asinhf(float); +long double asinhl(long double); +long double asinl(long double); +double atan(double); +double atan2(double, double); +float atan2f(float, float); +long double atan2l(long double, long double); +float atanf(float); +double atanh(double); +float atanhf(float); +long double atanhl(long double); +long double atanl(long double); +double cbrt(double); +float cbrtf(float); +long double cbrtl(long double); +double ceil(double); +float ceilf(float); +long double ceill(long double); +double copysign(double, double); +float copysignf(float, float); +long double copysignl(long double, long double); +double cos(double); +float cosf(float); +double cosh(double); +float coshf(float); +long double coshl(long double); +long double cosl(long double); +double erf(double); +double erfc(double); +float erfcf(float); +long double erfcl(long double); +float erff(float); +long double erfl(long double); +double exp(double); +double exp2(double); +float exp2f(float); +long double exp2l(long double); +float expf(float); +long double expl(long double); +double expm1(double); +float expm1f(float); +long double expm1l(long double); +double fabs(double); +float fabsf(float); +long double fabsl(long double); +double fdim(double, double); +float fdimf(float, float); +long double fdiml(long double, long double); +double floor(double); +float floorf(float); +long double floorl(long double); +double fma(double, double, double); +float fmaf(float, float, float); +long double fmal(long double, long double, long double); +double fmax(double, double); +float fmaxf(float, float); +long double fmaxl(long double, long double); +double fmin(double, double); +float fminf(float, float); +long double fminl(long double, long double); +double fmod(double, double); +float fmodf(float, float); +long double fmodl(long double, long double); +double frexp(double, int *); +float frexpf(float, int *); +long double frexpl(long double, int *); +double hypot(double, double); +float hypotf(float, float); +long double hypotl(long double, long double); +int ilogb(double); +int ilogbf(float); +int ilogbl(long double); +double j0(double); +double j1(double); +double jn(int, double); +double ldexp(double, int); +float ldexpf(float, int); +long double ldexpl(long double, int); +double lgamma(double); +float lgammaf(float); +long double lgammal(long double); +long long llrint(double); +long long llrintf(float); +long long llrintl(long double); +long long llround(double); +long long llroundf(float); +long long llroundl(long double); +double log(double); +double log10(double); +float log10f(float); +long double log10l(long double); +double log1p(double); +float log1pf(float); +long double log1pl(long double); +double log2(double); +float log2f(float); +long double log2l(long double); +double logb(double); +float logbf(float); +long double logbl(long double); +float logf(float); +long double logl(long double); +long lrint(double); +long lrintf(float); +long lrintl(long double); +long lround(double); +long lroundf(float); +long lroundl(long double); +double modf(double, double *); +float modff(float, float *); +long double modfl(long double, long double *); +double nan(const char *); +float nanf(const char *); +long double nanl(const char *); +double nearbyint(double); +float nearbyintf(float); +long double nearbyintl(long double); +double nextafter(double, double); +float nextafterf(float, float); +long double nextafterl(long double, long double); +double nexttoward(double, long double); +float nexttowardf(float, long double); +long double nexttowardl(long double, long double); +double pow(double, double); +float powf(float, float); +long double powl(long double, long double); +double remainder(double, double); +float remainderf(float, float); +long double remainderl(long double, long double); +double remquo(double, double, int *); +float remquof(float, float, int *); +long double remquol(long double, long double, int *); +double rint(double); +float rintf(float); +long double rintl(long double); +double round(double); +float roundf(float); +long double roundl(long double); +double scalbln(double, long); +float scalblnf(float, long); +long double scalblnl(long double, long); +double scalbn(double, int); +float scalbnf(float, int); +long double scalbnl(long double, int); +double sin(double); +float sinf(float); +double sinh(double); +float sinhf(float); +long double sinhl(long double); +long double sinl(long double); +double sqrt(double); +float sqrtf(float); +long double sqrtl(long double); +double tan(double); +float tanf(float); +double tanh(double); +float tanhf(float); +long double tanhl(long double); +long double tanl(long double); +double tgamma(double); +float tgammaf(float); +long double tgammal(long double); +double trunc(double); +float truncf(float); +long double truncl(long double); +double y0(double); +double y1(double); +double yn(int, double); +.fi \fR +.P +.RE +.P +The following external variable shall be defined: +.sp +.RS 4 +.nf +\fB +extern int signgam; +.fi \fR +.P +.RE +.P +The behavior of each of the functions defined in +.IR +is specified in the System Interfaces volume of POSIX.1\(hy2008 for all representable values of its input +arguments, except where stated otherwise. Each function shall execute +as if it were a single operation without generating any externally +visible exceptional conditions. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The FP_CONTRACT pragma can be used to allow (if the state is on) or +disallow (if the state is off) the implementation to contract +expressions. Each pragma can occur either outside external declarations +or preceding all explicit declarations and statements inside a compound +statement. When outside external declarations, the pragma takes effect +from its occurrence until another FP_CONTRACT pragma is encountered, or +until the end of the translation unit. When inside a compound +statement, the pragma takes effect from its occurrence until another +FP_CONTRACT pragma is encountered (including within a nested compound +statement), or until the end of the compound statement; at the end of a +compound statement the state for the pragma is restored to its +condition just before the compound statement. If this pragma is used in +any other context, the behavior is undefined. The default state (on or +off) for the pragma is implementation-defined. +.P +Applications should use FLT_MAX as described in the +.IR +header instead of the obsolescent MAXFLOAT. +.SH RATIONALE +Before the ISO/IEC\ 9899:\|1999 standard, the math library was defined only for the floating +type +.BR double . +All the names formed by appending +.BR 'f' +or +.BR 'l' +to a name in +.IR +were reserved to allow for the definition of +.BR float +and +.BR "long double" +libraries; and the ISO/IEC\ 9899:\|1999 standard provides for all three versions of math +functions. +.P +The functions +.IR ecvt (\|), +.IR fcvt (\|), +and +.IR gcvt (\|) +have been dropped from the ISO\ C standard since their capability is available +through +\fIsprintf\fR(). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment", +.IR "\fIacos\fR\^(\|)", +.IR "\fIacosh\fR\^(\|)", +.IR "\fIasin\fR\^(\|)", +.IR "\fIasinh\fR\^(\|)", +.IR "\fIatan\fR\^(\|)", +.IR "\fIatan2\fR\^(\|)", +.IR "\fIatanh\fR\^(\|)", +.IR "\fIcbrt\fR\^(\|)", +.IR "\fIceil\fR\^(\|)", +.IR "\fIcopysign\fR\^(\|)", +.IR "\fIcos\fR\^(\|)", +.IR "\fIcosh\fR\^(\|)", +.IR "\fIerf\fR\^(\|)", +.IR "\fIerfc\fR\^(\|)", +.IR "\fIexp\fR\^(\|)", +.IR "\fIexp2\fR\^(\|)", +.IR "\fIexpm1\fR\^(\|)", +.IR "\fIfabs\fR\^(\|)", +.IR "\fIfdim\fR\^(\|)", +.IR "\fIfloor\fR\^(\|)", +.IR "\fIfma\fR\^(\|)", +.IR "\fIfmax\fR\^(\|)", +.IR "\fIfmin\fR\^(\|)", +.IR "\fIfmod\fR\^(\|)", +.IR "\fIfpclassify\fR\^(\|)", +.IR "\fIfrexp\fR\^(\|)", +.IR "\fIhypot\fR\^(\|)", +.IR "\fIilogb\fR\^(\|)", +.IR "\fIisfinite\fR\^(\|)", +.IR "\fIisgreater\fR\^(\|)", +.IR "\fIisgreaterequal\fR\^(\|)", +.IR "\fIisinf\fR\^(\|)", +.IR "\fIisless\fR\^(\|)", +.IR "\fIislessequal\fR\^(\|)", +.IR "\fIislessgreater\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIisnormal\fR\^(\|)", +.IR "\fIisunordered\fR\^(\|)", +.IR "\fIj0\fR\^(\|)", +.IR "\fIldexp\fR\^(\|)", +.IR "\fIlgamma\fR\^(\|)", +.IR "\fIllrint\fR\^(\|)", +.IR "\fIllround\fR\^(\|)", +.IR "\fIlog\fR\^(\|)", +.IR "\fIlog10\fR\^(\|)", +.IR "\fIlog1p\fR\^(\|)", +.IR "\fIlog2\fR\^(\|)", +.IR "\fIlogb\fR\^(\|)", +.IR "\fIlrint\fR\^(\|)", +.IR "\fIlround\fR\^(\|)", +.IR "\fImodf\fR\^(\|)", +.IR "\fInan\fR\^(\|)", +.IR "\fInearbyint\fR\^(\|)", +.IR "\fInextafter\fR\^(\|)", +.IR "\fIpow\fR\^(\|)", +.IR "\fIremainder\fR\^(\|)", +.IR "\fIremquo\fR\^(\|)", +.IR "\fIrint\fR\^(\|)", +.IR "\fIround\fR\^(\|)", +.IR "\fIscalbln\fR\^(\|)", +.IR "\fIsignbit\fR\^(\|)", +.IR "\fIsin\fR\^(\|)", +.IR "\fIsinh\fR\^(\|)", +.IR "\fIsqrt\fR\^(\|)", +.IR "\fItan\fR\^(\|)", +.IR "\fItanh\fR\^(\|)", +.IR "\fItgamma\fR\^(\|)", +.IR "\fItrunc\fR\^(\|)", +.IR "\fIy0\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/monetary.h.0p b/man-pages-posix-2013/man0p/monetary.h.0p new file mode 100644 index 0000000..e377655 --- /dev/null +++ b/man-pages-posix-2013/man0p/monetary.h.0p @@ -0,0 +1,83 @@ +'\" et +.TH monetary.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +monetary.h +\(em monetary types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR locale_t +type as described in +.IR . +.P +The +.IR +header shall define the +.BR size_t +type as described in +.IR . +.P +The +.IR +header shall define the +.BR ssize_t +type as described in +.IR . +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided for use with ISO\ C standard +compilers. +.sp +.RS 4 +.nf +\fB +ssize_t strfmon(char *restrict, size_t, const char *restrict, ...); +ssize_t strfmon_l(char *restrict, size_t, locale_t, + const char *restrict, ...); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIstrfmon\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/mqueue.h.0p b/man-pages-posix-2013/man0p/mqueue.h.0p new file mode 100644 index 0000000..c551a6a --- /dev/null +++ b/man-pages-posix-2013/man0p/mqueue.h.0p @@ -0,0 +1,140 @@ +'\" et +.TH mqueue.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mqueue.h +\(em message queues +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR mqd_t +type, which is used for message queue descriptors. This is not an +array type. +.P +The +.IR +header shall define the +.BR pthread_attr_t , +.BR size_t , +and +.BR ssize_t +types as described in +.IR . +.P +The +.IR +header shall define the +.BR "struct timespec" +structure as described in +.IR . +.P +The tag +.BR sigevent +shall be declared as naming an incomplete structure type, the contents +of which are described in the +.IR +header. +.P +The +.IR +header shall define the +.BR mq_attr +structure, which is used in getting and setting the attributes of a +message queue. Attributes are initially set when the message queue is +created. An +.BR mq_attr +structure shall have at least the following fields: +.sp +.RS 4 +.nf +\fB +long mq_flags \fRMessage queue flags.\fP +long mq_maxmsg \fRMaximum number of messages.\fP +long mq_msgsize \fRMaximum message size.\fP +long mq_curmsgs \fRNumber of messages currently queued.\fP +.fi \fR +.P +.RE +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int mq_close(mqd_t); +int mq_getattr(mqd_t, struct mq_attr *); +int mq_notify(mqd_t, const struct sigevent *); +mqd_t mq_open(const char *, int, ...); +ssize_t mq_receive(mqd_t, char *, size_t, unsigned *); +int mq_send(mqd_t, const char *, size_t, unsigned); +int mq_setattr(mqd_t, const struct mq_attr *restrict, + struct mq_attr *restrict); +ssize_t mq_timedreceive(mqd_t, char *restrict, size_t, + unsigned *restrict, const struct timespec *restrict); +int mq_timedsend(mqd_t, const char *, size_t, unsigned, + const struct timespec *); +int mq_unlink(const char *); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may make visible symbols defined in the headers +.IR , +.IR , +and +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.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\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/ndbm.h.0p b/man-pages-posix-2013/man0p/ndbm.h.0p new file mode 100644 index 0000000..8037aeb --- /dev/null +++ b/man-pages-posix-2013/man0p/ndbm.h.0p @@ -0,0 +1,115 @@ +'\" et +.TH ndbm.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ndbm.h +\(em definitions for ndbm database operations +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR datum +type as a structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +void *dptr \fRA pointer to the application's data.\fR +size_t dsize \fRThe size of the object pointed to by \fIdptr.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR size_t +type as described in +.IR . +.P +The +.IR +header shall define the +.BR DBM +type. +.P +The +.IR +header shall define the following symbolic constants as possible +values for the +.IR store_mode +argument to +\fIdbm_store\fR(): +.IP DBM_INSERT 14 +Insertion of new entries only. +.IP DBM_REPLACE 14 +Allow replacing existing entries. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int dbm_clearerr(DBM *); +void dbm_close(DBM *); +int dbm_delete(DBM *, datum); +int dbm_error(DBM *); +datum dbm_fetch(DBM *, datum); +datum dbm_firstkey(DBM *); +datum dbm_nextkey(DBM *); +DBM *dbm_open(const char *, int, mode_t); +int dbm_store(DBM *, datum, datum, int); +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR mode_t +type through +.BR typedef , +as described in +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIdbm_clearerr\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/net_if.h.0p b/man-pages-posix-2013/man0p/net_if.h.0p new file mode 100644 index 0000000..fb150dc --- /dev/null +++ b/man-pages-posix-2013/man0p/net_if.h.0p @@ -0,0 +1,84 @@ +'\" et +.TH net_if.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +net/if.h +\(em sockets local interfaces +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR if_nameindex +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +unsigned if_index \fRNumeric index of the interface.\fR +char *if_name \fRNull-terminated name of the interface.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the following symbolic constant for the length of +a buffer containing an interface name (including the terminating NULL +character): +.IP IF_NAMESIZE 12 +Interface name length. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +void if_freenameindex(struct if_nameindex *); +char *if_indextoname(unsigned, char *); +struct if_nameindex *if_nameindex(void); +unsigned if_nametoindex(const char *); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIif_freenameindex\fR\^(\|)", +.IR "\fIif_indextoname\fR\^(\|)", +.IR "\fIif_nameindex\fR\^(\|)", +.IR "\fIif_nametoindex\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/netdb.h.0p b/man-pages-posix-2013/man0p/netdb.h.0p new file mode 100644 index 0000000..41d1376 --- /dev/null +++ b/man-pages-posix-2013/man0p/netdb.h.0p @@ -0,0 +1,325 @@ +'\" et +.TH netdb.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +netdb.h +\(em definitions for network database operations +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header may define the +.BR in_port_t +type and the +.BR in_addr_t +type as described in +.IR . +.P +The +.IR +header shall define the +.BR hostent +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +char *h_name \fROfficial name of the host.\fR +char **h_aliases \fRA pointer to an array of pointers to\fR + \fRalternative host names, terminated by a\fR + \fRnull pointer.\fR +int h_addrtype \fRAddress type.\fR +int h_length \fRThe length, in bytes, of the address.\fR +char **h_addr_list \fRA pointer to an array of pointers to network\fR + \fRaddresses (in network byte order) for the host,\fR + \fRterminated by a null pointer.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR netent +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +char *n_name \fROfficial, fully-qualified (including the\fR + \fRdomain) name of the host.\fR +char **n_aliases \fRA pointer to an array of pointers to\fR + \fRalternative network names, terminated by a\fR + \fRnull pointer.\fR +int n_addrtype \fRThe address type of the network.\fR +uint32_t n_net \fRThe network number, in host byte order.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR uint32_t +type as described in +.IR . +.P +The +.IR +header shall define the +.BR protoent +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +char *p_name \fROfficial name of the protocol.\fR +char **p_aliases \fRA pointer to an array of pointers to\fR + \fRalternative protocol names, terminated by\fR + \fRa null pointer.\fR +int p_proto \fRThe protocol number.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR servent +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +char *s_name \fROfficial name of the service.\fR +char **s_aliases \fRA pointer to an array of pointers to\fR + \fRalternative service names, terminated by\fR + \fRa null pointer.\fR +int s_port \fRA value which, when converted to uint16_t,\fR + \fRyields the port number in network byte order\fR + \fRat which the service resides.\fR +char *s_proto \fRThe name of the protocol to use when\fR + \fRcontacting the service.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the IPPORT_RESERVED symbolic constant with the +value of the highest reserved Internet port number. +.SS "Address Information Structure" +.P +The +.IR +header shall define the +.BR addrinfo +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +int ai_flags \fRInput flags.\fR +int ai_family \fRAddress family of socket.\fR +int ai_socktype \fRSocket type.\fR +int ai_protocol \fRProtocol of socket.\fR +socklen_t ai_addrlen \fRLength of socket address.\fR +struct sockaddr *ai_addr \fRSocket address of socket.\fR +char *ai_canonname \fRCanonical name of service location.\fR +struct addrinfo *ai_next \fRPointer to next in list.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the following symbolic constants that evaluate to +bitwise-distinct integer constants for use in the +.IR flags +field of the +.BR addrinfo +structure: +.IP AI_PASSIVE 14 +Socket address is intended for +\fIbind\fR(). +.IP AI_CANONNAME 14 +Request for canonical name. +.IP AI_NUMERICHOST 14 +Return numeric host address as name. +.IP AI_NUMERICSERV 14 +Inhibit service name resolution. +.IP AI_V4MAPPED 14 +If no IPv6 addresses are found, query for IPv4 addresses and return +them to the caller as IPv4-mapped IPv6 addresses. +.IP AI_ALL 14 +Query for both IPv4 and IPv6 addresses. +.IP AI_ADDRCONFIG 14 +Query for IPv4 addresses only when an IPv4 address is configured; +query for IPv6 addresses only when an IPv6 address is configured. +.P +The +.IR +header shall define the following symbolic constants that evaluate +to bitwise-distinct integer constants for use in the +.IR flags +argument to +\fIgetnameinfo\fR(): +.IP NI_NOFQDN 14 +Only the nodename portion of the FQDN is returned for local hosts. +.IP NI_NUMERICHOST 14 +The numeric form of the node's address is returned instead of its +name. +.IP NI_NAMEREQD 14 +Return an error if the node's name cannot be located in the database. +.IP NI_NUMERICSERV 14 +The numeric form of the service address is returned instead of its name. +.IP NI_NUMERICSCOPE 14 +.br +For IPv6 addresses, the numeric form of the scope identifier is +returned instead of its name. +.IP NI_DGRAM 14 +Indicates that the service is a datagram service (SOCK_DGRAM). +.SS "Address Information Errors" +.P +The +.IR +header shall define the following symbolic constants for use as +error values for +\fIgetaddrinfo\fR() +and +\fIgetnameinfo\fR(). +The values shall be suitable for use in +.BR #if +preprocessing directives. +.IP EAI_AGAIN 14 +The name could not be resolved at this time. Future attempts may +succeed. +.IP EAI_BADFLAGS 14 +The flags had an invalid value. +.IP EAI_FAIL 14 +A non-recoverable error occurred. +.IP EAI_FAMILY 14 +The address family was not recognized or the address length was invalid +for the specified family. +.IP EAI_MEMORY 14 +There was a memory allocation failure. +.IP EAI_NONAME 14 +The name does not resolve for the supplied parameters. +.RS 14 +.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_SERVICE 14 +The service passed was not recognized for the specified socket type. +.IP EAI_SOCKTYPE 14 +The intended socket type was not recognized. +.IP EAI_SYSTEM 14 +A system error occurred. The error code can be found in +.IR errno . +.IP EAI_OVERFLOW 14 +An argument buffer overflowed. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +void endhostent(void); +void endnetent(void); +void endprotoent(void); +void endservent(void); +void freeaddrinfo(struct addrinfo *); +const char *gai_strerror(int); +int getaddrinfo(const char *restrict, const char *restrict, + const struct addrinfo *restrict, + struct addrinfo **restrict); +struct hostent *gethostent(void); +int getnameinfo(const struct sockaddr *restrict, socklen_t, + char *restrict, socklen_t, char *restrict, + socklen_t, int); +struct netent *getnetbyaddr(uint32_t, int); +struct netent *getnetbyname(const char *); +struct netent *getnetent(void); +struct protoent *getprotobyname(const char *); +struct protoent *getprotobynumber(int); +struct protoent *getprotoent(void); +struct servent *getservbyname(const char *, const char *); +struct servent *getservbyport(int, const char *); +struct servent *getservent(void); +void sethostent(int); +void setnetent(int); +void setprotoent(int); +void setservent(int); +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR socklen_t +type through +.BR typedef , +as described in +.IR . +.P +Inclusion of the +.IR +header may also make visible all symbols from +.IR , +.IR , +and +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIbind\fR\^(\|)", +.IR "\fIendhostent\fR\^(\|)", +.IR "\fIendnetent\fR\^(\|)", +.IR "\fIendprotoent\fR\^(\|)", +.IR "\fIendservent\fR\^(\|)", +.IR "\fIfreeaddrinfo\fR\^(\|)", +.IR "\fIgai_strerror\fR\^(\|)", +.IR "\fIgetnameinfo\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/netinet_in.h.0p b/man-pages-posix-2013/man0p/netinet_in.h.0p new file mode 100644 index 0000000..039a116 --- /dev/null +++ b/man-pages-posix-2013/man0p/netinet_in.h.0p @@ -0,0 +1,391 @@ +'\" et +.TH netinet_in.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +netinet/in.h +\(em Internet address family +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following types: +.IP "\fBin_port_t\fP" 10 +Equivalent to the type +.BR uint16_t +as described in +.IR . +.IP "\fBin_addr_t\fP" 10 +Equivalent to the type +.BR uint32_t +as described in +.IR . +.P +The +.IR +header shall define the +.BR sa_family_t +type as described in +.IR . +.P +The +.IR +header shall define the +.BR uint8_t +and +.BR uint32_t +types as described in +.IR . +Inclusion of the +.IR +header may also make visible all symbols from +.IR +and +.IR . +.P +The +.IR +header shall define the +.BR in_addr +structure, which shall include at least the following member: +.sp +.RS 4 +.nf +\fB +in_addr_t s_addr +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR sockaddr_in +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +sa_family_t sin_family \fRAF_INET.\fR +in_port_t sin_port \fRPort number.\fR +struct in_addr sin_addr \fRIP address.\fR +.fi \fR +.P +.RE +.P +The +.IR sin_port +and +.IR sin_addr +members shall be in network byte order. +.P +The +.BR sockaddr_in +structure is used to store addresses for the Internet address family. +Pointers to this type shall be cast by applications to +.BR "struct sockaddr *" +for use with socket functions. +.P +The +.IR +header shall define the +.BR in6_addr +structure, which shall include at least the following member: +.sp +.RS 4 +.nf +\fB +uint8_t s6_addr[16] +.fi \fR +.P +.RE +.P +This array is used to contain a 128-bit IPv6 address, stored in network +byte order. +.P +The +.IR +header shall define the +.BR sockaddr_in6 +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +sa_family_t sin6_family \fRAF_INET6.\fR +in_port_t sin6_port \fRPort number.\fR +uint32_t sin6_flowinfo \fRIPv6 traffic class and flow information.\fR +struct in6_addr sin6_addr \fRIPv6 address.\fR +uint32_t sin6_scope_id \fRSet of interfaces for a scope.\fR +.fi \fR +.P +.RE +.P +The +.IR sin6_port +and +.IR sin6_addr +members shall be in network byte order. +.P +The +.BR sockaddr_in6 +structure shall be set to zero by an application prior to using it, +since implementations are free to have additional, +implementation-defined fields in +.BR sockaddr_in6 . +.P +The +.IR sin6_scope_id +field is a 32-bit integer that identifies a set of interfaces as +appropriate for the scope of the address carried in the +.IR sin6_addr +field. For a link scope +.IR sin6_addr , +the application shall ensure that +.IR sin6_scope_id +is a link index. For a site scope +.IR sin6_addr , +the application shall ensure that +.IR sin6_scope_id +is a site index. The mapping of +.IR sin6_scope_id +to an interface or set of interfaces is implementation-defined. +.P +The +.IR +header shall declare the following external variable: +.sp +.RS 4 +.nf +\fB +const struct in6_addr in6addr_any +.fi \fR +.P +.RE +.P +This variable is initialized by the system to contain the wildcard IPv6 +address. The +.IR +header also defines the IN6ADDR_ANY_INIT macro. This macro must be +constant at compile time and can be used to initialize a variable of +type +.BR "struct in6_addr" +to the IPv6 wildcard address. +.P +The +.IR +header shall declare the following external variable: +.sp +.RS 4 +.nf +\fB +const struct in6_addr in6addr_loopback +.fi \fR +.P +.RE +.P +This variable is initialized by the system to contain the loopback IPv6 +address. The +.IR +header also defines the IN6ADDR_LOOPBACK_INIT macro. This macro must be +constant at compile time and can be used to initialize a variable of +type +.BR "struct in6_addr" +to the IPv6 loopback address. +.P +The +.IR +header shall define the +.BR ipv6_mreq +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +struct in6_addr ipv6mr_multiaddr \fRIPv6 multicast address.\fR +unsigned ipv6mr_interface \fRInterface index.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the following symbolic constants for use as +values of the +.IR level +argument of +\fIgetsockopt\fR() +and +\fIsetsockopt\fR(): +.IP IPPROTO_IP 16 +Internet protocol. +.IP IPPROTO_IPV6 16 +Internet Protocol Version 6. +.IP IPPROTO_ICMP 16 +Control message protocol. +.IP IPPROTO_RAW 16 +Raw IP Packets Protocol. +.IP IPPROTO_TCP 16 +Transmission control protocol. +.IP IPPROTO_UDP 16 +User datagram protocol. +.P +The +.IR +header shall define the following symbolic constants for use as +destination addresses for +\fIconnect\fR(), +\fIsendmsg\fR(), +and +\fIsendto\fR(): +.IP INADDR_ANY 16 +IPv4 local host address. +.IP INADDR_BROADCAST 16 +IPv4 broadcast address. +.P +The +.IR +header shall define the following symbolic constant, with the value +specified, to help applications declare buffers of the proper size +to store IPv4 addresses in string form: +.IP INET_ADDRSTRLEN 16 +16. Length of the string form for IP. +.P +The +\fIhtonl\fR(), +\fIhtons\fR(), +\fIntohl\fR(), +and +\fIntohs\fR() +functions shall be available as described in +.IR . +Inclusion of the +.IR +header may also make visible all symbols from +.IR . +.P +The +.IR +header shall define the following symbolic constant, with the value +specified, to help applications declare buffers of the proper size +to store IPv6 addresses in string form: +.IP INET6_ADDRSTRLEN 16 +46. Length of the string form for IPv6. +.br +.P +The +.IR +header shall define the following symbolic constants, with distinct +integer values, for use in the +.IR option_name +argument in the +\fIgetsockopt\fR() +or +\fIsetsockopt\fR() +functions at protocol level IPPROTO_IPV6: +.IP IPV6_JOIN_GROUP 16 +Join a multicast group. +.IP IPV6_LEAVE_GROUP 16 +Quit a multicast group. +.IP IPV6_MULTICAST_HOPS 16 +.br +Multicast hop limit. +.IP IPV6_MULTICAST_IF 16 +Interface to use for outgoing multicast packets. +.IP IPV6_MULTICAST_LOOP 16 +.br +Multicast packets are delivered back to the local application. +.IP IPV6_UNICAST_HOPS 16 +Unicast hop limit. +.IP IPV6_V6ONLY 16 +Restrict AF_INET6 socket to IPv6 communications only. +.P +The +.IR +header shall define the following macros that test for special IPv6 +addresses. Each macro is of type +.BR int +and takes a single argument of type +.BR "const struct in6_addr *" : +.IP IN6_IS_ADDR_UNSPECIFIED 6 +.br +Unspecified address. +.IP IN6_IS_ADDR_LOOPBACK 6 +.br +Loopback address. +.IP IN6_IS_ADDR_MULTICAST 6 +.br +Multicast address. +.IP IN6_IS_ADDR_LINKLOCAL 6 +.br +Unicast link-local address. +.IP IN6_IS_ADDR_SITELOCAL 6 +.br +Unicast site-local address. +.IP IN6_IS_ADDR_V4MAPPED 6 +.br +IPv4 mapped address. +.IP IN6_IS_ADDR_V4COMPAT 6 +.br +IPv4-compatible address. +.IP IN6_IS_ADDR_MC_NODELOCAL 6 +.br +Multicast node-local address. +.IP IN6_IS_ADDR_MC_LINKLOCAL 6 +.br +Multicast link-local address. +.IP IN6_IS_ADDR_MC_SITELOCAL 6 +.br +Multicast site-local address. +.IP IN6_IS_ADDR_MC_ORGLOCAL 6 +.br +Multicast organization-local address. +.IP IN6_IS_ADDR_MC_GLOBAL 6 +.br +Multicast global address. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 4.9" ", " "Host and Network Byte Orders", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIconnect\fR\^(\|)", +.IR "\fIgetsockopt\fR\^(\|)", +.IR "\fIhtonl\fR\^(\|)", +.IR "\fIsendmsg\fR\^(\|)", +.IR "\fIsendto\fR\^(\|)", +.IR "\fIsetsockopt\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/netinet_tcp.h.0p b/man-pages-posix-2013/man0p/netinet_tcp.h.0p new file mode 100644 index 0000000..b04e7c3 --- /dev/null +++ b/man-pages-posix-2013/man0p/netinet_tcp.h.0p @@ -0,0 +1,59 @@ +'\" et +.TH netinet_tcp.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +netinet/tcp.h +\(em definitions for the Internet Transmission Control Protocol (TCP) +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following symbolic constant for use as a +socket option at the IPPROTO_TCP level: +.IP TCP_NODELAY 12 +Avoid coalescing of small segments. +.P +The implementation need not allow the value of the option to be set via +\fIsetsockopt\fR() +or retrieved via +\fIgetsockopt\fR(). +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIgetsockopt\fR\^(\|)", +.IR "\fIsetsockopt\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/nl_types.h.0p b/man-pages-posix-2013/man0p/nl_types.h.0p new file mode 100644 index 0000000..f0ef942 --- /dev/null +++ b/man-pages-posix-2013/man0p/nl_types.h.0p @@ -0,0 +1,109 @@ +'\" et +.TH nl_types.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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_types.h +\(em data types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define at least the following types: +.IP "\fBnl_catd\fP" 14 +Used by the message catalog functions +\fIcatopen\fR(), +\fIcatgets\fR(), +and +\fIcatclose\fR() +to identify a catalog descriptor. +.IP "\fBnl_item\fP" 14 +Used by +\fInl_langinfo\fR() +to identify items of +.IR langinfo +data. Values of objects of type +.BR nl_item +are defined in +.IR . +.P +The +.IR +header shall define at least the following symbolic constants: +.IP NL_SETD 14 +Used by +.IR gencat +when no $\fIset\fP directive is specified in a message text source +file. This constant can be passed as the value of +.IR set_id +on subsequent calls to +\fIcatgets\fR() +(that is, to retrieve messages from the default message set). The +value of NL_SETD is implementation-defined. +.IP NL_CAT_LOCALE 14 +Value that must be passed as the +.IR oflag +argument to +\fIcatopen\fR() +to ensure that message catalog selection depends on the +.IR LC_MESSAGES +locale category, rather than directly on the +.IR LANG +environment variable. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int catclose(nl_catd); +char *catgets(nl_catd, int, int, const char *); +nl_catd catopen(const char *, int); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIcatclose\fR\^(\|)", +.IR "\fIcatgets\fR\^(\|)", +.IR "\fIcatopen\fR\^(\|)", +.IR "\fInl_langinfo\fR\^(\|)" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIgencat\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/poll.h.0p b/man-pages-posix-2013/man0p/poll.h.0p new file mode 100644 index 0000000..82680aa --- /dev/null +++ b/man-pages-posix-2013/man0p/poll.h.0p @@ -0,0 +1,135 @@ +'\" et +.TH poll.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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.h +\(em definitions for the poll(\|) function +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR pollfd +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +int fd \fRThe following descriptor being polled.\fP +short events \fRThe input event flags (see below).\fP +short revents \fRThe output event flags (see below).\fP +.fi \fR +.P +.RE +.P +The +.IR +header shall define the following type through +.BR typedef : +.IP "\fBnfds_t\fR" 14 +An unsigned integer type used for the number of file descriptors. +.P +The implementation shall support one or more programming environments +in which the width of +.BR nfds_t +is no greater than the width of type +.BR long . +The names of these programming environments can be obtained using the +\fIconfstr\fR() +function or the +.IR getconf +utility. +.P +The +.IR +header shall define the following symbolic constants, zero or more of +which may be OR'ed together to form the +.IR events +or +.IR revents +members in the +.BR pollfd +structure: +.IP POLLIN 14 +Data other than high-priority data may be read without blocking. +.IP POLLRDNORM 14 +Normal data may be read without blocking. +.IP POLLRDBAND 14 +Priority data may be read without blocking. +.IP POLLPRI 14 +High priority data may be read without blocking. +.IP POLLOUT 14 +Normal data may be written without blocking. +.IP POLLWRNORM 14 +Equivalent to POLLOUT. +.IP POLLWRBAND 14 +Priority data may be written. +.IP POLLERR 14 +An error has occurred (\c +.IR revents +only). +.IP POLLHUP 14 +Device has been disconnected (\c +.IR revents +only). +.IP POLLNVAL 14 +Invalid +.IR fd +member (\c +.IR revents +only). +.P +The significance and semantics of normal, priority, and high-priority +data are file and device-specific. +.P +The following shall be declared as a function and may also be defined +as a macro. A function prototype shall be provided. +.sp +.RS 4 +.nf +\fB +int poll(struct pollfd [], nfds_t, int); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIconfstr\fR\^(\|)", +.IR "\fIpoll\fR\^(\|)" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIgetconf\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/pthread.h.0p b/man-pages-posix-2013/man0p/pthread.h.0p new file mode 100644 index 0000000..e8e1bce --- /dev/null +++ b/man-pages-posix-2013/man0p/pthread.h.0p @@ -0,0 +1,325 @@ +'\" et +.TH pthread.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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.h +\(em threads +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following symbolic constants: +.P +.nf +PTHREAD_BARRIER_SERIAL_THREAD +PTHREAD_CANCEL_ASYNCHRONOUS +PTHREAD_CANCEL_ENABLE +PTHREAD_CANCEL_DEFERRED +PTHREAD_CANCEL_DISABLE +PTHREAD_CANCELED +PTHREAD_CREATE_DETACHED +PTHREAD_CREATE_JOINABLE +PTHREAD_EXPLICIT_SCHED +PTHREAD_INHERIT_SCHED +PTHREAD_MUTEX_DEFAULT +PTHREAD_MUTEX_ERRORCHECK +PTHREAD_MUTEX_NORMAL +PTHREAD_MUTEX_RECURSIVE +PTHREAD_MUTEX_ROBUST +PTHREAD_MUTEX_STALLED +PTHREAD_ONCE_INIT +PTHREAD_PRIO_INHERIT +PTHREAD_PRIO_NONE +PTHREAD_PRIO_PROTECT +PTHREAD_PROCESS_SHARED +PTHREAD_PROCESS_PRIVATE +PTHREAD_SCOPE_PROCESS +PTHREAD_SCOPE_SYSTEM +.fi +.P +The +.IR +header shall define the following compile-time constant +expressions valid as initializers for the following types: +.TS +tab(!) center box; +cB | cB +l | lB. +Name!Initializer for Type +_ +PTHREAD_COND_INITIALIZER!pthread_cond_t +PTHREAD_MUTEX_INITIALIZER!pthread_mutex_t +PTHREAD_RWLOCK_INITIALIZER!pthread_rwlock_t +.TE +.P +The +.IR +header shall define the +.BR pthread_attr_t , +.BR pthread_barrier_t , +.BR pthread_barrierattr_t , +.BR pthread_cond_t , +.BR pthread_condattr_t , +.BR pthread_key_t , +.BR pthread_mutex_t , +.BR pthread_mutexattr_t , +.BR pthread_once_t , +.BR pthread_rwlock_t , +.BR pthread_rwlockattr_t , +.BR pthread_spinlock_t , +and +.BR pthread_t +types as described in +.IR . +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int pthread_atfork(void (*)(void), void (*)(void), + void(*)(void)); +int pthread_attr_destroy(pthread_attr_t *); +int pthread_attr_getdetachstate(const pthread_attr_t *, int *); +int pthread_attr_getguardsize(const pthread_attr_t *restrict, + size_t *restrict); +int pthread_attr_getinheritsched(const pthread_attr_t *restrict, + int *restrict); +int pthread_attr_getschedparam(const pthread_attr_t *restrict, + struct sched_param *restrict); +int pthread_attr_getschedpolicy(const pthread_attr_t *restrict, + int *restrict); +int pthread_attr_getscope(const pthread_attr_t *restrict, + int *restrict); +int pthread_attr_getstack(const pthread_attr_t *restrict, + void **restrict, size_t *restrict); +int pthread_attr_getstacksize(const pthread_attr_t *restrict, + size_t *restrict); +int pthread_attr_init(pthread_attr_t *); +int pthread_attr_setdetachstate(pthread_attr_t *, int); +int pthread_attr_setguardsize(pthread_attr_t *, size_t); +int pthread_attr_setinheritsched(pthread_attr_t *, int); +int pthread_attr_setschedparam(pthread_attr_t *restrict, + const struct sched_param *restrict); +int pthread_attr_setschedpolicy(pthread_attr_t *, int); +int pthread_attr_setscope(pthread_attr_t *, int); +int pthread_attr_setstack(pthread_attr_t *, void *, size_t); +int pthread_attr_setstacksize(pthread_attr_t *, size_t); +int pthread_barrier_destroy(pthread_barrier_t *); +int pthread_barrier_init(pthread_barrier_t *restrict, + const pthread_barrierattr_t *restrict, unsigned); +int pthread_barrier_wait(pthread_barrier_t *); +int pthread_barrierattr_destroy(pthread_barrierattr_t *); +int pthread_barrierattr_getpshared( + const pthread_barrierattr_t *restrict, int *restrict); +int pthread_barrierattr_init(pthread_barrierattr_t *); +int pthread_barrierattr_setpshared(pthread_barrierattr_t *, int); +int pthread_cancel(pthread_t); +void pthread_cleanup_pop(int); +void pthread_cleanup_push(void (*)(void*), void *); +int pthread_cond_broadcast(pthread_cond_t *); +int pthread_cond_destroy(pthread_cond_t *); +int pthread_cond_init(pthread_cond_t *restrict, + const pthread_condattr_t *restrict); +int pthread_cond_signal(pthread_cond_t *); +int pthread_cond_timedwait(pthread_cond_t *restrict, + pthread_mutex_t *restrict, const struct timespec *restrict); +int pthread_cond_wait(pthread_cond_t *restrict, + pthread_mutex_t *restrict); +int pthread_condattr_destroy(pthread_condattr_t *); +int pthread_condattr_getclock(const pthread_condattr_t *restrict, + clockid_t *restrict); +int pthread_condattr_getpshared(const pthread_condattr_t *restrict, + int *restrict); +int pthread_condattr_init(pthread_condattr_t *); +int pthread_condattr_setclock(pthread_condattr_t *, clockid_t); +int pthread_condattr_setpshared(pthread_condattr_t *, int); +int pthread_create(pthread_t *restrict, const pthread_attr_t *restrict, + void *(*)(void*), void *restrict); +int pthread_detach(pthread_t); +int pthread_equal(pthread_t, pthread_t); +void pthread_exit(void *); +int pthread_getconcurrency(void); +int pthread_getcpuclockid(pthread_t, clockid_t *); +int pthread_getschedparam(pthread_t, int *restrict, + struct sched_param *restrict); +void *pthread_getspecific(pthread_key_t); +int pthread_join(pthread_t, void **); +int pthread_key_create(pthread_key_t *, void (*)(void*)); +int pthread_key_delete(pthread_key_t); +int pthread_mutex_consistent(pthread_mutex_t *); +int pthread_mutex_destroy(pthread_mutex_t *); +int pthread_mutex_getprioceiling(const pthread_mutex_t *restrict, + int *restrict); +int pthread_mutex_init(pthread_mutex_t *restrict, + const pthread_mutexattr_t *restrict); +int pthread_mutex_lock(pthread_mutex_t *); +int pthread_mutex_setprioceiling(pthread_mutex_t *restrict, int, + int *restrict); +int pthread_mutex_timedlock(pthread_mutex_t *restrict, + const struct timespec *restrict); +int pthread_mutex_trylock(pthread_mutex_t *); +int pthread_mutex_unlock(pthread_mutex_t *); +int pthread_mutexattr_destroy(pthread_mutexattr_t *); +int pthread_mutexattr_getprioceiling( + const pthread_mutexattr_t *restrict, int *restrict); +int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *restrict, + int *restrict); +int pthread_mutexattr_getpshared(const pthread_mutexattr_t *restrict, + int *restrict); +int pthread_mutexattr_getrobust(const pthread_mutexattr_t *restrict, + int *restrict); +int pthread_mutexattr_gettype(const pthread_mutexattr_t *restrict, + int *restrict); +int pthread_mutexattr_init(pthread_mutexattr_t *); +int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *, int); +int pthread_mutexattr_setprotocol(pthread_mutexattr_t *, int); +int pthread_mutexattr_setpshared(pthread_mutexattr_t *, int); +int pthread_mutexattr_setrobust(pthread_mutexattr_t *, int); +int pthread_mutexattr_settype(pthread_mutexattr_t *, int); +int pthread_once(pthread_once_t *, void (*)(void)); +int pthread_rwlock_destroy(pthread_rwlock_t *); +int pthread_rwlock_init(pthread_rwlock_t *restrict, + const pthread_rwlockattr_t *restrict); +int pthread_rwlock_rdlock(pthread_rwlock_t *); +int pthread_rwlock_timedrdlock(pthread_rwlock_t *restrict, + const struct timespec *restrict); +int pthread_rwlock_timedwrlock(pthread_rwlock_t *restrict, + const struct timespec *restrict); +int pthread_rwlock_tryrdlock(pthread_rwlock_t *); +int pthread_rwlock_trywrlock(pthread_rwlock_t *); +int pthread_rwlock_unlock(pthread_rwlock_t *); +int pthread_rwlock_wrlock(pthread_rwlock_t *); +int pthread_rwlockattr_destroy(pthread_rwlockattr_t *); +int pthread_rwlockattr_getpshared( + const pthread_rwlockattr_t *restrict, int *restrict); +int pthread_rwlockattr_init(pthread_rwlockattr_t *); +int pthread_rwlockattr_setpshared(pthread_rwlockattr_t *, int); +pthread_t + pthread_self(void); +int pthread_setcancelstate(int, int *); +int pthread_setcanceltype(int, int *); +int pthread_setconcurrency(int); +int pthread_setschedparam(pthread_t, int, + const struct sched_param *); +int pthread_setschedprio(pthread_t, int); +int pthread_setspecific(pthread_key_t, const void *); +int pthread_spin_destroy(pthread_spinlock_t *); +int pthread_spin_init(pthread_spinlock_t *, int); +int pthread_spin_lock(pthread_spinlock_t *); +int pthread_spin_trylock(pthread_spinlock_t *); +int pthread_spin_unlock(pthread_spinlock_t *); +void pthread_testcancel(void); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header shall make symbols defined in the headers +.IR +and +.IR +visible. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +.ad l +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIpthread_atfork\fR\^(\|)", +.IR "\fIpthread_attr_destroy\fR\^(\|)", +.IR "\fIpthread_attr_getdetachstate\fR\^(\|)", +.IR "\fIpthread_attr_getguardsize\fR\^(\|)", +.IR "\fIpthread_attr_getinheritsched\fR\^(\|)", +.IR "\fIpthread_attr_getschedparam\fR\^(\|)", +.IR "\fIpthread_attr_getschedpolicy\fR\^(\|)", +.IR "\fIpthread_attr_getscope\fR\^(\|)", +.IR "\fIpthread_attr_getstack\fR\^(\|)", +.IR "\fIpthread_attr_getstacksize\fR\^(\|)", +.IR "\fIpthread_barrier_destroy\fR\^(\|)", +.IR "\fIpthread_barrier_wait\fR\^(\|)", +.IR "\fIpthread_barrierattr_destroy\fR\^(\|)", +.IR "\fIpthread_barrierattr_getpshared\fR\^(\|)", +.IR "\fIpthread_cancel\fR\^(\|)", +.IR "\fIpthread_cleanup_pop\fR\^(\|)", +.IR "\fIpthread_cond_broadcast\fR\^(\|)", +.IR "\fIpthread_cond_destroy\fR\^(\|)", +.IR "\fIpthread_cond_timedwait\fR\^(\|)", +.IR "\fIpthread_condattr_destroy\fR\^(\|)", +.IR "\fIpthread_condattr_getclock\fR\^(\|)", +.IR "\fIpthread_condattr_getpshared\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)", +.IR "\fIpthread_detach\fR\^(\|)", +.IR "\fIpthread_equal\fR\^(\|)", +.IR "\fIpthread_exit\fR\^(\|)", +.IR "\fIpthread_getconcurrency\fR\^(\|)", +.IR "\fIpthread_getcpuclockid\fR\^(\|)", +.IR "\fIpthread_getschedparam\fR\^(\|)", +.IR "\fIpthread_getspecific\fR\^(\|)", +.IR "\fIpthread_join\fR\^(\|)", +.IR "\fIpthread_key_create\fR\^(\|)", +.IR "\fIpthread_key_delete\fR\^(\|)", +.IR "\fIpthread_mutex_consistent\fR\^(\|)", +.IR "\fIpthread_mutex_destroy\fR\^(\|)", +.IR "\fIpthread_mutex_getprioceiling\fR\^(\|)", +.IR "\fIpthread_mutex_lock\fR\^(\|)", +.IR "\fIpthread_mutex_timedlock\fR\^(\|)", +.IR "\fIpthread_mutexattr_destroy\fR\^(\|)", +.IR "\fIpthread_mutexattr_getprioceiling\fR\^(\|)", +.IR "\fIpthread_mutexattr_getprotocol\fR\^(\|)", +.IR "\fIpthread_mutexattr_getpshared\fR\^(\|)", +.IR "\fIpthread_mutexattr_getrobust\fR\^(\|)", +.IR "\fIpthread_mutexattr_gettype\fR\^(\|)", +.IR "\fIpthread_once\fR\^(\|)", +.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\^(\|)", +.IR "\fIpthread_rwlock_unlock\fR\^(\|)", +.IR "\fIpthread_rwlockattr_destroy\fR\^(\|)", +.IR "\fIpthread_rwlockattr_getpshared\fR\^(\|)", +.IR "\fIpthread_self\fR\^(\|)", +.IR "\fIpthread_setcancelstate\fR\^(\|)", +.IR "\fIpthread_setschedprio\fR\^(\|)", +.IR "\fIpthread_spin_destroy\fR\^(\|)", +.IR "\fIpthread_spin_lock\fR\^(\|)", +.IR "\fIpthread_spin_unlock\fR\^(\|)" +.ad b +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/pwd.h.0p b/man-pages-posix-2013/man0p/pwd.h.0p new file mode 100644 index 0000000..f57166c --- /dev/null +++ b/man-pages-posix-2013/man0p/pwd.h.0p @@ -0,0 +1,95 @@ +'\" et +.TH pwd.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pwd.h +\(em password structure +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR "struct passwd" , +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +char *pw_name \fRUser's login name.\fP +uid_t pw_uid \fRNumerical user ID.\fP +gid_t pw_gid \fRNumerical group ID.\fP +char *pw_dir \fRInitial working directory.\fP +char *pw_shell \fRProgram to use as shell.\fP +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR gid_t , +.BR uid_t , +and +.BR size_t +types as described in +.IR . +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +void endpwent(void); +struct passwd *getpwent(void); +struct passwd *getpwnam(const char *); +int getpwnam_r(const char *, struct passwd *, char *, + size_t, struct passwd **); +struct passwd *getpwuid(uid_t); +int getpwuid_r(uid_t, struct passwd *, char *, + size_t, struct passwd **); +void setpwent(void); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIendpwent\fR\^(\|)", +.IR "\fIgetpwnam\fR\^(\|)", +.IR "\fIgetpwuid\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/regex.h.0p b/man-pages-posix-2013/man0p/regex.h.0p new file mode 100644 index 0000000..5d0caa5 --- /dev/null +++ b/man-pages-posix-2013/man0p/regex.h.0p @@ -0,0 +1,209 @@ +'\" et +.TH regex.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +regex.h +\(em regular expression matching types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the structures and symbolic constants used by the +\fIregcomp\fR(), +\fIregexec\fR(), +\fIregerror\fR(), +and +\fIregfree\fR() +functions. +.P +The +.IR +header shall define the +.BR regex_t +structure type, which shall include at least the following member: +.sp +.RS 4 +.nf +\fB +size_t re_nsub \fRNumber of parenthesized subexpressions.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR size_t +type as described in +.IR . +.P +The +.IR +header shall define the +.BR regoff_t +type as a signed integer type that can hold +the largest value that can be stored in either a +.BR ptrdiff_t +type or a +.BR ssize_t +type. +.P +The +.IR +header shall define the +.BR regmatch_t +structure type, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +regoff_t rm_so \fRByte offset from start of string\fR + \fRto start of substring.\fR +regoff_t rm_eo \fRByte offset from start of string of the\fR + \fRfirst character after the end of substring.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the following symbolic constants for the +.IR cflags +parameter to the +\fIregcomp\fR() +function: +.IP REG_EXTENDED 14 +Use Extended Regular Expressions. +.IP REG_ICASE 14 +Ignore case in match. +.IP REG_NOSUB 14 +Report only success or fail in +\fIregexec\fR(). +.IP REG_NEWLINE 14 +Change the handling of +. +.P +The +.IR +header shall define the following symbolic constants for the +.IR eflags +parameter to the +\fIregexec\fR() +function: +.IP REG_NOTBOL 14 +The + +character (\c +.BR '^' ), +when taken as a special character, does not match the beginning of +.IR string . +.IP REG_NOTEOL 14 +The + +(\c +.BR '$' ), +when taken as a special character, does not match the end of +.IR string . +.P +The +.IR +header shall define the following symbolic constants as error +return values: +.IP REG_NOMATCH 14 +\fIregexec\fR() +failed to match. +.IP REG_BADPAT 14 +Invalid regular expression. +.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_ESUBREG 14 +Number in \e\fIdigit\fP invalid or in error. +.IP REG_EBRACK 14 +.BR \(dq[]\(dq +imbalance. +.IP REG_EPAREN 14 +.BR \(dq\e(\e)\(dq +or +.BR \(dq()\(dq +imbalance. +.IP REG_EBRACE 14 +.BR \(dq\e{\e}\(dq +imbalance. +.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_ERANGE 14 +Invalid endpoint in range expression. +.IP REG_ESPACE 14 +Out of memory. +.IP REG_BADRPT 14 +.BR '?' , +.BR '*' , +or +.BR '+' +not preceded by valid regular expression. +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int regcomp(regex_t *restrict, const char *restrict, int); +size_t regerror(int, const regex_t *restrict, char *restrict, size_t); +int regexec(const regex_t *restrict, const char *restrict, size_t, + regmatch_t [restrict], int); +void regfree(regex_t *); +.fi \fR +.P +.RE +.P +The implementation may define additional macros or constants using +names beginning with REG_. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIregcomp\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/sched.h.0p b/man-pages-posix-2013/man0p/sched.h.0p new file mode 100644 index 0000000..488ffd1 --- /dev/null +++ b/man-pages-posix-2013/man0p/sched.h.0p @@ -0,0 +1,155 @@ +'\" et +.TH sched.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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.h +\(em execution scheduling +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR pid_t +type as described in +.IR . +.P +The +.IR +header shall define the +.BR time_t +type as described in +.IR . +.P +The +.IR +header shall define the +.BR timespec +structure as described in +.IR . +.P +The +.IR +header shall define the +.BR sched_param +structure, which shall include the scheduling parameters required for +implementation of each supported scheduling policy. This structure +shall include at least the following member: +.sp +.RS 4 +.nf +\fB +int sched_priority \fRProcess or thread execution scheduling priority.\fP +.fi \fR +.P +.RE +.P +The +.BR sched_param +structure defined in +.IR +shall include the following members in addition to those specified +above: +.sp +.RS 4 +.nf +\fB +int sched_ss_low_priority \fRLow scheduling priority for\fR + \fRsporadic server.\fR +struct timespec sched_ss_repl_period \fRReplenishment period for\fR + \fRsporadic server.\fR +struct timespec sched_ss_init_budget \fRInitial budget for sporadic server.\fR +int sched_ss_max_repl \fRMaximum pending replenishments for\fR + \fRsporadic server.\fR +.fi \fR +.P +.RE +.P +Each process or thread is controlled by an associated scheduling policy +and priority. Associated with each policy is a priority range. Each +policy definition specifies the minimum priority range for that +policy. The priority ranges for each policy may overlap the priority +ranges of other policies. +.P +Four scheduling policies are defined; others may be defined by the +implementation. The four standard policies are indicated by the +values of the following symbolic constants: +.IP SCHED_FIFO 14 +First in-first out (FIFO) scheduling policy. +.IP SCHED_RR 14 +Round robin scheduling policy. +.IP SCHED_SPORADIC 14 +Sporadic server scheduling policy. +.IP SCHED_OTHER 14 +Another scheduling policy. +.P +The values of these constants are distinct. +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int sched_get_priority_max(int); +int sched_get_priority_min(int); +int sched_getparam(pid_t, struct sched_param *); +int sched_getscheduler(pid_t); +int sched_rr_get_interval(pid_t, struct timespec *); +int sched_setparam(pid_t, const struct sched_param *); +int sched_setscheduler(pid_t, int, const struct sched_param *); +int sched_yield(void); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may make visible all symbols from the +.IR +header. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIsched_get_priority_max\fR\^(\|)", +.IR "\fIsched_getparam\fR\^(\|)", +.IR "\fIsched_getscheduler\fR\^(\|)", +.IR "\fIsched_rr_get_interval\fR\^(\|)", +.IR "\fIsched_setparam\fR\^(\|)", +.IR "\fIsched_setscheduler\fR\^(\|)", +.IR "\fIsched_yield\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/search.h.0p b/man-pages-posix-2013/man0p/search.h.0p new file mode 100644 index 0000000..fca8acf --- /dev/null +++ b/man-pages-posix-2013/man0p/search.h.0p @@ -0,0 +1,115 @@ +'\" et +.TH search.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +search.h +\(em search tables +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR ENTRY +type for structure +.BR entry +which shall include the following members: +.sp +.RS 4 +.nf +\fB +char *key +void *data +.fi \fR +.P +.RE +.P +and shall define +.BR ACTION +and +.BR VISIT +as enumeration data types through type definitions as follows: +.sp +.RS 4 +.nf +\fB +enum { FIND, ENTER } ACTION; +enum { preorder, postorder, endorder, leaf } VISIT; +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR size_t +type as described in +.IR . +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int hcreate(size_t); +void hdestroy(void); +ENTRY *hsearch(ENTRY, ACTION); +void insque(void *, void *); +void *lfind(const void *, const void *, size_t *, + size_t, int (*)(const void *, const void *)); +void *lsearch(const void *, void *, size_t *, + size_t, int (*)(const void *, const void *)); +void remque(void *); +void *tdelete(const void *restrict, void **restrict, + int(*)(const void *, const void *)); +void *tfind(const void *, void *const *, + int(*)(const void *, const void *)); +void *tsearch(const void *, void **, + int(*)(const void *, const void *)); +void twalk(const void *, + void (*)(const void *, VISIT, int )); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIhcreate\fR\^(\|)", +.IR "\fIinsque\fR\^(\|)", +.IR "\fIlsearch\fR\^(\|)", +.IR "\fItdelete\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/semaphore.h.0p b/man-pages-posix-2013/man0p/semaphore.h.0p new file mode 100644 index 0000000..3f277f4 --- /dev/null +++ b/man-pages-posix-2013/man0p/semaphore.h.0p @@ -0,0 +1,100 @@ +'\" et +.TH semaphore.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +semaphore.h +\(em semaphores +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR sem_t +type, used in performing semaphore operations. The semaphore may be +implemented using a file descriptor, in which case applications are +able to open up at least a total of +{OPEN_MAX} +files and semaphores. +.P +The +.IR +header shall define the symbolic constant SEM_FAILED which shall +have type +.BR "sem_t *" . +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int sem_close(sem_t *); +int sem_destroy(sem_t *); +int sem_getvalue(sem_t *restrict, int *restrict); +int sem_init(sem_t *, int, unsigned); +sem_t *sem_open(const char *, int, ...); +int sem_post(sem_t *); +int sem_timedwait(sem_t *restrict, const struct timespec *restrict); +int sem_trywait(sem_t *); +int sem_unlink(const char *); +int sem_wait(sem_t *); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may make visible symbols defined in the +.IR +and +.IR +headers. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.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_timedwait\fR\^(\|)", +.IR "\fIsem_trywait\fR\^(\|)", +.IR "\fIsem_unlink\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/setjmp.h.0p b/man-pages-posix-2013/man0p/setjmp.h.0p new file mode 100644 index 0000000..c090cc7 --- /dev/null +++ b/man-pages-posix-2013/man0p/setjmp.h.0p @@ -0,0 +1,89 @@ +'\" et +.TH setjmp.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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.h +\(em stack environment declarations +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends the +ISO\ C standard. Applications shall define the appropriate feature test macro +(see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment") +to enable the visibility of these symbols in this header. +.P +The +.IR +header shall define the array types +.BR jmp_buf +and +.BR sigjmp_buf . +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +void _longjmp(jmp_buf, int); +void longjmp(jmp_buf, int); +void siglongjmp(sigjmp_buf, int); +.fi \fR +.P +.RE +.P +The following may be declared as functions, or defined as macros, or +both. If functions are declared, function prototypes shall be +provided. +.sp +.RS 4 +.nf +\fB +int _setjmp(jmp_buf); +int setjmp(jmp_buf); +int sigsetjmp(sigjmp_buf, int); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment", +.IR "\fI_longjmp\fR\^(\|)", +.IR "\fIlongjmp\fR\^(\|)", +.IR "\fIsetjmp\fR\^(\|)", +.IR "\fIsiglongjmp\fR\^(\|)", +.IR "\fIsigsetjmp\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/signal.h.0p b/man-pages-posix-2013/man0p/signal.h.0p new file mode 100644 index 0000000..c3b579c --- /dev/null +++ b/man-pages-posix-2013/man0p/signal.h.0p @@ -0,0 +1,582 @@ +'\" et +.TH signal.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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.h +\(em signals +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends the +ISO\ C standard. Applications shall define the appropriate feature test macro +(see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment") +to enable the visibility of these symbols in this header. +.P +The +.IR +header shall define the following macros, which shall expand to constant +expressions with distinct values that have a type compatible with the +second argument to, and the return value of, the +\fIsignal\fR() +function, and whose values shall compare unequal to the address of any +declarable function. +.IP SIG_DFL 14 +Request for default signal handling. +.IP SIG_ERR 14 +Return value from +\fIsignal\fR() +in case of error. +.IP SIG_HOLD 14 +Request that signal be held. +.IP SIG_IGN 14 +Request that signal be ignored. +.P +The +.IR +header shall define the +.BR pthread_t , +.BR size_t , +and +.BR uid_t +types as described in +.IR . +.P +The +.IR +header shall define the +.BR timespec +structure as described in +.IR . +.P +The +.IR +header shall define the following data types: +.IP "\fBsig_atomic_t\fP" 14 +Possibly volatile-qualified integer type of an object that can be +accessed as an atomic entity, even in the presence of asynchronous +interrupts. +.IP "\fBsigset_t\fP" 14 +Integer or structure type of an object used to represent sets of +signals. +.IP "\fBpid_t\fP" 14 +As described in +.IR . +.P +The +.IR +header shall define the +.BR pthread_attr_t +type as described in +.IR . +.P +The +.IR +header shall define the +.BR sigevent +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +int sigev_notify \fRNotification type.\fP +int sigev_signo \fRSignal number.\fP +union sigval sigev_value \fRSignal value.\fP +void (*sigev_notify_function)(union sigval) + \fRNotification function.\fP +pthread_attr_t *sigev_notify_attributes \fRNotification attributes.\fP +.fi \fR +.P +.RE +.P +The +.IR +header shall define the following symbolic constants for the values of +.IR sigev_notify : +.IP SIGEV_NONE 14 +No asynchronous notification is delivered when the event of interest +occurs. +.IP SIGEV_SIGNAL 14 +A queued signal, with an application-defined value, is generated when +the event of interest occurs. +.IP SIGEV_THREAD 14 +A notification function is called to perform notification. +.br +.P +The +.BR sigval +union shall be defined as: +.sp +.RS 4 +.nf +\fB +int sival_int \fRInteger signal value.\fP +void *sival_ptr \fRPointer signal value.\fP +.fi \fR +.P +.RE +.P +The +.IR +header shall declare the SIGRTMIN and SIGRTMAX macros, +which shall expand to positive integer expressions with type +.BR int , +but which need not be constant expressions. These macros specify a +range of signal numbers that are reserved for application use and for +which the realtime signal behavior specified in this volume of POSIX.1\(hy2008 is supported. The +signal numbers in this range do not overlap any of the signals specified +in the following table. +.P +The range SIGRTMIN through SIGRTMAX inclusive shall include at least +{RTSIG_MAX} +signal numbers. +.P +It is implementation-defined whether realtime signal behavior is +supported for other signals. +.P +The +.IR +header shall define the following macros that are used to refer to the +signals that occur in the system. Signals defined here begin with the +letters SIG followed by an uppercase letter. The macros shall expand to +positive integer constant expressions with type +.BR int +and distinct values. The value 0 is reserved for use as the null signal +(see +\fIkill\fR()). +Additional implementation-defined signals may occur in the system. +.P +The ISO\ C standard only requires the signal names SIGABRT, SIGFPE, SIGILL, +SIGINT, SIGSEGV, and SIGTERM to be defined. +.P +The following signals shall be supported on all implementations +(default actions are explained below the table): +.TS +box center tab(!); +cB | cB | cB +l | n | lw(3.6i). +Signal!Default Action!Description +_ +SIGABRT!A!Process abort signal. +SIGALRM!T!Alarm clock. +SIGBUS!A!Access to an undefined portion of a memory object. +SIGCHLD!I!Child process terminated, stopped, +!!or continued. +SIGCONT!C!Continue executing, if stopped. +SIGFPE!A!Erroneous arithmetic operation. +SIGHUP!T!Hangup. +SIGILL!A!Illegal instruction. +SIGINT!T!Terminal interrupt signal. +SIGKILL!T!Kill (cannot be caught or ignored). +SIGPIPE!T!Write on a pipe with no one to read it. +SIGQUIT!A!Terminal quit signal. +SIGSEGV!A!Invalid memory reference. +SIGSTOP!S!Stop executing (cannot be caught or ignored). +SIGTERM!T!Termination signal. +SIGTSTP!S!Terminal stop signal. +SIGTTIN!S!Background process attempting read. +SIGTTOU!S!Background process attempting write. +SIGUSR1!T!User-defined signal 1. +SIGUSR2!T!User-defined signal 2. +SIGPOLL!T!Pollable event. +SIGPROF!T!Profiling timer expired. +SIGSYS!A!Bad system call. +SIGTRAP!A!Trace/breakpoint trap. +SIGURG!I!High bandwidth data is available at a socket. +SIGVTALRM!T!Virtual timer expired. +SIGXCPU!A!CPU time limit exceeded. +SIGXFSZ!A!File size limit exceeded. +.sp +.TE +.br +.P +The default actions are as follows: +.IP T 6 +Abnormal termination of the process. +.IP A 6 +Abnormal termination of the process +with additional actions. +.IP I 6 +Ignore the signal. +.IP S 6 +Stop the process. +.IP C 6 +Continue the process, if it is stopped; otherwise, ignore the signal. +.P +The effects on the process in each case are described in the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.4.3" ", " "Signal Actions". +.P +The +.IR +header shall declare the +.BR sigaction +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +void (*sa_handler)(int) \fRPointer to a signal-catching function\fR + \fRor one of the SIG_IGN or SIG_DFL.\fR +sigset_t sa_mask \fRSet of signals to be blocked during execution\fR + \fRof the signal handling function.\fR +int sa_flags \fRSpecial flags.\fR +void (*sa_sigaction)(int, siginfo_t *, void *) + \fRPointer to a signal-catching function.\fR +.fi \fR +.P +.RE +.P +The storage occupied by +.IR sa_handler +and +.IR sa_sigaction +may overlap, and a conforming application shall not use both +simultaneously. +.P +The +.IR +header shall define the following macros which shall expand to +integer constant expressions that need not be usable in +.BR #if +preprocessing directives: +.IP SIG_BLOCK 14 +The resulting set is the union of the current set and the signal set +pointed to by the argument +.IR set . +.IP SIG_UNBLOCK 14 +The resulting set is the intersection of the current set and the +complement of the signal set pointed to by the argument +.IR set . +.IP SIG_SETMASK 14 +The resulting set is the signal set pointed to by the argument +.IR set . +.P +The +.IR +header shall also define the following symbolic constants: +.IP SA_NOCLDSTOP 14 +Do not generate SIGCHLD when children stop +.br +or stopped children continue. +.IP SA_ONSTACK 14 +Causes signal delivery to occur on an alternate stack. +.IP SA_RESETHAND 14 +Causes signal dispositions to be set to SIG_DFL on entry to signal +handlers. +.IP SA_RESTART 14 +Causes certain functions to become restartable. +.IP SA_SIGINFO 14 +Causes extra information to be passed to signal handlers at the time of +receipt of a signal. +.IP SA_NOCLDWAIT 14 +Causes implementations not to create zombie processes on child death. +.IP SA_NODEFER 14 +Causes signal not to be automatically blocked on entry to signal handler. +.IP SS_ONSTACK 14 +Process is executing on an alternate signal stack. +.IP SS_DISABLE 14 +Alternate signal stack is disabled. +.IP MINSIGSTKSZ 14 +Minimum stack size for a signal handler. +.IP SIGSTKSZ 14 +Default size in bytes for the alternate signal stack. +.P +The +.IR +header shall define the +.BR mcontext_t +type through +.BR typedef . +.P +The +.IR +header shall define the +.BR ucontext_t +type as a structure that shall include at least the following members: +.sp +.RS 4 +.nf +\fB +ucontext_t *uc_link \fRPointer to the context that is resumed\fR + \fRwhen this context returns.\fR +sigset_t uc_sigmask \fRThe set of signals that are blocked when this\fR + \fRcontext is active.\fR +stack_t uc_stack \fRThe stack used by this context.\fR +mcontext_t uc_mcontext \fRA machine-specific representation of the saved\fR + \fRcontext.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR stack_t +type as a structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +void *ss_sp \fRStack base or pointer.\fR +size_t ss_size \fRStack size.\fR +int ss_flags \fRFlags.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR siginfo_t +type as a structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +int si_signo \fRSignal number.\fR +int si_code \fRSignal code.\fR +int si_errno \fRIf non-zero, an \fIerrno\fR value associated with\fR + \fRthis signal, as described in \fB\fR.\fR +pid_t si_pid \fRSending process ID.\fR +uid_t si_uid \fRReal user ID of sending process.\fR +void *si_addr \fRAddress of faulting instruction.\fR +int si_status \fRExit value or signal.\fR +long si_band \fRBand event for SIGPOLL.\fR +union sigval si_value \fRSignal value.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the symbolic constants in the +.BR Code +column of the following table for use as values of +.IR si_code +that are signal-specific or non-signal-specific reasons why the +signal was generated. +.TS +box center tab(!); +cB | cB | cB +l1 | l1 | l. +Signal!Code!Reason +_ +SIGILL!ILL_ILLOPC!Illegal opcode. +!ILL_ILLOPN!Illegal operand. +!ILL_ILLADR!Illegal addressing mode. +!ILL_ILLTRP!Illegal trap. +!ILL_PRVOPC!Privileged opcode. +!ILL_PRVREG!Privileged register. +!ILL_COPROC!Coprocessor error. +!ILL_BADSTK!Internal stack error. +_ +SIGFPE!FPE_INTDIV!Integer divide by zero. +!FPE_INTOVF!Integer overflow. +!FPE_FLTDIV!Floating-point divide by zero. +!FPE_FLTOVF!Floating-point overflow. +!FPE_FLTUND!Floating-point underflow. +!FPE_FLTRES!Floating-point inexact result. +!FPE_FLTINV!Invalid floating-point operation. +!FPE_FLTSUB!Subscript out of range. +_ +SIGSEGV!SEGV_MAPERR!Address not mapped to object. +!SEGV_ACCERR!Invalid permissions for mapped object. +_ +SIGBUS!BUS_ADRALN!Invalid address alignment. +!BUS_ADRERR!Nonexistent physical address. +!BUS_OBJERR!Object-specific hardware error. +_ +SIGTRAP!TRAP_BRKPT!Process breakpoint. +!TRAP_TRACE!Process trace trap. +_ +SIGCHLD!CLD_EXITED!Child has exited. +!CLD_KILLED!Child has terminated abnormally and did not create a \fBcore\fP file. +!CLD_DUMPED!Child has terminated abnormally and created a \fBcore\fP file. +!CLD_TRAPPED!Traced child has trapped. +!CLD_STOPPED!Child has stopped. +!CLD_CONTINUED!Stopped child has continued. +_ +SIGPOLL!POLL_IN!Data input available. +!POLL_OUT!Output buffers available. +!POLL_MSG!Input message available. +!POLL_ERR!I/O error. +!POLL_PRI!High priority input available. +!POLL_HUP!Device disconnected. +_ +Any!SI_USER!Signal sent by \fIkill\fP\^(\|). +!SI_QUEUE!Signal sent by \fIsigqueue\fP\^(\|). +!SI_TIMER!Signal generated by expiration of a timer set by \fItimer_settime\fP\^(\|). +!SI_ASYNCIO!Signal generated by completion of an asynchronous I/O +!!request. +!SI_MESGQ!Signal generated by arrival of a message on an empty message +!!queue. +.TE +.P +Implementations may support additional +.IR si_code +values not included in this list, may generate values included in this +list under circumstances other than those described in this list, and +may contain extensions or limitations that prevent some values from +being generated. Implementations do not generate a different value from +the ones described in this list for circumstances described in this +list. +.br +.P +In addition, the following signal-specific information shall be +available: +.TS +box center tab(!); +cB | cB | cB +l | lB | lw(3.9i). +Signal!Member!Value +_ +SIGILL!void * \fIsi_addr\fP!Address of faulting instruction. +SIGFPE +_ +SIGSEGV!void * \fIsi_addr\fP!Address of faulting memory reference. +SIGBUS +_ +SIGCHLD!pid_t \fIsi_pid\fP!Child process ID. +!int \fIsi_status\fP!Exit value or signal. +!uid_t \fIsi_uid\fP!Real user ID of the process that sent the signal. +_ +SIGPOLL!long \fIsi_band\fP!Band event for POLL_IN, POLL_OUT, or POLL_MSG. +.TE +.P +For some implementations, the value of \fIsi_addr\fR may be inaccurate. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int kill(pid_t, int); +int killpg(pid_t, int); +void psiginfo(const siginfo_t *, const char *); +void psignal(int, const char *); +int pthread_kill(pthread_t, int); +int pthread_sigmask(int, const sigset_t *restrict, + sigset_t *restrict); +int raise(int); +int sigaction(int, const struct sigaction *restrict, + struct sigaction *restrict); +int sigaddset(sigset_t *, int); +int sigaltstack(const stack_t *restrict, stack_t *restrict); +int sigdelset(sigset_t *, int); +int sigemptyset(sigset_t *); +int sigfillset(sigset_t *); +int sighold(int); +int sigignore(int); +int siginterrupt(int, int); +int sigismember(const sigset_t *, int); +void (*signal(int, void (*)(int)))(int); +int sigpause(int); +int sigpending(sigset_t *); +int sigprocmask(int, const sigset_t *restrict, sigset_t *restrict); +int sigqueue(pid_t, int, const union sigval); +int sigrelse(int); +void (*sigset(int, void (*)(int)))(int); +int sigsuspend(const sigset_t *); +int sigtimedwait(const sigset_t *restrict, siginfo_t *restrict, + const struct timespec *restrict); +int sigwait(const sigset_t *restrict, int *restrict); +int sigwaitinfo(const sigset_t *restrict, siginfo_t *restrict); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may make visible all symbols from the +.IR +header. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +On systems not supporting the XSI option, the +.IR si_pid +and +.IR si_uid +members of +.BR siginfo_t +are only required to be valid when +.IR si_code +is SI_USER or SI_QUEUE. On XSI-conforming systems, they are also +valid for all +.IR si_code +values less than or equal to 0; however, it is unspecified whether +SI_USER and SI_QUEUE have values less than or equal to zero, and +therefore XSI applications should check whether +.IR si_code +has the value SI_USER or SI_QUEUE or is less than or equal to 0 +to tell whether +.IR si_pid +and +.IR si_uid +are valid. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The SIGPOLL and SIGPROF signals may be removed in a future version. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +.ad l +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment", +.IR "\fIalarm\fR\^(\|)", +.IR "\fIioctl\fR\^(\|)", +.IR "\fIkill\fR\^(\|)", +.IR "\fIkillpg\fR\^(\|)", +.IR "\fIpsiginfo\fR\^(\|)", +.IR "\fIpthread_kill\fR\^(\|)", +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIraise\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigaddset\fR\^(\|)", +.IR "\fIsigaltstack\fR\^(\|)", +.IR "\fIsigdelset\fR\^(\|)", +.IR "\fIsigemptyset\fR\^(\|)", +.IR "\fIsigfillset\fR\^(\|)", +.IR "\fIsighold\fR\^(\|)", +.IR "\fIsiginterrupt\fR\^(\|)", +.IR "\fIsigismember\fR\^(\|)", +.IR "\fIsignal\fR\^(\|)", +.IR "\fIsigpending\fR\^(\|)", +.IR "\fIsigqueue\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)", +.IR "\fIsigtimedwait\fR\^(\|)", +.IR "\fIsigwait\fR\^(\|)", +.IR "\fItimer_create\fR\^(\|)", +.IR "\fIwait\fR\^(\|)", +.IR "\fIwaitid\fR\^(\|)" +.ad b +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/spawn.h.0p b/man-pages-posix-2013/man0p/spawn.h.0p new file mode 100644 index 0000000..1fe6495 --- /dev/null +++ b/man-pages-posix-2013/man0p/spawn.h.0p @@ -0,0 +1,168 @@ +'\" et +.TH spawn.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +spawn.h +\(em spawn (\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR posix_spawnattr_t +and +.BR posix_spawn_file_actions_t +types used in performing spawn operations. +.P +The +.IR +header shall define the +.BR mode_t +and +.BR pid_t +types as described in +.IR . +.P +The +.IR +header shall define the +.BR sigset_t +type as described in +.IR . +.P +The tag +.BR sched_param +shall be declared as naming an incomplete structure type, the contents +of which are described in the +.IR +header. +.P +The +.IR +header shall define the following symbolic constants for use as the +flags that may be set in a +.BR posix_spawnattr_t +object using the +\fIposix_spawnattr_setflags\fR() +function: +.P +.nf +POSIX_SPAWN_RESETIDS +POSIX_SPAWN_SETPGROUP +POSIX_SPAWN_SETSCHEDPARAM +POSIX_SPAWN_SETSCHEDULER +POSIX_SPAWN_SETSIGDEF +POSIX_SPAWN_SETSIGMASK +.fi +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int posix_spawn(pid_t *restrict, const char *restrict, + const posix_spawn_file_actions_t *, + const posix_spawnattr_t *restrict, char *const [restrict], + char *const [restrict]); +int posix_spawn_file_actions_addclose(posix_spawn_file_actions_t *, + int); +int posix_spawn_file_actions_adddup2(posix_spawn_file_actions_t *, + int, int); +int posix_spawn_file_actions_addopen(posix_spawn_file_actions_t *restrict, + int, const char *restrict, int, mode_t); +int posix_spawn_file_actions_destroy(posix_spawn_file_actions_t *); +int posix_spawn_file_actions_init(posix_spawn_file_actions_t *); +int posix_spawnattr_destroy(posix_spawnattr_t *); +int posix_spawnattr_getflags(const posix_spawnattr_t *restrict, + short *restrict); +int posix_spawnattr_getpgroup(const posix_spawnattr_t *restrict, + pid_t *restrict); +int posix_spawnattr_getschedparam(const posix_spawnattr_t *restrict, + struct sched_param *restrict); +int posix_spawnattr_getschedpolicy(const posix_spawnattr_t *restrict, + int *restrict); +int posix_spawnattr_getsigdefault(const posix_spawnattr_t *restrict, + sigset_t *restrict); +int posix_spawnattr_getsigmask(const posix_spawnattr_t *restrict, + sigset_t *restrict); +int posix_spawnattr_init(posix_spawnattr_t *); +int posix_spawnattr_setflags(posix_spawnattr_t *, short); +int posix_spawnattr_setpgroup(posix_spawnattr_t *, pid_t); +.br +int posix_spawnattr_setschedparam(posix_spawnattr_t *restrict, + const struct sched_param *restrict); +int posix_spawnattr_setschedpolicy(posix_spawnattr_t *, int); +int posix_spawnattr_setsigdefault(posix_spawnattr_t *restrict, + const sigset_t *restrict); +int posix_spawnattr_setsigmask(posix_spawnattr_t *restrict, + const sigset_t *restrict); +int posix_spawnp(pid_t *restrict, const char *restrict, + const posix_spawn_file_actions_t *, + const posix_spawnattr_t *restrict, + char *const [restrict], char *const [restrict]); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may make visible symbols defined in the +.IR +and +.IR +headers. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +.ad l +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIposix_spawn\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_getflags\fR\^(\|)", +.IR "\fIposix_spawnattr_getpgroup\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedparam\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedpolicy\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigdefault\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigmask\fR\^(\|)" +.ad b +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/stdarg.h.0p b/man-pages-posix-2013/man0p/stdarg.h.0p new file mode 100644 index 0000000..bfd5979 --- /dev/null +++ b/man-pages-posix-2013/man0p/stdarg.h.0p @@ -0,0 +1,224 @@ +'\" et +.TH stdarg.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +stdarg.h +\(em handle variable argument list +.SH SYNOPSIS +.LP +.nf +#include +.P +void va_start(va_list \fIap\fP, \fIargN\fP); +void va_copy(va_list \fIdest\fP, va_list \fIsrc\fP); +\fItype\fP va_arg(va_list \fIap\fP, \fItype\fP); +void va_end(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\(hy2008 defers to the ISO\ C standard. +.P +The +.IR +header shall contain a set of macros which allows portable functions +that accept variable argument lists to be written. Functions that have +variable argument lists (such as +\fIprintf\fR()) +but do not use these macros are inherently non-portable, as different +systems use different argument-passing conventions. +.P +The +.IR +header shall define the +.BR va_list +type for variables used to traverse the list. +.P +The +\fIva_start\fR() +macro is invoked to initialize +.IR ap +to the beginning of the list before any calls to +\fIva_arg\fR(). +.P +The +\fIva_copy\fR() +macro initializes +.IR dest +as a copy of +.IR src , +as if the +\fIva_start\fR() +macro had been applied to +.IR dest +followed by the same sequence of uses of the +\fIva_arg\fR() +macro as had previously been used to reach the present state of +.IR src . +Neither the +\fIva_copy\fR() +nor +\fIva_start\fR() +macro shall be invoked to reinitialize +.IR dest +without an intervening invocation of the +\fIva_end\fR() +macro for the same +.IR dest . +.P +The object +.IR ap +may be passed as an argument to another function; if that function +invokes the +\fIva_arg\fR() +macro with parameter +.IR ap , +the value of +.IR ap +in the calling function is unspecified and shall be passed to the +\fIva_end\fR() +macro prior to any further reference to +.IR ap . +The parameter +.IR argN +is the identifier of the rightmost parameter in the variable parameter +list in the function definition (the one just before the .\|.\|.). If +the parameter +.IR argN +is declared with the +.BR register +storage class, with a function type or array type, or with a type that +is not compatible with the type that results after application of the +default argument promotions, the behavior is undefined. +.P +The +\fIva_arg\fR() +macro shall return the next argument in the list pointed to by +.IR ap . +Each invocation of +\fIva_arg\fR() +modifies +.IR ap +so that the values of successive arguments are returned in turn. The +.IR type +parameter shall be a type name specified such that the type of a +pointer to an object that has the specified type can be obtained simply +by postfixing a +.BR '*' +to type. If there is no actual next argument, or if +.IR type +is not compatible with the type of the actual next argument (as +promoted according to the default argument promotions), the behavior is +undefined, except for the following cases: +.IP " *" 4 +One type is a signed integer type, the other type is the corresponding +unsigned integer type, and the value is representable in both types. +.IP " *" 4 +One type is a pointer to +.BR void +and the other is a pointer to a character type. +.IP " *" 4 +Both types are pointers. +.P +Different types can be mixed, but it is up to the routine to +know what type of argument is expected. +.P +The +\fIva_end\fR() +macro is used to clean up; it invalidates +.IR ap +for use (unless +\fIva_start\fR() +or +\fIva_copy\fR() +is invoked again). +.P +Each invocation of the +\fIva_start\fR() +and +\fIva_copy\fR() +macros shall be matched by a corresponding invocation of the +\fIva_end\fR() +macro in the same function. +.P +Multiple traversals, each bracketed by +\fIva_start\fR() +\&.\|.\|. +\fIva_end\fR(), +are possible. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +This example is a possible implementation of +\fIexecl\fR(): +.sp +.RS 4 +.nf +\fB +#include +.P +#define MAXARGS 31 +.P +/* + * execl is called by + * execl(file, arg1, arg2, ..., (char *)(0)); + */ +int execl(const char *file, const char *args, ...) +{ + va_list ap; + char *array[MAXARGS +1]; + int argno = 0; +.P + va_start(ap, args); + while (args != 0 && argno < MAXARGS) + { + array[argno++] = args; + args = va_arg(ap, const char *); + } + array[argno] = (char *) 0; + va_end(ap); + return execv(file, array); +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +It is up to the calling routine to communicate to the called routine +how many arguments there are, since it is not always possible for the +called routine to determine this in any other way. For example, +\fIexecl\fR() +is passed a null pointer to signal the end of the list. The +\fIprintf\fR() +function can tell how many arguments are there by the +.IR format +argument. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIexec\fR\^", +.IR "\fIfprintf\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/stdbool.h.0p b/man-pages-posix-2013/man0p/stdbool.h.0p new file mode 100644 index 0000000..746124b --- /dev/null +++ b/man-pages-posix-2013/man0p/stdbool.h.0p @@ -0,0 +1,65 @@ +'\" et +.TH stdbool.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +stdbool.h +\(em boolean type and values +.SH SYNOPSIS +.LP +.nf +#include +.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\(hy2008 defers to the ISO\ C standard. +.P +The +.IR +header shall define the following macros: +.IP bool 8 +Expands to +.BR _Bool . +.IP true 8 +Expands to the integer constant 1. +.IP false 8 +Expands to the integer constant 0. +.IP "_\|_bool_true_false_are_defined" 8 +.br +Expands to the integer constant 1. +.P +An application may undefine and then possibly redefine the macros bool, +true, and false. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The ability to undefine and redefine the macros bool, true, and false +is an obsolescent feature and may be removed in a future version. +.SH "SEE ALSO" +None. +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/stddef.h.0p b/man-pages-posix-2013/man0p/stddef.h.0p new file mode 100644 index 0000000..48a629d --- /dev/null +++ b/man-pages-posix-2013/man0p/stddef.h.0p @@ -0,0 +1,104 @@ +'\" et +.TH stddef.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +stddef.h +\(em standard type definitions +.SH SYNOPSIS +.LP +.nf +#include +.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\(hy2008 defers to the ISO\ C standard. +.P +The +.IR +header shall define the following macros: +.IP NULL 10 +Null pointer constant. +The macro shall expand to an integer constant expression with the +value 0 cast to type +.BR "void *" . +.IP "offsetof(\fItype\fP, \fImember-designator\fP)" 10 +.br +Integer constant expression of type +.BR size_t , +the value of which is the offset in bytes to the structure member +(\fImember-designator\fP), from the beginning of its structure +(\fItype\fP). +.P +The +.IR +header shall define the following types: +.IP "\fBptrdiff_t\fP" 10 +Signed integer type of the result of subtracting two pointers. +.IP "\fBwchar_t\fP" 10 +Integer type whose range of values can represent distinct codes for +all members of the largest extended character set specified among the +supported locales; the null character shall have the code value zero. Each +member of the basic character set shall have a code value equal to its +value when used as the lone character in an integer character constant +if an implementation does not define _\|_STDC_MB_MIGHT_NEQ_WC_\|_. +.IP "\fBsize_t\fP" 10 +Unsigned integer type of the result of the +.IR sizeof +operator. +.P +The implementation shall support one or more programming environments +in which the widths of +.BR ptrdiff_t , +.BR size_t , +and +.BR wchar_t +are no greater than the width of type +.BR long . +The names of these programming environments can be obtained using the +\fIconfstr\fR() +function or the +.IR getconf +utility. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The ISO\ C standard does not require the NULL macro to include the cast to type +.BR "void *" +and specifies that the NULL macro be implementation-defined. POSIX.1\(hy2008 +requires the cast and therefore need not be implementation-defined. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIconfstr\fR\^(\|)" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIgetconf\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/stdint.h.0p b/man-pages-posix-2013/man0p/stdint.h.0p new file mode 100644 index 0000000..96a0428 --- /dev/null +++ b/man-pages-posix-2013/man0p/stdint.h.0p @@ -0,0 +1,644 @@ +'\" et +.TH stdint.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of 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 +stdint.h +\(em integer types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends the +ISO\ C standard. Applications shall define the appropriate feature test macro +(see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment") +to enable the visibility of these symbols in this header. +.P +The +.IR +header shall declare sets of integer types having specified widths, and +shall define corresponding sets of macros. It shall also define macros +that specify limits of integer types corresponding to types defined in +other standard headers. +.TP 10 +.BR Note: +The ``width'' of an integer type is the number of bits used to store +its value in a pure binary system; the actual type may use more bits +than that (for example, a 28-bit type could be stored in 32 bits of +actual storage). An +.IR N -bit +signed type has values in the range \(mi2\s-3\u\fIN\fR\(mi1\d\s+3 or +1\(mi2\s-3\u\fIN\fR\(mi1\d\s+3 to 2\s-3\u\fIN\fR\(mi1\d\s+3\(mi1, while +an +.IR N -bit +unsigned type has values in the range 0 to 2\s-3\u\fIN\fR\d\s+3\(mi1. +.P +.P +Types are defined in the following categories: +.IP " *" 4 +Integer types having certain exact widths +.IP " *" 4 +Integer types having at least certain specified widths +.IP " *" 4 +Fastest integer types having at least certain specified widths +.IP " *" 4 +Integer types wide enough to hold pointers to objects +.IP " *" 4 +Integer types having greatest width +.P +(Some of these types may denote the same type.) +.P +Corresponding macros specify limits of the declared types and construct +suitable constants. +.P +For each type described herein that the implementation provides, the +.IR +header shall declare that +.BR typedef +name and define the associated macros. Conversely, for each type +described herein that the implementation does not provide, the +.IR +header shall not declare that +.BR typedef +name, nor shall it define the associated macros. An implementation +shall provide those types described as required, but need not provide +any of the others (described as optional). +.SS "Integer Types" +.P +When +.BR typedef +names differing only in the absence or presence of the initial +.IR u +are defined, they shall denote corresponding signed and unsigned types +as described in the ISO/IEC\ 9899:\|1999 standard, Section 6.2.5; an implementation providing +one of these corresponding types shall also provide the other. +.P +In the following descriptions, the symbol +.IR N +represents an unsigned decimal integer with no leading zeros (for +example, 8 or 24, but not 04 or 048). +.IP " *" 4 +Exact-width integer types +.RS 4 +.P +The +.BR typedef +name +.BR int \c +.IR N \c +.BR _t +designates a signed integer type with width +.IR N , +no padding bits, and a two's-complement representation. Thus, +.BR int8_t +denotes a signed integer type with a width of exactly 8 bits. +.P +The +.BR typedef +name +.BR uint \c +.IR N \c +.BR _t +designates an unsigned integer type with width +.IR N . +Thus, +.BR uint24_t +denotes an unsigned integer type with a width of exactly 24 bits. +.P +The following types are required: +.P +.nf +.BR int8_t +.BR int16_t +.BR int32_t +.BR uint8_t +.BR uint16_t +.BR uint32_t +.fi +.P +If an implementation provides integer types with width 64 that +meet these requirements, then the following types are required: +.BR int64_t +.BR uint64_t +.P +In particular, this will be the case if any of the following are +true: +.IP -- 4 +The implementation supports the _POSIX_V7_ILP32_OFFBIG programming +environment and the application is being built in the +_POSIX_V7_ILP32_OFFBIG programming environment (see the Shell and Utilities volume of POSIX.1\(hy2008, +.IR c99 , +Programming Environments). +.IP -- 4 +The implementation supports the _POSIX_V7_LP64_OFF64 programming +environment and the application is being built in the +_POSIX_V7_LP64_OFF64 programming environment. +.IP -- 4 +The implementation supports the _POSIX_V7_LPBIG_OFFBIG programming +environment and the application is being built in the +_POSIX_V7_LPBIG_OFFBIG programming environment. +.P +All other types of this form are optional. +.RE +.IP " *" 4 +Minimum-width integer types +.RS 4 +.P +The +.BR typedef +name +.BR int_least \c +.IR N \c +.BR _t +designates a signed integer type with a width of at least +.IR N , +such that no signed integer type with lesser size has at least the +specified width. Thus, +.BR int_least32_t +denotes a signed integer type with a width of at least 32 bits. +.P +The +.BR typedef +name +.BR uint_least \c +.IR N \c +.BR _t +designates an unsigned integer type with a width of at least +.IR N , +such that no unsigned integer type with lesser size has at least the +specified width. Thus, +.BR uint_least16_t +denotes an unsigned integer type with a width of at least 16 bits. +.P +The following types are required: +.BR int_least8_t +.BR int_least16_t +.BR int_least32_t +.BR int_least64_t +.BR uint_least8_t +.BR uint_least16_t +.BR uint_least32_t +.BR uint_least64_t +.P +All other types of this form are optional. +.RE +.IP " *" 4 +Fastest minimum-width integer types +.RS 4 +.P +Each of the following types designates an integer type that is usually +fastest to operate with among all integer types that have at least the +specified width. +.P +The designated type is not guaranteed to be fastest for all purposes; +if the implementation has no clear grounds for choosing one type over +another, it will simply pick some integer type satisfying the +signedness and width requirements. +.P +The +.BR typedef +name +.BR int_fast \c +.IR N \c +.BR _t +designates the fastest signed integer type with a width of at least +.IR N . +The +.BR typedef +name +.BR uint_fast \c +.IR N \c +.BR _t +designates the fastest unsigned integer type with a width of at least +.IR N . +.P +The following types are required: +.BR int_fast8_t +.BR int_fast16_t +.BR int_fast32_t +.BR int_fast64_t +.BR uint_fast8_t +.BR uint_fast16_t +.BR uint_fast32_t +.BR uint_fast64_t +.P +All other types of this form are optional. +.RE +.IP " *" 4 +Integer types capable of holding object pointers +.RS 4 +.P +The following type designates a signed integer type with the property +that any valid pointer to +.BR void +can be converted to this type, then converted back to a pointer to +.BR void , +and the result will compare equal to the original pointer: +.BR intptr_t +.P +The following type designates an unsigned integer type with the +property that any valid pointer to +.BR void +can be converted to this type, then converted back to a pointer to +.BR void , +and the result will compare equal to the original pointer: +.BR uintptr_t +.P +On XSI-conformant systems, the +.BR intptr_t +and +.BR uintptr_t +types are required; +otherwise, they are optional. +.RE +.IP " *" 4 +Greatest-width integer types +.RS 4 +.P +The following type designates a signed integer type capable of +representing any value of any signed integer type: +.BR intmax_t +.P +The following type designates an unsigned integer type capable of +representing any value of any unsigned integer type: +.BR uintmax_t +.P +These types are required. +.RE +.TP 10 +.BR Note: +Applications can test for optional types by using the corresponding +limit macro from +.IR "Limits of Specified-Width Integer Types". +.P +.SS "Limits of Specified-Width Integer Types" +.P +The following macros specify the minimum and maximum limits of the +types declared in the +.IR +header. Each macro name corresponds to a similar type name in +.IR "Integer Types". +.P +Each instance of any defined macro shall be replaced by a constant +expression suitable for use in +.BR #if +preprocessing directives, and this expression shall have the same type +as would an expression that is an object of the corresponding type +converted according to the integer promotions. Its +implementation-defined value shall be equal to or greater in magnitude +(absolute value) than the corresponding value given below, with the +same sign, except where stated to be exactly the given value. +.IP " *" 4 +Limits of exact-width integer types +.RS 4 +.IP -- 4 +Minimum values of exact-width signed integer types: +.RS 4 +.IP "{INT\fIN\fR_MIN}" 16 +Exactly \(mi($2"^" N\(mi1$) +.RE +.IP -- 4 +Maximum values of exact-width signed integer types: +.RS 4 +.IP "{INT\fIN\fR_MAX}" 16 +Exactly $2"^" N\(mi1$ \(mi1 +.RE +.IP -- 4 +Maximum values of exact-width unsigned integer types: +.RS 4 +.IP "{UINT\fIN\fR_MAX}" 16 +Exactly $2"^" N$ \(mi1 +.RE +.RE +.IP " *" 4 +Limits of minimum-width integer types +.RS 4 +.IP -- 4 +Minimum values of minimum-width signed integer types: +.RS 4 +.IP "{INT_LEAST\fIN\fR_MIN}" 16 +\(mi($2"^" N\(mi1$ \(mi1) +.RE +.IP -- 4 +Maximum values of minimum-width signed integer types: +.RS 4 +.IP "{INT_LEAST\fIN\fR_MAX}" 16 +$2"^" N\(mi1$ \(mi1 +.RE +.IP -- 4 +Maximum values of minimum-width unsigned integer types: +.RS 4 +.IP "{UINT_LEAST\fIN\fR_MAX}" 16 +$2"^" N$ \(mi1 +.RE +.RE +.IP " *" 4 +Limits of fastest minimum-width integer types +.RS 4 +.IP -- 4 +Minimum values of fastest minimum-width signed integer types: +.RS 4 +.IP "{INT_FAST\fIN\fR_MIN}" 16 +\(mi($2"^" N\(mi1$ \(mi1) +.RE +.IP -- 4 +Maximum values of fastest minimum-width signed integer types: +.RS 4 +.IP "{INT_FAST\fIN\fR_MAX}" 16 +$2"^" N\(mi1$ \(mi1 +.RE +.IP -- 4 +Maximum values of fastest minimum-width unsigned integer types: +.RS 4 +.IP "{UINT_FAST\fIN\fR_MAX}" 16 +$2"^" N$ \(mi1 +.RE +.RE +.IP " *" 4 +Limits of integer types capable of holding object pointers +.RS 4 +.IP -- 4 +Minimum value of pointer-holding signed integer type: +.RS 4 +.IP {INTPTR_MIN} 16 +\(mi($2"^" 15$ \(mi1) +.RE +.IP -- 4 +Maximum value of pointer-holding signed integer type: +.RS 4 +.IP {INTPTR_MAX} 16 +$2"^" 15$ \(mi1 +.RE +.IP -- 4 +Maximum value of pointer-holding unsigned integer type: +.RS 4 +.IP {UINTPTR_MAX} 16 +$2"^" 16$ \(mi1 +.RE +.RE +.IP " *" 4 +Limits of greatest-width integer types +.RS 4 +.IP -- 4 +Minimum value of greatest-width signed integer type: +.RS 4 +.IP {INTMAX_MIN} 16 +\(mi($2"^" 63$ \(mi1) +.RE +.IP -- 4 +Maximum value of greatest-width signed integer type: +.RS 4 +.IP {INTMAX_MAX} 16 +$2"^" 63$ \(mi1 +.RE +.IP -- 4 +Maximum value of greatest-width unsigned integer type: +.RS 4 +.IP {UINTMAX_MAX} 16 +$2"^" 64$ \(mi1 +.RE +.RE +.SS "Limits of Other Integer Types" +.P +The following macros specify the minimum and maximum limits of integer +types corresponding to types defined in other standard headers. +.P +Each instance of these macros shall be replaced by a constant +expression suitable for use in +.BR #if +preprocessing directives, and this expression shall have the same type +as would an expression that is an object of the corresponding type +converted according to the integer promotions. Its +implementation-defined value shall be equal to or greater in magnitude +(absolute value) than the corresponding value given below, with the +same sign. +.IP " *" 4 +Limits of \fBptrdiff_t\fR: +.RS 4 +.IP {PTRDIFF_MIN} 16 +\(mi65\|535 +.IP {PTRDIFF_MAX} 16 ++65\|535 +.RE +.IP " *" 4 +Limits of \fBsig_atomic_t\fR: +.RS 4 +.IP {SIG_ATOMIC_MIN} 16 +See below. +.IP {SIG_ATOMIC_MAX} 16 +See below. +.RE +.IP " *" 4 +Limit of \fBsize_t\fR: +.RS 4 +.IP {SIZE_MAX} 16 +65\|535 +.RE +.IP " *" 4 +Limits of \fBwchar_t\fR: +.RS 4 +.IP {WCHAR_MIN} 16 +See below. +.IP {WCHAR_MAX} 16 +See below. +.RE +.IP " *" 4 +Limits of \fBwint_t\fR: +.RS 4 +.IP {WINT_MIN} 16 +See below. +.IP {WINT_MAX} 16 +See below. +.RE +.P +If +.BR sig_atomic_t +(see the +.IR +header) is defined as a signed integer type, the value of +{SIG_ATOMIC_MIN} +shall be no greater than \(mi127 and the value of +{SIG_ATOMIC_MAX} +shall be no less than 127; otherwise, +.BR sig_atomic_t +shall be defined as an unsigned integer type, and the value of +{SIG_ATOMIC_MIN} +shall be 0 and the value of +{SIG_ATOMIC_MAX} +shall be no less than 255. +.P +If +.BR wchar_t +(see the +.IR +header) is defined as a signed integer type, the value of +{WCHAR_MIN} +shall be no greater than \(mi127 and the value of +{WCHAR_MAX} +shall be no less than 127; otherwise, +.BR wchar_t +shall be defined as an unsigned integer type, and the value of +{WCHAR_MIN} +shall be 0 and the value of +{WCHAR_MAX} +shall be no less than 255. +.P +If +.BR wint_t +(see the +.IR +header) is defined as a signed integer type, the value of +{WINT_MIN} +shall be no greater than \(mi32\|767 and the value of +{WINT_MAX} +shall be no less than 32\|767; otherwise, +.BR wint_t +shall be defined as an unsigned integer type, and the value of +{WINT_MIN} +shall be 0 and the value of +{WINT_MAX} +shall be no less than 65\|535. +.SS "Macros for Integer Constant Expressions" +.P +The following macros expand to integer constant expressions suitable for +initializing objects that have integer types corresponding to types +defined in the +.IR +header. Each macro name corresponds to a similar type name listed under +\fIMinimum-width integer types\fR and \fIGreatest-width integer +types\fR. +.P +Each invocation of one of these macros shall expand to an integer +constant expression suitable for use in +.BR #if +preprocessing directives. The type of the expression shall have the +same type as would an expression that is an object of the corresponding +type converted according to the integer promotions. The value of the +expression shall be that of the argument. +.P +The argument in any instance of these macros shall be an unsuffixed +integer constant with a value that does not exceed the limits for the +corresponding type. +.IP " *" 4 +Macros for minimum-width integer constant expressions +.RS 4 +.P +The macro +.IR INTN_C (\c +.IR value ) +shall expand to an integer constant expression corresponding to the +type +.BR int_least \c +.IR N \c +.BR _t . +The macro +.IR UINTN_C (\c +.IR value ) +shall expand to an integer constant expression corresponding to the +type +.BR uint_least \c +.IR N \c +.BR _t . +For example, if +.BR uint_least64_t +is a name for the type +.BR "unsigned long long" , +then +.IR UINT64_C (0x123) +might expand to the integer constant 0x123ULL. +.RE +.IP " *" 4 +Macros for greatest-width integer constant expressions +.RS 4 +.P +The following macro expands to an integer constant expression having +the value specified by its argument and the type +.BR intmax_t : +INTMAX_C(\fIvalue\fR) +.P +The following macro expands to an integer constant expression having +the value specified by its argument and the type +.BR uintmax_t : +UINTMAX_C(\fIvalue\fR) +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +.IR +header is a subset of the +.IR +header more suitable for use in freestanding environments, which might +not support the formatted I/O functions. In some environments, if the +formatted conversion support is not wanted, using this header instead +of the +.IR +header avoids defining such a large number of macros. +.br +.P +As a consequence of adding +.BR int8_t , +the following are true: +.IP " *" 4 +A byte is exactly 8 bits. +.IP " *" 4 +{CHAR_BIT} +has the value 8, +{SCHAR_MAX} +has the value 127, +{SCHAR_MIN} +has the value \(mi128, and +{UCHAR_MAX} +has the value 255. +.P +(The POSIX standard explicitly requires 8-bit char and +two's-complement arithmetic.) +.SH "FUTURE DIRECTIONS" +.BR typedef +names beginning with +.BR int +or +.BR uint +and ending with _t may be added to the types defined in the +.IR +header. Macro names beginning with INT or UINT and ending with _MAX, +_MIN, or _C may be added to the macros defined in the +.IR +header. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/stdio.h.0p b/man-pages-posix-2013/man0p/stdio.h.0p new file mode 100644 index 0000000..1954b79 --- /dev/null +++ b/man-pages-posix-2013/man0p/stdio.h.0p @@ -0,0 +1,327 @@ +'\" et +.TH stdio.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +stdio.h +\(em standard buffered input/output +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends the +ISO\ C standard. Applications shall define the appropriate feature test macro +(see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment") +to enable the visibility of these symbols in this header. +.P +The +.IR +header shall define the following data types through +.BR typedef : +.IP "\fBFILE\fP" 14 +A structure containing information about a file. +.IP "\fBfpos_t\fP" 14 +A non-array type containing all information needed to specify uniquely +every position within a file. +.IP "\fBoff_t\fP" 14 +As described in +.IR . +.IP "\fBsize_t\fP" 14 +As described in +.IR . +.IP "\fBssize_t\fP" 14 +As described in +.IR . +.IP "\fBva_list\fP" 14 +As described in +.IR . +.P +The +.IR +header shall define the following macros which shall expand to +integer constant expressions: +.IP BUFSIZ 14 +Size of +.IR +buffers. +This shall expand to a positive value. +.IP L_ctermid 14 +Maximum size of character array to hold +\fIctermid\fR() +output. +.IP L_tmpnam 14 +Maximum size of character array to hold +\fItmpnam\fR() +output. +.P +The +.IR +header shall define the following macros which shall expand to +integer constant expressions with distinct values: +.IP _IOFBF 14 +Input/output fully buffered. +.IP _IOLBF 14 +Input/output line buffered. +.IP _IONBF 14 +Input/output unbuffered. +.P +The +.IR +header shall define the following macros which shall expand to +integer constant expressions with distinct values: +.IP SEEK_CUR 14 +Seek relative to current position. +.IP SEEK_END 14 +Seek relative to end-of-file. +.IP SEEK_SET 14 +Seek relative to start-of-file. +.P +The +.IR +header shall define the following macros which shall expand to +integer constant expressions denoting implementation limits: +.IP {FILENAME_MAX} 14 +Maximum size in bytes of the longest pathname that the implementation +guarantees can be opened. +.IP {FOPEN_MAX} 14 +Number of streams which the implementation guarantees can be open +simultaneously. The value is at least eight. +.IP {TMP_MAX} 14 +Minimum number of unique filenames generated by +\fItmpnam\fR(). +Maximum number of times an application can call +\fItmpnam\fR() +reliably. The value of +{TMP_MAX} +is at least 25. +.RS 14 +.P +On XSI-conformant systems, the value of +{TMP_MAX} +is at least 10\|000. +.RE +.P +The +.IR +header shall define the following macro which shall expand to an integer +constant expression with type +.BR int +and a negative value: +.IP EOF 14 +End-of-file return value. +.P +The +.IR +header shall define NULL as described in +.IR . +.br +.P +The +.IR +header shall define the following macro which shall expand to a +string constant: +.IP P_tmpdir 14 +Default directory prefix for +\fItempnam\fR(). +.P +The +.IR +header shall define the following macros which shall expand to +expressions of type ``pointer to +.BR FILE '' +that point to the +.BR FILE +objects associated, respectively, with the standard error, input, and +output streams: +.IP "\fIstderr\fR" 14 +Standard error output stream. +.IP "\fIstdin\fR" 14 +Standard input stream. +.IP "\fIstdout\fR" 14 +Standard output stream. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +void clearerr(FILE *); +char *ctermid(char *); +int dprintf(int, const char *restrict, ...) +int fclose(FILE *); +FILE *fdopen(int, const char *); +int feof(FILE *); +int ferror(FILE *); +int fflush(FILE *); +int fgetc(FILE *); +int fgetpos(FILE *restrict, fpos_t *restrict); +char *fgets(char *restrict, int, FILE *restrict); +int fileno(FILE *); +void flockfile(FILE *); +FILE *fmemopen(void *restrict, size_t, const char *restrict); +FILE *fopen(const char *restrict, const char *restrict); +int fprintf(FILE *restrict, const char *restrict, ...); +int fputc(int, FILE *); +int fputs(const char *restrict, FILE *restrict); +size_t fread(void *restrict, size_t, size_t, FILE *restrict); +FILE *freopen(const char *restrict, const char *restrict, + FILE *restrict); +int fscanf(FILE *restrict, const char *restrict, ...); +int fseek(FILE *, long, int); +int fseeko(FILE *, off_t, int); +int fsetpos(FILE *, const fpos_t *); +long ftell(FILE *); +off_t ftello(FILE *); +int ftrylockfile(FILE *); +void funlockfile(FILE *); +size_t fwrite(const void *restrict, size_t, size_t, FILE *restrict); +int getc(FILE *); +int getchar(void); +int getc_unlocked(FILE *); +int getchar_unlocked(void); +ssize_t getdelim(char **restrict, size_t *restrict, int, + FILE *restrict); +ssize_t getline(char **restrict, size_t *restrict, FILE *restrict); +char *gets(char *); +FILE *open_memstream(char **, size_t *); +int pclose(FILE *); +void perror(const char *); +FILE *popen(const char *, const char *); +int printf(const char *restrict, ...); +int putc(int, FILE *); +int putchar(int); +int putc_unlocked(int, FILE *); +int putchar_unlocked(int); +int puts(const char *); +int remove(const char *); +int rename(const char *, const char *); +int renameat(int, const char *, int, const char *); +void rewind(FILE *); +int scanf(const char *restrict, ...); +void setbuf(FILE *restrict, char *restrict); +int setvbuf(FILE *restrict, char *restrict, int, size_t); +int snprintf(char *restrict, size_t, const char *restrict, ...); +int sprintf(char *restrict, const char *restrict, ...); +int sscanf(const char *restrict, const char *restrict, ...); +char *tempnam(const char *, const char *); +FILE *tmpfile(void); +char *tmpnam(char *); +int ungetc(int, FILE *); +int vdprintf(int, const char *restrict, va_list); +int vfprintf(FILE *restrict, const char *restrict, va_list); +int vfscanf(FILE *restrict, const char *restrict, va_list); +int vprintf(const char *restrict, va_list); +int vscanf(const char *restrict, va_list); +int vsnprintf(char *restrict, size_t, const char *restrict, + va_list); +int vsprintf(char *restrict, const char *restrict, va_list); +int vsscanf(const char *restrict, const char *restrict, va_list); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may also make visible all symbols from +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Since standard I/O streams may use an underlying file descriptor to +access the file associated with a stream, application developers need +to be aware that +{FOPEN_MAX} +streams may not be available if file descriptors are being used to access +files that are not associated with streams. +.SH RATIONALE +There is a conflict between the ISO\ C standard and the POSIX definition of the +{TMP_MAX} +macro that is addressed by ISO/IEC\ 9899:\|1999 standard, Defect Report 336. The POSIX standard is +in alignment with the public record of the response to the Defect Report. +This change has not yet been published as part of the ISO\ C standard. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +.ad l +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment", +.IR "\fIclearerr\fR\^(\|)", +.IR "\fIctermid\fR\^(\|)", +.IR "\fIfclose\fR\^(\|)", +.IR "\fIfdopen\fR\^(\|)", +.IR "\fIfeof\fR\^(\|)", +.IR "\fIferror\fR\^(\|)", +.IR "\fIfflush\fR\^(\|)", +.IR "\fIfgetc\fR\^(\|)", +.IR "\fIfgetpos\fR\^(\|)", +.IR "\fIfgets\fR\^(\|)", +.IR "\fIfileno\fR\^(\|)", +.IR "\fIflockfile\fR\^(\|)", +.IR "\fIfmemopen\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfprintf\fR\^(\|)", +.IR "\fIfputc\fR\^(\|)", +.IR "\fIfputs\fR\^(\|)", +.IR "\fIfread\fR\^(\|)", +.IR "\fIfreopen\fR\^(\|)", +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIfseek\fR\^(\|)", +.IR "\fIfsetpos\fR\^(\|)", +.IR "\fIftell\fR\^(\|)", +.IR "\fIfwrite\fR\^(\|)", +.IR "\fIgetc\fR\^(\|)", +.IR "\fIgetchar\fR\^(\|)", +.IR "\fIgetc_unlocked\fR\^(\|)", +.IR "\fIgetdelim\fR\^(\|)", +.IR "\fIgetopt\fR\^(\|)", +.IR "\fIgets\fR\^(\|)", +.IR "\fIopen_memstream\fR\^(\|)", +.IR "\fIpclose\fR\^(\|)", +.IR "\fIperror\fR\^(\|)", +.IR "\fIpopen\fR\^(\|)", +.IR "\fIputc\fR\^(\|)", +.IR "\fIputchar\fR\^(\|)", +.IR "\fIputs\fR\^(\|)", +.IR "\fIremove\fR\^(\|)", +.IR "\fIrename\fR\^(\|)", +.IR "\fIrewind\fR\^(\|)", +.IR "\fIsetbuf\fR\^(\|)", +.IR "\fIsetvbuf\fR\^(\|)", +.IR "\fIstdin\fR\^", +.IR "\fIsystem\fR\^(\|)", +.IR "\fItempnam\fR\^(\|)", +.IR "\fItmpfile\fR\^(\|)", +.IR "\fItmpnam\fR\^(\|)", +.IR "\fIungetc\fR\^(\|)", +.IR "\fIvfprintf\fR\^(\|)", +.IR "\fIvfscanf\fR\^(\|)" +.ad b +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/stdlib.h.0p b/man-pages-posix-2013/man0p/stdlib.h.0p new file mode 100644 index 0000000..8558574 --- /dev/null +++ b/man-pages-posix-2013/man0p/stdlib.h.0p @@ -0,0 +1,260 @@ +'\" et +.TH stdlib.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +stdlib.h +\(em standard library definitions +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends the +ISO\ C standard. Applications shall define the appropriate feature test macro +(see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment") +to enable the visibility of these symbols in this header. +.P +The +.IR +header shall define the following macros which shall expand to +integer constant expressions: +.IP EXIT_FAILURE 12 +Unsuccessful termination for +\fIexit\fR(); +evaluates to a non-zero value. +.IP EXIT_SUCCESS 12 +Successful termination for +\fIexit\fR(); +evaluates to 0. +.IP {RAND_MAX} 12 +Maximum value returned by +\fIrand\fR(); +at least 32\|767. +.P +The +.IR +header shall define the following macro which shall expand to a +positive integer expression with type +.BR size_t : +.IP {MB_CUR_MAX} 12 +Maximum number of bytes in a character specified by the current +locale (category +.IR LC_CTYPE ). +.P +The +.IR +header shall define NULL as described in +.IR . +.P +The +.IR +header shall define the following data types through +.BR typedef : +.IP "\fBdiv_t\fP" 12 +Structure type returned by the +\fIdiv\fR() +function. +.IP "\fBldiv_t\fP" 12 +Structure type returned by the +\fIldiv\fR() +function. +.IP "\fBlldiv_t\fP" 12 +Structure type returned by the +\fIlldiv\fR() +function. +.IP "\fBsize_t\fP" 12 +As described in +.IR . +.IP "\fBwchar_t\fP" 12 +As described in +.IR . +.P +In addition, the +.IR +header shall define the following symbolic constants and macros +as described in +.IR : +.P +.nf +WEXITSTATUS +WIFEXITED +WIFSIGNALED +WIFSTOPPED +WNOHANG +WSTOPSIG +WTERMSIG +WUNTRACED +.fi +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +void _Exit(int); +long a64l(const char *); +void abort(void); +int abs(int); +int atexit(void (*)(void)); +double atof(const char *); +int atoi(const char *); +long atol(const char *); +long long atoll(const char *); +void *bsearch(const void *, const void *, size_t, size_t, + int (*)(const void *, const void *)); +void *calloc(size_t, size_t); +div_t div(int, int); +double drand48(void); +double erand48(unsigned short [3]); +void exit(int); +void free(void *); +char *getenv(const char *); +int getsubopt(char **, char *const *, char **); +int grantpt(int); +char *initstate(unsigned, char *, size_t); +long jrand48(unsigned short [3]); +char *l64a(long); +long labs(long); +void lcong48(unsigned short [7]); +ldiv_t ldiv(long, long); +long long llabs(long long); +lldiv_t lldiv(long long, long long); +long lrand48(void); +void *malloc(size_t); +int mblen(const char *, size_t); +size_t mbstowcs(wchar_t *restrict, const char *restrict, size_t); +int mbtowc(wchar_t *restrict, const char *restrict, size_t); +char *mkdtemp(char *); +int mkstemp(char *); +long mrand48(void); +long nrand48(unsigned short [3]); +int posix_memalign(void **, size_t, size_t); +int posix_openpt(int); +char *ptsname(int); +int putenv(char *); +void qsort(void *, size_t, size_t, int (*)(const void *, + const void *)); +int rand(void); +int rand_r(unsigned *); +long random(void); +void *realloc(void *, size_t); +char *realpath(const char *restrict, char *restrict); +unsigned short *seed48(unsigned short [3]); +int setenv(const char *, const char *, int); +void setkey(const char *); +char *setstate(char *); +void srand(unsigned); +void srand48(long); +void srandom(unsigned); +double strtod(const char *restrict, char **restrict); +float strtof(const char *restrict, char **restrict); +long strtol(const char *restrict, char **restrict, int); +long double strtold(const char *restrict, char **restrict); +long long strtoll(const char *restrict, char **restrict, int); +unsigned long strtoul(const char *restrict, char **restrict, int); +unsigned long long + strtoull(const char *restrict, char **restrict, int); +int system(const char *); +int unlockpt(int); +int unsetenv(const char *); +size_t wcstombs(char *restrict, const wchar_t *restrict, size_t); +int wctomb(char *, wchar_t); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may also make visible all symbols from +.IR , +.IR , +.IR , +and +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +.ad l +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment", +.IR "\fI_Exit\fR\^(\|)", +.IR "\fIa64l\fR\^(\|)", +.IR "\fIabort\fR\^(\|)", +.IR "\fIabs\fR\^(\|)", +.IR "\fIatexit\fR\^(\|)", +.IR "\fIatof\fR\^(\|)", +.IR "\fIatoi\fR\^(\|)", +.IR "\fIatol\fR\^(\|)", +.IR "\fIbsearch\fR\^(\|)", +.IR "\fIcalloc\fR\^(\|)", +.IR "\fIdiv\fR\^(\|)", +.IR "\fIdrand48\fR\^(\|)", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfree\fR\^(\|)", +.IR "\fIgetenv\fR\^(\|)", +.IR "\fIgetsubopt\fR\^(\|)", +.IR "\fIgrantpt\fR\^(\|)", +.IR "\fIinitstate\fR\^(\|)", +.IR "\fIlabs\fR\^(\|)", +.IR "\fIldiv\fR\^(\|)", +.IR "\fImalloc\fR\^(\|)", +.IR "\fImblen\fR\^(\|)", +.IR "\fImbstowcs\fR\^(\|)", +.IR "\fImbtowc\fR\^(\|)", +.IR "\fImkdtemp\fR\^(\|)", +.IR "\fIposix_memalign\fR\^(\|)", +.IR "\fIposix_openpt\fR\^(\|)", +.IR "\fIptsname\fR\^(\|)", +.IR "\fIputenv\fR\^(\|)", +.IR "\fIqsort\fR\^(\|)", +.IR "\fIrand\fR\^(\|)", +.IR "\fIrealloc\fR\^(\|)", +.IR "\fIrealpath\fR\^(\|)", +.IR "\fIsetenv\fR\^(\|)", +.IR "\fIsetkey\fR\^(\|)", +.IR "\fIstrtod\fR\^(\|)", +.IR "\fIstrtol\fR\^(\|)", +.IR "\fIstrtoul\fR\^(\|)", +.IR "\fIsystem\fR\^(\|)", +.IR "\fIunlockpt\fR\^(\|)", +.IR "\fIunsetenv\fR\^(\|)", +.IR "\fIwcstombs\fR\^(\|)", +.IR "\fIwctomb\fR\^(\|)" +.ad b +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/string.h.0p b/man-pages-posix-2013/man0p/string.h.0p new file mode 100644 index 0000000..a178bc8 --- /dev/null +++ b/man-pages-posix-2013/man0p/string.h.0p @@ -0,0 +1,146 @@ +'\" et +.TH string.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +string.h +\(em string operations +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends the +ISO\ C standard. Applications shall define the appropriate feature test macro +(see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment") +to enable the visibility of these symbols in this header. +.P +The +.IR +header shall define NULL and +.BR size_t +as described in +.IR . +.P +The +.IR +header shall define the +.BR locale_t +type as described in +.IR . +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided for use with ISO\ C standard +compilers. +.sp +.RS 4 +.nf +\fB +void *memccpy(void *restrict, const void *restrict, int, size_t); +void *memchr(const void *, int, size_t); +int memcmp(const void *, const void *, size_t); +void *memcpy(void *restrict, const void *restrict, size_t); +void *memmove(void *, const void *, size_t); +void *memset(void *, int, size_t); +char *stpcpy(char *restrict, const char *restrict); +char *stpncpy(char *restrict, const char *restrict, size_t); +char *strcat(char *restrict, const char *restrict); +char *strchr(const char *, int); +int strcmp(const char *, const char *); +int strcoll(const char *, const char *); +int strcoll_l(const char *, const char *, locale_t); +char *strcpy(char *restrict, const char *restrict); +size_t strcspn(const char *, const char *); +char *strdup(const char *); +char *strerror(int); +char *strerror_l(int, locale_t); +int strerror_r(int, char *, size_t); +size_t strlen(const char *); +char *strncat(char *restrict, const char *restrict, size_t); +int strncmp(const char *, const char *, size_t); +char *strncpy(char *restrict, const char *restrict, size_t); +char *strndup(const char *, size_t); +size_t strnlen(const char *, size_t); +char *strpbrk(const char *, const char *); +char *strrchr(const char *, int); +char *strsignal(int); +size_t strspn(const char *, const char *); +char *strstr(const char *, const char *); +char *strtok(char *restrict, const char *restrict); +char *strtok_r(char *restrict, const char *restrict, char **restrict); +size_t strxfrm(char *restrict, const char *restrict, size_t); +size_t strxfrm_l(char *restrict, const char *restrict, + size_t, locale_t); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may also make visible all symbols from +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +.ad l +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment", +.IR "\fImemccpy\fR\^(\|)", +.IR "\fImemchr\fR\^(\|)", +.IR "\fImemcmp\fR\^(\|)", +.IR "\fImemcpy\fR\^(\|)", +.IR "\fImemmove\fR\^(\|)", +.IR "\fImemset\fR\^(\|)", +.IR "\fIstrcat\fR\^(\|)", +.IR "\fIstrchr\fR\^(\|)", +.IR "\fIstrcmp\fR\^(\|)", +.IR "\fIstrcoll\fR\^(\|)", +.IR "\fIstrcpy\fR\^(\|)", +.IR "\fIstrcspn\fR\^(\|)", +.IR "\fIstrdup\fR\^(\|)", +.IR "\fIstrerror\fR\^(\|)", +.IR "\fIstrlen\fR\^(\|)", +.IR "\fIstrncat\fR\^(\|)", +.IR "\fIstrncmp\fR\^(\|)", +.IR "\fIstrncpy\fR\^(\|)", +.IR "\fIstrpbrk\fR\^(\|)", +.IR "\fIstrrchr\fR\^(\|)", +.IR "\fIstrsignal\fR\^(\|)", +.IR "\fIstrspn\fR\^(\|)", +.IR "\fIstrstr\fR\^(\|)", +.IR "\fIstrtok\fR\^(\|)", +.IR "\fIstrxfrm\fR\^(\|)" +.ad b +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/strings.h.0p b/man-pages-posix-2013/man0p/strings.h.0p new file mode 100644 index 0000000..f1f114c --- /dev/null +++ b/man-pages-posix-2013/man0p/strings.h.0p @@ -0,0 +1,78 @@ +'\" et +.TH strings.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strings.h +\(em string operations +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided for use with ISO\ C standard +compilers. +.sp +.RS 4 +.nf +\fB +int ffs(int); +int strcasecmp(const char *, const char *); +int strcasecmp_l(const char *, const char *, locale_t); +int strncasecmp(const char *, const char *, size_t); +int strncasecmp_l(const char *, const char *, size_t, locale_t); +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR locale_t +type as described in +.IR . +.P +The +.IR +header shall define the +.BR size_t +type as described in +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIffs\fR\^(\|)", +.IR "\fIstrcasecmp\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/stropts.h.0p b/man-pages-posix-2013/man0p/stropts.h.0p new file mode 100644 index 0000000..814bfb1 --- /dev/null +++ b/man-pages-posix-2013/man0p/stropts.h.0p @@ -0,0 +1,433 @@ +'\" et +.TH stropts.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +stropts.h +\(em STREAMS interface (\fBSTREAMS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR bandinfo +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +int bi_flag \fRFlushing type.\fR +unsigned char bi_pri \fRPriority band.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR strpeek +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +struct strbuf ctlbuf \fRThe control portion of the message.\fR +struct strbuf databuf \fRThe data portion of the message.\fR +t_uscalar_t flags \fRRS_HIPRI or 0.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR strbuf +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +char *buf \fRPointer to buffer.\fP +int len \fRLength of data.\fP +int maxlen \fRMaximum buffer length.\fP +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR strfdinsert +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +struct strbuf ctlbuf \fRThe control portion of the message.\fR +struct strbuf databuf \fRThe data portion of the message.\fR +int fildes \fRFile descriptor of the other STREAM.\fR +t_uscalar_t flags \fRRS_HIPRI or 0.\fR +int offset \fRRelative location of the stored value.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR strioctl +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +int ic_cmd \fIioctl\fR(\|) command.\fR +char *ic_dp \fRPointer to buffer.\fR +int ic_len \fRLength of data.\fR +int ic_timout \fRTimeout for response.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR strrecvfd +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +int fd \fRReceived file descriptor.\fR +gid_t gid \fRGID of sender.\fR +uid_t uid \fRUID of sender.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR uid_t +and +.BR gid_t +types through +.BR typedef , +as described in +.IR . +.P +The +.IR +header shall define the +.BR t_scalar_t +and +.BR t_uscalar_t +types, respectively, as signed and unsigned opaque types of equal +length of at least 32 bits. +.P +The +.IR +header shall define the +.BR str_list +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +struct str_mlist *sl_modlist \fRSTREAMS module names.\fR +int sl_nmods \fRNumber of STREAMS module names.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR str_mlist +structure, which shall include at least the following member: +.sp +.RS 4 +.nf +\fB +char l_name[FMNAMESZ+1] \fRA STREAMS module name.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define at least the following symbolic constants for use +as the +.IR request +argument to +\fIioctl\fR(): +.IP I_ATMARK 12 +Is the top message ``marked''? +.IP I_CANPUT 12 +Is a band writable? +.IP I_CKBAND 12 +See if any messages exist in a band. +.IP I_FDINSERT 12 +Send implementation-defined information about another STREAM. +.IP I_FIND 12 +Look for a STREAMS module. +.IP I_FLUSH 12 +Flush a STREAM. +.IP I_FLUSHBAND 12 +Flush one band of a STREAM. +.IP I_GETBAND 12 +Get the band of the top message on a STREAM. +.IP I_GETCLTIME 12 +Get close time delay. +.IP I_GETSIG 12 +Retrieve current notification signals. +.IP I_GRDOPT 12 +Get the read mode. +.IP I_GWROPT 12 +Get the write mode. +.IP I_LINK 12 +Connect two STREAMs. +.IP I_LIST 12 +Get all the module names on a STREAM. +.IP I_LOOK 12 +Get the top module name. +.IP I_NREAD 12 +Size the top message. +.IP I_PEEK 12 +Peek at the top message on a STREAM. +.IP I_PLINK 12 +Persistently connect two STREAMs. +.IP I_POP 12 +Pop a STREAMS module. +.IP I_PUNLINK 12 +Dismantle a persistent STREAMS link. +.IP I_PUSH 12 +Push a STREAMS module. +.IP I_RECVFD 12 +Get a file descriptor sent via I_SENDFD. +.IP I_SENDFD 12 +Pass a file descriptor through a STREAMS pipe. +.IP I_SETCLTIME 12 +Set close time delay. +.IP I_SETSIG 12 +Ask for notification signals. +.IP I_SRDOPT 12 +Set the read mode. +.IP I_STR 12 +Send a STREAMS +\fIioctl\fR(). +.IP I_SWROPT 12 +Set the write mode. +.IP I_UNLINK 12 +Disconnect two STREAMs. +.P +The +.IR +header shall define at least the following symbolic constant for use +with I_LOOK: +.IP FMNAMESZ 12 +The minimum size in bytes of the buffer referred to by the +.IR arg +argument. +.P +The +.IR +header shall define at least the following symbolic constants for use +with I_FLUSH: +.IP FLUSHR 12 +Flush read queues. +.IP FLUSHRW 12 +Flush read and write queues. +.IP FLUSHW 12 +Flush write queues. +.P +The +.IR +header shall define at least the following symbolic constants for use +with I_SETSIG: +.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. +.IP S_ERROR 12 +Notification of an error condition reaches the STREAM head. +.IP S_HANGUP 12 +Notification of a hangup reaches the STREAM head. +.IP S_HIPRI 12 +A high-priority message is present on a STREAM head read queue. +.IP S_INPUT 12 +A message, other than a high-priority message, has arrived at the head +of a STREAM head read queue. +.IP S_MSG 12 +A STREAMS signal message that contains the SIGPOLL signal reaches the +front of the STREAM head read queue. +.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_RDBAND 12 +A message with a non-zero priority band has arrived at the head of a +STREAM head read queue. +.IP S_RDNORM 12 +A normal (priority band set to 0) message has arrived at the head of a +STREAM head read queue. +.IP S_WRBAND 12 +The write queue for a non-zero priority band just below the STREAM head +is no longer full. +.IP S_WRNORM 12 +Equivalent to S_OUTPUT. +.P +The +.IR +header shall define at least the following symbolic constant for use +with I_PEEK: +.IP RS_HIPRI 12 +Only look for high-priority messages. +.P +The +.IR +header shall define at least the following symbolic constants for use +with I_SRDOPT: +.IP RMSGD 12 +Message-discard mode. +.IP RMSGN 12 +Message-non-discard mode. +.IP RNORM 12 +Byte-STREAM mode, the default. +.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 part, when a +process issues a +\fIread\fR(). +.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. +.P +The +.IR +header shall define at least the following symbolic constant for use +with I_SWOPT: +.IP SNDZERO 12 +Send a zero-length message downstream when a +\fIwrite\fR() +of 0 bytes occurs. +.P +The +.IR +header shall define at least the following symbolic constants for use +with I_ATMARK: +.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 +.IR +header shall define at least the following symbolic constant for use +with I_UNLINK: +.IP MUXID_ALL 12 +Unlink all STREAMs linked to the STREAM associated with +.IR fildes . +.P +The +.IR +header shall define the following symbolic constants for +\fIgetmsg\fR(), +\fIgetpmsg\fR(), +\fIputmsg\fR(), +and +\fIputpmsg\fR(): +.IP MORECTL 12 +More control information is left in message. +.IP MOREDATA 12 +More data is left in message. +.IP MSG_ANY 12 +Receive any message. +.IP MSG_BAND 12 +Receive message from specified band. +.IP MSG_HIPRI 12 +Send/receive high-priority message. +.P +The +.IR +header may make visible all of the symbols from +.IR . +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int fattach(int, const char *); +int fdetach(const char *); +int getmsg(int, struct strbuf *restrict, struct strbuf *restrict, + int *restrict); +int getpmsg(int, struct strbuf *restrict, struct strbuf *restrict, + int *restrict, int *restrict); +int ioctl(int, int, ...); +int isastream(int); +int putmsg(int, const struct strbuf *, const struct strbuf *, int); +int putpmsg(int, const struct strbuf *, const struct strbuf *, int, + int); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIclose\fR\^(\|)", +.IR "\fIfattach\fR\^(\|)", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIfdetach\fR\^(\|)", +.IR "\fIgetmsg\fR\^(\|)", +.IR "\fIioctl\fR\^(\|)", +.IR "\fIisastream\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIpipe\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIpoll\fR\^(\|)", +.IR "\fIputmsg\fR\^(\|)", +.IR "\fIsignal\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/sys_ipc.h.0p b/man-pages-posix-2013/man0p/sys_ipc.h.0p new file mode 100644 index 0000000..6b8f259 --- /dev/null +++ b/man-pages-posix-2013/man0p/sys_ipc.h.0p @@ -0,0 +1,120 @@ +'\" et +.TH sys_ipc.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/ipc.h +\(em XSI interprocess communication access structure +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header is used by three mechanisms for XSI interprocess communication +(IPC): +messages, semaphores, and shared memory. All use a common structure +type, +.BR ipc_perm , +to pass information used in determining permission to perform an IPC +operation. +.P +The +.IR +header shall define the +.BR ipc_perm +structure, which shall include the following members: +.sp +.RS 4 +.nf +\fB +uid_t uid \fROwner's user ID.\fR +gid_t gid \fROwner's group ID.\fR +uid_t cuid \fRCreator's user ID.\fR +gid_t cgid \fRCreator's group ID.\fR +mode_t mode \fRRead/write permission.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR uid_t , +.BR gid_t , +.BR mode_t , +and +.BR key_t +types as described in +.IR . +.P +The +.IR +header shall define the following symbolic constants. +.P +Mode bits: +.IP IPC_CREAT 12 +Create entry if key does not exist. +.IP IPC_EXCL 12 +Fail if key exists. +.IP IPC_NOWAIT 12 +Error if request must wait. +.P +Keys: +.IP IPC_PRIVATE 12 +Private key. +.P +Control commands: +.IP IPC_RMID 12 +Remove identifier. +.IP IPC_SET 12 +Set options. +.IP IPC_STAT 12 +Get options. +.P +The following shall be declared as a function and may also be defined +as a macro. A function prototype shall be provided. +.sp +.RS 4 +.nf +\fB +key_t ftok(const char *, int); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIftok\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/sys_mman.h.0p b/man-pages-posix-2013/man0p/sys_mman.h.0p new file mode 100644 index 0000000..5b3dc15 --- /dev/null +++ b/man-pages-posix-2013/man0p/sys_mman.h.0p @@ -0,0 +1,213 @@ +'\" et +.TH sys_mman.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/mman.h +\(em memory management declarations +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following symbolic constants for use as +protection options: +.IP PROT_EXEC 14 +Page can be executed. +.IP PROT_NONE 14 +Page cannot be accessed. +.IP PROT_READ 14 +Page can be read. +.IP PROT_WRITE 14 +Page can be written. +.P +The +.IR +header shall define the following symbolic constants for use as +flag options: +.IP MAP_FIXED 14 +Interpret +.IR addr +exactly. +.IP MAP_PRIVATE 14 +Changes are private. +.IP MAP_SHARED 14 +Share changes. +.P +The +.IR +header shall define the following symbolic constants for the +\fImsync\fR() +function: +.IP MS_ASYNC 14 +Perform asynchronous writes. +.IP MS_INVALIDATE 14 +Invalidate mappings. +.IP MS_SYNC 14 +Perform synchronous writes. +.P +The +.IR +header shall define the following symbolic constants for the +\fImlockall\fR() +function: +.IP MCL_CURRENT 14 +Lock currently mapped pages. +.IP MCL_FUTURE 14 +Lock pages that become mapped. +.P +The +.IR +header shall define the symbolic constant MAP_FAILED which shall +have type +.BR "void *" +and shall be used to indicate a failure from the +\fImmap\fR() +function . +.P +If the Advisory Information option is supported, the +.IR +header shall define symbolic constants for the +.IR advice +argument to the +\fIposix_madvise\fR() +function as follows: +.IP POSIX_MADV_DONTNEED 6 +.br +The application expects that it will not access the specified range in +the near future. +.IP POSIX_MADV_NORMAL 6 +.br +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_RANDOM 6 +.br +The application expects to access the specified range in a random +order. +.IP POSIX_MADV_SEQUENTIAL 6 +.br +The application expects to access the specified range sequentially from +lower addresses to higher addresses. +.IP POSIX_MADV_WILLNEED 6 +.br +The application expects to access the specified range in the near +future. +.P +The +.IR +header shall define the following symbolic constants for use as +flags for the +\fIposix_typed_mem_open\fR() +function: +.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 +The +.IR +header shall define the +.BR mode_t , +.BR off_t , +and +.BR size_t +types as described in +.IR "\fB\fP". +.P +The +.IR +header shall define the +.BR posix_typed_mem_info +structure, which shall include at least the following member: +.sp +.RS 4 +.nf +\fB +size_t posix_tmi_length \fRMaximum length which may be allocated\fR + \fRfrom a typed memory object.\fR +.fi \fR +.P +.RE +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int mlock(const void *, size_t); +int mlockall(int); +void *mmap(void *, size_t, int, int, int, off_t); +int mprotect(void *, size_t, int); +int msync(void *, size_t, int); +int munlock(const void *, size_t); +int munlockall(void); +int munmap(void *, size_t); +int posix_madvise(void *, size_t, int); +int posix_mem_offset(const void *restrict, size_t, off_t *restrict, + size_t *restrict, int *restrict); +int posix_typed_mem_get_info(int, struct posix_typed_mem_info *); +int posix_typed_mem_open(const char *, int, int); +int shm_open(const char *, int, mode_t); +int shm_unlink(const char *); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fImlock\fR\^(\|)", +.IR "\fImlockall\fR\^(\|)", +.IR "\fImmap\fR\^(\|)", +.IR "\fImprotect\fR\^(\|)", +.IR "\fImsync\fR\^(\|)", +.IR "\fImunmap\fR\^(\|)", +.IR "\fIposix_madvise\fR\^(\|)", +.IR "\fIposix_mem_offset\fR\^(\|)", +.IR "\fIposix_typed_mem_get_info\fR\^(\|)", +.IR "\fIposix_typed_mem_open\fR\^(\|)", +.IR "\fIshm_open\fR\^(\|)", +.IR "\fIshm_unlink\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/sys_msg.h.0p b/man-pages-posix-2013/man0p/sys_msg.h.0p new file mode 100644 index 0000000..032a23d --- /dev/null +++ b/man-pages-posix-2013/man0p/sys_msg.h.0p @@ -0,0 +1,122 @@ +'\" et +.TH sys_msg.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/msg.h +\(em XSI message queue structures +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following data types through +.BR typedef : +.IP "\fBmsgqnum_t\fP" 14 +Used for the number of messages in the message queue. +.IP "\fBmsglen_t\fP" 14 +Used for the number of bytes allowed in a message queue. +.P +These types shall be unsigned integer types that are able to store +values at least as large as a type +.BR "unsigned short" . +.P +The +.IR +header shall define the following symbolic constant as a message +operation flag: +.IP MSG_NOERROR 14 +No error if big message. +.P +The +.IR +header shall define the +.BR msqid_ds +structure, which shall include the following members: +.sp +.RS 4 +.nf +\fB +struct ipc_perm msg_perm \fROperation permission structure.\fR +msgqnum_t msg_qnum \fRNumber of messages currently on queue.\fR +msglen_t msg_qbytes \fRMaximum number of bytes allowed on queue.\fR +pid_t msg_lspid \fRProcess ID of last \fImsgsnd\fP\^(\|).\fR +pid_t msg_lrpid \fRProcess ID of last \fImsgrcv\fP\^(\|).\fR +time_t msg_stime \fRTime of last \fImsgsnd\fP\^(\|).\fR +time_t msg_rtime \fRTime of last \fImsgrcv\fP\^(\|).\fR +time_t msg_ctime \fRTime of last change.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR pid_t , +.BR size_t , +.BR ssize_t , +and +.BR time_t +types as described in +.IR . +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int msgctl(int, int, struct msqid_ds *); +int msgget(key_t, int); +ssize_t msgrcv(int, void *, size_t, long, int); +int msgsnd(int, const void *, size_t, int); +.fi \fR +.P +.RE +.P +In addition, the +.IR +header shall include the +.IR +header. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fImsgctl\fR\^(\|)", +.IR "\fImsgget\fR\^(\|)", +.IR "\fImsgrcv\fR\^(\|)", +.IR "\fImsgsnd\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/sys_resource.h.0p b/man-pages-posix-2013/man0p/sys_resource.h.0p new file mode 100644 index 0000000..9c30d1e --- /dev/null +++ b/man-pages-posix-2013/man0p/sys_resource.h.0p @@ -0,0 +1,207 @@ +'\" et +.TH sys_resource.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/resource.h +\(em definitions for XSI resource operations +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following symbolic constants as possible values +of the +.IR which +argument of +\fIgetpriority\fR() +and +\fIsetpriority\fR(): +.IP PRIO_PROCESS 16 +Identifies the +.IR who +argument as a process ID. +.IP PRIO_PGRP 16 +Identifies the +.IR who +argument as a process group ID. +.IP PRIO_USER 16 +Identifies the +.IR who +argument as a user ID. +.P +The +.IR +header shall define the following type through +.BR typedef : +.IP "\fBrlim_t\fR" 16 +Unsigned integer type used for limit values. +.P +The +.IR +header shall define the following symbolic constants, which shall have +values suitable for use in +.BR #if +preprocessing directives: +.IP RLIM_INFINITY 16 +A value of +.BR rlim_t +indicating no limit. +.IP RLIM_SAVED_MAX 16 +A value of type +.BR rlim_t +indicating an unrepresentable saved hard limit. +.IP RLIM_SAVED_CUR 16 +A value of type +.BR rlim_t +indicating an unrepresentable saved soft limit. +.P +On implementations where all resource limits are representable in an +object of type +.BR rlim_t , +RLIM_SAVED_MAX and RLIM_SAVED_CUR need not be distinct from +RLIM_INFINITY. +.P +The +.IR +header shall define the following symbolic constants as possible values +of the +.IR who +parameter of +\fIgetrusage\fR(): +.IP RUSAGE_SELF 16 +Returns information about the current process. +.IP RUSAGE_CHILDREN 16 +Returns information about children of the current process. +.P +The +.IR +header shall define the +.BR rlimit +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +rlim_t rlim_cur \fRThe current (soft) limit.\fR +rlim_t rlim_max \fRThe hard limit.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR rusage +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +struct timeval ru_utime \fRUser time used.\fR +struct timeval ru_stime \fRSystem time used.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR timeval +structure as described in +.IR . +.P +The +.IR +header shall define the following symbolic constants as possible values +for the +.IR resource +argument of +\fIgetrlimit\fR() +and +\fIsetrlimit\fR(): +.IP RLIMIT_CORE 16 +Limit on size of +.BR core +file. +.IP RLIMIT_CPU 16 +Limit on CPU time per process. +.IP RLIMIT_DATA 16 +Limit on data segment size. +.IP RLIMIT_FSIZE 16 +Limit on file size. +.IP RLIMIT_NOFILE 16 +Limit on number of open files. +.IP RLIMIT_STACK 16 +Limit on stack size. +.IP RLIMIT_AS 16 +Limit on address space size. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int getpriority(int, id_t); +int getrlimit(int, struct rlimit *); +int getrusage(int, struct rusage *); +int setpriority(int, id_t, int); +int setrlimit(int, const struct rlimit *); +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR id_t +type through +.BR typedef , +as described in +.IR . +.P +Inclusion of the +.IR +header may also make visible all symbols from +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIgetpriority\fR\^(\|)", +.IR "\fIgetrlimit\fR\^(\|)", +.IR "\fIgetrusage\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/sys_select.h.0p b/man-pages-posix-2013/man0p/sys_select.h.0p new file mode 100644 index 0000000..af643c8 --- /dev/null +++ b/man-pages-posix-2013/man0p/sys_select.h.0p @@ -0,0 +1,144 @@ +'\" et +.TH sys_select.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/select.h +\(em select types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR timeval +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +time_t tv_sec \fRSeconds.\fR +suseconds_t tv_usec \fRMicroseconds.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR time_t +and +.BR suseconds_t +types as described in +.IR . +.P +The +.IR +header shall define the +.BR sigset_t +type as described in +.IR . +.P +The +.IR +header shall define the +.BR timespec +structure as described in +.IR . +.P +The +.IR +header shall define the +.BR fd_set +type as a structure. +.P +The +.IR +header shall define the following symbolic constant, which shall have +a value suitable for use in +.BR #if +preprocessing directives: +.IP FD_SETSIZE 12 +Maximum number of file descriptors in an +.BR fd_set +structure. +.P +The following shall be declared as functions, defined as macros, or +both. If functions are declared, function prototypes shall be +provided. +.sp +.RS 4 +.nf +\fB +void FD_CLR(int, fd_set *); +int FD_ISSET(int, fd_set *); +void FD_SET(int, fd_set *); +void FD_ZERO(fd_set *); +.fi \fR +.P +.RE +.P +If implemented as macros, these may evaluate their arguments more than +once, so applications should ensure that the arguments they supply are +never expressions with side-effects. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int pselect(int, fd_set *restrict, fd_set *restrict, fd_set *restrict, + const struct timespec *restrict, const sigset_t *restrict); +int select(int, fd_set *restrict, fd_set *restrict, fd_set *restrict, + struct timeval *restrict); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may make visible all symbols from the headers +.IR +and +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIpselect\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/sys_sem.h.0p b/man-pages-posix-2013/man0p/sys_sem.h.0p new file mode 100644 index 0000000..678771a --- /dev/null +++ b/man-pages-posix-2013/man0p/sys_sem.h.0p @@ -0,0 +1,162 @@ +'\" et +.TH sys_sem.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/sem.h +\(em XSI semaphore facility +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following symbolic constant for use as a +semaphore operation flag: +.IP SEM_UNDO 12 +Set up adjust on exit entry. +.P +The +.IR +header shall define the following symbolic constants for use as +commands for the +\fIsemctl\fR() +function: +.IP GETNCNT 12 +Get +.IR semncnt . +.IP GETPID 12 +Get +.IR sempid . +.IP GETVAL 12 +Get +.IR semval . +.IP GETALL 12 +Get all cases of +.IR semval . +.IP GETZCNT 12 +Get +.IR semzcnt . +.IP SETVAL 12 +Set +.IR semval . +.IP SETALL 12 +Set all cases of +.IR semval . +.P +The +.IR +header shall define the +.BR semid_ds +structure, which shall include the following members: +.sp +.RS 4 +.nf +\fB +struct ipc_perm sem_perm \fROperation permission structure.\fR +unsigned short sem_nsems \fRNumber of semaphores in set.\fR +time_t sem_otime \fRLast \fIsemop\fP\^(\|) time.\fR +time_t sem_ctime \fRLast time changed by \fIsemctl\fP\^(\|).\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR pid_t , +.BR size_t , +and +.BR time_t +types as described in +.IR . +.P +A semaphore shall be represented by an anonymous structure, +which shall include the following members: +.sp +.RS 4 +.nf +\fB +unsigned short semval \fRSemaphore value.\fR +pid_t sempid \fRProcess ID of last operation.\fR +unsigned short semncnt \fRNumber of processes waiting for \fIsemval\fR + \fRto become greater than current value.\fR +unsigned short semzcnt \fRNumber of processes waiting for \fIsemval\fR + \fRto become 0.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR sembuf +structure, which shall include the following members: +.sp +.RS 4 +.nf +\fB +unsigned short sem_num \fRSemaphore number.\fR +short sem_op \fRSemaphore operation.\fR +short sem_flg \fROperation flags.\fR +.fi \fR +.P +.RE +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int semctl(int, int, int, ...); +int semget(key_t, int, int); +int semop(int, struct sembuf *, size_t); +.fi \fR +.P +.RE +.P +In addition, the +.IR +header shall include the +.IR +header. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIsemctl\fR\^(\|)", +.IR "\fIsemget\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/sys_shm.h.0p b/man-pages-posix-2013/man0p/sys_shm.h.0p new file mode 100644 index 0000000..fcb74a8 --- /dev/null +++ b/man-pages-posix-2013/man0p/sys_shm.h.0p @@ -0,0 +1,120 @@ +'\" et +.TH sys_shm.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/shm.h +\(em XSI shared memory facility +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following symbolic constants: +.IP SHM_RDONLY 12 +Attach read-only (else read-write). +.IP SHM_RND 12 +Round attach address to SHMLBA. +.IP SHMLBA 12 +Segment low boundary address multiple. +.P +The +.IR +header shall define the following data types through +.BR typedef : +.IP "\fBshmatt_t\fP" 12 +Unsigned integer used for the number of current attaches that must be +able to store values at least as large as a type +.BR "unsigned short" . +.P +The +.IR +header shall define the +.BR shmid_ds +structure, which shall include the following members: +.sp +.RS 4 +.nf +\fB +struct ipc_perm shm_perm \fROperation permission structure.\fR +size_t shm_segsz \fRSize of segment in bytes.\fR +pid_t shm_lpid \fRProcess ID of last shared memory operation.\fR +pid_t shm_cpid \fRProcess ID of creator.\fR +shmatt_t shm_nattch \fRNumber of current attaches.\fR +time_t shm_atime \fRTime of last \fIshmat\fP\^(\|).\fR +time_t shm_dtime \fRTime of last \fIshmdt\fP\^(\|).\fR +time_t shm_ctime \fRTime of last change by \fIshmctl\fP\^(\|).\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR pid_t , +.BR size_t , +and +.BR time_t +types as described in +.IR . +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +void *shmat(int, const void *, int); +int shmctl(int, int, struct shmid_ds *); +int shmdt(const void *); +int shmget(key_t, size_t, int); +.fi \fR +.P +.RE +.P +In addition, the +.IR +header shall include the +.IR +header. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIshmat\fR\^(\|)", +.IR "\fIshmctl\fR\^(\|)", +.IR "\fIshmdt\fR\^(\|)", +.IR "\fIshmget\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/sys_socket.h.0p b/man-pages-posix-2013/man0p/sys_socket.h.0p new file mode 100644 index 0000000..1f0f18f --- /dev/null +++ b/man-pages-posix-2013/man0p/sys_socket.h.0p @@ -0,0 +1,563 @@ +'\" et +.TH sys_socket.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/socket.h +\(em main sockets header +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR socklen_t +type, which is an integer type of width of at least 32 bits; +see APPLICATION USAGE. +.P +The +.IR +header shall define the +.BR sa_family_t +unsigned integer type. +.P +The +.IR +header shall define the +.BR sockaddr +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +sa_family_t sa_family \fRAddress family.\fR +char sa_data[] \fRSocket address (variable-length data).\fR +.fi \fR +.P +.RE +.P +The +.BR sockaddr +structure is used to define a socket address which is used +in the +\fIbind\fR(), +\fIconnect\fR(), +\fIgetpeername\fR(), +\fIgetsockname\fR(), +\fIrecvfrom\fR(), +and +\fIsendto\fR() +functions. +.P +The +.IR +header shall define the +.BR sockaddr_storage +structure, which shall be: +.IP " *" 4 +Large enough to accommodate all supported protocol-specific address +structures +.IP " *" 4 +Aligned at an appropriate boundary so that pointers to it can be cast +as pointers to protocol-specific address structures and used to access +the fields of those structures without alignment problems +.P +The +.BR sockaddr_storage +structure shall include at least the following members: +.sp +.RS 4 +.nf +\fB +sa_family_t ss_family +.fi \fR +.P +.RE +.P +When a pointer to a +.BR sockaddr_storage +structure is cast as a pointer to a +.BR sockaddr +structure, the +.IR ss_family +field of the +.BR sockaddr_storage +structure shall map onto the +.IR sa_family +field of the +.BR sockaddr +structure. When a pointer to a +.BR sockaddr_storage +structure is cast as a pointer to a protocol-specific address structure, +the +.IR ss_family +field shall map onto +a field of that structure that is of type +.BR sa_family_t +and that identifies the protocol's address family. +.P +The +.IR +header shall define the +.BR msghdr +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +void *msg_name \fROptional address.\fR +socklen_t msg_namelen \fRSize of address.\fR +struct iovec *msg_iov \fRScatter/gather array.\fR +int msg_iovlen \fRMembers in \fImsg_iov\fR.\fR +void *msg_control \fRAncillary data; see below.\fR +socklen_t msg_controllen \fRAncillary data buffer \fIlen\fR.\fR +int msg_flags \fRFlags on received message.\fR +.fi \fR +.P +.RE +.P +The +.BR msghdr +structure is used to minimize the number of directly supplied +parameters to the +\fIrecvmsg\fR() +and +\fIsendmsg\fR() +functions. This structure is used as a +.IR value \(hy\c +.IR result +parameter in the +\fIrecvmsg\fR() +function and +.IR value +only for the +\fIsendmsg\fR() +function. +.P +The +.IR +header shall define the +.BR iovec +structure as described in +.IR . +.P +The +.IR +header shall define the +.BR cmsghdr +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +socklen_t cmsg_len \fRData byte count, including the \fBcmsghdr\fR.\fR +int cmsg_level \fROriginating protocol.\fR +int cmsg_type \fRProtocol-specific type.\fR +.fi \fR +.P +.RE +.P +The +.BR cmsghdr +structure is used for storage of ancillary data object information. +.P +Ancillary data consists of a sequence of pairs, each consisting of a +.BR cmsghdr +structure followed by a data array. The data array contains the +ancillary data message, and the +.BR cmsghdr +structure contains descriptive information that allows an application +to correctly parse the data. +.P +The values for +.IR cmsg_level +shall be legal values for the +.IR level +argument to the +\fIgetsockopt\fR() +and +\fIsetsockopt\fR() +functions. The system documentation shall specify the +.IR cmsg_type +definitions for the supported protocols. +.P +Ancillary data is also possible at the socket level. The +.IR +header shall define the following symbolic constant for use as the +.IR cmsg_type +value when +.IR cmsg_level +is SOL_SOCKET: +.IP SCM_RIGHTS 14 +Indicates that the data array contains the access rights to be sent or +received. +.P +The +.IR +header shall define the following macros to gain access to the data +arrays in the ancillary data associated with a message header: +.IP "CMSG_DATA(\fIcmsg\fP)" 6 +.br +If the argument is a pointer to a +.BR cmsghdr +structure, this macro shall return an unsigned character pointer +to the data array associated with the +.BR cmsghdr +structure. +.IP "CMSG_NXTHDR(\fImhdr,cmsg\fP)" 6 +.br +If the first argument is a pointer to a +.BR msghdr +structure and the second argument is a pointer to a +.BR cmsghdr +structure in the ancillary data pointed to by the +.IR msg_control +field of that +.BR msghdr +structure, this macro shall return a pointer to the next +.BR cmsghdr +structure, or a null pointer if this structure is the last +.BR cmsghdr +in the ancillary data. +.IP "CMSG_FIRSTHDR(\fImhdr\fP)" 6 +.br +If the argument is a pointer to a +.BR msghdr +structure, this macro shall return a pointer to the first +.BR cmsghdr +structure in the ancillary data associated with this +.BR msghdr +structure, or a null pointer if there is no ancillary data associated +with the +.BR msghdr +structure. +.P +The +.IR +header shall define the +.BR linger +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +int l_onoff \fRIndicates whether linger option is enabled.\fR +int l_linger \fRLinger time, in seconds.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the following symbolic constants with distinct values: +.IP SOCK_DGRAM 14 +Datagram socket. +.IP SOCK_RAW 14 +Raw Protocol Interface. +.IP SOCK_SEQPACKET 14 +Sequenced-packet socket. +.IP SOCK_STREAM 14 +Byte-stream socket. +.P +The +.IR +header shall define the following symbolic constant for use as the +.IR level +argument of +\fIsetsockopt\fR() +and +\fIgetsockopt\fR(). +.IP SOL_SOCKET 14 +Options to be accessed at socket level, not protocol level. +.P +The +.IR +header shall define the following symbolic constants with distinct values +for use as the +.IR option_name +argument in +\fIgetsockopt\fR() +or +\fIsetsockopt\fR() +calls (see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.10.16" ", " "Use of Options"): +.IP SO_ACCEPTCONN 14 +Socket is accepting connections. +.IP SO_BROADCAST 14 +Transmission of broadcast messages is supported. +.IP SO_DEBUG 14 +Debugging information is being recorded. +.IP SO_DONTROUTE 14 +Bypass normal routing. +.IP SO_ERROR 14 +Socket error status. +.IP SO_KEEPALIVE 14 +Connections are kept alive with periodic messages. +.IP SO_LINGER 14 +Socket lingers on close. +.IP SO_OOBINLINE 14 +Out-of-band data is transmitted in line. +.IP SO_RCVBUF 14 +Receive buffer size. +.IP SO_RCVLOWAT 14 +Receive ``low water mark''. +.IP SO_RCVTIMEO 14 +Receive timeout. +.IP SO_REUSEADDR 14 +Reuse of local addresses is supported. +.IP SO_SNDBUF 14 +Send buffer size. +.IP SO_SNDLOWAT 14 +Send ``low water mark''. +.IP SO_SNDTIMEO 14 +Send timeout. +.IP SO_TYPE 14 +Socket type. +.P +The +.IR +header shall define the following symbolic constant for use as the maximum +.IR backlog +queue length which may be specified by the +.IR backlog +field of the +\fIlisten\fR() +function: +.IP SOMAXCONN 14 +The maximum +.IR backlog +queue length. +.P +The +.IR +header shall define the following symbolic constants with distinct values +for use as the valid values for the +.IR msg_flags +field in the +.BR msghdr +structure, or the +.IR flags +parameter in +\fIrecv\fR(), +\fIrecvfrom\fR(), +\fIrecvmsg\fR(), +\fIsend\fR(), +\fIsendmsg\fR(), +or +\fIsendto\fR() +calls: +.IP MSG_CTRUNC 14 +Control data truncated. +.IP MSG_DONTROUTE 14 +Send without using routing tables. +.IP MSG_EOR 14 +Terminates a record (if supported by the protocol). +.IP MSG_OOB 14 +Out-of-band data. +.IP MSG_NOSIGNAL 14 +No SIGPIPE generated when an attempt to send is made on a +stream-oriented socket that is no longer connected. +.IP MSG_PEEK 14 +Leave received data in queue. +.IP MSG_TRUNC 14 +Normal data truncated. +.IP MSG_WAITALL 14 +Attempt to fill the read buffer. +.P +The +.IR +header shall define the following symbolic constants with distinct values: +.IP AF_INET 14 +Internet domain sockets for use with IPv4 addresses. +.IP AF_INET6 14 +Internet domain sockets for use with IPv6 addresses. +.IP AF_UNIX 14 +UNIX domain sockets. +.IP AF_UNSPEC 14 +Unspecified. +.P +The +.IR +header shall define the following symbolic constants with distinct values: +.IP SHUT_RD 14 +Disables further receive operations. +.IP SHUT_RDWR 14 +Disables further send and receive operations. +.IP SHUT_WR 14 +Disables further send operations. +.P +The +.IR +header shall define the +.BR size_t +and +.BR ssize_t +types as described in +.IR . +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int accept(int, struct sockaddr *restrict, socklen_t *restrict); +int bind(int, const struct sockaddr *, socklen_t); +int connect(int, const struct sockaddr *, socklen_t); +int getpeername(int, struct sockaddr *restrict, socklen_t *restrict); +int getsockname(int, struct sockaddr *restrict, socklen_t *restrict); +int getsockopt(int, int, int, void *restrict, socklen_t *restrict); +int listen(int, int); +ssize_t recv(int, void *, size_t, int); +ssize_t recvfrom(int, void *restrict, size_t, int, + struct sockaddr *restrict, socklen_t *restrict); +ssize_t recvmsg(int, struct msghdr *, int); +ssize_t send(int, const void *, size_t, int); +ssize_t sendmsg(int, const struct msghdr *, int); +ssize_t sendto(int, const void *, size_t, int, const struct sockaddr *, + socklen_t); +int setsockopt(int, int, int, const void *, socklen_t); +int shutdown(int, int); +int sockatmark(int); +int socket(int, int, int); +int socketpair(int, int, int, int [2]); +.fi \fR +.P +.RE +.P +Inclusion of +.IR +may also make visible all symbols from +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +To forestall portability problems, it is recommended that applications +not use values larger than 2\u\s-331\s+3\d \(mi1 for the +.BR socklen_t +type. +.P +The +.BR sockaddr_storage +structure solves the problem of declaring storage for automatic +variables which is both large enough and aligned enough for storing the +socket address data structure of any family. For example, code with a +file descriptor and without the context of the address family can pass +a pointer to a variable of this type, where a pointer to a socket +address structure is expected in calls such as +\fIgetpeername\fR(), +and determine the address family by accessing the received content +after the call. +.P +The example below illustrates a data structure which aligns on a 64-bit +boundary. An implementation-defined field +.IR _ss_align +following +.IR _ss_pad1 +is used to force a 64-bit alignment which covers proper alignment good +enough for needs of at least +.BR sockaddr_in6 +(IPv6) and +.BR sockaddr_in +(IPv4) address data structures. The size of padding field +.IR _ss_pad1 +depends on the chosen alignment boundary. The size of padding field +.IR _ss_pad2 +depends on the value of overall size chosen for the total size of the +structure. This size and alignment are represented in the above example +by implementation-defined (not required) constants _SS_MAXSIZE +(chosen value 128) and _SS_ALIGNMENT (with chosen value 8). Constants +_SS_PAD1SIZE (derived value 6) and _SS_PAD2SIZE (derived value 112) are +also for illustration and not required. The implementation-defined +definitions and structure field names above start with an + +to denote implementation private name space. Portable code is not expected +to access or reference those fields or constants. +.sp +.RS 4 +.nf +\fB +/* + * Desired design of maximum size and alignment. + */ +#define _SS_MAXSIZE 128 + /* Implementation-defined maximum size. */ +#define _SS_ALIGNSIZE (sizeof(int64_t)) + /* Implementation-defined desired alignment. */ +.P +/* + * Definitions used for sockaddr_storage structure paddings design. + */ +#define _SS_PAD1SIZE (_SS_ALIGNSIZE \(mi sizeof(sa_family_t)) +#define _SS_PAD2SIZE (_SS_MAXSIZE \(mi (sizeof(sa_family_t)+ \e + _SS_PAD1SIZE + _SS_ALIGNSIZE)) +struct sockaddr_storage { + sa_family_t ss_family; /* Address family. */ +/* + * Following fields are implementation-defined. + */ + char _ss_pad1[_SS_PAD1SIZE]; + /* 6-byte pad; this is to make implementation-defined + pad up to alignment field that follows explicit in + the data structure. */ + int64_t _ss_align; /* Field to force desired structure + storage alignment. */ + char _ss_pad2[_SS_PAD2SIZE]; + /* 112-byte pad to achieve desired size, + _SS_MAXSIZE value minus size of ss_family + __ss_pad1, __ss_align fields is 112. */ +}; +.fi \fR +.P +.RE +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIaccept\fR\^(\|)", +.IR "\fIbind\fR\^(\|)", +.IR "\fIconnect\fR\^(\|)", +.IR "\fIgetpeername\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 "\fIsendto\fR\^(\|)", +.IR "\fIsetsockopt\fR\^(\|)", +.IR "\fIshutdown\fR\^(\|)", +.IR "\fIsockatmark\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)", +.IR "\fIsocketpair\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/sys_stat.h.0p b/man-pages-posix-2013/man0p/sys_stat.h.0p new file mode 100644 index 0000000..d8cabe9 --- /dev/null +++ b/man-pages-posix-2013/man0p/sys_stat.h.0p @@ -0,0 +1,406 @@ +'\" et +.TH sys_stat.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/stat.h +\(em data returned by the stat(\|) function +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the structure of the data returned by the +\fIfstat\fR(), +\fIlstat\fR(), +and +\fIstat\fR() +functions. +.P +The +.IR +header shall define the +.BR stat +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +dev_t st_dev \fRDevice ID of device containing file.\fR +ino_t st_ino \fRFile serial number.\fR +mode_t st_mode \fRMode of file (see below).\fR +nlink_t st_nlink \fRNumber of hard links to the file.\fR +uid_t st_uid \fRUser ID of file.\fR +gid_t st_gid \fRGroup ID of file.\fR +dev_t st_rdev \fRDevice ID (if file is character or block special).\fR +off_t st_size \fRFor regular files, the file size in bytes.\fR + \fRFor symbolic links, the length in bytes of the\fR + \fRpathname contained in the symbolic link.\fR + \fRFor a shared memory object, the length in bytes.\fR + \fRFor a typed memory object, the length in bytes.\fR + \fRFor other file types, the use of this field is\fR + \fRunspecified.\fR +struct timespec st_atim \fRLast data access timestamp.\fR +struct timespec st_mtim \fRLast data modification timestamp.\fR +struct timespec st_ctim \fRLast file status change timestamp.\fR +blksize_t st_blksize \fRA file system-specific preferred I/O block size\fR + \fRfor this object. In some file system types, this\fR + \fRmay vary from file to file.\fR +blkcnt_t st_blocks \fRNumber of blocks allocated for this object.\fR +.fi \fR +.P +.RE +.P +The +.IR st_ino +and +.IR st_dev +fields taken together uniquely identify the file within the system. +.P +The +.IR +header shall define the +.BR blkcnt_t , +.BR blksize_t , +.BR dev_t , +.BR ino_t , +.BR mode_t , +.BR nlink_t , +.BR uid_t , +.BR gid_t , +.BR off_t , +and +.BR time_t +types as described in +.IR . +.P +The +.IR +header shall define the +.BR timespec +structure as described in +.IR . +Times shall be given in seconds since the Epoch. +.P +Which structure members have meaningful values depends on the +type of file. For further information, see the descriptions of +\fIfstat\fR(), +\fIlstat\fR(), +and +\fIstat\fR() +in the System Interfaces volume of POSIX.1\(hy2008. +.P +For compatibility with earlier versions of this standard, the +.IR st_atime +macro shall be defined with the value +.IR st_atim.tv_sec . +Similarly, +.IR st_ctime +and +.IR st_mtime +shall be defined as macros with the values +.IR st_ctim.tv_sec +and +.IR st_mtim.tv_sec , +respectively. +.br +.P +The +.IR +header shall define the following symbolic constants for the +file types encoded in type +.BR mode_t . +The values shall be suitable for use in +.BR #if +preprocessing directives: +.IP S_IFMT 12 +Type of file. +.RS 12 +.IP S_IFBLK 12 +Block special. +.IP S_IFCHR 12 +Character special. +.IP S_IFIFO 12 +FIFO special. +.IP S_IFREG 12 +Regular. +.IP S_IFDIR 12 +Directory. +.IP S_IFLNK 12 +Symbolic link. +.IP S_IFSOCK 12 +Socket. +.RE +.P +The +.IR +header shall define the following symbolic constants for the file mode +bits encoded in type +.BR mode_t , +with the indicated numeric values. These macros shall expand to an +expression which has a type that allows them to be used, either singly +or OR'ed together, as the third argument to +\fIopen\fR() +without the need for a +.BR mode_t +cast. The values shall be suitable for use in +.BR #if +preprocessing directives. +.TS +center box tab(@); +cB | cB | cB +l | n | l. +Name@Numeric Value@Description +_ +S_IRWXU@0700@Read, write, execute/search by owner. +S_IRUSR@0400@Read permission, owner. +S_IWUSR@0200@Write permission, owner. +S_IXUSR@0100@Execute/search permission, owner. +_ +S_IRWXG@070@Read, write, execute/search by group. +S_IRGRP@040@Read permission, group. +S_IWGRP@020@Write permission, group. +S_IXGRP@010@Execute/search permission, group. +_ +S_IRWXO@07@Read, write, execute/search by others. +S_IROTH@04@Read permission, others. +S_IWOTH@02@Write permission, others. +S_IXOTH@01@Execute/search permission, others. +_ +S_ISUID@04000@Set-user-ID on execution. +S_ISGID@02000@Set-group-ID on execution. +\*!S_ISVTX@01000@On directories, restricted deletion flag.\0\0\0\*? +.TE +.P +The following macros shall be provided to test whether a file is of the +specified type. The value +.IR m +supplied to the macros is the value of +.IR st_mode +from a +.BR stat +structure. The macro shall evaluate to a non-zero value if the test is +true; 0 if the test is false. +.IP "S_ISBLK(\fIm\fP)" 14 +Test for a block special file. +.IP "S_ISCHR(\fIm\fP)" 14 +Test for a character special file. +.IP "S_ISDIR(\fIm\fP)" 14 +Test for a directory. +.IP "S_ISFIFO(\fIm\fP)" 14 +Test for a pipe or FIFO special file. +.IP "S_ISREG(\fIm\fP)" 14 +Test for a regular file. +.IP "S_ISLNK(\fIm\fP)" 14 +Test for a symbolic link. +.IP "S_ISSOCK(\fIm\fP)" 14 +Test for a socket. +.P +The implementation may implement message queues, semaphores, or shared +memory objects as distinct file types. The following macros shall be +provided to test whether a file is of the specified type. The value of +the +.IR buf +argument supplied to the macros is a pointer to a +.BR stat +structure. The macro shall evaluate to a non-zero value if the +specified object is implemented as a distinct file type and the +specified file type is contained in the +.BR stat +structure referenced by +.IR buf . +Otherwise, the macro shall evaluate to zero. +.IP "S_TYPEISMQ(\fIbuf\fP)" 14 +Test for a message queue. +.IP "S_TYPEISSEM(\fIbuf\fP)" 14 +Test for a semaphore. +.IP "S_TYPEISSHM(\fIbuf\fP)" 14 +Test for a shared memory object. +.P +The implementation may implement typed memory objects as distinct +file types, and the following macro shall test whether a file is of the +specified type. The value of the +.IR buf +argument supplied to the macros is a pointer to a +.BR stat +structure. The macro shall evaluate to a non-zero value if the +specified object is implemented as a distinct file type and the +specified file type is contained in the +.BR stat +structure referenced by +.IR buf . +Otherwise, the macro shall evaluate to zero. +.IP "S_TYPEISTMO(\fIbuf\fP)" 14 +Test macro for a typed memory object. +.P +The +.IR +header shall define the following symbolic constants as distinct +integer values outside of the range [0,999\|999\|999], +for use with the +\fIfutimens\fR() +and +\fIutimensat\fR() +functions: +UTIME_NOW +UTIME_OMIT +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int chmod(const char *, mode_t); +int fchmod(int, mode_t); +int fchmodat(int, const char *, mode_t, int); +int fstat(int, struct stat *); +int fstatat(int, const char *restrict, struct stat *restrict, int); +int futimens(int, const struct timespec [2]); +int lstat(const char *restrict, struct stat *restrict); +int mkdir(const char *, mode_t); +int mkdirat(int, const char *, mode_t); +int mkfifo(const char *, mode_t); +int mkfifoat(int, const char *, mode_t); +int mknod(const char *, mode_t, dev_t); +int mknodat(int, const char *, mode_t, dev_t); +int stat(const char *restrict, struct stat *restrict); +mode_t umask(mode_t); +int utimensat(int, const char *, const struct timespec [2], int); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Use of the macros is recommended for determining the type of a file. +.SH RATIONALE +A conforming C-language application must include +.IR +for functions that have arguments or return values of type +.BR mode_t , +so that symbolic values for that type can be used. An alternative +would be to require that these constants are also defined by including +.IR . +.P +The S_ISUID and S_ISGID +bits may be cleared on any write, not just on +\fIopen\fR(), +as some historical implementations do. +.P +System calls that update the time entry fields in the +.BR stat +structure must be documented by the implementors. POSIX-conforming +systems should not update the time entry fields for functions listed in +the System Interfaces volume of POSIX.1\(hy2008 unless the standard requires that they do, except in the case +of documented extensions to the standard. +.P +Upon assignment, file timestamps are immediately converted to the +resolution of the file system by truncation (i.e., the recorded time +can be older than the actual time). For example, if the file system +resolution is 1 microsecond, then a conforming +\fIstat\fR() +must always return an +.IR st_mtim.tv_nsec +that is a multiple of 1000. Some older implementations returned +higher-resolution timestamps while the +.IR inode +information was cached, and then spontaneously truncated the +.IR tv_nsec +fields when they were stored to and retrieved from disk, but this behavior +does not conform. +.P +Note that +.IR st_dev +must be unique within a Local Area Network (LAN) in a ``system'' made +up of multiple computers' file systems connected by a LAN. +.P +Networked implementations of a POSIX-conforming system must guarantee +that all files visible within the file tree (including parts of the +tree that may be remotely mounted from other machines on the network) +on each individual processor are uniquely identified by the combination +of the +.IR st_ino +and +.IR st_dev +fields. +.P +The unit for the +.IR st_blocks +member of the +.BR stat +structure is not defined within POSIX.1\(hy2008. In some implementations +it is 512 bytes. It may differ on a file system basis. There is no +correlation between values of the +.IR st_blocks +and +.IR st_blksize , +and the +.IR f_bsize +(from +.IR ) +structure members. +.P +Traditionally, some implementations defined the multiplier for +.IR st_blocks +in +.IR +as the symbol DEV_BSIZE. +.P +Some earlier versions of this standard did not specify values for the +file mode bit macros. The expectation was that some implementors might +choose to use a different encoding for these bits than the traditional +one, and that new applications would use symbolic file modes instead of +numeric. This version of the standard specifies the traditional encoding, +in recognition that nearly 20 years after the first publication of this +standard numeric file modes are still in widespread use by application +developers, and that all conforming implementations still use the +traditional encoding. +.SH "FUTURE DIRECTIONS" +No new S_IFMT symbolic names for the file type values of +.BR mode_t +will be defined by POSIX.1\(hy2008; if new file types are required, they will +only be testable through +.IR S_ISxx (\|) +or +.IR S_TYPEISxxx (\|) +macros instead. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIchmod\fR\^(\|)", +.IR "\fIfchmod\fR\^(\|)", +.IR "\fIfstat\fR\^(\|)", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fIfutimens\fR\^(\|)", +.IR "\fImkdir\fR\^(\|)", +.IR "\fImkfifo\fR\^(\|)", +.IR "\fImknod\fR\^(\|)", +.IR "\fIumask\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/sys_statvfs.h.0p b/man-pages-posix-2013/man0p/sys_statvfs.h.0p new file mode 100644 index 0000000..ca53935 --- /dev/null +++ b/man-pages-posix-2013/man0p/sys_statvfs.h.0p @@ -0,0 +1,104 @@ +'\" et +.TH sys_statvfs.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/statvfs.h +\(em VFS File System information structure +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR statvfs +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +unsigned long f_bsize \fRFile system block size.\fR +unsigned long f_frsize \fRFundamental file system block size.\fR +fsblkcnt_t f_blocks \fRTotal number of blocks on file system in units of \fIf_frsize.\fR +fsblkcnt_t f_bfree \fRTotal number of free blocks.\fR +fsblkcnt_t f_bavail \fRNumber of free blocks available to\fR + \fRnon-privileged process.\fR +fsfilcnt_t f_files \fRTotal number of file serial numbers.\fR +fsfilcnt_t f_ffree \fRTotal number of free file serial numbers.\fR +fsfilcnt_t f_favail \fRNumber of file serial numbers available to\fR + \fRnon-privileged process.\fR +unsigned long f_fsid \fRFile system ID.\fR +unsigned long f_flag \fRBit mask of \fIf_flag\fR values.\fR +unsigned long f_namemax \fRMaximum filename length.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR fsblkcnt_t +and +.BR fsfilcnt_t +types as described in +.IR . +.P +The +.IR +header shall define the following symbolic constants for the +.IR f_flag +member: +.IP ST_RDONLY 12 +Read-only file system. +.IP ST_NOSUID 12 +Does not support the semantics of the ST_ISUID and ST_ISGID file mode +bits. +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int fstatvfs(int, struct statvfs *); +int statvfs(const char *restrict, struct statvfs *restrict); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIfstatvfs\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/sys_time.h.0p b/man-pages-posix-2013/man0p/sys_time.h.0p new file mode 100644 index 0000000..30d38ae --- /dev/null +++ b/man-pages-posix-2013/man0p/sys_time.h.0p @@ -0,0 +1,145 @@ +'\" et +.TH sys_time.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/time.h +\(em time types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR timeval +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +time_t tv_sec \fRSeconds.\fR +suseconds_t tv_usec \fRMicroseconds.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR itimerval +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +struct timeval it_interval \fRTimer interval.\fR +struct timeval it_value \fRCurrent value.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR time_t +and +.BR suseconds_t +types as described in +.IR . +.P +The +.IR +header shall define the +.BR fd_set +type as described in +.IR . +.P +The +.IR +header shall define the following symbolic constants for the +.IR which +argument of +\fIgetitimer\fR() +and +\fIsetitimer\fR(): +.IP ITIMER_REAL 14 +Decrements in real time. +.IP ITIMER_VIRTUAL 14 +Decrements in process virtual time. +.IP ITIMER_PROF 14 +Decrements both in process virtual time and when the system is running +on behalf of the process. +.P +The +.IR +header shall define the following as described in +.IR : +\fIFD_CLR\fR() +\fIFD_ISSET\fR() +\fIFD_SET\fR() +\fIFD_ZERO\fR() +FD_SETSIZE +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int getitimer(int, struct itimerval *); +int gettimeofday(struct timeval *restrict, void *restrict); +int setitimer(int, const struct itimerval *restrict, + struct itimerval *restrict); +int select(int, fd_set *restrict, fd_set *restrict, fd_set *restrict, + struct timeval *restrict); +int utimes(const char *, const struct timeval [2]); +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may make visible all symbols from the +.IR +header. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIfutimens\fR\^(\|)", +.IR "\fIgetitimer\fR\^(\|)", +.IR "\fIgettimeofday\fR\^(\|)", +.IR "\fIpselect\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/sys_times.h.0p b/man-pages-posix-2013/man0p/sys_times.h.0p new file mode 100644 index 0000000..28367a8 --- /dev/null +++ b/man-pages-posix-2013/man0p/sys_times.h.0p @@ -0,0 +1,83 @@ +'\" et +.TH sys_times.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/times.h +\(em file access and modification times structure +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR tms +structure, which is returned by +\fItimes\fR() +and shall include at least the following members: +.sp +.RS 4 +.nf +\fB +clock_t tms_utime \fRUser CPU time.\fR +clock_t tms_stime \fRSystem CPU time.\fR +clock_t tms_cutime \fRUser CPU time of terminated child processes.\fR +clock_t tms_cstime \fRSystem CPU time of terminated child processes.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR clock_t +type as described in +.IR . +.P +The following shall be declared as a function and may also be defined +as a macro. A function prototype shall be provided. +.sp +.RS 4 +.nf +\fB +clock_t times(struct tms *); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fItimes\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/sys_types.h.0p b/man-pages-posix-2013/man0p/sys_types.h.0p new file mode 100644 index 0000000..1eb0d65 --- /dev/null +++ b/man-pages-posix-2013/man0p/sys_types.h.0p @@ -0,0 +1,241 @@ +'\" et +.TH sys_types.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/types.h +\(em data types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define at least the following types: +.IP "\fBblkcnt_t\fP" 16 +Used for file block counts. +.IP "\fBblksize_t\fP" 16 +Used for block sizes. +.IP "\fBclock_t\fP" 16 +Used for system times in clock ticks or CLOCKS_PER_SEC; see +.IR . +.IP "\fBclockid_t\fP" 16 +Used for clock ID type in the clock and timer functions. +.IP "\fBdev_t\fP" 16 +Used for device IDs. +.IP "\fBfsblkcnt_t\fP" 16 +Used for file system block counts. +.IP "\fBfsfilcnt_t\fP" 16 +Used for file system file counts. +.IP "\fBgid_t\fP" 16 +Used for group IDs. +.IP "\fBid_t\fP" 16 +Used as a general identifier; can be used to contain at least a +.BR pid_t , +.BR uid_t , +or +.BR gid_t . +.IP "\fBino_t\fP" 16 +Used for file serial numbers. +.IP "\fBkey_t\fP" 16 +Used for XSI interprocess communication. +.IP "\fBmode_t\fP" 16 +Used for some file attributes. +.IP "\fBnlink_t\fP" 16 +Used for link counts. +.IP "\fBoff_t\fP" 16 +Used for file sizes. +.IP "\fBpid_t\fP" 16 +Used for process IDs and process group IDs. +.IP "\fBpthread_attr_t\fP" 16 +Used to identify a thread attribute object. +.IP "\fBpthread_barrier_t\fP" 16 +Used to identify a barrier. +.IP "\fBpthread_barrierattr_t\fP" 16 +Used to define a barrier attributes object. +.IP "\fBpthread_cond_t\fP" 16 +Used for condition variables. +.IP "\fBpthread_condattr_t\fP" 16 +Used to identify a condition attribute object. +.IP "\fBpthread_key_t\fP" 16 +Used for thread-specific data keys. +.IP "\fBpthread_mutex_t\fP" 16 +Used for mutexes. +.IP "\fBpthread_mutexattr_t\fP" 16 +Used to identify a mutex attribute object. +.IP "\fBpthread_once_t\fP" 16 +Used for dynamic package initialization. +.IP "\fBpthread_rwlock_t\fP" 16 +Used for read-write locks. +.IP "\fBpthread_rwlockattr_t\fP" 16 +Used for read-write lock attributes. +.IP "\fBpthread_spinlock_t\fP" 16 +Used to identify a spin lock. +.IP "\fBpthread_t\fP" 16 +Used to identify a thread. +.IP "\fBsize_t\fP" 16 +Used for sizes of objects. +.IP "\fBssize_t\fP" 16 +Used for a count of bytes or an error indication. +.IP "\fBsuseconds_t\fP" 16 +Used for time in microseconds. +.IP "\fBtime_t\fP" 16 +Used for time in seconds. +.IP "\fBtimer_t\fP" 16 +Used for timer ID returned by +\fItimer_create\fR(). +.IP "\fBtrace_attr_t\fP" 16 +Used to identify a trace stream attributes object +.IP "\fBtrace_event_id_t\fP" 16 +Used to identify a trace event type. +.IP "\fBtrace_event_set_t\fP" 16 +Used to identify a trace event type set. +.IP "\fBtrace_id_t\fP" 16 +Used to identify a trace stream. +.IP "\fBuid_t\fP" 16 +Used for user IDs. +.P +All of the types shall be defined as arithmetic types of an appropriate +length, with the following exceptions: +.P +.nf +.BR pthread_attr_t +.BR pthread_barrier_t +.BR pthread_barrierattr_t +.BR pthread_cond_t +.BR pthread_condattr_t +.BR pthread_key_t +.BR pthread_mutex_t +.BR pthread_mutexattr_t +.BR pthread_once_t +.BR pthread_rwlock_t +.BR pthread_rwlockattr_t +.BR pthread_spinlock_t +.BR pthread_t +.BR trace_attr_t +.BR trace_event_id_t +.BR trace_event_set_t +.BR trace_id_t +.fi +.P +Additionally: +.IP " *" 4 +.BR mode_t +shall be an integer type. +.IP " *" 4 +.BR dev_t +shall be an integer type. +.IP " *" 4 +.BR nlink_t , +.BR uid_t , +.BR gid_t , +and +.BR id_t +shall be integer types. +.IP " *" 4 +.BR blkcnt_t +and +.BR off_t +shall be signed integer types. +.IP " *" 4 +.BR fsblkcnt_t , +.BR fsfilcnt_t , +and +.BR ino_t +shall be defined as unsigned integer types. +.IP " *" 4 +.BR size_t +shall be an unsigned integer type. +.IP " *" 4 +.BR blksize_t , +.BR pid_t , +and +.BR ssize_t +shall be signed integer types. +.IP " *" 4 +.BR clock_t +shall be an integer or real-floating type. +.BR time_t +shall be an integer type. +.P +The type +.BR ssize_t +shall be capable of storing values at least in the range +[\(mi1,\ {SSIZE_MAX}]. +.P +The type +.BR suseconds_t +shall be a signed integer type capable of storing values at least in +the range [\(mi1,\ 1\|000\|000]. +.P +The implementation shall support one or more programming environments +in which the widths of +.BR blksize_t , +.BR pid_t , +.BR size_t , +.BR ssize_t , +and +.BR suseconds_t +are no greater than the width of type +.BR long . +The names of these programming environments can be obtained using the +\fIconfstr\fR() +function or the +.IR getconf +utility. +.P +There are no defined comparison or assignment operators for the +following types: +.P +.nf +.BR pthread_attr_t +.BR pthread_barrier_t +.BR pthread_barrierattr_t +.BR pthread_cond_t +.BR pthread_condattr_t +.BR pthread_mutex_t +.BR pthread_mutexattr_t +.BR pthread_rwlock_t +.BR pthread_rwlockattr_t +.BR pthread_spinlock_t +.BR trace_attr_t +.fi +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIconfstr\fR\^(\|)" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIgetconf\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/sys_uio.h.0p b/man-pages-posix-2013/man0p/sys_uio.h.0p new file mode 100644 index 0000000..d91d39f --- /dev/null +++ b/man-pages-posix-2013/man0p/sys_uio.h.0p @@ -0,0 +1,104 @@ +'\" et +.TH sys_uio.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/uio.h +\(em definitions for vector I/O operations +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR iovec +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +void *iov_base \fRBase address of a memory region for input or output.\fR +size_t iov_len \fRThe size of the memory pointed to by \fIiov_base.\fR +.fi \fR +.P +.RE +.P +The +.IR +header uses the +.BR iovec +structure for scatter/gather I/O. +.P +The +.IR +header shall define the +.BR ssize_t +and +.BR size_t +types as described in +.IR . +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +ssize_t readv(int, const struct iovec *, int); +ssize_t writev(int, const struct iovec *, int); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The implementation can put a limit on the number of scatter/gather +elements which can be processed in one call. The symbol +{IOV_MAX} +defined in +.IR +should always be used to learn about the limits instead of assuming a +fixed value. +.SH RATIONALE +Traditionally, the maximum number of scatter/gather elements the system +can process in one call were described by the symbolic value +{UIO_MAXIOV}. +In IEEE\ Std\ 1003.1\(hy2001 this value is replaced by the constant +{IOV_MAX} +which can be found in +.IR . +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIread\fR\^(\|)", +.IR "\fIreadv\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)", +.IR "\fIwritev\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/sys_un.h.0p b/man-pages-posix-2013/man0p/sys_un.h.0p new file mode 100644 index 0000000..bb7bce6 --- /dev/null +++ b/man-pages-posix-2013/man0p/sys_un.h.0p @@ -0,0 +1,89 @@ +'\" et +.TH sys_un.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/un.h +\(em definitions for UNIX domain sockets +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR sockaddr_un +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +sa_family_t sun_family \fRAddress family.\fR +char sun_path[] \fRSocket pathname.\fR +.fi \fR +.P +.RE +.P +The +.BR sockaddr_un +structure is used to store addresses for UNIX domain sockets. +Pointers to this type shall be cast by applications to +.BR "struct sockaddr *" +for use with socket functions. +.P +The +.IR +header shall define the +.BR sa_family_t +type as described in +.IR . +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The size of +.IR sun_path +has intentionally been left undefined. This is because different +implementations use different sizes. For example, 4.3 BSD uses a size of +108, and 4.4 BSD uses a size of 104. Since most implementations +originate from BSD versions, the size is typically in the range 92 to +108. +.P +Applications should not assume a particular length for +.IR sun_path +or assume that it can hold +{_POSIX_PATH_MAX} +bytes (256). +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIbind\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)", +.IR "\fIsocketpair\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/sys_utsname.h.0p b/man-pages-posix-2013/man0p/sys_utsname.h.0p new file mode 100644 index 0000000..dabaec3 --- /dev/null +++ b/man-pages-posix-2013/man0p/sys_utsname.h.0p @@ -0,0 +1,77 @@ +'\" et +.TH sys_utsname.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/utsname.h +\(em system name structure +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the structure +.BR utsname +which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +char sysname[] \fRName of this implementation of the operating system.\fR +char nodename[] \fRName of this node within the communications\fR + \fRnetwork to which this node is attached, if any.\fR +char release[] \fRCurrent release level of this implementation.\fR +char version[] \fRCurrent version level of this release.\fR +char machine[] \fRName of the hardware type on which the system is running.\fR +.fi \fR +.P +.RE +.P +The character arrays are of unspecified size, but the data stored in +them shall be terminated by a null byte. +.P +The following shall be declared as a function and may also be defined +as a macro: +.sp +.RS 4 +.nf +\fB +int uname(struct utsname *); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIuname\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/sys_wait.h.0p b/man-pages-posix-2013/man0p/sys_wait.h.0p new file mode 100644 index 0000000..cf88bc8 --- /dev/null +++ b/man-pages-posix-2013/man0p/sys_wait.h.0p @@ -0,0 +1,145 @@ +'\" et +.TH sys_wait.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sys/wait.h +\(em declarations for waiting +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following symbolic constants for use with +\fIwaitpid\fR(): +.IP WCONTINUED 14 +Report status of continued child process. +.IP WNOHANG 14 +Do not hang if no status is available; return immediately. +.IP WUNTRACED 14 +Report status of stopped child process. +.P +The +.IR +header shall define the following macros for analysis of process status +values: +.IP WEXITSTATUS 14 +Return exit status. +.IP WIFCONTINUED 14 +True if child has been continued. +.IP WIFEXITED 14 +True if child exited normally. +.IP WIFSIGNALED 14 +True if child exited due to uncaught signal. +.IP WIFSTOPPED 14 +True if child is currently stopped. +.IP WSTOPSIG 14 +Return signal number that caused process to stop. +.IP WTERMSIG 14 +Return signal number that caused process to terminate. +.P +The +.IR +header shall define the following symbolic constants as possible values +for the +.IR options +argument to +\fIwaitid\fR(): +.IP WEXITED 14 +Wait for processes that have exited. +.IP WNOWAIT 14 +Keep the process whose status is returned in +.IR infop +in a waitable state. +.IP WSTOPPED 14 +Status is returned for any child that has stopped upon receipt of a +signal. +.P +The +WCONTINUED +and WNOHANG constants, described above for +\fIwaitpid\fR(), +can also be used with +\fIwaitid\fR(). +.P +The type +.BR idtype_t +shall be defined as an enumeration type whose possible values shall +include at least the following: +P_ALL +P_PGID +P_PID +.P +The +.IR +header shall define the +.BR id_t +and +.BR pid_t +types as described in +.IR . +.P +The +.IR +header shall define the +.BR siginfo_t +type as described in +.IR . +.P +Inclusion of the +.IR +header may also make visible +all symbols from +.IR . +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +pid_t wait(int *); +int waitid(idtype_t, id_t, siginfo_t *, int); +pid_t waitpid(pid_t, int *, int); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIwait\fR\^(\|)", +.IR "\fIwaitid\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/syslog.h.0p b/man-pages-posix-2013/man0p/syslog.h.0p new file mode 100644 index 0000000..8793f9d --- /dev/null +++ b/man-pages-posix-2013/man0p/syslog.h.0p @@ -0,0 +1,158 @@ +'\" et +.TH syslog.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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.h +\(em definitions for system error logging +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following symbolic constants, zero or more +of which may be OR'ed together to form the +.IR logopt +option of +\fIopenlog\fR(): +.IP LOG_PID 14 +Log the process ID with each message. +.IP LOG_CONS 14 +Log to the system console on error. +.IP LOG_NDELAY 14 +Connect to syslog daemon immediately. +.IP LOG_ODELAY 14 +Delay open until +\fIsyslog\fR() +is called. +.IP LOG_NOWAIT 14 +Do not wait for child processes. +.P +The +.IR +header shall define the following symbolic constants for use as the +.IR facility +argument to +\fIopenlog\fR(): +.IP LOG_KERN 14 +Reserved for message generated by the system. +.IP LOG_USER 14 +Message generated by a process. +.IP LOG_MAIL 14 +Reserved for message generated by mail system. +.IP LOG_NEWS 14 +Reserved for message generated by news system. +.IP LOG_UUCP 14 +Reserved for message generated by UUCP system. +.IP LOG_DAEMON 14 +Reserved for message generated by system daemon. +.IP LOG_AUTH 14 +Reserved for message generated by authorization daemon. +.IP LOG_CRON 14 +Reserved for message generated by clock daemon. +.IP LOG_LPR 14 +Reserved for message generated by printer system. +.IP LOG_LOCAL0 14 +Reserved for local use. +.IP LOG_LOCAL1 14 +Reserved for local use. +.IP LOG_LOCAL2 14 +Reserved for local use. +.IP LOG_LOCAL3 14 +Reserved for local use. +.IP LOG_LOCAL4 14 +Reserved for local use. +.IP LOG_LOCAL5 14 +Reserved for local use. +.IP LOG_LOCAL6 14 +Reserved for local use. +.IP LOG_LOCAL7 14 +Reserved for local use. +.P +The +.IR +header shall define the following macros for constructing the +.IR maskpri +argument to +\fIsetlogmask\fR(). +The following macros expand to an expression of type +.BR int +when the argument +.IR pri +is an expression of type +.BR int : +.IP "LOG_MASK(\fIpri\fR)" 14 +A mask for priority +.IR pri . +.P +The +.IR +header shall define the following symbolic constants for use as the +.IR priority +argument of +\fIsyslog\fR(): +.IP LOG_EMERG 14 +A panic condition was reported to all processes. +.IP LOG_ALERT 14 +A condition that should be corrected immediately. +.IP LOG_CRIT 14 +A critical condition. +.IP LOG_ERR 14 +An error message. +.IP LOG_WARNING 14 +A warning message. +.IP LOG_NOTICE 14 +A condition requiring special handling. +.IP LOG_INFO 14 +A general information message. +.IP LOG_DEBUG 14 +A message useful for debugging programs. +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +void closelog(void); +void openlog(const char *, int, int); +int setlogmask(int); +void syslog(int, const char *, ...); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIcloselog\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/tar.h.0p b/man-pages-posix-2013/man0p/tar.h.0p new file mode 100644 index 0000000..499fc05 --- /dev/null +++ b/man-pages-posix-2013/man0p/tar.h.0p @@ -0,0 +1,102 @@ +'\" et +.TH tar.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tar.h +\(em extended tar definitions +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the following symbolic constants with the +indicated values. +.P +General definitions: +.TS +center box tab(@); +cB | cB | cB +lw(15) | cf5w(15) | lw(40). +Name@Value@Description +_ +TMAGIC@"ustar"@ustar plus null byte. +TMAGLEN@6@Length of the above. +TVERSION@"00"@00 without a null byte. +TVERSLEN@2@Length of the above. +.TE +.P +.IR Typeflag +field definitions: +.TS +center box tab(@); +cB | cB | cB +lw(15) | cf5w(15) | lw(40). +Name@Value@Description +_ +REGTYPE@'0'@Regular file. +AREGTYPE@'\e0'@Regular file. +LNKTYPE@'1'@Link. +SYMTYPE@'2'@Symbolic link. +CHRTYPE@'3'@Character special. +BLKTYPE@'4'@Block special. +DIRTYPE@'5'@Directory. +FIFOTYPE@'6'@FIFO special. +CONTTYPE@'7'@Reserved. +.TE +.P +\fIMode\fP field bit definitions (octal): +.TS +center box tab(@); +cB | cB | cB +lw(15) | cw(15) | lw(40). +Name@Value@Description +_ +TSUID@04000@Set UID on execution. +TSGID@02000@Set GID on execution. +TSVTX@01000@\*!On directories, restricted deletion flag.\0\0\0\*? +TUREAD@00400@Read by owner. +TUWRITE@00200@Write by owner special. +TUEXEC@00100@Execute/search by owner. +TGREAD@00040@Read by group. +TGWRITE@00020@Write by group. +TGEXEC@00010@Execute/search by group. +TOREAD@00004@Read by other. +TOWRITE@00002@Write by other. +TOEXEC@00001@Execute/search by other. +.TE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIpax\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/termios.h.0p b/man-pages-posix-2013/man0p/termios.h.0p new file mode 100644 index 0000000..a76d631 --- /dev/null +++ b/man-pages-posix-2013/man0p/termios.h.0p @@ -0,0 +1,457 @@ +'\" et +.TH termios.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +termios.h +\(em define values for termios +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall contain the definitions used by the terminal I/O +interfaces (see +.IR "Chapter 11" ", " "General Terminal Interface" +for the structures and names defined). +.SS "The termios Structure" +.P +The +.IR +header shall define the following data types through +.BR typedef : +.IP "\fBcc_t\fP" 12 +Used for terminal special characters. +.IP "\fBspeed_t\fP" 12 +Used for terminal baud rates. +.IP "\fBtcflag_t\fP" 12 +Used for terminal modes. +.P +The above types shall be all unsigned integer types. +.P +The implementation shall support one or more programming environments +in which the widths of +.BR cc_t , +.BR speed_t , +and +.BR tcflag_t +are no greater than the width of type +.BR long . +The names of these programming environments can be obtained using the +\fIconfstr\fR() +function or the +.IR getconf +utility. +.P +The +.IR +header shall define the +.BR termios +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +tcflag_t c_iflag \fRInput modes.\fR +tcflag_t c_oflag \fROutput modes.\fR +tcflag_t c_cflag \fRControl modes.\fR +tcflag_t c_lflag \fRLocal modes.\fR +cc_t c_cc[NCCS] \fRControl characters.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the following symbolic constant: +.IP NCCS 12 +Size of the array +.IR c_cc +for control characters. +.P +The +.IR +header shall define the following symbolic constants for use as +subscripts for the array +.IR c_cc : +.TS +box center tab(!); +cb s | l +cb cb | cb +l | l | l. +Subscript Usage +Canonical Mode!Non-Canonical Mode!Description +_ +VEOF!!EOF character. +VEOL!!EOL character. +VERASE!!ERASE character. +VINTR!VINTR!INTR character. +VKILL!!KILL character. +\&!VMIN!MIN value. +VQUIT!VQUIT!QUIT character. +VSTART!VSTART!START character. +VSTOP!VSTOP!STOP character. +VSUSP!VSUSP!SUSP character. +\&!VTIME!TIME value. +.TE +.P +The subscript values shall be suitable for use in +.BR #if +preprocessing directives and shall be distinct, except that the VMIN +and VTIME subscripts may have the same values as the VEOF and +VEOL subscripts, respectively. +.SS "Input Modes" +.P +The +.IR +header shall define the following symbolic constants for use as flags +in the +.IR c_iflag +field. The +.IR c_iflag +field describes the basic terminal input control. +.IP BRKINT 12 +Signal interrupt on break. +.IP ICRNL 12 +Map CR to NL on input. +.IP IGNBRK 12 +Ignore break condition. +.IP IGNCR 12 +Ignore CR. +.IP IGNPAR 12 +Ignore characters with parity errors. +.IP INLCR 12 +Map NL to CR on input. +.IP INPCK 12 +Enable input parity check. +.IP ISTRIP 12 +Strip character. +.IP IXANY 12 +Enable any character to restart output. +.IP IXOFF 12 +Enable start/stop input control. +.IP IXON 12 +Enable start/stop output control. +.IP PARMRK 12 +Mark parity errors. +.SS "Output Modes" +.P +The +.IR +header shall define the following symbolic constants for use as flags +in the +.IR c_oflag +field. The +.IR c_oflag +field specifies the system treatment of output. +.IP OPOST 12 +Post-process output. +.IP ONLCR 12 +Map NL to CR-NL on output. +.IP OCRNL 12 +Map CR to NL on output. +.IP ONOCR 12 +No CR output at column 0. +.IP ONLRET 12 +NL performs CR function. +.IP OFDEL 12 +Fill is DEL. +.IP OFILL 12 +Use fill characters for delay. +.IP NLDLY 12 +Select newline delays: +.RS 12 +.IP NL0 8 +Newline type 0. +.IP NL1 8 +Newline type 1. +.RE +.IP CRDLY 12 +Select carriage-return delays: +.RS 12 +.IP CR0 8 +Carriage-return delay type 0. +.IP CR1 8 +Carriage-return delay type 1. +.IP CR2 8 +Carriage-return delay type 2. +.IP CR3 8 +Carriage-return delay type 3. +.RE +.IP TABDLY 12 +Select horizontal-tab delays: +.RS 12 +.IP TAB0 8 +Horizontal-tab delay type 0. +.IP TAB1 8 +Horizontal-tab delay type 1. +.IP TAB2 8 +Horizontal-tab delay type 2. +.IP TAB3 8 +Expand tabs to spaces. +.RE +.IP BSDLY 12 +Select backspace delays: +.RS 12 +.IP BS0 8 +Backspace-delay type 0. +.IP BS1 8 +Backspace-delay type 1. +.RE +.IP VTDLY 12 +Select vertical-tab delays: +.RS 12 +.IP VT0 8 +Vertical-tab delay type 0. +.IP VT1 8 +Vertical-tab delay type 1. +.RE +.IP FFDLY 12 +Select form-feed delays: +.RS 12 +.IP FF0 8 +Form-feed delay type 0. +.IP FF1 8 +Form-feed delay type 1. +.RE +.SS "Baud Rate Selection" +.P +The +.IR +header shall define the following symbolic constants for use as values +of objects of type +.BR speed_t . +.P +The input and output baud rates are stored in the +.BR termios +structure. These are the valid values for objects of type +.BR speed_t . +Not all baud rates need be supported by the underlying hardware. +.IP B0 12 +Hang up +.IP B50 12 +50 baud +.IP B75 12 +75 baud +.IP B110 12 +110 baud +.IP B134 12 +134.5 baud +.IP B150 12 +150 baud +.IP B200 12 +200 baud +.IP B300 12 +300 baud +.IP B600 12 +600 baud +.IP B1200 12 +1\|200 baud +.IP B1800 12 +1\|800 baud +.IP B2400 12 +2\|400 baud +.IP B4800 12 +4\|800 baud +.IP B9600 12 +9\|600 baud +.IP B19200 12 +19\|200 baud +.IP B38400 12 +38\|400 baud +.SS "Control Modes" +.P +The +.IR +header shall define the following symbolic constants for use as flags +in the +.IR c_cflag +field. The +.IR c_cflag +field describes the hardware control of the terminal; not all values +specified are required to be supported by the underlying hardware. +.IP CSIZE 12 +Character size: +.RS 12 +.IP CS5 8 +5 bits +.IP CS6 8 +6 bits +.IP CS7 8 +7 bits +.IP CS8 8 +8 bits +.RE +.IP CSTOPB 12 +Send two stop bits, else one. +.IP CREAD 12 +Enable receiver. +.IP PARENB 12 +Parity enable. +.IP PARODD 12 +Odd parity, else even. +.IP HUPCL 12 +Hang up on last close. +.IP CLOCAL 12 +Ignore modem status lines. +.P +The implementation shall support the functionality associated with the +symbols CS7, CS8, CSTOPB, PARODD, and PARENB. +.SS "Local Modes" +.P +The +.IR +header shall define the following symbolic constants for use as flags +in the +.IR c_lflag +field. The +.IR c_lflag +field of the argument structure is used to control various terminal +functions. +.IP ECHO 12 +Enable echo. +.IP ECHOE 12 +Echo erase character as error-correcting backspace. +.IP ECHOK 12 +Echo KILL. +.IP ECHONL 12 +Echo NL. +.IP ICANON 12 +Canonical input (erase and kill processing). +.IP IEXTEN 12 +Enable extended input character processing. +.IP ISIG 12 +Enable signals. +.IP NOFLSH 12 +Disable flush after interrupt or quit. +.IP TOSTOP 12 +Send SIGTTOU for background output. +.SS "Attribute Selection" +.P +The +.IR +header shall define the following symbolic constants for use with +\fItcsetattr\fR(): +.IP TCSANOW 12 +Change attributes immediately. +.IP TCSADRAIN 12 +Change attributes when output has drained. +.IP TCSAFLUSH 12 +Change attributes when output has drained; also flush pending input. +.SS "Line Control" +.P +The +.IR +header shall define the following symbolic constants for use with +\fItcflush\fR(): +.IP TCIFLUSH 12 +Flush pending input. +.IP TCIOFLUSH 12 +Flush both pending input and untransmitted output. +.IP TCOFLUSH 12 +Flush untransmitted output. +.P +The +.IR +header shall define the following symbolic constants for use with +\fItcflow\fR(): +.IP TCIOFF 12 +Transmit a STOP character, intended to suspend input data. +.IP TCION 12 +Transmit a START character, intended to restart input data. +.IP TCOOFF 12 +Suspend output. +.IP TCOON 12 +Restart output. +.P +The +.IR +header shall define the +.BR pid_t +type as described in +.IR . +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +speed_t cfgetispeed(const struct termios *); +speed_t cfgetospeed(const struct termios *); +int cfsetispeed(struct termios *, speed_t); +int cfsetospeed(struct termios *, speed_t); +int tcdrain(int); +int tcflow(int, int); +int tcflush(int, int); +int tcgetattr(int, struct termios *); +pid_t tcgetsid(int); +int tcsendbreak(int, int); +int tcsetattr(int, int, const struct termios *); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The following names are reserved for XSI-conformant systems to use as +an extension to the above; therefore strictly conforming applications +shall not use them: +.TS +tab(@); +le le le. +CBAUD@EXTB@VDSUSP +DEFECHO@FLUSHO@VLNEXT +ECHOCTL@LOBLK@VREPRINT +ECHOKE@PENDIN@VSTATUS +ECHOPRT@SWTCH@VWERASE +EXTA@VDISCARD +.TE +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIcfgetispeed\fR\^(\|)", +.IR "\fIcfgetospeed\fR\^(\|)", +.IR "\fIcfsetispeed\fR\^(\|)", +.IR "\fIcfsetospeed\fR\^(\|)", +.IR "\fIconfstr\fR\^(\|)", +.IR "\fItcdrain\fR\^(\|)", +.IR "\fItcflow\fR\^(\|)", +.IR "\fItcflush\fR\^(\|)", +.IR "\fItcgetattr\fR\^(\|)", +.IR "\fItcgetsid\fR\^(\|)", +.IR "\fItcsendbreak\fR\^(\|)", +.IR "\fItcsetattr\fR\^(\|)" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "\fIgetconf\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/tgmath.h.0p b/man-pages-posix-2013/man0p/tgmath.h.0p new file mode 100644 index 0000000..8ebfa52 --- /dev/null +++ b/man-pages-posix-2013/man0p/tgmath.h.0p @@ -0,0 +1,396 @@ +'\" et +.TH tgmath.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tgmath.h +\(em type-generic macros +.SH SYNOPSIS +.LP +.nf +#include +.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\(hy2008 defers to the ISO\ C standard. +.P +The +.IR +header shall include the headers +.IR +and +.IR +and shall define several type-generic macros. +.P +Of the functions contained within the +.IR +and +.IR +headers without an +.IR f +(\c +.BR float ) +or +.IR l +(\c +.BR "long double" ) +suffix, several have one or more parameters whose corresponding real +type is +.BR double . +For each such function, except +\fImodf\fR(), +\fIj0\fR(), +\fIj1\fR(), +\fIjn\fR(), +\fIy0\fR(), +\fIy1\fR(), +and +\fIyn\fR(), +there shall be a corresponding type-generic macro. The parameters +whose corresponding real type is +.BR double +in the function synopsis are generic parameters. Use of the macro +invokes a function whose corresponding real type and type domain are +determined by the arguments for the generic parameters. +.P +Use of the macro invokes a function whose generic parameters have the +corresponding real type determined as follows: +.IP " *" 4 +First, if any argument for generic parameters has type +.BR "long double" , +the type determined is +.BR "long double" . +.IP " *" 4 +Otherwise, if any argument for generic parameters has type +.BR double +or is of integer type, the type determined is +.BR double . +.IP " *" 4 +Otherwise, the type determined is +.BR float . +.P +For each unsuffixed function in the +.IR +header for which there is a function in the +.IR +header with the same name except for a +.IR c +prefix, the corresponding type-generic macro (for both functions) has +the same name as the function in the +.IR +header. The corresponding type-generic macro for +\fIfabs\fR() +and +\fIcabs\fR() +is +\fIfabs\fR(). +.TS +center box tab(!); +cB | cB | cB +l | l | l. + Function! Function!Type-Generic Macro +_ +\fIacos\fR\^(\|)!\fIcacos\fR\^(\|)!\fIacos\fR\^(\|) +\fIasin\fR\^(\|)!\fIcasin\fR\^(\|)!\fIasin\fR\^(\|) +\fIatan\fR\^(\|)!\fIcatan\fR\^(\|)!\fIatan\fR\^(\|) +\fIacosh\fR\^(\|)!\fIcacosh\fR\^(\|)!\fIacosh\fR\^(\|) +\fIasinh\fR\^(\|)!\fIcasinh\fR\^(\|)!\fIasinh\fR\^(\|) +\fIatanh\fR\^(\|)!\fIcatanh\fR\^(\|)!\fIatanh\fR\^(\|) +\fIcos\fR\^(\|)!\fIccos\fR\^(\|)!\fIcos\fR\^(\|) +\fIsin\fR\^(\|)!\fIcsin\fR\^(\|)!\fIsin\fR\^(\|) +\fItan\fR\^(\|)!\fIctan\fR\^(\|)!\fItan\fR\^(\|) +\fIcosh\fR\^(\|)!\fIccosh\fR\^(\|)!\fIcosh\fR\^(\|) +\fIsinh\fR\^(\|)!\fIcsinh\fR\^(\|)!\fIsinh\fR\^(\|) +\fItanh\fR\^(\|)!\fIctanh\fR\^(\|)!\fItanh\fR\^(\|) +\fIexp\fR\^(\|)!\fIcexp\fR\^(\|)!\fIexp\fR\^(\|) +\fIlog\fR\^(\|)!\fIclog\fR\^(\|)!\fIlog\fR\^(\|) +\fIpow\fR\^(\|)!\fIcpow\fR\^(\|)!\fIpow\fR\^(\|) +\fIsqrt\fR\^(\|)!\fIcsqrt\fR\^(\|)!\fIsqrt\fR\^(\|) +\fIfabs\fR\^(\|)!\fIcabs\fR\^(\|)!\fIfabs\fR\^(\|) +.TE +.P +If at least one argument for a generic parameter is complex, then use +of the macro invokes a complex function; otherwise, use of the macro +invokes a real function. +.P +For each unsuffixed function in the +.IR +header without a +.IR c -prefixed +counterpart in the +.IR +header, except for +\fImodf\fR(), +\fIj0\fR(), +\fIj1\fR(), +\fIjn\fR(), +\fIy0\fR(), +\fIy1\fR(), +and +\fIyn\fR(), +the corresponding type-generic macro has the same name as the function. +These type-generic macros are: +.sp +.RS +.TS +tab(!); +l l l l. +T{ +.nf +\fIatan2\fR() +\fIcbrt\fR() +\fIceil\fR() +\fIcopysign\fR() +\fIerf\fR() +\fIerfc\fR() +\fIexp2\fR() +\fIexpm1\fR() +\fIfdim\fR() +\fIfloor\fR() +T}!T{ +.nf +\fIfma\fR() +\fIfmax\fR() +\fIfmin\fR() +\fIfmod\fR() +\fIfrexp\fR() +\fIhypot\fR() +\fIilogb\fR() +\fIldexp\fR() +\fIlgamma\fR() +\fIllrint\fR() +T}!T{ +.nf +\fIllround\fR() +\fIlog10\fR() +\fIlog1p\fR() +\fIlog2\fR() +\fIlogb\fR() +\fIlrint\fR() +\fIlround\fR() +\fInearbyint\fR() +\fInextafter\fR() +\fInexttoward\fR() +T}!T{ +.nf +\fIremainder\fR() +\fIremquo\fR() +\fIrint\fR() +\fIround\fR() +\fIscalbln\fR() +\fIscalbn\fR() +\fItgamma\fR() +\fItrunc\fR() +.fi +T} +.TE +.RE +.P +If all arguments for generic parameters are real, then use of the macro +invokes a real function; otherwise, use of the macro results in +undefined behavior. +.P +For each unsuffixed function in the +.IR +header that is not a +.IR c -prefixed +counterpart to a function in the +.IR +header, the corresponding type-generic macro has the same name as the +function. These type-generic macros are: +.sp +.RS +\fIcarg\fR() +\fIcimag\fR() +\fIconj\fR() +\fIcproj\fR() +\fIcreal\fR() +.RE +.P +Use of the macro with any real or complex argument invokes a complex +function. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +With the declarations: +.sp +.RS 4 +.nf +\fB +#include +int n; +float f; +double d; +long double ld; +float complex fc; +double complex dc; +long double complex ldc; +.fi \fR +.P +.RE +.P +functions invoked by use of type-generic macros are shown in the +following table: +.TS +center box tab(!); +cB | cB +l | l. +Macro!Use Invokes +_ +\fIexp\fR(\fIn\fR)!\fIexp\fR(\fIn\fR), the function +\fIacosh\fR(\fIf\fR)!\fIacoshf\fR(\fIf\fR) +\fIsin\fR(\fId\fR)!\fIsin\fR(\fId\fR), the function +\fIatan\fR(\fIld\fR)!\fIatanl\fR(\fIld\fR) +\fIlog\fR(\fIfc\fR)!\fIclogf\fR(\fIfc\fR) +\fIsqrt\fR(\fIdc\fR)!\fIcsqrt\fR(\fIdc\fR) +\fIpow\fR(\fIldc,f\fR)!\fIcpowl\fR(\fIldc, f\fR) +\fIremainder\fR(\fIn,n\fR)!\fIremainder\fR(\fIn, n\fR), the function +\fInextafter\fR(\fId,f\fR)!\fInextafter\fR(\fId, f\fR), the function +\fInexttoward\fR(\fIf,ld\fR)!\fInexttowardf\fR(\fIf, ld\fR) +\fIcopysign\fR(\fIn,ld\fR)!\fIcopysignl\fR(\fIn, ld\fR) +\fIceil\fR(\fIfc\fR)!Undefined behavior +\fIrint\fR(\fIdc\fR)!Undefined behavior +\fIfmax\fR(\fIldc,ld\fR)!Undefined behavior +\fIcarg\fR(\fIn\fR)!\fIcarg\fR(\fIn\fR), the function +\fIcproj\fR(\fIf\fR)!\fIcprojf\fR(\fIf\fR) +\fIcreal\fR(\fId\fR)!\fIcreal\fR(\fId\fR), the function +\fIcimag\fR(\fIld\fR)!\fIcimagl\fR(\fIld\fR) +\fIcabs\fR(\fIfc\fR)!\fIcabsf\fR(\fIfc\fR) +\fIcarg\fR(\fIdc\fR)!\fIcarg\fR(\fIdc\fR), the function +\fIcproj\fR(\fIldc\fR)!\fIcprojl\fR(\fIldc\fR) +.TE +.SH RATIONALE +Type-generic macros allow calling a function whose type is determined +by the argument type, as is the case for C operators such as +.BR '+' +and +.BR '*' . +For example, with a type-generic +\fIcos\fR() +macro, the expression +.IR cos ((\c +.BR float )\c +.IR x ) +will have type +.BR float . +This feature enables writing more portably efficient code and +alleviates need for awkward casting and suffixing in the process of +porting or adjusting precision. Generic math functions are a widely +appreciated feature of Fortran. +.P +The only arguments that affect the type resolution are the arguments +corresponding to the parameters that have type +.BR double +in the synopsis. Hence the type of a type-generic call to +\fInexttoward\fR(), +whose second parameter is +.BR "long double" +in the synopsis, is determined solely by the type of the first +argument. +.P +The term ``type-generic'' was chosen over the proposed alternatives of +intrinsic and overloading. The term is more specific than intrinsic, +which already is widely used with a more general meaning, and reflects +a closer match to Fortran's generic functions than to C++ overloading. +.P +The macros are placed in their own header in order not to silently +break old programs that include the +.IR +header; for example, with: +.sp +.RS 4 +.nf +\fB +printf ("%e", sin(x)) +.fi \fR +.P +.RE +.P +.IR modf (\c +.BR double , +.BR "double *" ) +is excluded because no way was seen to make it safe without +complicating the type resolution. +.P +The implementation might, as an extension, endow appropriate ones of +the macros that POSIX.1\(hy2008 specifies only for real arguments with the +ability to invoke the complex functions. +.P +POSIX.1\(hy2008 does not prescribe any particular implementation mechanism +for generic macros. It could be implemented simply with built-in +macros. The generic macro for +\fIsqrt\fR(), +for example, could be implemented with: +.sp +.RS 4 +.nf +\fB +#undef sqrt +#define sqrt(x) __BUILTIN_GENERIC_sqrt(x) +.fi \fR +.P +.RE +.P +Generic macros are designed for a useful level of consistency with C++ +overloaded math functions. +.P +The great majority of existing C programs are expected to be unaffected +when the +.IR +header is included instead of the +.IR +or +.IR +headers. Generic macros are similar to the ISO/IEC\ 9899:\|1999 standard library masking +macros, though the semantic types of return values differ. +.P +The ability to overload on integer as well as floating types would have +been useful for some functions; for example, +\fIcopysign\fR(). +Overloading with different numbers of arguments would have allowed +reusing names; for example, +\fIremainder\fR() +for +\fIremquo\fR(). +However, these facilities would have complicated the specification; and +their natural consistent use, such as for a floating +\fIabs\fR() +or a two-argument +\fIatan\fR(), +would have introduced further inconsistencies with the ISO/IEC\ 9899:\|1999 standard for +insufficient benefit. +.P +The ISO\ C standard in no way limits the implementation's options for efficiency, +including inlining library functions. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIcabs\fR\^(\|)", +.IR "\fIfabs\fR\^(\|)", +.IR "\fImodf\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/time.h.0p b/man-pages-posix-2013/man0p/time.h.0p new file mode 100644 index 0000000..81f63b6 --- /dev/null +++ b/man-pages-posix-2013/man0p/time.h.0p @@ -0,0 +1,331 @@ +'\" et +.TH time.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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.h +\(em time types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends the +ISO\ C standard. Applications shall define the appropriate feature test macro +(see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment") +to enable the visibility of these symbols in this header. +.P +The +.IR +header shall define the +.BR clock_t , +.BR size_t , +.BR time_t , +types as described in +.IR . +.P +The +.IR +header shall define the +.BR clockid_t +and +.BR timer_t +types as described in +.IR . +.P +The +.IR +header shall define the +.BR locale_t +type as described in +.IR . +.P +The +.IR +header shall define the +.BR pid_t +type as described in +.IR . +.P +The tag +.BR sigevent +shall be declared as naming an incomplete structure type, the contents +of which are described in the +.IR +header. +.P +The +.IR +header shall declare the +.BR tm +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +int tm_sec \fRSeconds [0,60].\fR +int tm_min \fRMinutes [0,59].\fR +int tm_hour \fRHour [0,23].\fR +int tm_mday \fRDay of month [1,31].\fR +int tm_mon \fRMonth of year [0,11].\fR +int tm_year \fRYears since 1900.\fR +int tm_wday \fRDay of week [0,6] (Sunday =0).\fR +int tm_yday \fRDay of year [0,365].\fR +int tm_isdst \fRDaylight Savings flag.\fR +.fi \fR +.P +.RE +.P +The value of +.IR tm_isdst +shall be positive if Daylight Savings Time is in effect, 0 if Daylight +Savings Time is not in effect, and negative if the information is not +available. +.P +The +.IR +header shall declare the +.BR timespec +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +time_t tv_sec \fRSeconds.\fR +long tv_nsec \fRNanoseconds.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall also declare the +.BR itimerspec +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +struct timespec it_interval \fRTimer period.\fR +struct timespec it_value \fRTimer expiration.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the following macros: +.IP NULL 14 +As described in +.IR . +.IP CLOCKS_PER_SEC 14 +A number used to convert the value returned by the +\fIclock\fR() +function into seconds. The value shall be an expression with type +.BR clock_t . +The value of CLOCKS_PER_SEC shall be 1 million +on XSI-conformant systems. However, it may be variable on other systems, +and it should not be assumed that CLOCKS_PER_SEC is a compile-time +constant. +.P +The +.IR +header shall define the following symbolic constants. The values shall +have a type that is assignment-compatible with +.BR clockid_t . +.IP CLOCK_MONOTONIC 14 +.br +The identifier for the system-wide monotonic clock, which is defined as +a clock measuring real time, whose value cannot be set via +\fIclock_settime\fR() +and which cannot have negative clock jumps. The maximum possible clock +jump shall be implementation-defined. +.IP CLOCK_PROCESS_CPUTIME_ID 14 +.br +The identifier of the CPU-time clock associated with the process +making a +\fIclock\fR() +or +.IR timer* (\|) +function call. +.IP CLOCK_REALTIME 14 +The identifier of the system-wide clock measuring real time. +.IP CLOCK_THREAD_CPUTIME_ID 14 +.br +The identifier of the CPU-time clock associated with the thread making a +\fIclock\fR() +or +.IR timer* (\|) +function call. +.P +The +.IR +header shall define the following symbolic constant: +.IP TIMER_ABSTIME 14 +Flag indicating time is absolute. For functions taking timer objects, +this refers to the clock associated with the timer. +.P +The +.IR +header shall provide a declaration or definition for +.IR getdate_err . +The +.IR getdate_err +symbol shall expand to an expression of type +.BR int . +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 +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +char *asctime(const struct tm *); +char *asctime_r(const struct tm *restrict, char *restrict); +clock_t clock(void); +int clock_getcpuclockid(pid_t, clockid_t *); +int clock_getres(clockid_t, struct timespec *); +int clock_gettime(clockid_t, struct timespec *); +int clock_nanosleep(clockid_t, int, const struct timespec *, + struct timespec *); +int clock_settime(clockid_t, const struct timespec *); +char *ctime(const time_t *); +char *ctime_r(const time_t *, char *); +double difftime(time_t, time_t); +struct tm *getdate(const char *); +struct tm *gmtime(const time_t *); +struct tm *gmtime_r(const time_t *restrict, struct tm *restrict); +struct tm *localtime(const time_t *); +struct tm *localtime_r(const time_t *restrict, struct tm *restrict); +time_t mktime(struct tm *); +int nanosleep(const struct timespec *, struct timespec *); +size_t strftime(char *restrict, size_t, const char *restrict, + const struct tm *restrict); +size_t strftime_l(char *restrict, size_t, const char *restrict, + const struct tm *restrict, locale_t); +char *strptime(const char *restrict, const char *restrict, + struct tm *restrict); +time_t time(time_t *); +int timer_create(clockid_t, struct sigevent *restrict, + timer_t *restrict); +int timer_delete(timer_t); +int timer_getoverrun(timer_t); +int timer_gettime(timer_t, struct itimerspec *); +int timer_settime(timer_t, int, const struct itimerspec *restrict, + struct itimerspec *restrict); +void tzset(void); +.fi \fR +.P +.RE +.br +.P +The +.IR +header shall declare the following as variables: +.sp +.RS 4 +.nf +\fB +extern int daylight; +extern long timezone; +extern char *tzname[]; +.fi \fR +.P +.RE +.P +Inclusion of the +.IR +header may make visible all symbols from the +.IR +header. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The range [0,60] for +.IR tm_sec +allows for the occasional leap second. +.P +.IR tm_year +is a signed value; therefore, years before 1900 may be represented. +.P +To obtain the number of clock ticks per second returned by the +\fItimes\fR() +function, applications should call +.IR sysconf (_SC_CLK_TCK). +.SH RATIONALE +The range [0,60] seconds allows for positive or negative leap seconds. +The formal definition of UTC does not permit double leap seconds, so +all mention of double leap seconds has been removed, and the range +shortened from the former [0,61] seconds seen in earlier versions of +this standard. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +.ad l +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment", +.IR "\fIasctime\fR\^(\|)", +.IR "\fIclock\fR\^(\|)", +.IR "\fIclock_getcpuclockid\fR\^(\|)", +.IR "\fIclock_getres\fR\^(\|)", +.IR "\fIclock_nanosleep\fR\^(\|)", +.IR "\fIctime\fR\^(\|)", +.IR "\fIdifftime\fR\^(\|)", +.IR "\fIgetdate\fR\^(\|)", +.IR "\fIgmtime\fR\^(\|)", +.IR "\fIlocaltime\fR\^(\|)", +.IR "\fImktime\fR\^(\|)", +.IR "\fImq_receive\fR\^(\|)", +.IR "\fImq_send\fR\^(\|)", +.IR "\fInanosleep\fR\^(\|)", +.IR "\fIpthread_getcpuclockid\fR\^(\|)", +.IR "\fIpthread_mutex_timedlock\fR\^(\|)", +.IR "\fIpthread_rwlock_timedrdlock\fR\^(\|)", +.IR "\fIpthread_rwlock_timedwrlock\fR\^(\|)", +.IR "\fIsem_timedwait\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)", +.IR "\fIstrptime\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fItimer_create\fR\^(\|)", +.IR "\fItimer_delete\fR\^(\|)", +.IR "\fItimer_getoverrun\fR\^(\|)", +.IR "\fItzset\fR\^(\|)", +.IR "\fIutime\fR\^(\|)" +.ad b +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/trace.h.0p b/man-pages-posix-2013/man0p/trace.h.0p new file mode 100644 index 0000000..4e0555f --- /dev/null +++ b/man-pages-posix-2013/man0p/trace.h.0p @@ -0,0 +1,236 @@ +'\" et +.TH trace.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +trace.h +\(em tracing +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR posix_trace_event_info +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +trace_event_id_t posix_event_id +pid_t posix_pid +void *posix_prog_address +pthread_t posix_thread_id +struct timespec posix_timestamp +int posix_truncation_status +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR posix_trace_status_info +structure, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +int posix_stream_full_status +int posix_stream_overrun_status +int posix_stream_status +int posix_log_full_status +int posix_log_overrun_status +int posix_stream_flush_error +int posix_stream_flush_status +.fi \fR +.P +.RE +.P +The +.IR +header shall define the following symbolic constants: +.P +.nf +POSIX_TRACE_ALL_EVENTS +POSIX_TRACE_APPEND +POSIX_TRACE_CLOSE_FOR_CHILD +POSIX_TRACE_FILTER +POSIX_TRACE_FLUSH +POSIX_TRACE_FLUSH_START +POSIX_TRACE_FLUSH_STOP +POSIX_TRACE_FLUSHING +POSIX_TRACE_FULL +POSIX_TRACE_LOOP +POSIX_TRACE_NO_OVERRUN +POSIX_TRACE_NOT_FLUSHING +POSIX_TRACE_NOT_FULL +POSIX_TRACE_INHERITED +POSIX_TRACE_NOT_TRUNCATED +POSIX_TRACE_OVERFLOW +POSIX_TRACE_OVERRUN +POSIX_TRACE_RESUME +POSIX_TRACE_RUNNING +POSIX_TRACE_START +POSIX_TRACE_STOP +POSIX_TRACE_SUSPENDED +POSIX_TRACE_SYSTEM_EVENTS +POSIX_TRACE_TRUNCATED_READ +POSIX_TRACE_TRUNCATED_RECORD +POSIX_TRACE_UNNAMED_USER_EVENT +POSIX_TRACE_UNTIL_FULL +POSIX_TRACE_WOPID_EVENTS +.fi +.P +The +.IR +header shall define the +.BR size_t , +.BR trace_attr_t , +.BR trace_event_id_t , +.BR trace_event_set_t , +and +.BR trace_id_t +types as described in +.IR . +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int posix_trace_attr_destroy(trace_attr_t *); +int posix_trace_attr_getclockres(const trace_attr_t *, + struct timespec *); +int posix_trace_attr_getcreatetime(const trace_attr_t *, + struct timespec *); +int posix_trace_attr_getgenversion(const trace_attr_t *, char *); +int posix_trace_attr_getinherited(const trace_attr_t *restrict, + int *restrict); +int posix_trace_attr_getlogfullpolicy(const trace_attr_t *restrict, + int *restrict); +int posix_trace_attr_getlogsize(const trace_attr_t *restrict, + size_t *restrict); +int posix_trace_attr_getmaxdatasize(const trace_attr_t *restrict, + size_t *restrict); +int posix_trace_attr_getmaxsystemeventsize(const trace_attr_t *restrict, + size_t *restrict); +int posix_trace_attr_getmaxusereventsize(const trace_attr_t *restrict, + size_t, size_t *restrict); +int posix_trace_attr_getname(const trace_attr_t *, char *); +int posix_trace_attr_getstreamfullpolicy(const trace_attr_t *restrict, + int *restrict); +int posix_trace_attr_getstreamsize(const trace_attr_t *restrict, + size_t *restrict); +int posix_trace_attr_init(trace_attr_t *); +int posix_trace_attr_setinherited(trace_attr_t *, int); +int posix_trace_attr_setlogfullpolicy(trace_attr_t *, int); +int posix_trace_attr_setlogsize(trace_attr_t *, size_t); +int posix_trace_attr_setmaxdatasize(trace_attr_t *, size_t); +int posix_trace_attr_setname(trace_attr_t *, const char *); +int posix_trace_attr_setstreamfullpolicy(trace_attr_t *, int); +int posix_trace_attr_setstreamsize(trace_attr_t *, size_t); +int posix_trace_clear(trace_id_t); +int posix_trace_close(trace_id_t); +int posix_trace_create(pid_t, const trace_attr_t *restrict, + trace_id_t *restrict); +int posix_trace_create_withlog(pid_t, const trace_attr_t *restrict, + int, trace_id_t *restrict); +void posix_trace_event(trace_event_id_t, const void *restrict, size_t); +int posix_trace_eventid_equal(trace_id_t, trace_event_id_t, + trace_event_id_t); +int posix_trace_eventid_get_name(trace_id_t, trace_event_id_t, char *); +int posix_trace_eventid_open(const char *restrict, + trace_event_id_t *restrict); +int posix_trace_eventset_add(trace_event_id_t, trace_event_set_t *); +int posix_trace_eventset_del(trace_event_id_t, trace_event_set_t *); +int posix_trace_eventset_empty(trace_event_set_t *); +int posix_trace_eventset_fill(trace_event_set_t *, int); +int posix_trace_eventset_ismember(trace_event_id_t, + const trace_event_set_t *restrict, int *restrict); +int posix_trace_eventtypelist_getnext_id(trace_id_t, + trace_event_id_t *restrict, int *restrict); +int posix_trace_eventtypelist_rewind(trace_id_t); +int posix_trace_flush(trace_id_t); +int posix_trace_get_attr(trace_id_t, trace_attr_t *); +int posix_trace_get_filter(trace_id_t, trace_event_set_t *); +int posix_trace_get_status(trace_id_t, + struct posix_trace_status_info *); +int posix_trace_getnext_event(trace_id_t, + struct posix_trace_event_info *restrict, void *restrict, + size_t, size_t *restrict, int *restrict); +int posix_trace_open(int, trace_id_t *); +int posix_trace_rewind(trace_id_t); +int posix_trace_set_filter(trace_id_t, const trace_event_set_t *, int); +int posix_trace_shutdown(trace_id_t); +int posix_trace_start(trace_id_t); +int posix_trace_stop(trace_id_t); +int posix_trace_timedgetnext_event(trace_id_t, + struct posix_trace_event_info *restrict, void *restrict, + size_t, size_t *restrict, int *restrict, + const struct timespec *restrict); +int posix_trace_trid_eventid_open(trace_id_t, const char *restrict, + trace_event_id_t *restrict); +int posix_trace_trygetnext_event(trace_id_t, + struct posix_trace_event_info *restrict, void *restrict, size_t, + size_t *restrict, int *restrict); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +.IR +header may be removed in a future version. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +.ad l +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.11" ", " "Tracing", +.IR "\fIposix_trace_attr_destroy\fR\^(\|)", +.IR "\fIposix_trace_attr_getclockres\fR\^(\|)", +.IR "\fIposix_trace_attr_getinherited\fR\^(\|)", +.IR "\fIposix_trace_attr_getlogsize\fR\^(\|)", +.IR "\fIposix_trace_clear\fR\^(\|)", +.IR "\fIposix_trace_close\fR\^(\|)", +.IR "\fIposix_trace_create\fR\^(\|)", +.IR "\fIposix_trace_event\fR\^(\|)", +.IR "\fIposix_trace_eventid_equal\fR\^(\|)", +.IR "\fIposix_trace_eventset_add\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\^(\|)" +.ad b +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/ulimit.h.0p b/man-pages-posix-2013/man0p/ulimit.h.0p new file mode 100644 index 0000000..284107b --- /dev/null +++ b/man-pages-posix-2013/man0p/ulimit.h.0p @@ -0,0 +1,68 @@ +'\" et +.TH ulimit.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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.h +\(em ulimit commands +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the symbolic constants used by the +\fIulimit\fR() +function. +.P +Symbolic constants: +.IP UL_GETFSIZE 12 +Get maximum file size. +.IP UL_SETFSIZE 12 +Set maximum file size. +.P +The following shall be declared as a function and may also be defined +as a macro. A function prototype shall be provided. +.sp +.RS 4 +.nf +\fB +long ulimit(int, ...); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +See +\fIulimit\fR(). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIulimit\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/unistd.h.0p b/man-pages-posix-2013/man0p/unistd.h.0p new file mode 100644 index 0000000..a2a9b7c --- /dev/null +++ b/man-pages-posix-2013/man0p/unistd.h.0p @@ -0,0 +1,1621 @@ +'\" et +.TH unistd.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +unistd.h +\(em standard symbolic constants and types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header defines miscellaneous symbolic constants and types, and declares +miscellaneous functions. The actual values of the constants are +unspecified except as shown. The contents of this header are shown +below. +.SS "Version Test Macros" +.P +The +.IR +header shall define the following symbolic constants. The values shall +be suitable for use in +.BR #if +preprocessing directives. +.IP _POSIX_VERSION 6 +.br +Integer value indicating version of this standard (C-language +binding) to which the implementation conforms. For implementations +conforming to POSIX.1\(hy2008, the value shall be 200809L. +.IP _POSIX2_VERSION 6 +.br +Integer value indicating version of the Shell and Utilities volume of POSIX.1 to which the implementation +conforms. For implementations conforming to POSIX.1\(hy2008, the value shall +be 200809L. For profile implementations that define _POSIX_SUBPROFILE +(see +.IR "Section 2.1.5.1" ", " "Subprofiling Considerations") +in +.IR , +POSIX2_VERSION may be left undefined or be defined with the value \(mi1 +to indicate that the Shell and Utilities volume of POSIX.1 is not supported. In this case, a call to +.IR sysconf(_SC_2_VERSION) +shall return either 200809L or \(mi1 indicating that the Shell and Utilities volume of POSIX.1 is or is +not, respectively, supported at runtime. +.P +The +.IR +header shall define the following symbolic constant only if +the implementation supports the XSI option; see +.IR "Section 2.1.4" ", " "XSI Conformance". +If defined, its value shall be suitable for use in +.BR #if +preprocessing directives. +.IP _XOPEN_VERSION 6 +.br +Integer value indicating version of the X/Open Portability Guide +to which the implementation conforms. The value shall be 700. +.SS "Constants for Options and Option Groups" +.P +The following symbolic constants, if defined in +.IR , +shall have a value of \(mi1, 0, or greater, unless otherwise specified +below. For profile implementations that define _POSIX_SUBPROFILE (see +.IR "Section 2.1.5.1" ", " "Subprofiling Considerations") +in +.IR , +constants described below as always having a value greater than zero need +not be defined and, if defined, may have a value of \(mi1, 0, or greater. +The values shall be suitable for use in +.BR #if +preprocessing directives. +.P +If a symbolic constant is not defined or is defined with the value +\(mi1, the option is not supported for compilation. If it is defined +with a value greater than zero, the option shall always be supported +when the application is executed. If it is defined with the value zero, +the option shall be supported for compilation and might or might not be +supported at runtime. See +.IR "Section 2.1.6" ", " "Options" +for further information about the conformance requirements of these +three categories of support. +.IP _POSIX_ADVISORY_INFO 6 +.br +The implementation supports the Advisory Information option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_ASYNCHRONOUS_IO 6 +.br +The implementation supports asynchronous input and output. +This symbol shall always be set to the value 200809L. +.IP _POSIX_BARRIERS 6 +.br +The implementation supports barriers. +This symbol shall always be set to the value 200809L. +.IP _POSIX_CHOWN_RESTRICTED 6 +.br +The use of +\fIchown\fR() +and +\fIfchown\fR() +is restricted to a process with appropriate privileges, and to changing +the group ID of a file only to the effective group ID of the process or +to one of its supplementary group IDs. This symbol shall be defined +with a value other than \(mi1. +.IP _POSIX_CLOCK_SELECTION 6 +.br +The implementation supports clock selection. +This symbol shall always be set to the value 200809L. +.IP _POSIX_CPUTIME 6 +.br +The implementation supports the Process CPU-Time Clocks option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_FSYNC 6 +.br +The implementation supports the File Synchronization option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_IPV6 6 +.br +The implementation supports the IPv6 option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_JOB_CONTROL 6 +.br +The implementation supports job control. This symbol shall always be +set to a value greater than zero. +.IP _POSIX_MAPPED_FILES 6 +.br +The implementation supports memory mapped Files. +This symbol shall always be set to the value 200809L. +.IP _POSIX_MEMLOCK 6 +.br +The implementation supports the Process Memory Locking option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_MEMLOCK_RANGE 6 +.br +The implementation supports the Range Memory Locking option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_MEMORY_PROTECTION 6 +.br +The implementation supports memory protection. +This symbol shall always be set to the value 200809L. +.IP _POSIX_MESSAGE_PASSING 6 +.br +The implementation supports the Message Passing option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_MONOTONIC_CLOCK 6 +.br +The implementation supports the Monotonic Clock option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_NO_TRUNC 6 +.br +Pathname components longer than +{NAME_MAX} +generate an error. This symbol shall be defined with a value +other than \(mi1. +.IP _POSIX_PRIORITIZED_IO 6 +.br +The implementation supports the Prioritized Input and Output option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_PRIORITY_SCHEDULING 6 +.br +The implementation supports the Process Scheduling option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_RAW_SOCKETS 6 +.br +The implementation supports the Raw Sockets option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_READER_WRITER_LOCKS 6 +.br +The implementation supports read-write locks. +This symbol shall always be set to the value 200809L. +.IP _POSIX_REALTIME_SIGNALS 6 +.br +The implementation supports realtime signals. +This symbol shall always be set to the value 200809L. +.IP _POSIX_REGEXP 6 +.br +The implementation supports the Regular Expression Handling option. +This symbol shall always be set to a value greater than zero. +.IP _POSIX_SAVED_IDS 6 +.br +Each process has a saved set-user-ID and a saved set-group-ID. +This symbol shall always be set to a value greater than zero. +.IP _POSIX_SEMAPHORES 6 +.br +The implementation supports semaphores. +This symbol shall always be set to the value 200809L. +.IP _POSIX_SHARED_MEMORY_OBJECTS 6 +.br +The implementation supports the Shared Memory Objects option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_SHELL 6 +.br +The implementation supports the POSIX shell. This symbol shall always +be set to a value greater than zero. +.IP _POSIX_SPAWN 6 +.br +The implementation supports the Spawn option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_SPIN_LOCKS 6 +.br +The implementation supports spin locks. +This symbol shall always be set to the value 200809L. +.IP _POSIX_SPORADIC_SERVER 6 +.br +The implementation supports the Process Sporadic Server option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_SYNCHRONIZED_IO 6 +.br +The implementation supports the Synchronized Input and Output option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_THREAD_ATTR_STACKADDR 6 +.br +The implementation supports the Thread Stack Address Attribute option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_THREAD_ATTR_STACKSIZE 6 +.br +The implementation supports the Thread Stack Size Attribute option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_THREAD_CPUTIME 6 +.br +The implementation supports the Thread CPU-Time Clocks option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_THREAD_PRIO_INHERIT 6 +.br +The implementation supports the Non-Robust Mutex Priority +Inheritance option. If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_THREAD_PRIO_PROTECT 6 +.br +The implementation supports the Non-Robust Mutex Priority +Protection option. If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_THREAD_PRIORITY_SCHEDULING 6 +.br +The implementation supports the Thread Execution Scheduling option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_THREAD_PROCESS_SHARED 6 +.br +The implementation supports the Thread Process-Shared Synchronization +option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_THREAD_ROBUST_PRIO_INHERIT 6 +.br +The implementation supports the Robust Mutex Priority Inheritance +option. If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_THREAD_ROBUST_PRIO_PROTECT 6 +.br +The implementation supports the Robust Mutex Priority Protection +option. If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_THREAD_SAFE_FUNCTIONS 6 +.br +The implementation supports thread-safe functions. +This symbol shall always be set to the value 200809L. +.IP _POSIX_THREAD_SPORADIC_SERVER 6 +.br +The implementation supports the Thread Sporadic Server option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_THREADS 6 +.br +The implementation supports threads. +This symbol shall always be set to the value 200809L. +.IP _POSIX_TIMEOUTS 6 +.br +The implementation supports timeouts. +This symbol shall always be set to the value 200809L. +.IP _POSIX_TIMERS 6 +.br +The implementation supports timers. +This symbol shall always be set to the value 200809L. +.IP _POSIX_TRACE 6 +.br +The implementation supports the Trace option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_TRACE_EVENT_FILTER 6 +.br +The implementation supports the Trace Event Filter option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_TRACE_INHERIT 6 +.br +The implementation supports the Trace Inherit option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_TRACE_LOG 6 +.br +The implementation supports the Trace Log option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_TYPED_MEMORY_OBJECTS 6 +.br +The implementation supports the Typed Memory Objects option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX_V6_ILP32_OFF32 6 +.br +The implementation provides a C-language compilation environment with +32-bit +.BR int , +.BR long , +.BR pointer , +and +.BR off_t +types. +.IP _POSIX_V6_ILP32_OFFBIG 6 +.br +The implementation provides a C-language compilation environment with +32-bit +.BR int , +.BR long , +and +.BR pointer +types and an +.BR off_t +type using at least 64 bits. +.IP _POSIX_V6_LP64_OFF64 6 +.br +The implementation provides a C-language compilation environment with +32-bit +.BR int +and 64-bit +.BR long , +.BR pointer , +and +.BR off_t +types. +.IP _POSIX_V6_LPBIG_OFFBIG 6 +.br +The implementation provides a C-language compilation environment with +an +.BR int +type using at least 32 bits and +.BR long , +.BR pointer , +and +.BR off_t +types using at least 64 bits. +.IP _POSIX_V7_ILP32_OFF32 6 +.br +The implementation provides a C-language compilation environment with +32-bit +.BR int , +.BR long , +.BR pointer , +and +.BR off_t +types. +.IP _POSIX_V7_ILP32_OFFBIG 6 +.br +The implementation provides a C-language compilation environment with +32-bit +.BR int , +.BR long , +and +.BR pointer +types and an +.BR off_t +type using at least 64 bits. +.IP _POSIX_V7_LP64_OFF64 6 +.br +The implementation provides a C-language compilation environment with +32-bit +.BR int +and 64-bit +.BR long , +.BR pointer , +and +.BR off_t +types. +.IP _POSIX_V7_LPBIG_OFFBIG 6 +.br +The implementation provides a C-language compilation environment with +an +.BR int +type using at least 32 bits and +.BR long , +.BR pointer , +and +.BR off_t +types using at least 64 bits. +.IP _POSIX2_C_BIND 6 +.br +The implementation supports the C-Language Binding option. This +symbol shall always have the value 200809L. +.IP _POSIX2_C_DEV 6 +.br +The implementation supports the C-Language Development Utilities option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX2_CHAR_TERM 6 +.br +The implementation supports the Terminal Characteristics option. +The value of this symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or a value greater than zero. +.IP _POSIX2_FORT_DEV 6 +.br +The implementation supports the FORTRAN Development Utilities option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX2_FORT_RUN 6 +.br +The implementation supports the FORTRAN Runtime Utilities option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX2_LOCALEDEF 6 +.br +The implementation supports the creation of locales by the +.IR localedef +utility. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX2_PBS 6 +.br +The implementation supports the Batch Environment Services and +Utilities option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX2_PBS_ACCOUNTING 6 +.br +The implementation supports the Batch Accounting option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX2_PBS_CHECKPOINT 6 +.br +The implementation supports the Batch Checkpoint/Restart option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX2_PBS_LOCATE 6 +.br +The implementation supports the Locate Batch Job Request option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX2_PBS_MESSAGE 6 +.br +The implementation supports the Batch Job Message Request option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX2_PBS_TRACK 6 +.br +The implementation supports the Track Batch Job Request option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX2_SW_DEV 6 +.br +The implementation supports the Software Development Utilities option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _POSIX2_UPE 6 +.br +The implementation supports the User Portability Utilities option. +If this symbol is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this +symbol reported by +\fIsysconf\fR() +shall either be \(mi1 or 200809L. +.IP _XOPEN_CRYPT 6 +.br +The implementation supports the X/Open Encryption Option Group. +.IP _XOPEN_ENH_I18N 6 +.br +The implementation supports the Issue 4, Version 2 Enhanced +Internationalization Option Group. This symbol shall always be set +to a value other than \(mi1. +.IP _XOPEN_REALTIME 6 +.br +The implementation supports the X/Open Realtime Option Group. +.IP _XOPEN_REALTIME_THREADS 6 +.br +The implementation supports the X/Open Realtime Threads Option Group. +.IP _XOPEN_SHM 6 +.br +The implementation supports the Issue 4, Version 2 Shared Memory Option +Group. This symbol shall always be set to a value other than \(mi1. +.IP _XOPEN_STREAMS 6 +.br +The implementation supports the XSI STREAMS Option Group. +.IP _XOPEN_UNIX 6 +.br +The implementation supports the XSI option. +.IP _XOPEN_UUCP 6 +.br +The implementation supports the UUCP Utilities option. If this symbol +is defined in +.IR , +it shall be defined to be \(mi1, 0, or 200809L. The value of this symbol +reported by +\fIsysconf\fR() +shall be either \(mi1 or 200809L. +.SS "Execution-Time Symbolic Constants" +.P +If any of the following symbolic constants are not defined in the +.IR +header, the value shall vary depending on the file to which it +is applied. If defined, they shall have values suitable for use in +.BR #if +preprocessing directives. +.P +If any of the following symbolic constants are defined to have value +\(mi1 in the +.IR +header, the implementation shall not provide the option on any file; if +any are defined to have a value other than \(mi1 in the +.IR +header, the implementation shall provide the option on all applicable +files. +.P +All of the following values, whether defined as symbolic constants in +.IR +or not, may be queried with respect to a specific file using the +\fIpathconf\fR() +or +\fIfpathconf\fR() +functions: +.IP _POSIX_ASYNC_IO 6 +.br +Asynchronous input or output operations may be performed for the +associated file. +.IP _POSIX_PRIO_IO 6 +.br +Prioritized input or output operations may be performed for the +associated file. +.IP _POSIX_SYNC_IO 6 +.br +Synchronized input or output operations may be performed for the +associated file. +.P +If the following symbolic constants are defined in the +.IR +header, they apply to files and all paths in all file systems on +the implementation: +.IP _POSIX_TIMESTAMP_RESOLUTION 6 +.br +The resolution in nanoseconds for all file timestamps. +.IP _POSIX2_SYMLINKS 6 +.br +Symbolic links can be created. +.SS "Constants for Functions" +.P +The +.IR +header shall define NULL as described in +.IR . +.P +The +.IR +header shall define the following symbolic constants for use with the +\fIaccess\fR() +function. The values shall be suitable for use in +.BR #if +preprocessing directives. +.IP F_OK 12 +Test for existence of file. +.IP R_OK 12 +Test for read permission. +.IP W_OK 12 +Test for write permission. +.IP X_OK 12 +Test for execute (search) permission. +.P +The constants F_OK, R_OK, W_OK, and X_OK and the expressions +\fIR_OK\fP|\fIW_OK\fP, \fIR_OK\fP|\fIX_OK\fP, and +\fIR_OK\fP|\fIW_OK\fP|\fIX_OK\fP shall all have distinct values. +.P +The +.IR +header shall define the following symbolic constants for the +\fIconfstr\fR() +function: +.IP _CS_PATH 6 +.br +This is the value for the +.IR PATH +environment variable that finds all standard utilities. +.IP _CS_POSIX_V7_ILP32_OFF32_CFLAGS 6 +.br +If \fIsysconf\fP(_SC_V7_ILP32_OFF32) returns \(mi1, the meaning of +this value is unspecified. Otherwise, this value is the set of initial +options to be given to the +.IR c99 +utility to build an application using a programming model with 32-bit +.BR int , +.BR long , +.BR pointer , +and +.BR off_t +types. +.IP _CS_POSIX_V7_ILP32_OFF32_LDFLAGS 6 +.br +If \fIsysconf\fP(_SC_V7_ILP32_OFF32) returns \(mi1, the meaning of +this value is unspecified. Otherwise, this value is the set of final +options to be given to the +.IR c99 +utility to build an application using a programming model with 32-bit +.BR int , +.BR long , +.BR pointer , +and +.BR off_t +types. +.IP _CS_POSIX_V7_ILP32_OFF32_LIBS 6 +.br +If \fIsysconf\fP(_SC_V7_ILP32_OFF32) returns \(mi1, the meaning of +this value is unspecified. Otherwise, this value is the set of +libraries to be given to the +.IR c99 +utility to build an application using a programming model with 32-bit +.BR int , +.BR long , +.BR pointer , +and +.BR off_t +types. +.IP _CS_POSIX_V7_ILP32_OFFBIG_CFLAGS 6 +.br +If \fIsysconf\fP(_SC_V7_ILP32_OFFBIG) returns \(mi1, the meaning of +this value is unspecified. Otherwise, this value is the set of initial +options to be given to the +.IR c99 +utility to build an application using a programming model with 32-bit +.BR int , +.BR long , +and +.BR pointer +types, and an +.BR off_t +type using at least 64 bits. +.IP _CS_POSIX_V7_ILP32_OFFBIG_LDFLAGS 6 +.br +If \fIsysconf\fP(_SC_V7_ILP32_OFFBIG) returns \(mi1, the meaning of +this value is unspecified. Otherwise, this value is the set of final +options to be given to the +.IR c99 +utility to build an application using a programming model with 32-bit +.BR int , +.BR long , +and +.BR pointer +types, and an +.BR off_t +type using at least 64 bits. +.IP _CS_POSIX_V7_ILP32_OFFBIG_LIBS 6 +.br +If \fIsysconf\fP(_SC_V7_ILP32_OFFBIG) returns \(mi1, the meaning of +this value is unspecified. Otherwise, this value is the set of +libraries to be given to the +.IR c99 +utility to build an application using a programming model with 32-bit +.BR int , +.BR long , +and +.BR pointer +types, and an +.BR off_t +type using at least 64 bits. +.IP _CS_POSIX_V7_LP64_OFF64_CFLAGS 6 +.br +If \fIsysconf\fP(_SC_V7_LP64_OFF64) returns \(mi1, the meaning of +this value is unspecified. Otherwise, this value is the set of initial +options to be given to the +.IR c99 +utility to build an application using a programming model with 32-bit +.BR int +and 64-bit +.BR long , +.BR pointer , +and +.BR off_t +types. +.IP _CS_POSIX_V7_LP64_OFF64_LDFLAGS 6 +.br +If \fIsysconf\fP(_SC_V7_LP64_OFF64) returns \(mi1, the meaning of +this value is unspecified. Otherwise, this value is the set of final +options to be given to the +.IR c99 +utility to build an application using a programming model with 32-bit +.BR int +and 64-bit +.BR long , +.BR pointer , +and +.BR off_t +types. +.IP _CS_POSIX_V7_LP64_OFF64_LIBS 6 +.br +If \fIsysconf\fP(_SC_V7_LP64_OFF64) returns \(mi1, the meaning of +this value is unspecified. Otherwise, this value is the set of +libraries to be given to the +.IR c99 +utility to build an application using a programming model with 32-bit +.BR int +and 64-bit +.BR long , +.BR pointer , +and +.BR off_t +types. +.IP _CS_POSIX_V7_LPBIG_OFFBIG_CFLAGS 6 +.br +If \fIsysconf\fP(_SC_V7_LPBIG_OFFBIG) returns \(mi1, the meaning of +this value is unspecified. Otherwise, this value is the set of initial +options to be given to the +.IR c99 +utility to build an application using a programming model with an +.BR int +type using at least 32 bits and +.BR long , +.BR pointer , +and +.BR off_t +types using at least 64 bits. +.IP _CS_POSIX_V7_LPBIG_OFFBIG_LDFLAGS 6 +.br +If \fIsysconf\fP(_SC_V7_LPBIG_OFFBIG) returns \(mi1, the meaning of +this value is unspecified. Otherwise, this value is the set of final +options to be given to the +.IR c99 +utility to build an application using a programming model with an +.BR int +type using at least 32 bits and +.BR long , +.BR pointer , +and +.BR off_t +types using at least 64 bits. +.IP _CS_POSIX_V7_LPBIG_OFFBIG_LIBS 6 +.br +If \fIsysconf\fP(_SC_V7_LPBIG_OFFBIG) returns \(mi1, the meaning of +this value is unspecified. Otherwise, this value is the set of +libraries to be given to the +.IR c99 +utility to build an application using a programming model with an +.BR int +type using at least 32 bits and +.BR long , +.BR pointer , +and +.BR off_t +types using at least 64 bits. +.IP _CS_POSIX_V7_THREADS_CFLAGS 6 +.br +If +.IR sysconf (_SC_POSIX_THREADS) +returns \(mi1, the meaning of this value is unspecified. Otherwise, +this value is the set of initial options to be given to the +.IR c99 +utility to build a multi-threaded application. These flags are in addition +to those associated with any of the other _CS_POSIX_V7_*_CFLAGS values +used to specify particular type size programing environments. +.IP _CS_POSIX_V7_THREADS_LDFLAGS 6 +.br +If +.IR sysconf (_SC_POSIX_THREADS) +returns \(mi1, the meaning of this value is unspecified. Otherwise, +this value is the set of final options to be given to the +.IR c99 +utility to build a multi-threaded application. These flags are in addition +to those associated with any of the other _CS_POSIX_V7_*_LDFLAGS values +used to specify particular type size programing environments. +.IP _CS_POSIX_V7_WIDTH_RESTRICTED_ENVS 6 +.br +This value is a +-separated +list of names of programming environments supported by the +implementation in which the widths of the +.BR blksize_t , +.BR cc_t , +.BR mode_t , +.BR nfds_t , +.BR pid_t , +.BR ptrdiff_t , +.BR size_t , +.BR speed_t , +.BR ssize_t , +.BR suseconds_t , +.BR tcflag_t , +.BR wchar_t , +and +.BR wint_t +types are no greater than the width of type +.BR long . +The format of each name shall be suitable for use with the +.IR getconf +.BR \(miv +option. +.IP _CS_V7_ENV 6 +.br +This is the value that provides the environment variable information +(other than that provided by _CS_PATH) that is required by the +implementation to create a conforming environment, as described in the +implementation's conformance documentation. +.br +.P +The following symbolic constants are reserved for compatibility +with Issue 6: +.P +.nf +_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 +The +.IR +header shall define SEEK_CUR, SEEK_END, and SEEK_SET as described in +.IR . +.P +The +.IR +header shall define the following symbolic constants as possible +values for the +.IR function +argument to the +\fIlockf\fR() +function: +.IP F_LOCK 12 +Lock a section for exclusive use. +.IP F_TEST 12 +Test section for locks by other processes. +.IP F_TLOCK 12 +Test and lock a section for exclusive use. +.IP F_ULOCK 12 +Unlock locked sections. +.P +The +.IR +header shall define the following symbolic constants for +\fIpathconf\fR(): +.P +.nf +_PC_2_SYMLINKS +_PC_ALLOC_SIZE_MIN +_PC_ASYNC_IO +_PC_CHOWN_RESTRICTED +_PC_FILESIZEBITS +_PC_LINK_MAX +_PC_MAX_CANON +_PC_MAX_INPUT +_PC_NAME_MAX +_PC_NO_TRUNC +_PC_PATH_MAX +_PC_PIPE_BUF +_PC_PRIO_IO +_PC_REC_INCR_XFER_SIZE +_PC_REC_MAX_XFER_SIZE +_PC_REC_MIN_XFER_SIZE +_PC_REC_XFER_ALIGN +_PC_SYMLINK_MAX +_PC_SYNC_IO +_PC_TIMESTAMP_RESOLUTION +_PC_VDISABLE +.fi +.P +The +.IR +header shall define the following symbolic constants for +\fIsysconf\fR(): +.P +.nf +_SC_2_C_BIND +_SC_2_C_DEV +_SC_2_CHAR_TERM +_SC_2_FORT_DEV +_SC_2_FORT_RUN +_SC_2_LOCALEDEF +_SC_2_PBS +_SC_2_PBS_ACCOUNTING +_SC_2_PBS_CHECKPOINT +_SC_2_PBS_LOCATE +_SC_2_PBS_MESSAGE +_SC_2_PBS_TRACK +_SC_2_SW_DEV +_SC_2_UPE +_SC_2_VERSION +_SC_ADVISORY_INFO +_SC_AIO_LISTIO_MAX +_SC_AIO_MAX +_SC_AIO_PRIO_DELTA_MAX +_SC_ARG_MAX +_SC_ASYNCHRONOUS_IO +_SC_ATEXIT_MAX +_SC_BARRIERS +_SC_BC_BASE_MAX +_SC_BC_DIM_MAX +_SC_BC_SCALE_MAX +_SC_BC_STRING_MAX +_SC_CHILD_MAX +_SC_CLK_TCK +_SC_CLOCK_SELECTION +_SC_COLL_WEIGHTS_MAX +_SC_CPUTIME +_SC_DELAYTIMER_MAX +_SC_EXPR_NEST_MAX +_SC_FSYNC +_SC_GETGR_R_SIZE_MAX +_SC_GETPW_R_SIZE_MAX +_SC_HOST_NAME_MAX +_SC_IOV_MAX +_SC_IPV6 +_SC_JOB_CONTROL +_SC_LINE_MAX +_SC_LOGIN_NAME_MAX +_SC_MAPPED_FILES +_SC_MEMLOCK +_SC_MEMLOCK_RANGE +_SC_MEMORY_PROTECTION +_SC_MESSAGE_PASSING +_SC_MONOTONIC_CLOCK +_SC_MQ_OPEN_MAX +_SC_MQ_PRIO_MAX +_SC_NGROUPS_MAX +_SC_OPEN_MAX +_SC_PAGE_SIZE +_SC_PAGESIZE +_SC_PRIORITIZED_IO +_SC_PRIORITY_SCHEDULING +_SC_RAW_SOCKETS +_SC_RE_DUP_MAX +_SC_READER_WRITER_LOCKS +_SC_REALTIME_SIGNALS +_SC_REGEXP +_SC_RTSIG_MAX +_SC_SAVED_IDS +_SC_SEM_NSEMS_MAX +_SC_SEM_VALUE_MAX +_SC_SEMAPHORES +_SC_SHARED_MEMORY_OBJECTS +_SC_SHELL +_SC_SIGQUEUE_MAX +_SC_SPAWN +_SC_SPIN_LOCKS +_SC_SPORADIC_SERVER +_SC_SS_REPL_MAX +_SC_STREAM_MAX +_SC_SYMLOOP_MAX +_SC_SYNCHRONIZED_IO +_SC_THREAD_ATTR_STACKADDR +_SC_THREAD_ATTR_STACKSIZE +_SC_THREAD_CPUTIME +_SC_THREAD_DESTRUCTOR_ITERATIONS +_SC_THREAD_KEYS_MAX +_SC_THREAD_PRIO_INHERIT +_SC_THREAD_PRIO_PROTECT +_SC_THREAD_PRIORITY_SCHEDULING +_SC_THREAD_PROCESS_SHARED +_SC_THREAD_ROBUST_PRIO_INHERIT +_SC_THREAD_ROBUST_PRIO_PROTECT +_SC_THREAD_SAFE_FUNCTIONS +_SC_THREAD_SPORADIC_SERVER +_SC_THREAD_STACK_MIN +_SC_THREAD_THREADS_MAX +_SC_THREADS +_SC_TIMEOUTS +_SC_TIMER_MAX +_SC_TIMERS +_SC_TRACE +_SC_TRACE_EVENT_FILTER +_SC_TRACE_EVENT_NAME_MAX +_SC_TRACE_INHERIT +_SC_TRACE_LOG +_SC_TRACE_NAME_MAX +_SC_TRACE_SYS_MAX +_SC_TRACE_USER_EVENT_MAX +_SC_TTY_NAME_MAX +_SC_TYPED_MEMORY_OBJECTS +_SC_TZNAME_MAX +_SC_V7_ILP32_OFF32 +_SC_V7_ILP32_OFFBIG +_SC_V7_LP64_OFF64 +_SC_V7_LPBIG_OFFBIG +_SC_V6_ILP32_OFF32 +_SC_V6_ILP32_OFFBIG +_SC_V6_LP64_OFF64 +_SC_V6_LPBIG_OFFBIG +_SC_VERSION +_SC_XOPEN_CRYPT +_SC_XOPEN_ENH_I18N +_SC_XOPEN_REALTIME +_SC_XOPEN_REALTIME_THREADS +_SC_XOPEN_SHM +_SC_XOPEN_STREAMS +_SC_XOPEN_UNIX +_SC_XOPEN_UUCP +_SC_XOPEN_VERSION +.fi +.P +The two constants _SC_PAGESIZE and _SC_PAGE_SIZE may be defined to +have the same value. +.P +The +.IR +header shall define the following symbolic constants for file streams: +.IP STDERR_FILENO 14 +File number of +.IR stderr ; +2. +.IP STDIN_FILENO 14 +File number of +.IR stdin ; +0. +.IP STDOUT_FILENO 14 +File number of +.IR stdout ; +1. +.P +The +.IR +header shall define the following symbolic constant for terminal +special character handling: +.IP _POSIX_VDISABLE 14 +This symbol shall be defined to be the value of a character that shall +disable terminal special character handling as described in +.IR "Section 11.2.6" ", " "Special Control Characters". +This symbol shall always be set to a value other than \(mi1. +.SS "Type Definitions" +.P +The +.IR +header shall define the +.BR size_t , +.BR ssize_t , +.BR uid_t , +.BR gid_t , +.BR off_t , +and +.BR pid_t +types as described in +.IR . +.P +The +.IR +header shall define the +.BR intptr_t +type as described in +.IR . +.SS "Declarations" +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int access(const char *, int); +unsigned alarm(unsigned); +int chdir(const char *); +int chown(const char *, uid_t, gid_t); +int close(int); +size_t confstr(int, char *, size_t); +char *crypt(const char *, const char *); +int dup(int); +.br +int dup2(int, int); +void _exit(int); +void encrypt(char [64], int); +int execl(const char *, const char *, ...); +int execle(const char *, const char *, ...); +int execlp(const char *, const char *, ...); +int execv(const char *, char *const []); +int execve(const char *, char *const [], char *const []); +int execvp(const char *, char *const []); +int faccessat(int, const char *, int, int); +int fchdir(int); +int fchown(int, uid_t, gid_t); +int fchownat(int, const char *, uid_t, gid_t, int); +int fdatasync(int); +int fexecve(int, char *const [], char *const []); +pid_t fork(void); +long fpathconf(int, int); +int fsync(int); +int ftruncate(int, off_t); +char *getcwd(char *, size_t); +gid_t getegid(void); +uid_t geteuid(void); +gid_t getgid(void); +int getgroups(int, gid_t []); +long gethostid(void); +int gethostname(char *, size_t); +char *getlogin(void); +int getlogin_r(char *, size_t); +int getopt(int, char * const [], const char *); +pid_t getpgid(pid_t); +pid_t getpgrp(void); +pid_t getpid(void); +pid_t getppid(void); +pid_t getsid(pid_t); +uid_t getuid(void); +int isatty(int); +int lchown(const char *, uid_t, gid_t); +int link(const char *, const char *); +int linkat(int, const char *, int, const char *, int); +int lockf(int, int, off_t); +off_t lseek(int, off_t, int); +int nice(int); +long pathconf(const char *, int); +int pause(void); +int pipe(int [2]); +ssize_t pread(int, void *, size_t, off_t); +ssize_t pwrite(int, const void *, size_t, off_t); +ssize_t read(int, void *, size_t); +ssize_t readlink(const char *restrict, char *restrict, size_t); +ssize_t readlinkat(int, const char *restrict, char *restrict, size_t); +int rmdir(const char *); +int setegid(gid_t); +int seteuid(uid_t); +int setgid(gid_t); +.br +int setpgid(pid_t, pid_t); +pid_t setpgrp(void); +int setregid(gid_t, gid_t); +int setreuid(uid_t, uid_t); +pid_t setsid(void); +int setuid(uid_t); +unsigned sleep(unsigned); +void swab(const void *restrict, void *restrict, ssize_t); +int symlink(const char *, const char *); +int symlinkat(const char *, int, const char *); +void sync(void); +long sysconf(int); +pid_t tcgetpgrp(int); +int tcsetpgrp(int, pid_t); +int truncate(const char *, off_t); +char *ttyname(int); +int ttyname_r(int, char *, size_t); +int unlink(const char *); +int unlinkat(int, const char *, int); +ssize_t write(int, const void *, size_t); +.fi \fR +.P +.RE +.P +Implementations may also include the +\fIpthread_atfork\fR() +prototype as defined in +.IR . +Implementations may also include the +\fIctermid\fR() +prototype as defined in +.IR . +.P +The +.IR +header shall declare the following external variables: +.sp +.RS 4 +.nf +\fB +extern char *optarg; +extern int opterr, optind, optopt; +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +POSIX.1\(hy2008 only describes the behavior of systems that claim conformance to +it. However, application developers who want to write applications that +adapt to other versions of this standard (or to systems that do not +conform to any POSIX standard) may find it useful to code them so as to +conditionally compile different code depending on the value of +_POSIX_VERSION, for example: +.sp +.RS 4 +.nf +\fB +#if _POSIX_VERSION >= 200112L +/* Use the newer function that copes with large files. */ +off_t pos=ftello(fp); +#else +/* Either this is an old version of POSIX, or _POSIX_VERSION is + not even defined, so use the traditional function. */ +long pos=ftell(fp); +#endif +.fi \fR +.P +.RE +.P +Earlier versions of POSIX.1\(hy2008 and of the Single UNIX Specification +can be identified by the following macros: +.IP "POSIX.1\(hy1988 standard" 6 +.br +_POSIX_VERSION\|=\^=\|198808L +.IP "POSIX.1\(hy1990 standard" 6 +.br +_POSIX_VERSION\|=\^=\|199009L +.IP "ISO\ POSIX\(hy1:\|1996 standard" 6 +.br +_POSIX_VERSION\|=\^=\|199506L +.IP "Single UNIX Specification, Version 1" 6 +.br +_XOPEN_UNIX and _XOPEN_VERSION\|=\^=\|4 +.IP "Single UNIX Specification, Version 2" 6 +.br +_XOPEN_UNIX and _XOPEN_VERSION\|=\^=\|500 +.IP "ISO POSIX\(hy1:\|2001 and Single UNIX Specification, Version 3" 6 +.br +_POSIX_VERSION\|=\^=\|200112L, plus (if the XSI option is supported) +_XOPEN_UNIX and _XOPEN_VERSION\|=\^=\|600 +.P +POSIX.1\(hy2008 does not make any attempt to define application binary +interaction with the underlying operating system. However, application +developers may find it useful to query _SC_VERSION at runtime via +\fIsysconf\fR() +to determine whether the current version of the operating system +supports the necessary functionality as in the following program +fragment: +.sp +.RS 4 +.nf +\fB +if (sysconf(_SC_VERSION) < 200809L) { + fprintf(stderr, "POSIX.1-2008 system required, terminating \en"); + exit(1); +} +.fi \fR +.P +.RE +.P +New applications should not use _XOPEN_SHM or _XOPEN_ENH_I18N. +.SH RATIONALE +As POSIX.1\(hy2008 evolved, certain options became sufficiently standardized that +it was concluded that simply requiring one of the option choices was +simpler than retaining the option. However, for backwards-compatibility, +the option flags (with required constant values) are retained. +.SS "Version Test Macros" +.P +The standard developers considered altering the definition of +_POSIX_VERSION and removing _SC_VERSION from the specification of +\fIsysconf\fR() +since the utility to an application was deemed by some to be minimal, +and since the implementation of the functionality is potentially +problematic. However, they recognized that support for existing +application binaries is a concern to manufacturers, application +developers, and the users of implementations conforming to POSIX.1\(hy2008. +.P +While the example using _SC_VERSION in the APPLICATION USAGE section +does not provide the greatest degree of imaginable utility to the +application developer or user, it is arguably better than a +.BR core +file or some other equally obscure result. (It is also possible for +implementations to encode and recognize application binaries compiled +in various POSIX.1-conforming environments, and modify the semantics of +the underlying system to conform to the expectations of the +application.) For the reasons outlined in the preceding paragraphs and +in the APPLICATION USAGE section, the standard developers elected to +retain the _POSIX_VERSION and _SC_VERSION functionality. +.SS "Compile-Time Symbolic Constants for System-Wide Options" +.P +POSIX.1\(hy2008 includes support in certain areas for the newly adopted +policy governing options and stubs. +.P +This policy provides flexibility for implementations in how they +support options. It also specifies how conforming applications can +adapt to different implementations that support different sets of +options. It allows the following: +.IP " 1." 4 +If an implementation has no interest in supporting an option, it does +not have to provide anything associated with that option beyond the +announcement that it does not support it. +.IP " 2." 4 +An implementation can support a partial or incompatible version of an +option (as a non-standard extension) as long as it does not claim to +support the option. +.IP " 3." 4 +An application can determine whether the option is supported. A +strictly conforming application must check this announcement mechanism +before first using anything associated with the option. +.P +There is an important implication of this policy. POSIX.1\(hy2008 cannot +dictate the behavior of interfaces associated with an option when the +implementation does not claim to support the option. In particular, it +cannot require that a function associated with an unsupported option +will fail if it does not perform as specified. However, this policy +does not prevent a standard from requiring certain functions to always +be present, but that they shall always fail on some implementations. +The +\fIsetpgid\fR() +function in the POSIX.1\(hy1990 standard, for example, is considered appropriate. +.P +The POSIX standards include various options, and the C-language +binding support for an option implies that the implementation must +supply data types and function interfaces. An application must be able +to discover whether the implementation supports each option. +.P +Any application must consider the following three cases for each +option: +.IP " 1." 4 +Option never supported. +.RS 4 +.P +The implementation advertises at compile time that the option will +never be supported. In this case, it is not necessary for the +implementation to supply any of the data types or function interfaces +that are provided only as part of the option. The implementation might +provide data types and functions that are similar to those defined by +POSIX.1\(hy2008, but there is no guarantee for any particular behavior. +.RE +.IP " 2." 4 +Option always supported. +.RS 4 +.P +The implementation advertises at compile time that the option will +always be supported. In this case, all data types and function +interfaces shall be available and shall operate as specified. +.RE +.IP " 3." 4 +Option might or might not be supported. +.RS 4 +.P +Some implementations might not provide a mechanism to specify support +of options at compile time. In addition, the implementation might be +unable or unwilling to specify support or non-support at compile time. +In either case, any application that might use the option at runtime +must be able to compile and execute. The implementation must provide, +at compile time, all data types and function interfaces that are +necessary to allow this. In this situation, there must be a mechanism +that allows the application to query, at runtime, whether the option is +supported. If the application attempts to use the option when it is not +supported, the result is unspecified unless explicitly specified +otherwise in POSIX.1\(hy2008. +.RE +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +.ad l +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIaccess\fR\^(\|)", +.IR "\fIalarm\fR\^(\|)", +.IR "\fIchown\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIconfstr\fR\^(\|)", +.IR "\fIcrypt\fR\^(\|)", +.IR "\fIctermid\fR\^(\|)", +.IR "\fIdup\fR\^(\|)", +.IR "\fI_Exit\fR\^(\|)", +.IR "\fIencrypt\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfchdir\fR\^(\|)", +.IR "\fIfchown\fR\^(\|)", +.IR "\fIfdatasync\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIfpathconf\fR\^(\|)", +.IR "\fIfsync\fR\^(\|)", +.IR "\fIftruncate\fR\^(\|)", +.IR "\fIgetcwd\fR\^(\|)", +.IR "\fIgetegid\fR\^(\|)", +.IR "\fIgeteuid\fR\^(\|)", +.IR "\fIgetgid\fR\^(\|)", +.IR "\fIgetgroups\fR\^(\|)", +.IR "\fIgethostid\fR\^(\|)", +.IR "\fIgethostname\fR\^(\|)", +.IR "\fIgetlogin\fR\^(\|)", +.IR "\fIgetopt\fR\^(\|)", +.IR "\fIgetpgid\fR\^(\|)", +.IR "\fIgetpgrp\fR\^(\|)", +.IR "\fIgetpid\fR\^(\|)", +.IR "\fIgetppid\fR\^(\|)", +.IR "\fIgetsid\fR\^(\|)", +.IR "\fIgetuid\fR\^(\|)", +.IR "\fIisatty\fR\^(\|)", +.IR "\fIlchown\fR\^(\|)", +.IR "\fIlink\fR\^(\|)", +.IR "\fIlockf\fR\^(\|)", +.IR "\fIlseek\fR\^(\|)", +.IR "\fInice\fR\^(\|)", +.IR "\fIpause\fR\^(\|)", +.IR "\fIpipe\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIreadlink\fR\^(\|)", +.IR "\fIrmdir\fR\^(\|)", +.IR "\fIsetegid\fR\^(\|)", +.IR "\fIseteuid\fR\^(\|)", +.IR "\fIsetgid\fR\^(\|)", +.IR "\fIsetpgid\fR\^(\|)", +.IR "\fIsetpgrp\fR\^(\|)", +.IR "\fIsetregid\fR\^(\|)", +.IR "\fIsetreuid\fR\^(\|)", +.IR "\fIsetsid\fR\^(\|)", +.IR "\fIsetuid\fR\^(\|)", +.IR "\fIsleep\fR\^(\|)", +.IR "\fIswab\fR\^(\|)", +.IR "\fIsymlink\fR\^(\|)", +.IR "\fIsync\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)", +.IR "\fItcgetpgrp\fR\^(\|)", +.IR "\fItcsetpgrp\fR\^(\|)", +.IR "\fItruncate\fR\^(\|)", +.IR "\fIttyname\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.ad b +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/utime.h.0p b/man-pages-posix-2013/man0p/utime.h.0p new file mode 100644 index 0000000..9474f4f --- /dev/null +++ b/man-pages-posix-2013/man0p/utime.h.0p @@ -0,0 +1,91 @@ +'\" et +.TH utime.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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.h +\(em access and modification times structure +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall declare the +.BR utimbuf +structure, which shall include the following members: +.sp +.RS 4 +.nf +\fB +time_t actime \fRAccess time.\fR +time_t modtime \fRModification time.\fR +.fi \fR +.P +.RE +.P +The times shall be measured in seconds since the Epoch. +.P +The +.IR +header shall define the +.BR time_t +type as described in +.IR . +.P +The following shall be declared as a function and may also be defined +as a macro. A function prototype shall be provided. +.sp +.RS 4 +.nf +\fB +int utime(const char *, const struct utimbuf *); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +\fIutime\fR() +function only allows setting file timestamps to the nearest second. +Applications should use the +\fIutimensat\fR() +function instead. See +.IR . +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +.IR +header may be removed in a future version. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIfutimens\fR\^(\|)", +.IR "\fIutime\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/utmpx.h.0p b/man-pages-posix-2013/man0p/utmpx.h.0p new file mode 100644 index 0000000..8b14cd7 --- /dev/null +++ b/man-pages-posix-2013/man0p/utmpx.h.0p @@ -0,0 +1,128 @@ +'\" et +.TH utmpx.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +utmpx.h +\(em user accounting database definitions +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the +.BR utmpx +structure that shall include at least the following members: +.sp +.RS 4 +.nf +\fB +char ut_user[] \fRUser login name.\fR +char ut_id[] \fRUnspecified initialization process identifier.\fR +char ut_line[] \fRDevice name.\fR +pid_t ut_pid \fRProcess ID.\fR +short ut_type \fRType of entry.\fR +struct timeval ut_tv \fRTime entry was made.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the +.BR pid_t +type through +.BR typedef , +as described in +.IR . +.P +The +.IR +header shall define the +.BR timeval +structure as described in +.IR . +.P +Inclusion of the +.IR +header may also make visible all symbols from +.IR . +.P +The +.IR +header shall define the following symbolic constants as possible values +for the +.IR ut_type +member of the +.BR utmpx +structure: +.IP EMPTY 14 +No valid user accounting information. +.IP BOOT_TIME 14 +Identifies time of system boot. +.IP OLD_TIME 14 +Identifies time when system clock changed. +.IP NEW_TIME 14 +Identifies time after system clock changed. +.IP USER_PROCESS 14 +Identifies a process. +.IP INIT_PROCESS 14 +Identifies a process spawned by the init process. +.IP LOGIN_PROCESS 14 +Identifies the session leader of a logged-in user. +.IP DEAD_PROCESS 14 +Identifies a session leader who has exited. +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +void endutxent(void); +struct utmpx *getutxent(void); +struct utmpx *getutxid(const struct utmpx *); +struct utmpx *getutxline(const struct utmpx *); +struct utmpx *pututxline(const struct utmpx *); +void setutxent(void); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIendutxent\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/wchar.h.0p b/man-pages-posix-2013/man0p/wchar.h.0p new file mode 100644 index 0000000..c202a3f --- /dev/null +++ b/man-pages-posix-2013/man0p/wchar.h.0p @@ -0,0 +1,353 @@ +'\" et +.TH wchar.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wchar.h +\(em wide-character handling +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends the +ISO\ C standard. Applications shall define the appropriate feature test macro +(see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment") +to enable the visibility of these symbols in this header. +.P +The +.IR +header shall define the following types: +.IP "\fBFILE\fP" 12 +As described in +.IR . +.IP "\fBlocale_t\fP" 12 +As described in +.IR . +.IP "\fBmbstate_t\fP" 12 +An object type other than an array type that can hold the conversion +state information necessary to convert between sequences of (possibly +multi-byte) characters and wide characters. +If a codeset is being used such that an +.BR mbstate_t +needs to preserve more than two levels of reserved state, the +results are unspecified. +.IP "\fBsize_t\fP" 12 +As described in +.IR . +.IP "\fBva_list\fP" 12 +As described in +.IR . +.IP "\fBwchar_t\fP" 12 +As described in +.IR . +.IP "\fBwctype_t\fP" 12 +A scalar type of a data object that can hold values which represent +locale-specific character classification. +.IP "\fBwint_t\fP" 12 +An integer type capable of storing any valid value of +.BR wchar_t +or WEOF. +.P +The tag +.BR tm +shall be declared as naming an incomplete structure type, the contents +of which are described in the +.IR +header. +.P +The implementation shall support one or more programming environments +in which the width of +.BR wint_t +is no greater than the width of type +.BR long . +The names of these programming environments can be obtained using the +\fIconfstr\fR() +function or the +.IR getconf +utility. +.P +The +.IR +header shall define the following macros: +.IP WCHAR_MAX 12 +As described in +.IR . +.IP WCHAR_MIN 12 +As described in +.IR . +.IP WEOF 12 +Constant expression of type +.BR wint_t +that is returned by several WP functions to indicate end-of-file. +.IP NULL 12 +As described in +.IR . +.P +Inclusion of the +.IR +header may make visible all symbols from the headers +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +and +.IR . +.P +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided for use with ISO\ C standard +compilers. +.sp +.RS 4 +.nf +\fB +wint_t btowc(int); +wint_t fgetwc(FILE *); +wchar_t *fgetws(wchar_t *restrict, int, FILE *restrict); +wint_t fputwc(wchar_t, FILE *); +int fputws(const wchar_t *restrict, FILE *restrict); +int fwide(FILE *, int); +int fwprintf(FILE *restrict, const wchar_t *restrict, ...); +int fwscanf(FILE *restrict, const wchar_t *restrict, ...); +wint_t getwc(FILE *); +wint_t getwchar(void); +int iswalnum(wint_t); +int iswalpha(wint_t); +int iswcntrl(wint_t); +int iswctype(wint_t, wctype_t); +int iswdigit(wint_t); +int iswgraph(wint_t); +int iswlower(wint_t); +int iswprint(wint_t); +int iswpunct(wint_t); +int iswspace(wint_t); +int iswupper(wint_t); +int iswxdigit(wint_t); +size_t mbrlen(const char *restrict, size_t, mbstate_t *restrict); +size_t mbrtowc(wchar_t *restrict, const char *restrict, size_t, + mbstate_t *restrict); +int mbsinit(const mbstate_t *); +size_t mbsnrtowcs(wchar_t *restrict, const char **restrict, + size_t, size_t, mbstate_t *restrict); +size_t mbsrtowcs(wchar_t *restrict, const char **restrict, size_t, + mbstate_t *restrict); +FILE *open_wmemstream(wchar_t **, size_t *); +wint_t putwc(wchar_t, FILE *); +wint_t putwchar(wchar_t); +int swprintf(wchar_t *restrict, size_t, + const wchar_t *restrict, ...); +int swscanf(const wchar_t *restrict, + const wchar_t *restrict, ...); +wint_t towlower(wint_t); +wint_t towupper(wint_t); +wint_t ungetwc(wint_t, FILE *); +int vfwprintf(FILE *restrict, const wchar_t *restrict, va_list); +int vfwscanf(FILE *restrict, const wchar_t *restrict, va_list); +int vswprintf(wchar_t *restrict, size_t, + const wchar_t *restrict, va_list); +int vswscanf(const wchar_t *restrict, const wchar_t *restrict, + va_list); +int vwprintf(const wchar_t *restrict, va_list); +int vwscanf(const wchar_t *restrict, va_list); +wchar_t *wcpcpy(wchar_t *restrict, const wchar_t *restrict); +wchar_t *wcpncpy(wchar_t *restrict, const wchar_t *restrict, size_t); +size_t wcrtomb(char *restrict, wchar_t, mbstate_t *restrict); +int wcscasecmp(const wchar_t *, const wchar_t *); +int wcscasecmp_l(const wchar_t *, const wchar_t *, locale_t); +wchar_t *wcscat(wchar_t *restrict, const wchar_t *restrict); +wchar_t *wcschr(const wchar_t *, wchar_t); +int wcscmp(const wchar_t *, const wchar_t *); +int wcscoll(const wchar_t *, const wchar_t *); +int wcscoll_l(const wchar_t *, const wchar_t *, locale_t); +wchar_t *wcscpy(wchar_t *restrict, const wchar_t *restrict); +size_t wcscspn(const wchar_t *, const wchar_t *); +wchar_t *wcsdup(const wchar_t *); +size_t wcsftime(wchar_t *restrict, size_t, + const wchar_t *restrict, const struct tm *restrict); +size_t wcslen(const wchar_t *); +int wcsncasecmp(const wchar_t *, const wchar_t *, size_t); +int wcsncasecmp_l(const wchar_t *, const wchar_t *, size_t, + locale_t); +wchar_t *wcsncat(wchar_t *restrict, const wchar_t *restrict, size_t); +int wcsncmp(const wchar_t *, const wchar_t *, size_t); +wchar_t *wcsncpy(wchar_t *restrict, const wchar_t *restrict, size_t); +size_t wcsnlen(const wchar_t *, size_t); +size_t wcsnrtombs(char *restrict, const wchar_t **restrict, size_t, + size_t, mbstate_t *restrict); +wchar_t *wcspbrk(const wchar_t *, const wchar_t *); +wchar_t *wcsrchr(const wchar_t *, wchar_t); +size_t wcsrtombs(char *restrict, const wchar_t **restrict, + size_t, mbstate_t *restrict); +size_t wcsspn(const wchar_t *, const wchar_t *); +wchar_t *wcsstr(const wchar_t *restrict, const wchar_t *restrict); +double wcstod(const wchar_t *restrict, wchar_t **restrict); +float wcstof(const wchar_t *restrict, wchar_t **restrict); +wchar_t *wcstok(wchar_t *restrict, const wchar_t *restrict, + wchar_t **restrict); +long wcstol(const wchar_t *restrict, wchar_t **restrict, int); +long double wcstold(const wchar_t *restrict, wchar_t **restrict); +long long wcstoll(const wchar_t *restrict, wchar_t **restrict, int); +unsigned long wcstoul(const wchar_t *restrict, wchar_t **restrict, int); +unsigned long long + wcstoull(const wchar_t *restrict, wchar_t **restrict, int); +int wcswidth(const wchar_t *, size_t); +size_t wcsxfrm(wchar_t *restrict, const wchar_t *restrict, size_t); +size_t wcsxfrm_l(wchar_t *restrict, const wchar_t *restrict, + size_t, locale_t); +int wctob(wint_t); +wctype_t wctype(const char *); +int wcwidth(wchar_t); +wchar_t *wmemchr(const wchar_t *, wchar_t, size_t); +int wmemcmp(const wchar_t *, const wchar_t *, size_t); +wchar_t *wmemcpy(wchar_t *restrict, const wchar_t *restrict, size_t); +wchar_t *wmemmove(wchar_t *, const wchar_t *, size_t); +wchar_t *wmemset(wchar_t *, wchar_t, size_t); +int wprintf(const wchar_t *restrict, ...); +int wscanf(const wchar_t *restrict, ...); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +\fIiswblank\fR() +function was a late addition to the ISO\ C standard and was introduced at the same +time as the ISO\ C standard introduced +.IR , +which contains all of the +.IR isw* (\|) +functions. The Open Group Base Specifications had previously aligned +with the MSE working draft and had introduced the rest of the +.IR isw* (\|) +functions into +.IR . +For backwards-compatibility, the original set of +.IR isw* (\|) +functions, without +\fIiswblank\fR(), +are permitted (as part of the XSI option) in +.IR . +For maximum portability, applications should include +.IR +in order to obtain declarations for the +.IR isw* (\|) +functions. This compatibility has been made obsolescent. +.SH RATIONALE +In the ISO\ C standard, the symbols referenced as XSI extensions are in +.IR . +Their presence here is thus an extension. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +.ad l +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment", +.IR "\fIbtowc\fR\^(\|)", +.IR "\fIconfstr\fR\^(\|)", +.IR "\fIfgetwc\fR\^(\|)", +.IR "\fIfgetws\fR\^(\|)", +.IR "\fIfputwc\fR\^(\|)", +.IR "\fIfputws\fR\^(\|)", +.IR "\fIfwide\fR\^(\|)", +.IR "\fIfwprintf\fR\^(\|)", +.IR "\fIfwscanf\fR\^(\|)", +.IR "\fIgetwc\fR\^(\|)", +.IR "\fIgetwchar\fR\^(\|)", +.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 "\fImbrlen\fR\^(\|)", +.IR "\fImbrtowc\fR\^(\|)", +.IR "\fImbsinit\fR\^(\|)", +.IR "\fImbsrtowcs\fR\^(\|)", +.IR "\fIopen_memstream\fR\^(\|)", +.IR "\fIputwc\fR\^(\|)", +.IR "\fIputwchar\fR\^(\|)", +.IR "\fItowlower\fR\^(\|)", +.IR "\fItowupper\fR\^(\|)", +.IR "\fIungetwc\fR\^(\|)", +.IR "\fIvfwprintf\fR\^(\|)", +.IR "\fIvfwscanf\fR\^(\|)", +.IR "\fIwcrtomb\fR\^(\|)", +.IR "\fIwcscasecmp\fR\^(\|)", +.IR "\fIwcscat\fR\^(\|)", +.IR "\fIwcschr\fR\^(\|)", +.IR "\fIwcscmp\fR\^(\|)", +.IR "\fIwcscoll\fR\^(\|)", +.IR "\fIwcscpy\fR\^(\|)", +.IR "\fIwcscspn\fR\^(\|)", +.IR "\fIwcsdup\fR\^(\|)", +.IR "\fIwcsftime\fR\^(\|)", +.IR "\fIwcslen\fR\^(\|)", +.IR "\fIwcsncat\fR\^(\|)", +.IR "\fIwcsncmp\fR\^(\|)", +.IR "\fIwcsncpy\fR\^(\|)", +.IR "\fIwcspbrk\fR\^(\|)", +.IR "\fIwcsrchr\fR\^(\|)", +.IR "\fIwcsrtombs\fR\^(\|)", +.IR "\fIwcsspn\fR\^(\|)", +.IR "\fIwcsstr\fR\^(\|)", +.IR "\fIwcstod\fR\^(\|)", +.IR "\fIwcstok\fR\^(\|)", +.IR "\fIwcstol\fR\^(\|)", +.IR "\fIwcstoul\fR\^(\|)", +.IR "\fIwcswidth\fR\^(\|)", +.IR "\fIwcsxfrm\fR\^(\|)", +.IR "\fIwctob\fR\^(\|)", +.IR "\fIwctype\fR\^(\|)", +.IR "\fIwcwidth\fR\^(\|)", +.IR "\fIwmemchr\fR\^(\|)", +.IR "\fIwmemcmp\fR\^(\|)", +.IR "\fIwmemcpy\fR\^(\|)", +.IR "\fIwmemmove\fR\^(\|)", +.IR "\fIwmemset\fR\^(\|)" +.ad b +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIgetconf\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/wctype.h.0p b/man-pages-posix-2013/man0p/wctype.h.0p new file mode 100644 index 0000000..3d2e1c6 --- /dev/null +++ b/man-pages-posix-2013/man0p/wctype.h.0p @@ -0,0 +1,178 @@ +'\" et +.TH wctype.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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.h +\(em wide-character classification and mapping utilities +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +Some of the functionality described on this reference page extends the +ISO\ C standard. Applications shall define the appropriate feature test macro +(see the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment") +to enable the visibility of these symbols in this header. +.P +The +.IR +header shall define the following types: +.IP "\fBwint_t\fP" 12 +As described in +.IR . +.IP "\fBwctrans_t\fP" 12 +A scalar type that can hold values which represent locale-specific +character mappings. +.IP "\fBwctype_t\fP" 12 +As described in +.IR . +.P +The +.IR +header shall define the +.BR locale_t +type as described in +.IR . +.P +The +.IR +header shall define the following macro: +.IP WEOF 12 +As described in +.IR . +.P +For all functions described in this header that accept an argument of +type +.BR wint_t , +the value is representable as a +.BR wchar_t +or equals the value of WEOF. If this argument has any other value, the +behavior is undefined. +.P +The behavior of these functions shall be affected by the +.IR LC_CTYPE +category of the current locale. +.P +Inclusion of the +.IR +header may make visible all symbols from the headers +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +and +.IR . +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided for use with ISO\ C standard +compilers. +.sp +.RS 4 +.nf +\fB +int iswalnum(wint_t); +int iswalnum_l(wint_t, locale_t); +int iswalpha(wint_t); +int iswalpha_l(wint_t, locale_t); +int iswblank(wint_t); +int iswblank_l(wint_t, locale_t); +int iswcntrl(wint_t); +int iswcntrl_l(wint_t, locale_t); +int iswctype(wint_t, wctype_t); +int iswctype_l(wint_t, wctype_t, locale_t); +int iswdigit(wint_t); +int iswdigit_l(wint_t, locale_t); +int iswgraph(wint_t); +int iswgraph_l(wint_t, locale_t); +int iswlower(wint_t); +int iswlower_l(wint_t, locale_t); +int iswprint(wint_t); +int iswprint_l(wint_t, locale_t); +int iswpunct(wint_t); +int iswpunct_l(wint_t, locale_t); +int iswspace(wint_t); +int iswspace_l(wint_t, locale_t); +int iswupper(wint_t); +int iswupper_l(wint_t, locale_t); +int iswxdigit(wint_t); +int iswxdigit_l(wint_t, locale_t); +wint_t towctrans(wint_t, wctrans_t); +wint_t towctrans_l(wint_t, wctrans_t, locale_t); +wint_t towlower(wint_t); +wint_t towlower_l(wint_t, locale_t); +wint_t towupper(wint_t); +wint_t towupper_l(wint_t, locale_t); +wctrans_t wctrans(const char *); +wctrans_t wctrans_l(const char *, locale_t); +wctype_t wctype(const char *); +wctype_t wctype_l(const char *, locale_t); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.2" ", " "The Compilation Environment", +.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 "\fIsetlocale\fR\^(\|)", +.IR "\fItowctrans\fR\^(\|)", +.IR "\fItowlower\fR\^(\|)", +.IR "\fItowupper\fR\^(\|)", +.IR "\fIwctrans\fR\^(\|)", +.IR "\fIwctype\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man0p/wordexp.h.0p b/man-pages-posix-2013/man0p/wordexp.h.0p new file mode 100644 index 0000000..c036cbd --- /dev/null +++ b/man-pages-posix-2013/man0p/wordexp.h.0p @@ -0,0 +1,152 @@ +'\" et +.TH wordexp.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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.h +\(em word-expansion types +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The +.IR +header shall define the structures and symbolic constants used by the +\fIwordexp\fR() +and +\fIwordfree\fR() +functions. +.P +The +.IR +header shall define the +.BR wordexp_t +structure type, which shall include at least the following members: +.sp +.RS 4 +.nf +\fB +size_t we_wordc \fRCount of words matched by \fIwords.\fR +char **we_wordv \fRPointer to list of expanded words.\fR +size_t we_offs \fRSlots to reserve at the beginning of \fIwe_wordv.\fR +.fi \fR +.P +.RE +.P +The +.IR +header shall define the following symbolic constants for use as flags +for the +\fIwordexp\fR() +function: +.IP WRDE_APPEND 14 +Append words to those previously generated. +.IP WRDE_DOOFFS 14 +Number of null pointers to prepend to +.IR we_wordv . +.IP WRDE_NOCMD 14 +Fail if 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 is 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 +.IR +header shall define the following symbolic constants 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. +.P +The +.IR +header shall define the +.BR size_t +type as described in +.IR . +.P +The following shall be declared as functions and may also be defined as +macros. Function prototypes shall be provided. +.sp +.RS 4 +.nf +\fB +int wordexp(const char *restrict, wordexp_t *restrict, int); +void wordfree(wordexp_t *); +.fi \fR +.P +.RE +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.6" ", " "Word Expansions" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/admin.1p b/man-pages-posix-2013/man1p/admin.1p new file mode 100644 index 0000000..485769e --- /dev/null +++ b/man-pages-posix-2013/man1p/admin.1p @@ -0,0 +1,510 @@ +'\" et +.TH ADMIN "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +admin +\(em create and administer SCCS files (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +admin \(mii\fB[\fIname\fB] [\fR\(min\fB] [\fR\(mia \fIlogin\fB] [\fR\(mid \fIflag\fB] [\fR\(mie \fIlogin\fB] [\fR\(mif \fIflag\fB] + [\fR\(mim \fImrlist\fB] [\fR\(mir \fIrel\fB] [\fR\(mit\fB[\fIname\fB] [\fR\(miy\fB[\fIcomment\fB]] \fInewfile\fR +.P +admin \(min\fB [\fR\(mia \fIlogin\fB] [\fR\(mid \fIflag\fB] [\fR\(mie \fIlogin\fB] [\fR\(mif \fIflag\fB] [\fR\(mim \fImrlist\fB] + [\fR\(mit\fB[\fIname\fB]] [\fR\(miy\fB[\fIcomment\fB]] \fInewfile\fR... +.P +admin \fB[\fR\(mia \fIlogin\fB] [\fR\(mid \fIflag\fB] [\fR\(mim \fImrlist\fB] [\fR\(mir \fIrel\fB] [\fR\(mit\fB[\fIname\fB]]\fR \fIfile\fR... +.P +admin \(mih \fIfile\fR... +.P +admin \(miz \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR admin +utility shall create new SCCS files or change parameters of existing +ones. If a named file does not exist, it shall be created, and its +parameters shall be initialized according to the specified options. +Parameters not initialized by an option shall be assigned a default +value. If a named file does exist, parameters corresponding to +specified options shall be changed, and other parameters shall be left +as is. +.P +All SCCS filenames supplied by the application shall be of the form +s.\fIfilename\fP. New SCCS files shall be given read-only permission +mode. Write permission in the parent directory is required to create a +file. All writing done by +.IR admin +shall be to a temporary +.IR x-file , +named x.\fIfilename\fP (see +.IR "\fIget\fR\^") +created with read-only mode if +.IR admin +is creating a new SCCS file, or created with the same mode as that of +the SCCS file if the file already exists. After successful execution of +.IR admin , +the SCCS file shall be removed (if it exists), and the +.IR x-file +shall be renamed with the name of the SCCS file. This ensures that +changes are made to the SCCS file only if no errors occur. +.P +The +.IR admin +utility shall also use a transient lock file (named z.\fIfilename\fP), +which is used to prevent simultaneous updates to the SCCS file; see +.IR "\fIget\fR\^". +.SH OPTIONS +The +.IR admin +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that the +.BR \(mii , +.BR \(mit , +and +.BR \(miy +options have optional option-arguments. These optional option-arguments +shall not be presented as separate arguments. The following options are +supported: +.IP "\fB\(min\fP" 10 +Create a new SCCS file. When +.BR \(min +is used without +.BR \(mii , +the SCCS file shall be created with control information but without any +file data. +.IP "\fB\(mii[\fIname\fB]\fR" 10 +Specify the +.IR name +of a file from which the text for a new SCCS file shall be taken. The +text constitutes the first delta of the file (see the +.BR \(mir +option for the delta numbering scheme). If the +.BR \(mii +option is used, but the +.IR name +option-argument is omitted, the text shall be obtained by reading the +standard input. If this option is omitted, the SCCS file shall be +created with control information but without any file data. The +.BR \(mii +option implies the +.BR \(min +option. +.IP "\fB\(mir\ \fISID\fR" 10 +Specify the SID of the initial delta to be inserted. This SID shall be +a trunk SID; that is, the branch and sequence numbers shall be zero or +missing. The level number is optional, and defaults to 1. +.IP "\fB\(mit[\fIname\fB]\fR" 10 +Specify the +.IR name +of a file from which descriptive text for the SCCS file shall be taken. +In the case of existing SCCS files (neither +.BR \(mii +nor +.BR \(min +is specified): +.RS 10 +.IP " *" 4 +A +.BR \(mit +option without a +.IR name +option-argument shall cause the removal of descriptive text (if any) +currently in the SCCS file. +.IP " *" 4 +A +.BR \(mit +option with a +.IR name +option-argument shall cause the text (if any) in the named file to +replace the descriptive text (if any) currently in the SCCS file. +.RE +.IP "\fB\(mif\ \fIflag\fR" 10 +Specify a +.IR flag , +and, possibly, a value for the +.IR flag , +to be placed in the SCCS file. Several +.BR \(mif +options may be supplied on a single +.IR admin +command line. Implementations shall recognize the following flags +and associated values: +.RS 10 +.IP "\fBb\fP" 8 +Allow use of the +.BR \(mib +option on a +.IR get +command to create branch deltas. +.IP "\fBc\fIceil\fR" 8 +Specify the highest release (that is, ceiling), a number less than or +equal to 9\|999, which may be retrieved by a +.IR get +command for editing. The default value for an unspecified +.BR c +flag shall be 9\|999. +.IP "\fBf\fIfloor\fR" 8 +Specify the lowest release (that is, floor), a number greater than 0 +but less than 9\|999, which may be retrieved by a +.IR get +command for editing. The default value for an unspecified +.BR f +flag shall be 1. +.IP "\fBd\fISID\fR" 8 +Specify the default delta number (SID) to be used by a +.IR get +command. +.IP "\fBi\fIstr\fR" 8 +Treat the ``No ID keywords'' message issued by +.IR get +or +.IR delta +as a fatal error. In the absence of this flag, the message is only a +warning. The message is issued if no SCCS identification keywords (see +.IR "\fIget\fR\^") +are found in the text retrieved or stored in the SCCS file. If a value +is supplied, the application shall ensure that the keywords exactly +match the given string; however, the string shall contain a keyword, +and no embedded + +characters. +.IP "\fBj\fP" 8 +Allow concurrent +.IR get +commands for editing on the same SID of an SCCS file. This allows +multiple concurrent updates to the same version of the SCCS file. +.IP "\fBl\fIlist\fR" 8 +Specify a +.IR list +of releases to which deltas can no longer be made (that is, +.IR get +.BR \(mie +against one of these locked releases fails). Conforming applications +shall use the following syntax to specify a +.IR list . +Implementations may accept additional forms as an extension: +.RS 8 +.sp +.RS 4 +.nf +\fB + ::= a | + ::= | , + ::= +.fi \fR +.P +.RE +.P +The character +.IR a +in the +.IR list +shall be equivalent to specifying all releases for the named SCCS file. +The non-terminal <\fISID\fP> in range shall be the delta number of an +existing delta associated with the SCCS file. +.RE +.IP "\fBn\fP" 8 +Cause +.IR delta +to create a null delta in each of those releases (if any) being skipped +when a delta is made in a new release (for example, in making delta 5.1 +after delta 2.7, releases 3 and 4 are skipped). These null deltas shall +serve as anchor points so that branch deltas may later be created from +them. The absence of this flag shall cause skipped releases to be +nonexistent in the SCCS file, preventing branch deltas from being +created from them in the future. During the initial creation of an SCCS +file, the +.BR n +flag may be ignored; that is, if the +.BR \(mir +option is used to set the release number of the initial SID to a value +greater than 1, null deltas need not be created for the ``skipped'' +releases. +.IP "\fBq\fItext\fR" 8 +Substitute user-definable +.IR text +for all occurrences of the %\fBQ\fP% keyword in the SCCS file text +retrieved by +.IR get . +.IP "\fBm\fImod\fR" 8 +Specify the module name of the SCCS file substituted for all +occurrences of the %\fBM\fP% keyword in the SCCS file text retrieved by +.IR get . +If the +.BR m +flag is not specified, the value assigned shall be the name of the SCCS +file with the leading +.BR '.' +removed. +.IP "\fBt\fItype\fR" 8 +Specify the +.IR type +of module in the SCCS file substituted for all occurrences of the +%\fBY\fP% keyword in the SCCS file text retrieved by +.IR get . +.IP "\fBv\fIpgm\fR" 8 +Cause +.IR delta +to prompt for modification request (MR) numbers as the reason for +creating a delta. The optional value specifies the name of an MR +number validation program. (If this flag is set when creating an SCCS +file, the application shall ensure that the +.BR m +option is also used even if its value is null.) +.RE +.IP "\fB\(mid\ \fIflag\fR" 10 +Remove (delete) the specified +.IR flag +from an SCCS file. Several +.BR \(mid +options may be supplied on a single +.IR admin +command. See the +.BR \(mif +option for allowable +.IR flag +names. (The +.BR l \c +.IR list +flag gives a +.IR list +of releases to be unlocked. See the +.BR \(mif +option for further description of the +.BR l +flag and the syntax of a +.IR list .) +.IP "\fB\(mia\ \fIlogin\fR" 10 +Specify a +.IR login +name, or numerical group ID, to be added to the list of users who may +make deltas (changes) to the SCCS file. A group ID shall be equivalent +to specifying all +.IR login +names common to that group ID. Several +.BR \(mia +options may be used on a single +.IR admin +command line. As many +.IR login s, +or numerical group IDs, as desired may be on the list simultaneously. +If the list of users is empty, then anyone may add deltas. If +.IR login +or group ID is preceded by a +.BR '!' , +the users so specified shall be denied permission to make deltas. +.IP "\fB\(mie\ \fIlogin\fR" 10 +Specify a +.IR login +name, or numerical group ID, to be erased from the list of users +allowed to make deltas (changes) to the SCCS file. Specifying a group +ID is equivalent to specifying all +.IR login +names common to that group ID. Several +.BR \(mie +options may be used on a single +.IR admin +command line. +.IP "\fB\(miy[\fIcomment\fB]\fR" 10 +Insert the +.IR comment +text into the SCCS file as a comment for the initial delta in a manner +identical to that of +.IR delta . +In the POSIX locale, omission of the +.BR \(miy +option shall result in a default comment line being inserted in +the form: +.RS 10 +.sp +.RS 4 +.nf +\fB +"date and time created %s %s by %s", <\fIdate\fR>, <\fItime\fR>, <\fIlogin\fR> +.fi \fR +.P +.RE +.P +where <\fIdate\fP> is expressed in the format of the +.IR date +utility's +.BR %y /\c +.BR %m /\c +.BR %d +conversion specification, <\fItime\fP> in the format of the +.IR date +utility's +.BR %T +conversion specification format, and <\fIlogin\fP> is the login name of +the user creating the file. +.RE +.IP "\fB\(mim\ \fImrlist\fR" 10 +Insert the list of modification request (MR) numbers into the SCCS +file as the reason for creating the initial delta in a manner identical to +.IR delta . +The application shall ensure that the +.BR v +flag is set and the MR numbers are validated if the +.BR v +flag has a value (the name of an MR number validation program). +A diagnostic message shall be written if the +.BR v +flag is not set or MR validation fails. +.IP "\fB\(mih\fP" 10 +Check the structure of the SCCS file and compare the newly computed +checksum with the checksum that is stored in the SCCS file. If the +newly computed checksum does not match the checksum in the SCCS file, a +diagnostic message shall be written. +.IP "\fB\(miz\fR" 10 +Recompute the SCCS file checksum and store it in the first line of the +SCCS file (see the +.BR \(mih +option above). Note that use of this option on a truly corrupted +file may prevent future detection of the corruption. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an existing SCCS file or a directory. If +.IR file +is a directory, the +.IR admin +utility shall behave as though each file in the directory were +specified as a named file, except that non-SCCS files (last component +of the pathname does not begin with +.BR s. ) +and unreadable files shall be silently ignored. +.IP "\fInewfile\fR" 10 +A pathname of an SCCS file to be created. +.P +If exactly one +.IR file +or +.IR newfile +operand appears, and it is +.BR '\(mi' , +the standard input shall be read; each line of the standard input shall +be taken to be the name of an SCCS file to be processed. Non-SCCS files +and unreadable files shall be silently ignored. +.SH STDIN +The standard input shall be a text file used only if +.BR \(mii +is specified without an option-argument or if a +.IR file +or +.IR newfile +operand is specified as +.BR '\(mi' . +If the first character of any standard input line is + +in the POSIX locale, the results are unspecified. +.SH "INPUT FILES" +The existing SCCS files shall be text files of an unspecified format. +.P +The application shall ensure that the file named by the +.BR \(mii +option's +.IR name +option-argument shall be a text file; if the first character of any +line in this file is + +in the POSIX locale, the results are unspecified. If this file contains +more than 99\|999 lines, the number of lines recorded in the header for +this file shall be 99\|999 for this delta. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR admin : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and the +contents of the default +.BR \(miy +comment. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +Any SCCS files created shall be text files of an unspecified format. +During processing of a +.IR file , +a locking +.IR z-file , +as described in +.IR "\fIget\fR\^", +may be created and deleted. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +It is recommended that directories containing SCCS files be writable by +the owner only, and that SCCS files themselves be read-only. The mode +of the directories should allow only the owner to modify SCCS files +contained in the directories. The mode of the SCCS files prevents any +modification at all except by SCCS commands. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdelta\fR\^", +.IR "\fIget\fR\^", +.IR "\fIprs\fR\^", +.IR "\fIwhat\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/alias.1p b/man-pages-posix-2013/man1p/alias.1p new file mode 100644 index 0000000..bf15887 --- /dev/null +++ b/man-pages-posix-2013/man1p/alias.1p @@ -0,0 +1,222 @@ +'\" et +.TH ALIAS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +alias +\(em define or display aliases +.SH SYNOPSIS +.LP +.nf +alias \fB[\fIalias-name\fB[\fR=\fIstring\fB]\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR alias +utility shall create or redefine alias definitions or write the values +of existing alias definitions to standard output. An alias definition +provides a string value that shall replace a command name when it is +encountered; see +.IR "Section 2.3.1" ", " "Alias Substitution". +.P +An alias definition shall affect the current shell execution +environment and the execution environments of the subshells of the +current shell. When used as specified by this volume of POSIX.1\(hy2008, the alias definition +shall not affect the parent process of the current shell nor any +utility environment invoked by the shell; see +.IR "Section 2.12" ", " "Shell Execution Environment". +.SH OPTIONS +None. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIalias-name\fR" 10 +Write the alias definition to standard output. +.IP "\fIalias-name\fP=\fIstring\fR" 10 +.br +Assign the value of +.IR string +to the alias +.IR alias-name . +.P +If no operands are given, all alias definitions shall be written to +standard output. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR alias : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The format for displaying aliases (when no operands or only +.IR name +operands are specified) shall be: +.sp +.RS 4 +.nf +\fB +"%s=%s\en", \fIname\fR, \fIvalue\fR +.fi \fR +.P +.RE +.P +The +.IR value +string shall be written with appropriate quoting so that it is suitable +for reinput to the shell. See the description of shell quoting in +.IR "Section 2.2" ", " "Quoting". +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +One of the +.IR name +operands specified did not have an alias definition, or an error +occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +.IP " 1." 4 +Create a short alias for a commonly used +.IR ls +command: +.RS 4 +.sp +.RS 4 +.nf +\fB +alias lf="ls \(miCF" +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +Create a simple ``redo'' command to repeat previous entries in the +command history file: +.RS 4 +.sp +.RS 4 +.nf +\fB +alias r='fc \(mis' +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +Use 1K units for +.IR du : +.RS 4 +.sp +.RS 4 +.nf +\fB +alias du=du\e \(mik +.fi \fR +.P +.RE +.RE +.IP " 4." 4 +Set up +.IR nohup +so that it can deal with an argument that is itself an alias name: +.RS 4 +.sp +.RS 4 +.nf +\fB +alias nohup="nohup " +.fi \fR +.P +.RE +.RE +.SH RATIONALE +The +.IR alias +description is based on historical KornShell implementations. Known +differences exist between that and the C shell. The KornShell version +was adopted to be consistent with all the other KornShell features in +\&this volume of POSIX.1\(hy2008, such as command line editing. +.P +Since +.IR alias +affects the current shell execution environment, it is generally +provided as a shell regular built-in. +.P +Historical versions of the KornShell have allowed aliases to be +exported to scripts that are invoked by the same shell. This is +triggered by the +.IR alias +.BR \(mix +flag; it is allowed by this volume of POSIX.1\(hy2008 only when an explicit extension such as +.BR \(mix +is used. The standard developers considered that aliases were of use +primarily to interactive users and that they should normally not affect +shell scripts called by those users; functions are available to such +scripts. +.P +Historical versions of the KornShell had not written aliases in a +quoted manner suitable for reentry to the shell, but this volume of POSIX.1\(hy2008 has made +this a requirement for all similar output. Therefore, consistency was +chosen over this detail of historical practice. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.9.5" ", " "Function Definition Command" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/ar.1p b/man-pages-posix-2013/man1p/ar.1p new file mode 100644 index 0000000..760dd6f --- /dev/null +++ b/man-pages-posix-2013/man1p/ar.1p @@ -0,0 +1,727 @@ +'\" et +.TH AR "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ar +\(em create and maintain library archives +.SH SYNOPSIS +.LP +.nf +ar \(mid \fB[\fR\(miv\fB] \fIarchive file\fR... +.P +ar \(mim \fB[\fR\(miv\fB] \fIarchive file\fR... +ar \(mim \(mia \fB[\fR\(miv\fB] \fIposname archive file\fR... +ar \(mim \(mib \fB[\fR\(miv\fB] \fIposname archive file\fR... +ar \(mim \(mii \fB[\fR\(miv\fB] \fIposname archive file\fR... +.P +ar \(mip \fB[\fR\(miv\fB] [\fR\(mis\fB] \fIarchive\fB [\fIfile\fR...\fB]\fR +.P +ar \(miq \fB[\fR\(micv\fB] \fIarchive file\fR... +.P +ar \(mir \fB[\fR\(micuv\fB] \fIarchive file\fR... +.P +ar \(mir \(mia \fB[\fR\(micuv\fB] \fIposname archive file\fR... +ar \(mir \(mib \fB[\fR\(micuv\fB] \fIposname archive file\fR... +ar \(mir \(mii \fB[\fR\(micuv\fB] \fIposname archive file\fR... +.P +ar \(mit \fB[\fR\(miv\fB] [\fR\(mis\fB] \fIarchive \fB[\fIfile\fR...\fB]\fR +.P +ar \(mix \fB[\fR\(miv\fB] [\fR\(misCT\fB] \fIarchive \fB[\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +.P +The +.IR ar +utility is part of the Software Development Utilities option. +.P +The +.IR ar +utility can be used to create and maintain groups of files combined +into an archive. Once an archive has been created, new files can be +added, and existing files in an archive can be extracted, deleted, or +replaced. When an archive consists entirely of valid object files, the +implementation shall format the archive so that it is usable as a +library for link editing (see +.IR c99 +and +.IR fort77 ). +When some of the archived files are not valid object files, the +suitability of the archive for library use is undefined. +If an archive consists entirely of printable files, the entire +archive shall be printable. +.P +When +.IR ar +creates an archive, it creates administrative information indicating +whether a symbol table is present in the archive. When there is at +least one object file that +.IR ar +recognizes as such in the archive, an archive symbol table shall be +created in the archive and maintained by +.IR ar ; +it is used by the link editor to search the archive. Whenever the +.IR ar +utility is used to create or update the contents of such an archive, +the symbol table shall be rebuilt. The +.BR \(mis +option shall force the symbol table to be rebuilt. +.P +All +.IR file +operands can be pathnames. However, files within archives shall be +named by a filename, which is the last component of the pathname used +when the file was entered into the archive. The comparison of +.IR file +operands to the names of files in archives shall be performed by +comparing the last component of the operand to the name of the file +in the archive. +.P +It is unspecified whether multiple files in the archive may be +identically named. In the case of such files, however, each +.IR file +and +.IR posname +operand shall match only the first file in the archive having a name +that is the same as the last component of the operand. +.SH OPTIONS +The +.IR ar +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except for Guideline 9. +.P +The following options shall be supported: +.IP "\fB\(mia\fP" 10 +Position new files in the archive after the file named by the +.IR posname +operand. +.IP "\fB\(mib\fP" 10 +Position new files in the archive before the file named by the +.IR posname +operand. +.IP "\fB\(mic\fP" 10 +Suppress the diagnostic message that is written to standard error by +default when the archive +.IR archive +is created. +.IP "\fB\(miC\fP" 10 +Prevent extracted files from replacing like-named files in the +file system. This option is useful when +.BR \(miT +is also used, to prevent truncated filenames from replacing files with +the same prefix. +.IP "\fB\(mid\fP" 10 +Delete one or more +.IR file s +from +.IR archive . +.IP "\fB\(mii\fP" 10 +Position new files in the archive before the file in the archive +named by the +.IR posname +operand (equivalent to +.BR \(mib ). +.IP "\fB\(mim\fP" 10 +Move the named files in the archive. The +.BR \(mia , +.BR \(mib , +or +.BR \(mii +options with the +.IR posname +operand indicate the position; otherwise, move the names files in the +archive to the end of the archive. +.IP "\fB\(mip\fP" 10 +Write the contents of the +.IR file s +in the archive named by +.IR file +operands from +.IR archive +to the standard output. If no +.IR file +operands are specified, the contents of all files in the archive shall +be written in the order of the archive. +.IP "\fB\(miq\fP" 10 +Append the named files to the end of the archive. In this case +.IR ar +does not check whether the added files are already in the archive. +This is useful to bypass the searching otherwise done when creating a +large archive piece by piece. +.IP "\fB\(mir\fP" 10 +Replace or add +.IR file s +to +.IR archive . +If the archive named by +.IR archive +does not exist, a new archive shall be created and a diagnostic message +shall be written to standard error (unless the +.BR \(mic +option is specified). If no +.IR file s +are specified and the +.IR archive +exists, the results are undefined. Files that replace existing files in +the archive shall not change the order of the archive. Files that do +not replace existing files in the archive shall be appended to the +archive +unless a +.BR \(mia , +.BR \(mib , +or +.BR \(mii +option specifies another position. +.IP "\fB\(mis\fP" 10 +Force the regeneration of the archive symbol table even if +.IR ar +is not invoked with an option that modifies the archive contents. This +option is useful to restore the archive symbol table after it has been +stripped; see +.IR strip . +.IP "\fB\(mit\fP" 10 +Write a table of contents of +.IR archive +to the standard output. Only the files specified by the +.IR file +operands shall be included in the written list. If no +.IR file +operands are specified, all files in +.IR archive +shall be included in the order of the archive. +.IP "\fB\(miT\fP" 10 +Allow filename truncation of extracted files whose archive names are +longer than the file system can support. By default, extracting a file +with a name that is too long shall be an error; a diagnostic message +shall be written and the file shall not be extracted. +.IP "\fB\(miu\fP" 10 +Update older files in the archive. When used with the +.BR \(mir +option, files in the archive shall be replaced only if the +corresponding +.IR file +has a modification time that is at least as new as the modification +time of the file in the archive. +.IP "\fB\(miv\fP" 10 +Give verbose output. When used with the option characters +.BR \(mid , +.BR \(mir , +or +.BR \(mix , +write a detailed file-by-file description of the archive creation and +maintenance activity, as described in the STDOUT section. +.RS 10 +.P +When used with +.BR \(mip , +write the name of the file in the archive to the standard output before +writing the file in the archive itself to the standard output, as +described in the STDOUT section. +.P +When used with +.BR \(mit , +include a long listing of information about the files in the archive, +as described in the STDOUT section. +.RE +.IP "\fB\(mix\fP" 10 +Extract the files in the archive named by the +.IR file +operands from +.IR archive . +The contents of the archive shall not be changed. If no +.IR file +operands are given, all files in the archive shall be extracted. The +modification time of each file extracted shall be set to the time the +file is extracted from the archive. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIarchive\fR" 10 +A pathname of the archive. +.IP "\fIfile\fR" 10 +A pathname. Only the last component shall be used when comparing +against the names of files in the archive. If two or more +.IR file +operands have the same last pathname component (basename), the results +are unspecified. The implementation's archive format shall not truncate +valid filenames of files added to or replaced in the archive. +.IP "\fIposname\fR" 10 +The name of a file in the archive, used for relative positioning; see +options +.BR \(mim +and +.BR \(mir . +.SH STDIN +Not used. +.SH "INPUT FILES" +The archive named by +.IR archive +shall be a file in the format created by +.IR ar +.BR \(mir . +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR ar : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILC_TIME\fP" 10 +Determine the format and content for date and time strings written by +.IR ar +.BR \(mitv . +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITMPDIR\fP" 10 +Determine the pathname that overrides the default directory for +temporary files, if any. +.IP "\fITZ\fP" 10 +Determine the timezone used to calculate date and time strings written +by +.IR ar +.BR \(mitv . +If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If the +.BR \(mid +option is used with the +.BR \(miv +option, the standard output format shall be: +.sp +.RS 4 +.nf +\fB +"d \(mi %s\en", <\fIfile\fR> +.fi \fR +.P +.RE +.P +where +.IR file +is the operand specified on the command line. +.P +If the +.BR \(mip +option is used with the +.BR \(miv +option, +.IR ar +shall precede the contents of each file with: +.sp +.RS 4 +.nf +\fB +"\en<%s>\en\en", <\fIfile\fR> +.fi \fR +.P +.RE +.P +where +.IR file +is the operand specified on the command line, if +.IR file +operands were specified, and the name of the file in the archive if +they were not. +.P +If the +.BR \(mir +option is used with the +.BR \(miv +option: +.IP " *" 4 +If +.IR file +is already in the archive, the standard output format shall be: +.RS 4 +.sp +.RS 4 +.nf +\fB +"r \(mi %s\en", <\fIfile\fR> +.fi \fR +.P +.RE +.P +where <\fIfile\fP> is the operand specified on the command line. +.RE +.IP " *" 4 +If +.IR file +is not already in the archive, the standard output format shall be: +.RS 4 +.sp +.RS 4 +.nf +\fB +"a \(mi %s\en", <\fIfile\fR> +.fi \fR +.P +.RE +.P +where <\fIfile\fP> is the operand specified on the command line. +.RE +.P +If the +.BR \(mit +option is used, +.IR ar +shall write the names of the files in the archive to the standard +output in the format: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIfile\fR> +.fi \fR +.P +.RE +.P +where +.IR file +is the operand specified on the command line, if +.IR file +operands were specified, or the name of the file in the archive if they +were not. +.P +If the +.BR \(mit +option is used with the +.BR \(miv +option, the standard output format shall be: +.sp +.RS 4 +.nf +\fB +"%s %u/%u %u %s %d %d:%d %d %s\en", <\fImember mode\fR>, <\fIuser ID\fR>, + <\fIgroup ID\fR>, <\fInumber of bytes in member\fR>, + <\fIabbreviated month\fR>, <\fIday-of-month\fR>, <\fIhour\fR>, + <\fIminute\fR>, <\fIyear\fR>, <\fIfile\fR> +.fi \fR +.P +.RE +.P +where: +.IP "<\fIfile\fR>" 10 +Shall be the operand specified on the command line, if +.IR file +operands were specified, or the name of the file in the archive if they +were not. +.IP "<\fImember\ mode\fR>" 10 +.br +Shall be formatted the same as the <\fIfile\ mode\fR> string defined in +the STDOUT section of +.IR ls , +except that the first character, the <\fIentry\ type\fR>, is not used; +the string represents the file mode of the file in the archive at the +time it was added to or replaced in the archive. +.br +.P +The following represent the last-modification time of a file when it +was most recently added to or replaced in the archive: +.IP "<\fIabbreviated\ month\fR>" 10 +.br +Equivalent to the format of the +.BR %b +conversion specification format in +.IR date . +.IP "<\fIday-of-month\fR>" 10 +.br +Equivalent to the format of the +.BR %e +conversion specification format in +.IR date . +.IP "<\fIhour\fR>" 10 +Equivalent to the format of the +.BR %H +conversion specification format in +.IR date . +.IP "<\fIminute\fR>" 10 +Equivalent to the format of the +.BR %M +conversion specification format in +.IR date . +.IP "<\fIyear\fR>" 10 +Equivalent to the format of the +.BR %Y +conversion specification format in +.IR date . +.P +When +.IR LC_TIME +does not specify the POSIX locale, a different format and order of +presentation of these fields relative to each other may be used in a +format appropriate in the specified locale. +.P +If the +.BR \(mix +option is used with the +.BR \(miv +option, the standard output format shall be: +.sp +.RS 4 +.nf +\fB +"x \(mi %s\en", <\fIfile\fR> +.fi \fR +.P +.RE +.P +where +.IR file +is the operand specified on the command line, if +.IR file +operands were specified, or the name of the file in the archive if they +were not. +.SH STDERR +The standard error shall be used only for diagnostic messages. +The diagnostic message about creating a new archive when +.BR \(mic +is not specified shall not modify the exit status. +.SH "OUTPUT FILES" +Archives are files with unspecified formats. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The archive format is not described. It is recognized that there are +several known +.IR ar +formats, which are not compatible. The +.IR ar +utility is included, however, to allow creation of archives that +are intended for use only on one machine. The archive is +specified as a file, and it can be moved as a file. This does allow an +archive to be moved from one machine to another machine that uses the +same implementation of +.IR ar . +.P +Utilities such as +.IR pax +(and its forebears +.IR tar +and +.IR cpio ) +also provide portable ``archives''. This is a not a duplication; the +.IR ar +utility is included to provide an interface primarily for +.IR make +and the compilers, based on a historical model. +.P +In historical implementations, the +.BR \(miq +option (available on XSI-conforming systems) is known to execute +quickly because +.IR ar +does not check on whether the added members are already in the +archive. This is useful to bypass the searching otherwise done when +creating a large archive piece-by-piece. These remarks may but need not +remain true for a brand new implementation of this utility; hence, +these remarks have been moved into the RATIONALE. +.P +BSD implementations historically required applications to provide the +.BR \(mis +option whenever the archive was supposed to contain a symbol table. +As in this volume of POSIX.1\(hy2008, System V historically creates or updates an archive symbol +table whenever an object file is removed from, added to, or updated +in the archive. +.P +The OPERANDS section requires what might seem to be true without +specifying it: the archive cannot truncate the filenames below +{NAME_MAX}. +Some historical implementations do so, however, causing unexpected +results for the application. Therefore, this volume of POSIX.1\(hy2008 makes the requirement +explicit to avoid misunderstandings. +.P +According to the System V documentation, the options +.BR \(midmpqrtx +are not required to begin with a + +(\c +.BR '\(mi' ). +This volume of POSIX.1\(hy2008 requires that a conforming application use the leading +. +.P +The archive format used by the 4.4 BSD implementation is documented in +this RATIONALE as an example: +.sp +.RS +A file created by +.IR ar +begins with the ``magic'' string +.BR \(dq!\en\(dq . +The rest of the archive is made up of objects, each of which is +composed of a header for a file, a possible filename, and the file +contents. The header is portable between machine architectures, and, if +the file contents are printable, the archive is itself printable. +.P +The header is made up of six ASCII fields, followed by a two-character +trailer. The fields are the object name (16 characters), the file last +modification time (12 characters), the user and group IDs (each 6 +characters), the file mode (8 characters), and the file size (10 +characters). All numeric fields are in decimal, except for the file +mode, which is in octal. +.P +The modification time is the file +.IR st_mtime +field. The user and group IDs are the file +.IR st_uid +and +.IR st_gid +fields. The file mode is the file +.IR st_mode +field. The file size is the file +.IR st_size +field. The two-byte trailer is the string +.BR \(dq`\(dq . +.P +Only the name field has any provision for overflow. If any filename is +more than 16 characters in length or contains an embedded space, the +string +.BR \(dq#1/\(dq +followed by the ASCII length of the name is written in the name field. +The file size (stored in the archive header) is incremented by the +length of the name. The name is then written immediately following the +archive header. +.P +Any unused characters in any of these fields are written as + +characters. If any fields are their particular maximum number of +characters in length, there is no separation between the fields. +.P +Objects in the archive are always an even number of bytes long; files +that are an odd number of bytes long are padded with a +, +although the size in the header does not reflect this. +.RE +.P +The +.IR ar +utility description requires that (when all its members are valid +object files) +.IR ar +produce an object code library, which the linkage editor can use to +extract object modules. If the linkage editor needs a symbol table to +permit random access to the archive, +.IR ar +must provide it; however, +.IR ar +does not require a symbol table. +.P +The BSD +.BR \(mio +option was omitted. It is a rare conforming application that uses +.IR ar +to extract object code from a library with concern for its modification +time, since this can only be of importance to +.IR make . +Hence, since this functionality is not deemed important for +applications portability, the modification time of the extracted files +is set to the current time. +.P +There is at least one known implementation (for a small computer) that +can accommodate only object files for that system, disallowing mixed +object and other files. The ability to handle any type of file is not +only historical practice for most implementations, but is also a +reasonable expectation. +.P +Consideration was given to changing the output format of +.IR ar +.BR \(mitv +to the same format as the output of +.IR ls +.BR \(mil . +This would have made parsing the output of +.IR ar +the same as that of +.IR ls . +This was rejected in part because the current +.IR ar +format is commonly used and changes would break historical usage. +Second, +.IR ar +gives the user ID and group ID in numeric format separated by a +. +Changing this to be the user name and group name would not be correct +if the archive were moved to a machine that contained a different user +database. Since +.IR ar +cannot know whether the archive was generated on the same machine, +it cannot tell what to report. +.P +The text on the +.BR \(miur +option combination is historical practice\(emsince one filename can +easily represent two different files (for example, +.BR /a/foo +and +.BR /b/foo ), +it is reasonable to replace the file in the archive even when the +modification time in the archive is identical to that in the file +system. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIc99\fR\^", +.IR "\fIdate\fR\^", +.IR "\fIfort77\fR\^", +.IR "\fIpax\fR\^", +.IR "\fIstrip\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +.IR "\fB\fP", +description of +{POSIX_NO_TRUNC} +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/asa.1p b/man-pages-posix-2013/man1p/asa.1p new file mode 100644 index 0000000..2f75607 --- /dev/null +++ b/man-pages-posix-2013/man1p/asa.1p @@ -0,0 +1,212 @@ +'\" et +.TH ASA "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +asa +\(em interpret carriage-control characters +.SH SYNOPSIS +.LP +.nf +asa \fB[\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR asa +utility shall write its input files to standard output, mapping +carriage-control characters from the text files to line-printer control +sequences in an implementation-defined manner. +.P +The first character of every line shall be removed from the input, and +the following actions are performed. +.P +If the character removed is: +.IP 10 +The rest of the line is output without change. +.IP 0 10 +A + +is output, then the rest of the input line. +.IP 1 10 +One or more implementation-defined characters that causes an advance +to the next page shall be output, followed by the rest of the input +line. +.IP "\fR+\fP" 10 +The + +of the previous line shall be replaced with one or more +implementation-defined characters that causes printing to return to +column position 1, followed by the rest of the input line. If the +.BR '\(pl' +is the first character in the input, it shall be equivalent to +. +.P +The action of the +.IR asa +utility is unspecified upon encountering any character other than those +listed above as the first character in a line. +.SH OPTIONS +None. +.SH OPERANDS +.IP "\fIfile\fR" 10 +A pathname of a text file used for input. If no +.IR file +operands are specified, the standard input shall be used. +.SH STDIN +The standard input shall be used if no +.IR file +operands are specified, and shall be used if a +.IR file +operand is +.BR '\(mi' +and the implementation treats the +.BR '\(mi' +as meaning standard input. +Otherwise, the standard input shall not be used. +See the INPUT FILES section. +.SH "INPUT FILES" +The input files shall be text files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR asa : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall be the text from the input file modified as +described in the DESCRIPTION section. +.SH STDERR +None. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All input files were output successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +.IP " 1." 4 +The following command: +.RS 4 +.sp +.RS 4 +.nf +\fB +asa \fIfile\fR +.fi \fR +.P +.RE +.P +permits the viewing of +.IR file +(created by a program using FORTRAN-style carriage-control characters) +on a terminal. +.RE +.IP " 2." 4 +The following command: +.RS 4 +.sp +.RS 4 +.nf +\fB +a.out | asa | lp +.fi \fR +.P +.RE +.P +formats the FORTRAN output of +.BR a.out +and directs it to the printer. +.RE +.SH RATIONALE +The +.IR asa +utility is needed to map ``standard'' FORTRAN 77 output into a form +acceptable to contemporary printers. Usually, +.IR asa +is used to pipe data to the +.IR lp +utility; see +.IR lp . +.P +This utility is generally used only by FORTRAN programs. The +standard developers decided to retain +.IR asa +to avoid breaking the historical large base of FORTRAN applications +that put carriage-control characters in their output files. There is no +requirement that a system have a FORTRAN compiler in order to run +applications that need +.IR asa . +.P +Historical implementations have used an ASCII + +in response to a 1 and an ASCII + +in response to a +.BR '\(pl' . +It is suggested that implementations treat characters other than 0, 1, +and +.BR '\(pl' +as + +in the absence of any compelling reason to do otherwise. However, the +action is listed here as ``unspecified'', permitting an implementation +to provide extensions to access fast multiple-line slewing and channel +seeking in a non-portable manner. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfort77\fR\^", +.IR "\fIlp\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/at.1p b/man-pages-posix-2013/man1p/at.1p new file mode 100644 index 0000000..fab231c --- /dev/null +++ b/man-pages-posix-2013/man1p/at.1p @@ -0,0 +1,798 @@ +'\" et +.TH AT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +at +\(em execute commands at a later time +.SH SYNOPSIS +.LP +.nf +at \fB[\fR\(mim\fB] [\fR\(mif \fIfile\fB] [\fR\(miq \fIqueuename\fB] \fR\(mit \fItime_arg\fR +.P +at \fB[\fR\(mim\fB] [\fR\(mif \fIfile\fB] [\fR\(miq \fIqueuename\fB] \fItimespec\fR... +.P +at \(mir \fIat_job_id\fR... +.P +at \(mil \(miq \fIqueuename\fR +.P +at \(mil \fB[\fIat_job_id\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR at +utility shall read commands from standard input and group them together +as an +.IR at-job , +to be executed at a later time. +.P +The at-job shall be executed in a separate invocation of the shell, +running in a separate process group with no controlling terminal, +except that the environment variables, current working directory, +file creation mask, and other implementation-defined execution-time +attributes in effect when the +.IR at +utility is executed shall be retained and used when the at-job is +executed. +.P +When the at-job is submitted, the +.IR at_job_id +and scheduled time shall be written to standard error. The +.IR at_job_id +is an identifier that shall be a string consisting solely of +alphanumeric characters and the + +character. The +.IR at_job_id +shall be assigned by the system when the job is scheduled such that it +uniquely identifies a particular job. +.P +User notification and the processing of the job's standard output and +standard error are described under the +.BR \(mim +option. +.P +Users shall be permitted to use +.IR at +if their name appears in the file +.BR at.allow +which is located in an implementation-defined directory. +If that file does not exist, the file +.BR at.deny , +which is located in an implementation-defined directory, +shall be checked to determine whether the user shall be denied access to +.IR at . +If neither file exists, only a process with appropriate privileges +shall be allowed to submit a job. If only +.BR at.deny +exists and is empty, global usage shall be permitted. The +.BR at.allow +and +.BR at.deny +files shall consist of one user name per line. +.SH OPTIONS +The +.IR at +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mif\ \fIfile\fR" 10 +Specify the pathname of a file to be used as the source of the at-job, +instead of standard input. +.IP "\fB\(mil\fP" 10 +(The letter ell.) Report all jobs scheduled for the invoking user if no +.IR at_job_id +operands are specified. If +.IR at_job_id s +are specified, report only information for these jobs. The output shall +be written to standard output. +.IP "\fB\(mim\fP" 10 +Send mail to the invoking user after the at-job has run, announcing its +completion. Standard output and standard error produced by the at-job +shall be mailed to the user as well, unless redirected elsewhere. Mail +shall be sent even if the job produces no output. +.RS 10 +.P +If +.BR \(mim +is not used, the job's standard output and standard error shall be +provided to the user by means of mail, unless they are redirected +elsewhere; if there is no such output to provide, the implementation +need not notify the user of the job's completion. +.RE +.IP "\fB\(miq\ \fIqueuename\fR" 10 +.br +Specify in which queue to schedule a job for submission. When used with +the +.BR \(mil +option, limit the search to that particular queue. By default, at-jobs +shall be scheduled in queue +.IR a . +In contrast, queue +.IR b +shall be reserved for batch jobs; see +.IR batch . +The meanings of all other +.IR queuename s +are implementation-defined. If +.BR \(miq +is specified along with either of the +.BR \(mit +.IR time_arg +or +.IR timespec +arguments, the results are unspecified. +.IP "\fB\(mir\fP" 10 +Remove the jobs with the specified +.IR at_job_id +operands that were previously scheduled by the +.IR at +utility. +.IP "\fB\(mit\ \fItime_arg\fR" 10 +Submit the job to be run at the time specified by the +.IR time +option-argument, which the application shall ensure has the format as +specified by the +.IR touch +.BR \(mit +.IR time +utility. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIat_job_id\fR" 10 +The name reported by a previous invocation of the +.IR at +utility at the time the job was scheduled. +.IP "\fItimespec\fR" 10 +Submit the job to be run at the date and time specified. All of the +.IR timespec +operands are interpreted as if they were separated by + +characters and concatenated, and shall be parsed as described in the +grammar at the end of this section. The date and time shall be interpreted +as being in the timezone of the user (as determined by the +.IR TZ +variable), unless a timezone name appears as part of +.IR time , +below. +.RS 10 +.P +In the POSIX locale, the following describes the three parts of the +time specification string. All of the values from the +.IR LC_TIME +categories in the POSIX locale shall be recognized in a +case-insensitive manner. +.IP "\fItime\fR" 10 +The time can be specified as one, two, or four digits. One-digit and +two-digit numbers shall be taken to be hours; four-digit numbers to be +hours and minutes. The time can alternatively be specified as two +numbers separated by a +, +meaning \fIhour\fP:\fIminute\fR. An AM/PM indication (one of the values +from the +.BR am_pm +keywords in the +.IR LC_TIME +locale category) can follow the time; otherwise, a 24-hour clock time +shall be understood. A timezone name can also follow to further qualify +the time. The acceptable timezone names are implementation-defined, +except that they shall be case-insensitive and the string +.BR utc +is supported to indicate the time is in Coordinated Universal Time. +In the POSIX locale, the +.IR time +field can also be one of the following tokens: +.RS 10 +.IP "\fBmidnight\fR" 10 +Indicates the time 12:00 am (00:00). +.IP "\fBnoon\fR" 10 +Indicates the time 12:00 pm. +.IP "\fBnow\fR" 10 +Indicates the current day and time. Invoking +.IR at +<\fBnow\fR> shall submit an at-job for potentially immediate execution +(that is, subject only to unspecified scheduling delays). +.RE +.IP "\fIdate\fR" 10 +An optional +.IR date +can be specified as either a month name (one of the values from the +.BR mon +or +.BR abmon +keywords in the +.IR LC_TIME +locale category) followed by a day number (and possibly year number +preceded by a comma), or a day of the week (one of the values from the +.BR day +or +.BR abday +keywords in the +.IR LC_TIME +locale category). In the POSIX locale, two special days shall be +recognized: +.RS 10 +.IP "\fBtoday\fR" 10 +Indicates the current day. +.IP "\fBtomorrow\fR" 10 +Indicates the day following the current day. +.P +If no +.IR date +is given, +.BR today +shall be assumed if the given time is greater than the current time, +and +.BR tomorrow +shall be assumed if it is less. If the given month is less than the +current month (and no year is given), next year shall be assumed. +.RE +.IP "\fIincrement\fR" 10 +The optional +.IR increment +shall be a number preceded by a + +(\c +.BR '\(pl' ) +and suffixed by one of the following: +.BR minutes , +.BR hours , +.BR days , +.BR weeks , +.BR months , +or +.BR years . +(The singular forms shall also be accepted.) The keyword +.BR next +shall be equivalent to an increment number of +1. For example, the +following are equivalent commands: +.RS 10 +.sp +.RS 4 +.nf +\fB +at 2pm + 1 week +at 2pm next week +.fi \fR +.P +.RE +.RE +.RE +.P +The following grammar describes the precise format of +.IR timespec +in the POSIX locale. The general conventions for this style of grammar +are described in +.IR "Section 1.3" ", " "Grammar Conventions". +This formal syntax shall take precedence over the preceding text syntax +description. The longest possible token or delimiter shall be +recognized at a given point. When used in a +.IR timespec , +white space shall also delimit tokens. +.sp +.RS 4 +.nf +\fB +%token hr24clock_hr_min +%token hr24clock_hour +/* + An hr24clock_hr_min is a one, two, or four-digit number. A one-digit + or two-digit number constitutes an hr24clock_hour. An hr24clock_hour + may be any of the single digits [0,9], or may be double digits, ranging + from [00,23]. If an hr24clock_hr_min is a four-digit number, the + first two digits shall be a valid hr24clock_hour, while the last two + represent the number of minutes, from [00,59]. +*/ +.P +%token wallclock_hr_min +%token wallclock_hour +/* + A wallclock_hr_min is a one, two-digit, or four-digit number. + A one-digit or two-digit number constitutes a wallclock_hour. + A wallclock_hour may be any of the single digits [1,9], or may + be double digits, ranging from [01,12]. If a wallclock_hr_min + is a four-digit number, the first two digits shall be a valid + wallclock_hour, while the last two represent the number of + minutes, from [00,59]. +*/ +.P +%token minute +/* + A minute is a one or two-digit number whose value can be [0,9] + or [00,59]. +*/ +.P +%token day_number +/* + A day_number is a number in the range appropriate for the particular + month and year specified by month_name and year_number, respectively. + If no year_number is given, the current year is assumed if the given + date and time are later this year. If no year_number is given and + the date and time have already occurred this year and the month is + not the current month, next year is the assumed year. +*/ +.P +%token year_number +/* + A year_number is a four-digit number representing the year A.D., in + which the at_job is to be run. +*/ +.P +%token inc_number +/* + The inc_number is the number of times the succeeding increment + period is to be added to the specified date and time. +*/ +.P +%token timezone_name +/* + The name of an optional timezone suffix to the time field, in an + implementation-defined format. +*/ +.P +%token month_name +/* + One of the values from the mon or abmon keywords in the LC_TIME + locale category. +*/ +.P +%token day_of_week +/* + One of the values from the day or abday keywords in the LC_TIME + locale category. +*/ +.P +%token am_pm +/* + One of the values from the am_pm keyword in the LC_TIME locale + category. +*/ +.P +%start timespec +%% +timespec : time + | time date + | time increment + | time date increment + | nowspec + ; +.P +nowspec : "now" + | "now" increment + ; +.P +time : hr24clock_hr_min + | hr24clock_hr_min timezone_name + | hr24clock_hour ":" minute + | hr24clock_hour ":" minute timezone_name + | wallclock_hr_min am_pm + | wallclock_hr_min am_pm timezone_name + | wallclock_hour ":" minute am_pm + | wallclock_hour ":" minute am_pm timezone_name + | "noon" + | "midnight" + ; +.P +date : month_name day_number + | month_name day_number "," year_number + | day_of_week + | "today" + | "tomorrow" + ; +.P +increment : "+" inc_number inc_period + | "next" inc_period + ; +.P +inc_period : "minute" | "minutes" + | "hour" | "hours" + | "day" | "days" + | "week" | "weeks" + | "month" | "months" + | "year" | "years" + ; +.fi \fR +.P +.RE +.SH STDIN +The standard input shall be a text file consisting of commands +acceptable to the shell command language described in +.IR "Chapter 2" ", " "Shell Command Language". +The standard input shall only be used if no +.BR \(mif +.IR file +option is specified. +.SH "INPUT FILES" +See the STDIN section. +.P +The text files +.BR at.allow +and +.BR at.deny , +which are located in an implementation-defined directory, +shall contain zero or more user names, one per line, of users who are, +respectively, authorized or denied access to the +.IR at +and +.IR batch +utilities. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR at : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fILC_TIME\fP" 10 +Determine the format and contents for date and time strings written and +accepted by +.IR at . +.IP "\fISHELL\fP" 10 +Determine a name of a command interpreter to be used to invoke the +at-job. If the variable is unset or null, +.IR sh +shall be used. If it is set to a value other than a name for +.IR sh , +the implementation shall do one of the following: use that shell; use +.IR sh ; +use the login shell from the user database; or any of the preceding +accompanied by a warning diagnostic about which was chosen. +.IP "\fITZ\fP" 10 +Determine the timezone. The job shall be submitted for execution at the +time specified by +.IR timespec +or +.BR \(mit +.IR time +relative to the timezone specified by the +.IR TZ +variable. If +.IR timespec +specifies a timezone, it shall override +.IR TZ . +If +.IR timespec +does not specify a timezone and +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +When standard input is a terminal, prompts of unspecified format for +each line of the user input described in the STDIN section may be +written to standard output. +.P +In the POSIX locale, the following shall be written to the standard +output for each job when jobs are listed in response to the +.BR \(mil +option: +.sp +.RS 4 +.nf +\fB +"%s\et%s\en", \fIat_job_id\fR, <\fIdate\fR> +.fi \fR +.P +.RE +.P +where +.IR date +shall be equivalent in format to the output of: +.sp +.RS 4 +.nf +\fB +date +"%a %b %e %T %Y" +.fi \fR +.P +.RE +.P +The date and time written shall be adjusted so that they appear in the +timezone of the user (as determined by the +.IR TZ +variable). +.SH STDERR +In the POSIX locale, the following shall be written to standard error +when a job has been successfully submitted: +.sp +.RS 4 +.nf +\fB +"job %s at %s\en", \fIat_job_id\fR, <\fIdate\fR> +.fi \fR +.P +.RE +.P +where +.IR date +has the same format as that described in the STDOUT section. Neither +this, nor warning messages concerning the selection of the command +interpreter, shall be considered a diagnostic that changes the exit +status. +.P +Diagnostic messages, if any, shall be written to standard error. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The +.IR at +utility successfully submitted, removed, or listed a job or jobs. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +The job shall not be scheduled, removed, or listed. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The format of the +.IR at +command line shown here is guaranteed only for the POSIX locale. Other +cultures may be supported with substantially different interfaces, +although implementations are encouraged to provide comparable levels of +functionality. +.P +Since the commands run in a separate shell invocation, running in a +separate process group with no controlling terminal, open file +descriptors, traps, and priority inherited from the invoking +environment are lost. +.P +Some implementations do not allow substitution of different shells +using +.IR SHELL . +System V systems, for example, have used the login shell value for the +user in +.BR /etc/passwd . +To select reliably another command interpreter, the user must include +it as part of the script, such as: +.sp +.RS 4 +.nf +\fB +\fB$\fR at 1800 +myshell myscript +EOT +\fBjob ... at ... +\fB$\fR +.fi \fR +.P +.RE +.SH EXAMPLES +.IP " 1." 4 +This sequence can be used at a terminal: +.RS 4 +.sp +.RS 4 +.nf +\fB +at \(mim 0730 tomorrow +sort < file >outfile +EOT +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +This sequence, which demonstrates redirecting standard error to a pipe, +is useful in a command procedure (the sequence of output redirection +specifications is significant): +.RS 4 +.sp +.RS 4 +.nf +\fB +at now + 1 hour <&1 >outfile | mailx mygroup +! +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +To have a job reschedule itself, +.IR at +can be invoked from within the at-job. For example, this daily +processing script named +.BR my.daily +runs every day (although +.IR crontab +is a more appropriate vehicle for such work): +.RS 4 +.sp +.RS 4 +.nf +\fB +# my.daily runs every day +\fIdaily processing\fR +at now tomorrow < my.daily +.fi \fR +.P +.RE +.RE +.IP " 4." 4 +The spacing of the three portions of the POSIX locale +.IR timespec +is quite flexible as long as there are no ambiguities. Examples of +various times and operand presentation include: +.RS 4 +.sp +.RS 4 +.nf +\fB +at 0815am Jan 24 +at 8 :15amjan24 +at now "+ 1day" +at 5 pm FRIday +at '17 + utc+ + 30minutes' +.fi \fR +.P +.RE +.RE +.SH RATIONALE +The +.IR at +utility reads from standard input the commands to be executed at a +later time. It may be useful to redirect standard output and standard +error within the specified commands. +.P +The +.BR \(mit +.IR time +option was added as a new capability to support an internationalized +way of specifying a time for execution of the submitted job. +.P +Early proposals added a ``jobname'' concept as a way of giving +submitted jobs names that are meaningful to the user submitting them. +The historical, system-specified +.IR at_job_id +gives no indication of what the job is. Upon further reflection, it was +decided that the benefit of this was not worth the change in historical +interface. The +.IR at +functionality is useful in simple environments, but in large or complex +situations, the functionality provided by the Batch Services option is +more suitable. +.P +The +.BR \(miq +option historically has been an undocumented option, used mainly by the +.IR batch +utility. +.P +The System V +.BR \(mim +option was added to provide a method for informing users that an at-job +had completed. Otherwise, users are only informed when output to +standard error or standard output are not redirected. +.P +The behavior of +.IR at +<\fBnow\fP> was changed in an early proposal from being unspecified to +submitting a job for potentially immediate execution. Historical BSD +.IR at +implementations support this. Historical System V implementations give +an error in that case, but a change to the System V versions should +have no backwards-compatibility ramifications. +.P +On BSD-based systems, a +.BR \(miu +.IR user +option has allowed those with appropriate privileges to access the work +of other users. Since this is primarily a system administration feature +and is not universally implemented, it has been omitted. Similarly, a +specification for the output format for a user with appropriate +privileges viewing the queues of other users has been omitted. +.P +The +.BR \(mif +.IR file +option from System V is used instead of the BSD method of using the +last operand as the pathname. The BSD method is ambiguous\(emdoes: +.sp +.RS 4 +.nf +\fB +at 1200 friday +.fi \fR +.P +.RE +.P +mean the same thing if there is a file named +.BR friday +in the current directory? +.P +The +.IR at_job_id +is composed of a limited character set in historical practice, and it +is mandated here to invalidate systems that might try using characters +that require shell quoting or that could not be easily parsed by shell +scripts. +.P +The +.IR at +utility varies between System V and BSD systems in the way timezones +are used. On System V systems, the +.IR TZ +variable affects the at-job submission times and the times displayed +for the user. On BSD systems, +.IR TZ +is not taken into account. The BSD behavior is easily achieved with +the current specification. If the user wishes to have the timezone +default to that of the system, they merely need to issue the +.IR at +command immediately following an unsetting or null assignment to +.IR TZ . +For example: +.sp +.RS 4 +.nf +\fB +TZ= at noon ... +.fi \fR +.P +.RE +.P +gives the desired BSD result. +.P +While the +.IR yacc -like +grammar specified in the OPERANDS section is lexically unambiguous with +respect to the digit strings, a lexical analyzer would probably be +written to look for and return digit strings in those cases. The parser +could then check whether the digit string returned is a valid +.IR day_number , +.IR year_number , +and so on, based on the context. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIbatch\fR\^", +.IR "\fIcrontab\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/awk.1p b/man-pages-posix-2013/man1p/awk.1p new file mode 100644 index 0000000..8a67a2f --- /dev/null +++ b/man-pages-posix-2013/man1p/awk.1p @@ -0,0 +1,3966 @@ +'\" et +.TH AWK "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +awk +\(em pattern scanning and processing language +.SH SYNOPSIS +.LP +.nf +awk \fB[\fR\(miF \fIsepstring\fB] [\fR\(miv \fIassignment\fB]\fR... \fIprogram\fB [\fIargument\fR...\fB]\fR +.P +awk \fB[\fR\(miF \fIsepstring\fB] \fR\(mif \fIprogfile \fB[\fR\(mif \fIprogfile\fB]\fR... \fB[\fR\(miv \fIassignment\fB]\fR... + \fB[\fIargument\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR awk +utility shall execute programs written in the +.IR awk +programming language, which is specialized for textual data +manipulation. An +.IR awk +program is a sequence of patterns and corresponding actions. When +input is read that matches a pattern, the action associated with that +pattern is carried out. +.P +Input shall be interpreted as a sequence of records. By default, a +record is a line, less its terminating +, +but this can be changed by using the +.BR RS +built-in variable. Each record of input shall be matched in turn +against each pattern in the program. For each pattern matched, the +associated action shall be executed. +.P +The +.IR awk +utility shall interpret each input record as a sequence of fields +where, by default, a field is a string of non-\c + +non-\c + +characters. This default + +and + +field delimiter can be changed by using the +.BR FS +built-in variable or the +.BR \(miF +.IR sepstring +option. The +.IR awk +utility shall denote the first field in a record $1, the second $2, and +so on. The symbol $0 shall refer to the entire record; setting any +other field causes the re-evaluation of $0. Assigning to $0 shall reset +the values of all other fields and the +.BR NF +built-in variable. +.SH OPTIONS +The +.IR awk +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(miF\ \fIsepstring\fR" 10 +Define the input field separator. This option shall be equivalent to: +.RS 10 +.sp +.RS 4 +.nf +\fB +-v FS=\fIsepstring +.fi \fR +.P +.RE +.P +except that if +.BR \(miF +.IR sepstring +and +.BR \(miv +.IR \fRFS=\fPsepstring\fR +are both used, it is unspecified whether the +.BR FS +assignment resulting from +.BR \(miF +.IR sepstring +is processed in command line order or is processed after the last +.BR \(miv +.IR \fRFS=\fPsepstring\fR . +See the description of the +.BR FS +built-in variable, and how it is used, in the EXTENDED DESCRIPTION +section. +.RE +.IP "\fB\(mif\ \fIprogfile\fR" 10 +Specify the pathname of the file +.IR progfile +containing an +.IR awk +program. A pathname of +.BR '\(mi' +shall denote the standard input. If multiple instances of this option +are specified, the concatenation of the files specified as +.IR progfile +in the order specified shall be the +.IR awk +program. The +.IR awk +program can alternatively be specified in the command line as a single +argument. +.IP "\fB\(miv\ \fIassignment\fR" 10 +.br +The application shall ensure that the +.IR assignment +argument is in the same form as an +.IR assignment +operand. The specified variable assignment shall occur prior to +executing the +.IR awk +program, including the actions associated with +.BR BEGIN +patterns (if any). Multiple occurrences of this option can be +specified. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIprogram\fR" 10 +If no +.BR \(mif +option is specified, the first operand to +.IR awk +shall be the text of the +.IR awk +program. The application shall supply the +.IR program +operand as a single argument to +.IR awk . +If the text does not end in a +, +.IR awk +shall interpret the text as if it did. +.IP "\fIargument\fR" 10 +Either of the following two types of +.IR argument +can be intermixed: +.RS 10 +.IP "\fIfile\fR" 10 +A pathname of a file that contains the input to be read, which is +matched against the set of patterns in the program. If no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' , +the standard input shall be used. +.IP "\fIassignment\fR" 10 +An operand that begins with an + +or alphabetic character from the portable character set (see the table +in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set"), +followed by a sequence of underscores, digits, and alphabetics from the +portable character set, followed by the +.BR '=' +character, shall specify a variable assignment rather than a pathname. +The characters before the +.BR '=' +represent the name of an +.IR awk +variable; if that name is an +.IR awk +reserved word (see +.IR "Grammar") +the behavior is undefined. The characters following the + +shall be interpreted as if they appeared in the +.IR awk +program preceded and followed by a double-quote (\c +.BR '\&"' ) +character, as a +.BR STRING +token (see +.IR "Grammar"), +except that if the last character is an unescaped +, +it shall be interpreted as a literal + +rather than as the first character of the sequence +.BR \(dq\e"\(dq . +The variable shall be assigned the value of that +.BR STRING +token and, if appropriate, shall be considered a +.IR "numeric string" +(see +.IR "Expressions in awk"), +the variable shall also be assigned its numeric value. Each such +variable assignment shall occur just prior to the processing of the +following +.IR file , +if any. Thus, an assignment before the first +.IR file +argument shall be executed after the +.BR BEGIN +actions (if any), while an assignment after the last +.IR file +argument shall occur before the +.BR END +actions (if any). If there are no +.IR file +arguments, assignments shall be executed before processing the standard +input. +.RE +.SH STDIN +The standard input shall be used only if no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' , +or if a +.IR progfile +option-argument is +.BR '\(mi' ; +see the INPUT FILES section. If the +.IR awk +program contains no actions and no patterns, but is otherwise a valid +.IR awk +program, standard input and any +.IR file +operands shall not be read and +.IR awk +shall exit with a return status of zero. +.SH "INPUT FILES" +Input files to the +.IR awk +program from any of the following sources shall be text files: +.IP " *" 4 +Any +.IR file +operands or their equivalents, achieved by modifying the +.IR awk +variables +.BR ARGV +and +.BR ARGC +.IP " *" 4 +Standard input in the absence of any +.IR file +operands +.IP " *" 4 +Arguments to the +.BR getline +function +.P +Whether the variable +.BR RS +is set to a value other than a + +or not, for these files, implementations shall support records +terminated with the specified separator up to +{LINE_MAX} +bytes and may support longer records. +.P +If +.BR \(mif +.IR progfile +is specified, the application shall ensure that the files named by each +of the +.IR progfile +option-arguments are text files and their concatenation, in the same +order as they appear in the arguments, is an +.IR awk +program. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR awk : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular expressions and +in comparisons of string values. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files), the behavior of +character classes within regular expressions, the identification of +characters as letters, and the mapping of uppercase and lowercase +characters for the +.BR toupper +and +.BR tolower +functions. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILC_NUMERIC\fP" 10 +.br +Determine the radix character used when interpreting numeric input, +performing conversions between numeric and string values, and +formatting numeric output. Regardless of locale, the + +character (the decimal-point character of the POSIX locale) is the +decimal-point character recognized in processing +.IR awk +programs (including assignments in command line arguments). +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPATH\fP" 10 +Determine the search path when looking for commands executed by +\fIsystem\fR(\fIexpr\fR), or input and output pipes; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +.P +In addition, all environment variables shall be visible via the +.IR awk +variable +.BR ENVIRON . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The nature of the output files depends on the +.IR awk +program. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The nature of the output files depends on the +.IR awk +program. +.br +.SH "EXTENDED DESCRIPTION" +.SS "Overall Program Structure" +.P +An +.IR awk +program is composed of pairs of the form: +.sp +.RS 4 +.nf +\fB +\fIpattern\fR { \fIaction\fR } +.fi \fR +.P +.RE +.P +Either the pattern or the action (including the enclosing brace +characters) can be omitted. +.P +A missing pattern shall match any record of input, and a missing action +shall be equivalent to: +.sp +.RS 4 +.nf +\fB +{ print } +.fi \fR +.P +.RE +.P +Execution of the +.IR awk +program shall start by first executing the actions associated with all +.BR BEGIN +patterns in the order they occur in the program. Then each +.IR file +operand (or standard input if no files were specified) shall be +processed in turn by reading data from the file until a record +separator is seen (\c + +by default). Before the first reference to a field in the record is +evaluated, the record shall be split into fields, according to the +rules in +.IR "Regular Expressions", +using the value of +.BR FS +that was current at the time the record was read. Each pattern in the +program then shall be evaluated in the order of occurrence, and the +action associated with each pattern that matches the current record +executed. The action for a matching pattern shall be executed before +evaluating subsequent patterns. Finally, the actions associated with +all +.BR END +patterns shall be executed in the order they occur in the program. +.SS "Expressions in awk" +.P +Expressions describe computations used in +.IR patterns +and +.IR actions . +In the following table, valid expression operations are given in groups +from highest precedence first to lowest precedence last, with +equal-precedence operators grouped between horizontal lines. In +expression evaluation, where the grammar is formally ambiguous, higher +precedence operators shall be evaluated before lower precedence +operators. In this table +.IR expr , +.IR expr1 , +.IR expr2 , +and +.IR expr3 +represent any expression, while lvalue represents any entity that can +be assigned to (that is, on the left side of an assignment operator). +The precise syntax of expressions is given in +.IR "Grammar". +.sp +.ce 1 +\fBTable 4-1: Expressions in Decreasing Precedence in \fIawk\fP\fR +.TS +box tab(@) center; +cB | cB | cB | cB +l1f5 | l1 | l1 | l. +Syntax@Name@Type of Result@Associativity +_ +( \fIexpr\fP )@Grouping@Type of \fIexpr\fP@N/A +_ +$\fIexpr\fP@Field reference@String@N/A +_ +lvalue ++@Post-increment@Numeric@N/A +lvalue \(mi\|\(mi@Post-decrement@Numeric@N/A +_ +++ lvalue@Pre-increment@Numeric@N/A +\(mi\|\(mi lvalue@Pre-decrement@Numeric@N/A +_ +\fIexpr\fP ^ \fIexpr\fP@Exponentiation@Numeric@Right +_ +! \fIexpr\fP@Logical not@Numeric@N/A ++ \fIexpr\fP@Unary plus@Numeric@N/A +\(mi \fIexpr\fP@Unary minus@Numeric@N/A +_ +\fIexpr\fP * \fIexpr\fP@Multiplication@Numeric@Left +\fIexpr\fP / \fIexpr\fP@Division@Numeric@Left +\fIexpr\fP % \fIexpr\fP@Modulus@Numeric@Left +_ +\fIexpr\fP + \fIexpr\fP@Addition@Numeric@Left +\fIexpr\fP \(mi \fIexpr\fP@Subtraction@Numeric@Left +_ +\fIexpr\fP \fIexpr\fP@String concatenation@String@Left +_ +\fIexpr\fP < \fIexpr\fP@Less than@Numeric@None +\fIexpr\fP <= \fIexpr\fP@Less than or equal to@Numeric@None +\fIexpr\fP != \fIexpr\fP@Not equal to@Numeric@None +\fIexpr\fP == \fIexpr\fP@Equal to@Numeric@None +\fIexpr\fP > \fIexpr\fP@Greater than@Numeric@None +\fIexpr\fP >= \fIexpr\fP@Greater than or equal to@Numeric@None +_ +\fIexpr\fP ~ \fIexpr\fP@ERE match@Numeric@None +\fIexpr\fP !~ \fIexpr\fP@ERE non-match@Numeric@None +_ +\fIexpr\fP in array@Array membership@Numeric@Left +( \fIindex\fP ) in \fIarray\fP@Multi-dimension array@Numeric@Left +@membership +_ +\fIexpr\fP && \fIexpr\fP@Logical AND@Numeric@Left +_ +\fIexpr\fP || \fIexpr\fP@Logical OR@Numeric@Left +_ +\fIexpr1\fP ? \fIexpr2\fP : \fIexpr3\fP@Conditional expression@Type of selected@Right +@@\fIexpr2\fP or \fIexpr3\fP +_ +lvalue ^= \fIexpr\fP@Exponentiation assignment@Numeric@Right +lvalue %= \fIexpr\fP@Modulus assignment@Numeric@Right +lvalue *= \fIexpr\fP@Multiplication assignment@Numeric@Right +lvalue /= \fIexpr\fP@Division assignment@Numeric@Right +lvalue += \fIexpr\fP@Addition assignment@Numeric@Right +lvalue \(mi= \fIexpr\fP@Subtraction assignment@Numeric@Right +lvalue = \fIexpr\fP@Assignment@Type of \fIexpr\fP@Right +.TE +.P +Each expression shall have either a string value, a numeric value, or +both. Except as stated for specific contexts, the value of an expression +shall be implicitly converted to the type needed for the context in which +it is used. A string value shall be converted to a numeric value either by +the equivalent of the following calls to functions defined by the ISO\ C standard: +.sp +.RS 4 +.nf +\fB +setlocale(LC_NUMERIC, ""); +\fInumeric_value\fR = atof(\fIstring_value\fR); +.fi \fR +.P +.RE +.P +or by converting the initial portion of the string to type +.BR double +representation as follows: +.sp +.RS +The input string is decomposed into two parts: an initial, possibly empty, +sequence of white-space characters (as specified by +\fIisspace\fR()) +and a subject sequence interpreted as a floating-point constant. +.P +The expected form of the subject sequence is an optional +.BR '+' +or +.BR '\(mi' +sign, then a non-empty sequence of digits optionally containing a +, +then an optional exponent part. An exponent part consists of +.BR 'e' +or +.BR 'E' , +followed by an optional sign, followed by one or more decimal digits. +.P +The sequence starting with the first digit or the + +(whichever occurs first) is interpreted as a floating constant of the +C language, and if neither an exponent part nor a + +appears, a + +is assumed to follow the last digit in the string. If the subject +sequence begins with a minus-sign, the value resulting from the conversion +is negated. +.RE +.P +A numeric value that is exactly equal to the value of an integer (see +.IR "Section 1.1.2" ", " "Concepts Derived from the ISO C Standard") +shall be converted to a string by the equivalent of a call to the +.BR sprintf +function (see +.IR "String Functions") +with the string +.BR \(dq%d\(dq +as the +.IR fmt +argument and the numeric value being converted as the first and only +.IR expr +argument. Any other numeric value shall be converted to a string by the +equivalent of a call to the +.BR sprintf +function with the value of the variable +.BR CONVFMT +as the +.IR fmt +argument and the numeric value being converted as the first and only +.IR expr +argument. The result of the conversion is unspecified if the value of +.BR CONVFMT +is not a floating-point format specification. This volume of POSIX.1\(hy2008 specifies no +explicit conversions between numbers and strings. An application can +force an expression to be treated as a number by adding zero to it, or +can force it to be treated as a string by concatenating the null string +(\c +.BR \(dq\^\(dq ) +to it. +.P +A string value shall be considered a +.IR "numeric string" +if it comes from one of the following: +.IP " 1." 4 +Field variables +.IP " 2." 4 +Input from the +\fIgetline\fR() +function +.IP " 3." 4 +.BR FILENAME +.IP " 4." 4 +.BR ARGV +array elements +.IP " 5." 4 +.BR ENVIRON +array elements +.IP " 6." 4 +Array elements created by the +\fIsplit\fR() +function +.IP " 7." 4 +A command line variable assignment +.IP " 8." 4 +Variable assignment from another numeric string variable +.P +and an implementation-dependent condition corresponding to either +case (a) or (b) below is met. +.IP " a." 4 +After the equivalent of the following calls to functions defined by +the ISO\ C standard, +.IR string_value_end +would differ from +.IR string_value , +and any characters before the terminating null character in +.IR string_value_end +would be + +characters: +.RS 4 +.sp +.RS 4 +.nf +\fB +char *string_value_end; +setlocale(LC_NUMERIC, ""); +numeric_value = strtod (string_value, &string_value_end); +.fi \fR +.P +.RE +.RE +.IP " b." 4 +After all the following conversions have been applied, the resulting +string would lexically be recognized as a +.BR NUMBER +token as described by the lexical conventions in +.IR "Grammar": +.RS 4 +.IP -- 4 +All leading and trailing + +characters are discarded. +.IP -- 4 +If the first non-\c + +is +.BR '\(pl' +or +.BR '\(mi' , +it is discarded. +.IP -- 4 +Each occurrence of the decimal point character from the current locale +is changed to a +. +.RE +In case (a) the numeric value of the +.IR "numeric string" +shall be the value that would be returned by the +\fIstrtod\fR() +call. In case (b) if the first non-\c + +is +.BR '\(mi' , +the numeric value of the +.IR "numeric string" +shall be the negation of the numeric value of the recognized +.BR NUMBER +token; otherwise, the numeric value of the +.IR "numeric string" +shall be the numeric value of the recognized +.BR NUMBER +token. Whether or not a string is a +.IR "numeric string" +shall be relevant only in contexts where that term is used in this +section. +.P +When an expression is used in a Boolean context, if it has a numeric +value, a value of zero shall be treated as false and any other value +shall be treated as true. Otherwise, a string value of the null string +shall be treated as false and any other value shall be treated as true. +A Boolean context shall be one of the following: +.IP " *" 4 +The first subexpression of a conditional expression +.IP " *" 4 +An expression operated on by logical NOT, logical AND, or logical OR +.IP " *" 4 +The second expression of a +.BR for +statement +.IP " *" 4 +The expression of an +.BR if +statement +.IP " *" 4 +The expression of the +.BR while +clause in either a +.BR while +or +.BR do .\|.\|.\c +.BR while +statement +.IP " *" 4 +An expression used as a pattern (as in Overall Program Structure) +.P +All arithmetic shall follow the semantics of floating-point arithmetic as +specified by the ISO\ C standard (see +.IR "Section 1.1.2" ", " "Concepts Derived from the ISO C Standard"). +.P +The value of the expression: +.sp +.RS 4 +.nf +\fB +\fIexpr1\fR ^ \fIexpr2\fR +.fi \fR +.P +.RE +.P +shall be equivalent to the value returned by the ISO\ C standard function call: +.sp +.RS 4 +.nf +\fB +\fRpow(\fIexpr1\fR, \fIexpr2\fR) +.fi \fR +.P +.RE +.P +The expression: +.sp +.RS 4 +.nf +\fB +lvalue ^= \fIexpr\fR +.fi \fR +.P +.RE +.P +shall be equivalent to the ISO\ C standard expression: +.sp +.RS 4 +.nf +\fB +lvalue = pow(lvalue, \fIexpr\fR) +.fi \fR +.P +.RE +.P +except that lvalue shall be evaluated only once. The value of the +expression: +.sp +.RS 4 +.nf +\fB +\fIexpr1\fR % \fIexpr2\fR +.fi \fR +.P +.RE +.P +shall be equivalent to the value returned by the ISO\ C standard function call: +.sp +.RS 4 +.nf +\fB +fmod(\fIexpr1\fR, \fIexpr2\fR) +.fi \fR +.P +.RE +.P +The expression: +.sp +.RS 4 +.nf +\fB +lvalue %= \fIexpr\fR +.fi \fR +.P +.RE +.P +shall be equivalent to the ISO\ C standard expression: +.sp +.RS 4 +.nf +\fB +lvalue = fmod(lvalue, \fIexpr\fR) +.fi \fR +.P +.RE +.P +except that lvalue shall be evaluated only once. +.P +Variables and fields shall be set by the assignment statement: +.sp +.RS 4 +.nf +\fB +lvalue = \fIexpression\fR +.fi \fR +.P +.RE +.P +and the type of +.IR expression +shall determine the resulting variable type. The assignment includes +the arithmetic assignments (\c +.BR \(dq+=\(dq , +.BR \(dq\(mi=\(dq , +.BR \(dq*=\(dq , +.BR \(dq/=\(dq , +.BR \(dq%=\(dq , +.BR \(dq^=\(dq , +.BR \(dq++\(dq , +.BR \(dq\(mi\|\(mi\(dq ) +all of which shall produce a numeric result. The left-hand side of an +assignment and the target of increment and decrement operators can be +one of a variable, an array with index, or a field selector. +.P +The +.IR awk +language supplies arrays that are used for storing numbers or strings. +Arrays need not be declared. They shall initially be empty, and their +sizes shall change dynamically. The subscripts, or element identifiers, +are strings, providing a type of associative array capability. An array +name followed by a subscript within square brackets can be used as an +lvalue and thus as an expression, as described in the grammar; see +.IR "Grammar". +Unsubscripted array names can be used in only the following contexts: +.IP " *" 4 +A parameter in a function definition or function call +.IP " *" 4 +The +.BR NAME +token following any use of the keyword +.BR in +as specified in the grammar (see +.IR "Grammar"); +if the name used in this context is not an array name, the behavior is +undefined +.P +A valid array +.IR index +shall consist of one or more +-separated +expressions, similar to the way in which multi-dimensional arrays are +indexed in some programming languages. Because +.IR awk +arrays are really one-dimensional, such a +-separated +list shall be converted to a single string by concatenating the string +values of the separate expressions, each separated from the other by +the value of the +.BR SUBSEP +variable. Thus, the following two index operations shall be +equivalent: +.sp +.RS 4 +.nf +\fB +\fIvar\fB[\fIexpr1\fR, \fIexpr2\fR, ... \fIexprn\fB] +.P +\fIvar\fB[\fIexpr1\fR SUBSEP \fIexpr2\fR SUBSEP ... \fRSUBSEP \fIexprn\fB]\fR +.fi \fR +.P +.RE +.P +The application shall ensure that a multi-dimensioned +.IR index +used with the +.BR in +operator is parenthesized. The +.BR in +operator, which tests for the existence of a particular array element, +shall not cause that element to exist. Any other reference to a +nonexistent array element shall automatically create it. +.P +Comparisons (with the +.BR '<' , +.BR \(dq<=\(dq , +.BR \(dq!=\(dq , +.BR \(dq==\(dq , +.BR '>' , +and +.BR \(dq>=\(dq +operators) shall be made numerically if both operands are numeric, if +one is numeric and the other has a string value that is a numeric +string, or if one is numeric and the other has the uninitialized value. +Otherwise, operands shall be converted to strings as required and a +string comparison shall be made using the locale-specific collation +sequence. The value of the comparison expression shall be 1 if the +relation is true, or 0 if the relation is false. +.SS "Variables and Special Variables" +.P +Variables can be used in an +.IR awk +program by referencing them. With the exception of function parameters +(see +.IR "User-Defined Functions"), +they are not explicitly declared. Function parameter names shall be +local to the function; all other variable names shall be global. The +same name shall not be used as both a function parameter name and as +the name of a function or a special +.IR awk +variable. The same name shall not be used both as a variable name with +global scope and as the name of a function. The same name shall not be +used within the same scope both as a scalar variable and as an array. +Uninitialized variables, including scalar variables, array elements, +and field variables, shall have an uninitialized value. An +uninitialized value shall have both a numeric value of zero and a +string value of the empty string. Evaluation of variables with an +uninitialized value, to either string or numeric, shall be determined +by the context in which they are used. +.P +Field variables shall be designated by a +.BR '$' +followed by a number or numerical expression. The effect of the field +number +.IR expression +evaluating to anything other than a non-negative integer is +unspecified; uninitialized variables or string values need not be +converted to numeric values in this context. New field variables can be +created by assigning a value to them. References to nonexistent fields +(that is, fields after $\fBNF\fP), shall evaluate to the uninitialized +value. Such references shall not create new fields. However, assigning +to a nonexistent field (for example, $(\fBNF\fP+2)=5) shall increase +the value of +.BR NF ; +create any intervening fields with the uninitialized value; and cause +the value of $0 to be recomputed, with the fields being separated by +the value of +.BR OFS . +Each field variable shall have a string value or an uninitialized value +when created. Field variables shall have the uninitialized value when +created from $0 using +.BR FS +and the variable does not contain any characters. If appropriate, the +field variable shall be considered a numeric string (see +.IR "Expressions in awk"). +.P +Implementations shall support the following other special variables +that are set by +.IR awk : +.IP "\fBARGC\fR" 10 +The number of elements in the +.BR ARGV +array. +.IP "\fBARGV\fR" 10 +An array of command line arguments, excluding options and the +.IR program +argument, numbered from zero to +.BR ARGC \(mi1. +.RS 10 +.P +The arguments in +.BR ARGV +can be modified or added to; +.BR ARGC +can be altered. As each input file ends, +.IR awk +shall treat the next non-null element of +.BR ARGV , +up to the current value of +.BR ARGC \(mi1, +inclusive, as the name of the next input file. Thus, setting an element +of +.BR ARGV +to null means that it shall not be treated as an input file. The name +.BR '\(mi' +indicates the standard input. If an argument matches the format of an +.IR assignment +operand, this argument shall be treated as an +.IR assignment +rather than a +.IR file +argument. +.RE +.IP "\fBCONVFMT\fR" 10 +The +.BR printf +format for converting numbers to strings (except for output statements, +where +.BR OFMT +is used); +.BR \(dq%.6g\(dq +by default. +.IP "\fBENVIRON\fR" 10 +An array representing the value of the environment, as described in the +.IR exec +functions defined in the System Interfaces volume of POSIX.1\(hy2008. The indices of the array shall be +strings consisting of the names of the environment variables, and the +value of each array element shall be a string consisting of the value +of that variable. If appropriate, the environment variable shall be +considered a +.IR "numeric string" +(see +.IR "Expressions in awk"); +the array element shall also have its numeric value. +.RS 10 +.P +In all cases where the behavior of +.IR awk +is affected by environment variables (including the environment of any +commands that +.IR awk +executes via the +.BR system +function or via pipeline redirections with the +.BR print +statement, the +.BR printf +statement, or the +.BR getline +function), the environment used shall be the environment at the time +.IR awk +began executing; it is implementation-defined whether any +modification of +.BR ENVIRON +affects this environment. +.RE +.IP "\fBFILENAME\fR" 10 +A pathname of the current input file. Inside a +.BR BEGIN +action the value is undefined. Inside an +.BR END +action the value shall be the name of the last input file processed. +.IP "\fBFNR\fR" 10 +The ordinal number of the current record in the current file. Inside a +.BR BEGIN +action the value shall be zero. Inside an +.BR END +action the value shall be the number of the last record processed in +the last file processed. +.IP "\fBFS\fR" 10 +Input field separator regular expression; a + +by default. +.IP "\fBNF\fR" 10 +The number of fields in the current record. Inside a +.BR BEGIN +action, the use of +.BR NF +is undefined unless a +.BR getline +function without a +.IR var +argument is executed previously. Inside an +.BR END +action, +.BR NF +shall retain the value it had for the last record read, unless a +subsequent, redirected, +.BR getline +function without a +.IR var +argument is performed prior to entering the +.BR END +action. +.IP "\fBNR\fR" 10 +The ordinal number of the current record from the start of input. +Inside a +.BR BEGIN +action the value shall be zero. Inside an +.BR END +action the value shall be the number of the last record processed. +.IP "\fBOFMT\fR" 10 +The +.BR printf +format for converting numbers to strings in output statements (see +.IR "Output Statements"); +.BR \(dq%.6g\(dq +by default. The result of the conversion is unspecified if the value of +.BR OFMT +is not a floating-point format specification. +.IP "\fBOFS\fR" 10 +The +.BR print +statement output field separator; + +by default. +.IP "\fBORS\fR" 10 +The +.BR print +statement output record separator; a + +by default. +.IP "\fBRLENGTH\fR" 10 +The length of the string matched by the +.BR match +function. +.IP "\fBRS\fR" 10 +The first character of the string value of +.BR RS +shall be the input record separator; a + +by default. If +.BR RS +contains more than one character, the results are unspecified. If +.BR RS +is null, then records are separated by sequences consisting of a + +plus one or more blank lines, leading or trailing blank lines shall not +result in empty records at the beginning or end of the input, and a + +shall always be a field separator, no matter what the value of +.BR FS +is. +.IP "\fBRSTART\fR" 10 +The starting position of the string matched by the +.BR match +function, numbering from 1. This shall always be equivalent to the +return value of the +.BR match +function. +.IP "\fBSUBSEP\fR" 10 +The subscript separator string for multi-dimensional arrays; the +default value is implementation-defined. +.SS "Regular Expressions" +.P +The +.IR awk +utility shall make use of the extended regular expression notation +(see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.4" ", " "Extended Regular Expressions") +except that it shall allow the use of C-language conventions +for escaping special characters within the EREs, as specified in the +table in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation" +(\c +.BR '\e\e' , +.BR '\ea' , +.BR '\eb' , +.BR '\ef' , +.BR '\en' , +.BR '\er' , +.BR '\et' , +.BR '\ev' ) +and the following table; these escape sequences shall be recognized +both inside and outside bracket expressions. Note that records need not +be separated by + +characters and string constants can contain + +characters, so even the +.BR \(dq\en\(dq +sequence is valid in +.IR awk +EREs. Using a + +character within an ERE requires the escaping shown in the following +table. +.br +.sp +.ce 1 +\fBTable 4-2: Escape Sequences in \fIawk\fP\fR +.ad l +.TS +center tab(@) box; +cB | cB | cB +cB | cB | cB +lf5 | lw(34) | lw(34). +Escape +Sequence@Description@Meaning +_ +\e"@T{ + +T}@T{ + character +T} +_ +\e/@T{ + +T}@T{ + character +T} +_ +\eddd@T{ +A + +character followed by the longest sequence of one, two, or +three octal-digit characters (01234567). If all of the digits are 0 +(that is, representation of the NUL character), the behavior is +undefined. +T}@T{ +The character whose encoding is represented by the one, two, or +three-digit octal integer. Multi-byte characters require +multiple, concatenated escape sequences of this type, including the +leading + +for each byte. +T} +_ +\ec@T{ +A + +character followed by any character not described in this +table or in the table in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation" +(\c +.BR '\e\e' , +.BR '\ea' , +.BR '\eb' , +.BR '\ef' , +.BR '\en' , +.BR '\er' , +.BR '\et' , +.BR '\ev' ). +T}@Undefined +.TE +.ad b +.P +A regular expression can be matched against a specific field or string +by using one of the two regular expression matching operators, +.BR '~' +and +.BR \(dq!~\(dq . +These operators shall interpret their right-hand operand as a regular +expression and their left-hand operand as a string. If the regular +expression matches the string, the +.BR '~' +expression shall evaluate to a value of 1, and the +.BR \(dq!~\(dq +expression shall evaluate to a value of 0. (The regular expression +matching operation is as defined by the term matched in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.1" ", " "Regular Expression Definitions", +where a match occurs on any part of the string unless the regular +expression is limited with the + +or + +special characters.) If the regular expression does not match the +string, the +.BR '~' +expression shall evaluate to a value of 0, and the +.BR \(dq!~\(dq +expression shall evaluate to a value of 1. If the right-hand operand is +any expression other than the lexical token +.BR ERE , +the string value of the expression shall be interpreted as an extended +regular expression, including the escape conventions described above. +Note that these same escape conventions shall also be applied in +determining the value of a string literal (the lexical token +.BR STRING ), +and thus shall be applied a second time when a string literal is used +in this context. +.P +When an +.BR ERE +token appears as an expression in any context other than as the +right-hand of the +.BR '~' +or +.BR \(dq!~\(dq +operator or as one of the built-in function arguments described below, +the value of the resulting expression shall be the equivalent of: +.sp +.RS 4 +.nf +\fB +$0 " " /\fIere\fR/ +.fi \fR +.P +.RE +.P +The +.IR ere +argument to the +.BR gsub , +.BR match , +.BR sub +functions, and the +.IR fs +argument to the +.BR split +function (see +.IR "String Functions") +shall be interpreted as extended regular expressions. These can be +either +.BR ERE +tokens or arbitrary expressions, and shall be interpreted in the same +manner as the right-hand side of the +.BR '~' +or +.BR \(dq!~\(dq +operator. +.P +An extended regular expression can be used to separate fields by assigning +a string containing the expression to the built-in variable +.BR FS , +either directly or as a consequence of using the +.BR \(miF +.IR sepstring +option. +The default value of the +.BR FS +variable shall be a single +. +The following describes +.BR FS +behavior: +.IP " 1." 4 +If +.BR FS +is a null string, the behavior is unspecified. +.IP " 2." 4 +If +.BR FS +is a single character: +.RS 4 +.IP " a." 4 +If +.BR FS +is +, +skip leading and trailing + +and + +characters; fields shall be delimited by sets of one or more + +or + +characters. +.IP " b." 4 +Otherwise, if +.BR FS +is any other character +.IR c , +fields shall be delimited by each single occurrence of +.IR c . +.RE +.IP " 3." 4 +Otherwise, the string value of +.BR FS +shall be considered to be an extended regular expression. Each +occurrence of a sequence matching the extended regular expression shall +delimit fields. +.P +Except for the +.BR '~' +and +.BR \(dq!~\(dq +operators, and in the +.BR gsub , +.BR match , +.BR split , +and +.BR sub +built-in functions, ERE matching shall be based on input records; that +is, record separator characters (the first character of the value of +the variable +.BR RS , + +by default) cannot be embedded in the expression, and no expression +shall match the record separator character. If the record separator is +not +, + +characters embedded in the expression can be matched. For the +.BR '~' +and +.BR \(dq!~\(dq +operators, and in those four built-in functions, ERE matching shall be +based on text strings; that is, any character (including + +and the record separator) can be embedded in the pattern, and an +appropriate pattern shall match any character. However, in all +.IR awk +ERE matching, the use of one or more NUL characters in the pattern, +input record, or text string produces undefined results. +.SS "Patterns" +.P +A +.IR pattern +is any valid +.IR expression , +a range specified by two expressions separated by a comma, or one of the +two special patterns +.BR BEGIN +or +.BR END . +.SS "Special Patterns" +.P +The +.IR awk +utility shall recognize two special patterns, +.BR BEGIN +and +.BR END . +Each +.BR BEGIN +pattern shall be matched once and its associated action executed before +the first record of input is read\(emexcept possibly by use of the +.BR getline +function (see +.IR "Input/Output and General Functions") +in a prior +.BR BEGIN +action\(emand before command line assignment is done. Each +.BR END +pattern shall be matched once and its associated action executed after +the last record of input has been read. These two patterns shall have +associated actions. +.P +.BR BEGIN +and +.BR END +shall not combine with other patterns. Multiple +.BR BEGIN +and +.BR END +patterns shall be allowed. The actions associated with the +.BR BEGIN +patterns shall be executed in the order specified in the program, as +are the +.BR END +actions. An +.BR END +pattern can precede a +.BR BEGIN +pattern in a program. +.P +If an +.IR awk +program consists of only actions with the pattern +.BR BEGIN , +and the +.BR BEGIN +action contains no +.BR getline +function, +.IR awk +shall exit without reading its input when the last statement in the +last +.BR BEGIN +action is executed. If an +.IR awk +program consists of only actions with the pattern +.BR END +or only actions with the patterns +.BR BEGIN +and +.BR END , +the input shall be read before the statements in the +.BR END +actions are executed. +.SS "Expression Patterns" +.P +An expression pattern shall be evaluated as if it were an expression in +a Boolean context. If the result is true, the pattern shall be +considered to match, and the associated action (if any) shall be +executed. If the result is false, the action shall not be executed. +.SS "Pattern Ranges" +.P +A pattern range consists of two expressions separated by a comma; in +this case, the action shall be performed for all records between a +match of the first expression and the following match of the second +expression, inclusive. At this point, the pattern range can be repeated +starting at input records subsequent to the end of the matched range. +.SS "Actions" +.P +An action is a sequence of statements as shown in the grammar in +.IR "Grammar". +Any single statement can be replaced by a statement list enclosed in +curly braces. The application shall ensure that statements in a +statement list are separated by + +or + +characters. Statements in a statement list shall be executed sequentially +in the order that they appear. +.P +The +.IR expression +acting as the conditional in an +.BR if +statement shall be evaluated and if it is non-zero or non-null, the +following statement shall be executed; otherwise, if +.BR else +is present, the statement following the +.BR else +shall be executed. +.P +The +.BR if , +.BR while , +.BR do .\|.\|.\c +.BR while , +.BR for , +.BR break , +and +.BR continue +statements are based on the ISO\ C standard (see +.IR "Section 1.1.2" ", " "Concepts Derived from the ISO C Standard"), +except that the Boolean expressions shall be treated as described in +.IR "Expressions in awk", +and except in the case of: +.sp +.RS 4 +.nf +\fB +for (\fIvariable\fR in \fIarray\fR) +.fi \fR +.P +.RE +.P +which shall iterate, assigning each +.IR index +of +.IR array +to +.IR variable +in an unspecified order. The results of adding new elements to +.IR array +within such a +.BR for +loop are undefined. If a +.BR break +or +.BR continue +statement occurs outside of a loop, the behavior is undefined. +.P +The +.BR delete +statement shall remove an individual array element. Thus, the following +code deletes an entire array: +.sp +.RS 4 +.nf +\fB +for (index in array) + delete array[index] +.fi \fR +.P +.RE +.P +The +.BR next +statement shall cause all further processing of the current input +record to be abandoned. The behavior is undefined if a +.BR next +statement appears or is invoked in a +.BR BEGIN +or +.BR END +action. +.P +The +.BR exit +statement shall invoke all +.BR END +actions in the order in which they occur in the program source and then +terminate the program without reading further input. An +.BR exit +statement inside an +.BR END +action shall terminate the program without further execution of +.BR END +actions. If an expression is specified in an +.BR exit +statement, its numeric value shall be the exit status of +.IR awk , +unless subsequent errors are encountered or a subsequent +.BR exit +statement with an expression is executed. +.SS "Output Statements" +.P +Both +.BR print +and +.BR printf +statements shall write to standard output by default. The output shall +be written to the location specified by +.IR output_redirection +if one is supplied, as follows: +.sp +.RS 4 +.nf +\fB +> \fIexpression\fR +>> \fIexpression\fR +| \fIexpression\fR +.fi \fR +.P +.RE +.P +In all cases, the +.IR expression +shall be evaluated to produce a string that is used as a pathname +into which to write (for +.BR '>' +or +.BR \(dq>>\(dq ) +or as a command to be executed (for +.BR '|' ). +Using the first two forms, if the file of that name is not currently +open, it shall be opened, creating it if necessary and using the first +form, truncating the file. The output then shall be appended to the +file. As long as the file remains open, subsequent calls in which +.IR expression +evaluates to the same string value shall simply append output to the +file. The file remains open until the +.BR close +function (see +.IR "Input/Output and General Functions") +is called with an expression that evaluates to the same string value. +.P +The third form shall write output onto a stream piped to the input of a +command. The stream shall be created if no stream is currently open +with the value of +.IR expression +as its command name. The stream created shall be equivalent to one +created by a call to the +\fIpopen\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008 with the value of +.IR expression +as the +.IR command +argument and a value of +.IR w +as the +.IR mode +argument. As long as the stream remains open, subsequent calls in which +.IR expression +evaluates to the same string value shall write output to the existing +stream. The stream shall remain open until the +.BR close +function (see +.IR "Input/Output and General Functions") +is called with an expression that evaluates to the same string value. +At that time, the stream shall be closed as if by a call to the +\fIpclose\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008. +.P +As described in detail by the grammar in +.IR "Grammar", +these output statements shall take a +-separated +list of +.IR expression s +referred to in the grammar by the non-terminal symbols +.BR expr_list , +.BR print_expr_list , +or +.BR print_expr_list_opt . +This list is referred to here as the +.IR "expression list" , +and each member is referred to as an +.IR "expression argument" . +.P +The +.BR print +statement shall write the value of each expression argument onto the +indicated output stream separated by the current output field separator +(see variable +.BR OFS +above), and terminated by the output record separator (see variable +.BR ORS +above). All expression arguments shall be taken as strings, being +converted if necessary; this conversion shall be as described in +.IR "Expressions in awk", +with the exception that the +.BR printf +format in +.BR OFMT +shall be used instead of the value in +.BR CONVFMT . +An empty expression list shall stand for the whole input record ($0). +.P +The +.BR printf +statement shall produce output based on a notation similar to the +File Format Notation used to describe file formats in this volume of POSIX.1\(hy2008 (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation"). +Output shall be produced as specified with the first +.IR expression +argument as the string +.IR format +and subsequent +.IR expression +arguments as the strings +.IR arg1 +to +.IR argn , +inclusive, with the following exceptions: +.IP " 1." 4 +The +.IR format +shall be an actual character string rather than a graphical +representation. Therefore, it cannot contain empty character +positions. The + +in the +.IR format +string, in any context other than a +.IR flag +of a conversion specification, shall be treated as an ordinary +character that is copied to the output. +.IP " 2." 4 +If the character set contains a +.BR ' ' +character and that character appears in the +.IR format +string, it shall be treated as an ordinary character that is copied to +the output. +.IP " 3." 4 +The +.IR "escape sequences" +beginning with a + +character shall be treated as sequences of ordinary characters that are +copied to the output. Note that these same sequences shall be interpreted +lexically by +.IR awk +when they appear in literal strings, but they shall not be treated +specially by the +.BR printf +statement. +.IP " 4." 4 +A +.IR "field width" +or +.IR precision +can be specified as the +.BR '*' +character instead of a digit string. In this case the next argument +from the expression list shall be fetched and its numeric value taken +as the field width or precision. +.IP " 5." 4 +The implementation shall not precede or follow output from the +.BR d +or +.BR u +conversion specifier characters with + +characters not specified by the +.IR format +string. +.IP " 6." 4 +The implementation shall not precede output from the +.BR o +conversion specifier character with leading zeros not specified by the +.IR format +string. +.IP " 7." 4 +For the +.BR c +conversion specifier character: if the argument has a numeric value, the +character whose encoding is that value shall be output. If the value is +zero or is not the encoding of any character in the character set, the +behavior is undefined. If the argument does not have a numeric value, +the first character of the string value shall be output; if the string +does not contain any characters, the behavior is undefined. +.IP " 8." 4 +For each conversion specification that consumes an argument, the next +expression argument shall be evaluated. With the exception of the +.BR c +conversion specifier character, the value shall be converted (according +to the rules specified in +.IR "Expressions in awk") +to the appropriate type for the conversion specification. +.IP " 9." 4 +If there are insufficient expression arguments to satisfy all the +conversion specifications in the +.IR format +string, the behavior is undefined. +.IP 10. 4 +If any character sequence in the +.IR format +string begins with a +.BR '%' +character, but does not form a valid conversion specification, the +behavior is unspecified. +.P +Both +.BR print +and +.BR printf +can output at least +{LINE_MAX} +bytes. +.SS "Functions" +.P +The +.IR awk +language has a variety of built-in functions: arithmetic, string, +input/output, and general. +.SS "Arithmetic Functions" +.P +The arithmetic functions, except for +.BR int , +shall be based on the ISO\ C standard (see +.IR "Section 1.1.2" ", " "Concepts Derived from the ISO C Standard"). +The behavior is undefined in cases where the ISO\ C standard specifies that an +error be returned or that the behavior is undefined. Although the +grammar (see +.IR "Grammar") +permits built-in functions to appear with no arguments or parentheses, +unless the argument or parentheses are indicated as optional in the +following list (by displaying them within the +.BR \(dq[]\(dq +brackets), such use is undefined. +.IP "\fBatan2\fR(\fIy\fR,\fIx\fR)" 10 +Return arctangent of \fIy\fP/\fIx\fR in radians in the range +[\(mi\(*p,\(*p]. +.IP "\fBcos\fR(\fIx\fR)" 10 +Return cosine of \fIx\fP, where \fIx\fP is in radians. +.IP "\fBsin\fR(\fIx\fR)" 10 +Return sine of \fIx\fP, where \fIx\fP is in radians. +.IP "\fBexp\fR(\fIx\fR)" 10 +Return the exponential function of \fIx\fP. +.IP "\fBlog\fR(\fIx\fR)" 10 +Return the natural logarithm of \fIx\fP. +.IP "\fBsqrt\fR(\fIx\fR)" 10 +Return the square root of \fIx\fP. +.IP "\fBint\fR(\fIx\fR)" 10 +Return the argument truncated to an integer. Truncation shall +be toward 0 when \fIx\fP>0. +.IP "\fBrand\fP(\|)" 10 +Return a random number \fIn\fP, such that 0\(<=\fIn\fP<1. +.IP "\fBsrand\fR(\fB[\fIexpr\fB]\fR)" 10 +Set the seed value for +.IR rand +to +.IR expr +or use the time of day if +.IR expr +is omitted. The previous seed value shall be returned. +.SS "String Functions" +.P +The string functions in the following list shall be supported. +Although the grammar (see +.IR "Grammar") +permits built-in functions to appear with no arguments or parentheses, +unless the argument or parentheses are indicated as optional in the +following list (by displaying them within the +.BR \(dq[]\(dq +brackets), such use is undefined. +.IP "\fBgsub\fR(\fIere\fR,\ \fIrepl\fB[\fR,\ \fIin\fB]\fR)" 10 +.br +Behave like +.BR sub +(see below), except that it shall replace all occurrences of the +regular expression (like the +.IR ed +utility global substitute) in $0 or in the +.IR in +argument, when specified. +.IP "\fBindex\fR(\fIs\fR,\ \fIt\fR)" 10 +Return the position, in characters, numbering from 1, in string +.IR s +where string +.IR t +first occurs, or zero if it does not occur at all. +.IP "\fBlength[\fR(\fB[\fIs\fB]\fR)\fB]\fR" 10 +Return the length, in characters, of its argument taken as a string, or +of the whole record, $0, if there is no argument. +.IP "\fBmatch\fR(\fIs\fR,\ \fIere\fR)" 10 +Return the position, in characters, numbering from 1, in string +.IR s +where the extended regular expression +.IR ere +occurs, or zero if it does not occur at all. RSTART shall be set to the +starting position (which is the same as the returned value), zero if no +match is found; RLENGTH shall be set to the length of the matched +string, \(mi1 if no match is found. +.IP "\fBsplit\fR(\fIs\fR,\ \fIa\fB[\fR,\ \fIfs\ \fB]\fR)" 10 +.br +Split the string +.IR s +into array elements +.IR a [1], +.IR a [2], +\&.\|.\|., +.IR a [ n ], +and return +.IR n . +All elements of the array shall be deleted before the split is +performed. The separation shall be done with the ERE +.IR fs +or with the field separator +.BR FS +if +.IR fs +is not given. Each array element shall have a string value when created +and, if appropriate, the array element shall be considered a numeric +string (see +.IR "Expressions in awk"). +The effect of a null string as the value of +.IR fs +is unspecified. +.IP "\fBsprintf\fR(\fIfmt\fR,\ \fIexpr\fR,\ \fIexpr\fR,\ .\|.\|.)" 10 +.br +Format the expressions according to the +.BR printf +format given by +.IR fmt +and return the resulting string. +.IP "\fBsub(\fIere\fR,\ \fIrepl\fB[\fR,\ \fIin\ \fB]\fR)" 10 +.br +Substitute the string +.IR repl +in place of the first instance of the extended regular expression +.IR ERE +in string +.IR in +and return the number of substitutions. An + +(\c +.BR '&' ) +appearing in the string +.IR repl +shall be replaced by the string from +.IR in +that matches the ERE. An + +preceded with a + +shall be interpreted as the literal + +character. An occurrence of two consecutive + +characters shall be interpreted as just a single literal + +character. Any other occurrence of a + +(for example, preceding any other character) shall be treated as a +literal + +character. Note that if +.IR repl +is a string literal (the lexical token +.BR STRING ; +see +.IR "Grammar"), +the handling of the + +character occurs after any lexical processing, including any lexical +-escape +sequence processing. If +.IR in +is specified and it is not an lvalue (see +.IR "Expressions in awk"), +the behavior is undefined. If +.IR in +is omitted, +.IR awk +shall use the current record ($0) in its place. +.IP "\fBsubstr\fR(\fIs\fR,\ \fIm\fB[\fR,\ \fIn\ \fB]\fR)" 10 +.br +Return the at most +.IR n -character +substring of +.IR s +that begins at position +.IR m , +numbering from 1. If +.IR n +is omitted, or if +.IR n +specifies more characters than are left in the string, the length of +the substring shall be limited by the length of the string +.IR s . +.IP "\fBtolower\fR(\fIs\fR)" 10 +Return a string based on the string +.IR s . +Each character in +.IR s +that is an uppercase letter specified to have a +.BR tolower +mapping by the +.IR LC_CTYPE +category of the current locale shall be replaced in the returned string +by the lowercase letter specified by the mapping. Other characters in +.IR s +shall be unchanged in the returned string. +.IP "\fBtoupper\fR(\fIs\fR)" 10 +Return a string based on the string +.IR s . +Each character in +.IR s +that is a lowercase letter specified to have a +.BR toupper +mapping by the +.IR LC_CTYPE +category of the current locale is replaced in the returned string by +the uppercase letter specified by the mapping. Other characters in +.IR s +are unchanged in the returned string. +.P +All of the preceding functions that take +.IR ERE +as a parameter expect a pattern or a string valued expression that is a +regular expression as defined in +.IR "Regular Expressions". +.SS "Input/Output and General Functions" +.P +The input/output and general functions are: +.IP "\fBclose\fR(\fIexpression\fR)" 10 +.br +Close the file or pipe opened by a +.BR print +or +.BR printf +statement or a call to +.BR getline +with the same string-valued +.IR expression . +The limit on the number of open +.IR expression +arguments is implementation-defined. If the close was successful, the +function shall return zero; otherwise, it shall return non-zero. +.IP "\fIexpression\ |\ \fBgetline\ [\fIvar\fB]\fR" 10 +.br +Read a record of input from a stream piped from the output of a +command. The stream shall be created if no stream is currently open +with the value of +.IR expression +as its command name. The stream created shall be equivalent to one +created by a call to the +\fIpopen\fR() +function with the value of +.IR expression +as the +.IR command +argument and a value of +.IR r +as the +.IR mode +argument. As long as the stream remains open, subsequent calls in which +.IR expression +evaluates to the same string value shall read subsequent records from +the stream. The stream shall remain open until the +.BR close +function is called with an expression that evaluates to the same string +value. At that time, the stream shall be closed as if by a call to the +\fIpclose\fR() +function. If +.IR var +is omitted, $0 and +.BR NF +shall be set; otherwise, +.IR var +shall be set and, if appropriate, it shall be considered a numeric +string (see +.IR "Expressions in awk"). +.RS 10 +.P +The +.BR getline +operator can form ambiguous constructs when there are unparenthesized +operators (including concatenate) to the left of the +.BR '|' +(to the beginning of the expression containing +.BR getline ). +In the context of the +.BR '$' +operator, +.BR '|' +shall behave as if it had a lower precedence than +.BR '$' . +The result of evaluating other operators is unspecified, and conforming +applications shall parenthesize properly all such usages. +.RE +.IP "\fBgetline\fR" 10 +Set $0 to the next input record from the current input file. This form +of +.BR getline +shall set the +.BR NF , +.BR NR , +and +.BR FNR +variables. +.IP "\fBgetline\ \fIvar\fR" 10 +Set variable +.IR var +to the next input record from the current input file and, if +appropriate, +.IR var +shall be considered a numeric string (see +.IR "Expressions in awk"). +This form of +.BR getline +shall set the +.BR FNR +and +.BR NR +variables. +.IP "\fBgetline\ \fB[\fIvar\fB]\ \fR<\ \fIexpression\fR" 10 +.br +Read the next record of input from a named file. The +.IR expression +shall be evaluated to produce a string that is used as a pathname. +If the file of that name is not currently open, it shall be opened. As +long as the stream remains open, subsequent calls in which +.IR expression +evaluates to the same string value shall read subsequent records from +the file. The file shall remain open until the +.BR close +function is called with an expression that evaluates to the same string +value. If +.IR var +is omitted, $0 and +.BR NF +shall be set; otherwise, +.IR var +shall be set and, if appropriate, it shall be considered a numeric +string (see +.IR "Expressions in awk"). +.RS 10 +.P +The +.BR getline +operator can form ambiguous constructs when there are unparenthesized +binary operators (including concatenate) to the right of the +.BR '<' +(up to the end of the expression containing the +.BR getline ). +The result of evaluating such a construct is unspecified, and conforming +applications shall parenthesize properly all such usages. +.RE +.IP "\fBsystem\fR(\fIexpression\fR)" 10 +.br +Execute the command given by +.IR expression +in a manner equivalent to the +\fIsystem\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008 and return the exit status of the +command. +.P +All forms of +.BR getline +shall return 1 for successful input, zero for end-of-file, and \(mi1 +for an error. +.P +Where strings are used as the name of a file or pipeline, the +application shall ensure that the strings are textually identical. The +terminology ``same string value'' implies that ``equivalent strings'', +even those that differ only by + +characters, represent different files. +.SS "User-Defined Functions" +.P +The +.IR awk +language also provides user-defined functions. Such functions can be +defined as: +.sp +.RS 4 +.nf +\fB +function \fIname\fR(\fB[\fIparameter\fR, ...\fB]\fR) { \fIstatements\fR } +.fi \fR +.P +.RE +.P +A function can be referred to anywhere in an +.IR awk +program; in particular, its use can precede its definition. The scope +of a function is global. +.P +Function parameters, if present, can be either scalars or arrays; the +behavior is undefined if an array name is passed as a parameter that +the function uses as a scalar, or if a scalar expression is passed as a +parameter that the function uses as an array. Function parameters shall +be passed by value if scalar and by reference if array name. +.P +The number of parameters in the function definition need not match the +number of parameters in the function call. Excess formal parameters can +be used as local variables. If fewer arguments are supplied in a +function call than are in the function definition, the extra parameters +that are used in the function body as scalars shall evaluate to the +uninitialized value until they are otherwise initialized, and the extra +parameters that are used in the function body as arrays shall be +treated as uninitialized arrays where each element evaluates to the +uninitialized value until otherwise initialized. +.P +When invoking a function, no white space can be placed between the +function name and the opening parenthesis. Function calls can be nested +and recursive calls can be made upon functions. Upon return from any +nested or recursive function call, the values of all of the calling +function's parameters shall be unchanged, except for array parameters +passed by reference. The +.BR return +statement can be used to return a value. If a +.BR return +statement appears outside of a function definition, the behavior is +undefined. +.P +In the function definition, + +characters shall be optional before the opening brace and after the +closing brace. Function definitions can appear anywhere in the program +where a +.IR pattern-action +pair is allowed. +.SS "Grammar" +.P +The grammar in this section and the lexical conventions in the +following section shall together describe the syntax for +.IR awk +programs. The general conventions for this style of grammar are +described in +.IR "Section 1.3" ", " "Grammar Conventions". +A valid program can be represented as the non-terminal symbol +.IR program +in the grammar. This formal syntax shall take precedence over the +preceding text syntax description. +.sp +.RS 4 +.nf +\fB +%token NAME NUMBER STRING ERE +%token FUNC_NAME /* Name followed by '(' without white space. */ +.P +/* Keywords */ +%token Begin End +/* 'BEGIN' 'END' */ +.P +%token Break Continue Delete Do Else +/* 'break' 'continue' 'delete' 'do' 'else' */ +.P +%token Exit For Function If In +/* 'exit' 'for' 'function' 'if' 'in' */ +.P +%token Next Print Printf Return While +/* 'next' 'print' 'printf' 'return' 'while' */ +.P +/* Reserved function names */ +%token BUILTIN_FUNC_NAME + /* One token for the following: + * atan2 cos sin exp log sqrt int rand srand + * gsub index length match split sprintf sub + * substr tolower toupper close system + */ +%token GETLINE + /* Syntactically different from other built-ins. */ +.P +/* Two-character tokens. */ +%token ADD_ASSIGN SUB_ASSIGN MUL_ASSIGN DIV_ASSIGN MOD_ASSIGN POW_ASSIGN +/* '+=' '\(mi=' '*=' '/=' '%=' '^=' */ +.P +%token OR AND NO_MATCH EQ LE GE NE INCR DECR APPEND +/* '||' '&&' '!\^~' '==' '<=' '>=' '!=' '++' '\(mi\|\(mi' '>>' */ +.P +/* One-character tokens. */ +%token '{' '}' '(' ')' '[' ']' ',' ';' NEWLINE +%token '+' '\(mi' '*' '%' '^' '!' '>' '<' '|' '?' ':' ' " " ' '$' '=' +.P +%start program +%% +.P +program : item_list + | actionless_item_list + ; +.P +item_list : newline_opt + | actionless_item_list item terminator + | item_list item terminator + | item_list action terminator + ; +.P +actionless_item_list : item_list pattern terminator + | actionless_item_list pattern terminator + ; +.P +item : pattern action + | Function NAME '(' param_list_opt ')' + newline_opt action + | Function FUNC_NAME '(' param_list_opt ')' + newline_opt action + ; +.P +param_list_opt : /* empty */ + | param_list + ; +.P +param_list : NAME + | param_list ',' NAME + ; +.P +pattern : Begin + | End + | expr + | expr ',' newline_opt expr + ; +.P +action : '{' newline_opt '}' + | '{' newline_opt terminated_statement_list '}' + | '{' newline_opt unterminated_statement_list '}' + ; +.P +terminator : terminator ';' + | terminator NEWLINE + | ';' + | NEWLINE + ; +.P +terminated_statement_list : terminated_statement + | terminated_statement_list terminated_statement + ; +.P +unterminated_statement_list : unterminated_statement + | terminated_statement_list unterminated_statement + ; +.P +terminated_statement : action newline_opt + | If '(' expr ')' newline_opt terminated_statement + | If '(' expr ')' newline_opt terminated_statement + Else newline_opt terminated_statement + | While '(' expr ')' newline_opt terminated_statement + | For '(' simple_statement_opt ';' + expr_opt ';' simple_statement_opt ')' newline_opt + terminated_statement + | For '(' NAME In NAME ')' newline_opt + terminated_statement + | ';' newline_opt + | terminatable_statement NEWLINE newline_opt + | terminatable_statement ';' newline_opt + ; +.P +unterminated_statement : terminatable_statement + | If '(' expr ')' newline_opt unterminated_statement + | If '(' expr ')' newline_opt terminated_statement + Else newline_opt unterminated_statement + | While '(' expr ')' newline_opt unterminated_statement + | For '(' simple_statement_opt ';' + expr_opt ';' simple_statement_opt ')' newline_opt + unterminated_statement + | For '(' NAME In NAME ')' newline_opt + unterminated_statement + ; +.P +terminatable_statement : simple_statement + | Break + | Continue + | Next + | Exit expr_opt + | Return expr_opt + | Do newline_opt terminated_statement While '(' expr ')' + ; +.P +simple_statement_opt : /* empty */ + | simple_statement + ; +.P +simple_statement : Delete NAME '[' expr_list ']' + | expr + | print_statement + ; +.P +print_statement : simple_print_statement + | simple_print_statement output_redirection + ; +.P +simple_print_statement : Print print_expr_list_opt + | Print '(' multiple_expr_list ')' + | Printf print_expr_list + | Printf '(' multiple_expr_list ')' + ; +.P +output_redirection : '>' expr + | APPEND expr + | '|' expr + ; +.P +expr_list_opt : /* empty */ + | expr_list + ; +.P +expr_list : expr + | multiple_expr_list + ; +.P +multiple_expr_list : expr ',' newline_opt expr + | multiple_expr_list ',' newline_opt expr + ; +.P +expr_opt : /* empty */ + | expr + ; +.P +expr : unary_expr + | non_unary_expr + ; +.P +unary_expr : '+' expr + | '\(mi' expr + | unary_expr '^' expr + | unary_expr '*' expr + | unary_expr '/' expr + | unary_expr '%' expr + | unary_expr '+' expr + | unary_expr '\(mi' expr + | unary_expr non_unary_expr + | unary_expr '<' expr + | unary_expr LE expr + | unary_expr NE expr + | unary_expr EQ expr + | unary_expr '>' expr + | unary_expr GE expr + | unary_expr '~' expr + | unary_expr NO_MATCH expr + | unary_expr In NAME + | unary_expr AND newline_opt expr + | unary_expr OR newline_opt expr + | unary_expr '?' expr ':' expr + | unary_input_function + ; +.P +non_unary_expr : '(' expr ')' + | '!' expr + | non_unary_expr '^' expr + | non_unary_expr '*' expr + | non_unary_expr '/' expr + | non_unary_expr '%' expr + | non_unary_expr '+' expr + | non_unary_expr '\(mi' expr + | non_unary_expr non_unary_expr + | non_unary_expr '<' expr + | non_unary_expr LE expr + | non_unary_expr NE expr + | non_unary_expr EQ expr + | non_unary_expr '>' expr + | non_unary_expr GE expr + | non_unary_expr '~' expr + | non_unary_expr NO_MATCH expr + | non_unary_expr In NAME + | '(' multiple_expr_list ')' In NAME + | non_unary_expr AND newline_opt expr + | non_unary_expr OR newline_opt expr + | non_unary_expr '?' expr ':' expr + | NUMBER + | STRING + | lvalue + | ERE + | lvalue INCR + | lvalue DECR + | INCR lvalue + | DECR lvalue + | lvalue POW_ASSIGN expr + | lvalue MOD_ASSIGN expr + | lvalue MUL_ASSIGN expr + | lvalue DIV_ASSIGN expr + | lvalue ADD_ASSIGN expr + | lvalue SUB_ASSIGN expr + | lvalue '=' expr + | FUNC_NAME '(' expr_list_opt ')' + /* no white space allowed before '(' */ + | BUILTIN_FUNC_NAME '(' expr_list_opt ')' + | BUILTIN_FUNC_NAME + | non_unary_input_function + ; +.P +print_expr_list_opt : /* empty */ + | print_expr_list + ; +.P +print_expr_list : print_expr + | print_expr_list ',' newline_opt print_expr + ; +.P +print_expr : unary_print_expr + | non_unary_print_expr + ; +.P +unary_print_expr : '+' print_expr + | '\(mi' print_expr + | unary_print_expr '^' print_expr + | unary_print_expr '*' print_expr + | unary_print_expr '/' print_expr + | unary_print_expr '%' print_expr + | unary_print_expr '+' print_expr + | unary_print_expr '\(mi' print_expr + | unary_print_expr non_unary_print_expr + | unary_print_expr '~' print_expr + | unary_print_expr NO_MATCH print_expr + | unary_print_expr In NAME + | unary_print_expr AND newline_opt print_expr + | unary_print_expr OR newline_opt print_expr + | unary_print_expr '?' print_expr ':' print_expr + ; +.P +non_unary_print_expr : '(' expr ')' + | '!' print_expr + | non_unary_print_expr '^' print_expr + | non_unary_print_expr '*' print_expr + | non_unary_print_expr '/' print_expr + | non_unary_print_expr '%' print_expr + | non_unary_print_expr '+' print_expr + | non_unary_print_expr '\(mi' print_expr + | non_unary_print_expr non_unary_print_expr + | non_unary_print_expr '~' print_expr + | non_unary_print_expr NO_MATCH print_expr + | non_unary_print_expr In NAME + | '(' multiple_expr_list ')' In NAME + | non_unary_print_expr AND newline_opt print_expr + | non_unary_print_expr OR newline_opt print_expr + | non_unary_print_expr '?' print_expr ':' print_expr + | NUMBER + | STRING + | lvalue + | ERE + | lvalue INCR + | lvalue DECR + | INCR lvalue + | DECR lvalue + | lvalue POW_ASSIGN print_expr + | lvalue MOD_ASSIGN print_expr + | lvalue MUL_ASSIGN print_expr + | lvalue DIV_ASSIGN print_expr + | lvalue ADD_ASSIGN print_expr + | lvalue SUB_ASSIGN print_expr + | lvalue '=' print_expr + | FUNC_NAME '(' expr_list_opt ')' + /* no white space allowed before '(' */ + | BUILTIN_FUNC_NAME '(' expr_list_opt ')' + | BUILTIN_FUNC_NAME + ; +.P +lvalue : NAME + | NAME '[' expr_list ']' + | '$' expr + ; +.P +non_unary_input_function : simple_get + | simple_get '<' expr + | non_unary_expr '|' simple_get + ; +.P +unary_input_function : unary_expr '|' simple_get + ; +.P +simple_get : GETLINE + | GETLINE lvalue + ; +.P +newline_opt : /* empty */ + | newline_opt NEWLINE + ; +.fi \fR +.P +.RE +.P +This grammar has several ambiguities that shall be resolved as +follows: +.IP " *" 4 +Operator precedence and associativity shall be as described in +.IR "Table 4-1, Expressions in Decreasing Precedence in \fIawk\fP". +.IP " *" 4 +In case of ambiguity, an +.BR else +shall be associated with the most immediately preceding +.BR if +that would satisfy the grammar. +.IP " *" 4 +In some contexts, a + +(\c +.BR '/' ) +that is used to surround an ERE could also be the division operator. +This shall be resolved in such a way that wherever the division +operator could appear, a + +is assumed to be the division operator. (There is no unary division +operator.) +.P +Each expression in an +.IR awk +program shall conform to the precedence and associativity rules, even +when this is not needed to resolve an ambiguity. For example, because +.BR '$' +has higher precedence than +.BR '++' , +the string +.BR \(dq$x++\(mi\|\(mi\(dq +is not a valid +.IR awk +expression, even though it is unambiguously parsed by the grammar as +.BR \(dq$(x++)\(mi\|\(mi\(dq . +.P +One convention that might not be obvious from the formal grammar is +where + +characters are acceptable. There are several obvious placements such as +terminating a statement, and a + +can be used to escape + +characters between any lexical tokens. In addition, + +characters without + +characters can follow a comma, an open brace, logical AND operator (\c +.BR \(dq&&\(dq ), +logical OR operator (\c +.BR \(dq||\(dq ), +the +.BR do +keyword, the +.BR else +keyword, and the closing parenthesis of an +.BR if , +.BR for , +or +.BR while +statement. For example: +.sp +.RS 4 +.nf +\fB +{ print $1, + $2 } +.fi \fR +.P +.RE +.SS "Lexical Conventions" +.P +The lexical conventions for +.IR awk +programs, with respect to the preceding grammar, shall be as follows: +.IP " 1." 4 +Except as noted, +.IR awk +shall recognize the longest possible token or delimiter beginning at a +given point. +.IP " 2." 4 +A comment shall consist of any characters beginning with the + +character and terminated by, but excluding the next occurrence of, a +. +Comments shall have no effect, except to delimit lexical tokens. +.IP " 3." 4 +The + +shall be recognized as the token +.BR NEWLINE . +.IP " 4." 4 +A + +character immediately followed by a + +shall have no effect. +.IP " 5." 4 +The token +.BR STRING +shall represent a string constant. A string constant shall begin with +the character +.BR '\&"' . +Within a string constant, a + +character shall be considered to begin an escape sequence as specified +in the table in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation" +(\c +.BR '\e\e' , +.BR '\ea' , +.BR '\eb' , +.BR '\ef' , +.BR '\en' , +.BR '\er' , +.BR '\et' , +.BR '\ev' ). +In addition, the escape sequences in +.IR "Table 4-2, Escape Sequences in \fIawk\fP" +shall be recognized. A + +shall not occur within a string constant. A string constant shall be +terminated by the first unescaped occurrence of the character +.BR '\&"' +after the one that begins the string constant. The value of the string +shall be the sequence of all unescaped characters and values of escape +sequences between, but not including, the two delimiting +.BR '\&"' +characters. +.IP " 6." 4 +The token +.BR ERE +represents an extended regular expression constant. An ERE constant +shall begin with the + +character. Within an ERE constant, a + +character shall be considered to begin an escape sequence as +specified in the table in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation". +In addition, the escape sequences in +.IR "Table 4-2, Escape Sequences in \fIawk\fP" +shall be recognized. The application shall ensure that a + +does not occur within an ERE constant. An ERE constant shall be +terminated by the first unescaped occurrence of the + +character after the one that begins the ERE constant. The extended regular +expression represented by the ERE constant shall be the sequence of all +unescaped characters and values of escape sequences between, but not +including, the two delimiting + +characters. +.IP " 7." 4 +A + +shall have no effect, except to delimit lexical tokens or within +.BR STRING +or +.BR ERE +tokens. +.IP " 8." 4 +The token +.BR NUMBER +shall represent a numeric constant. Its form and numeric value shall +either be equivalent to the +.BR decimal-floating-constant +token as specified by the ISO\ C standard, or it shall be a sequence of decimal +digits and shall be evaluated as an integer constant in decimal. In +addition, implementations may accept numeric constants with the form +and numeric value equivalent to the +.BR hexadecimal-constant +and +.BR hexadecimal-floating-constant +tokens as specified by the ISO\ C standard. +.RS 4 +.P +If the value is too large or too small to be representable (see +.IR "Section 1.1.2" ", " "Concepts Derived from the ISO C Standard"), +the behavior is undefined. +.RE +.IP " 9." 4 +A sequence of underscores, digits, and alphabetics from the portable +character set (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set"), +beginning with an + +or alphabetic character, shall be considered a word. +.IP 10. 4 +The following words are keywords that shall be recognized as individual +tokens; the name of the token is the same as the keyword: +.TS +tab(@); +lw(0.6i)eB leB leB leB leB leB. +T{ +.nf +BEGIN +break +continue +T}@T{ +.nf +delete +do +else +T}@T{ +.nf +END +exit +for +T}@T{ +.nf +function +getline +if +T}@T{ +.nf +in +next +print +T}@T{ +.nf +printf +return +while +T} +.TE +.IP 11. 4 +The following words are names of built-in functions and shall be +recognized as the token +.BR BUILTIN_FUNC_NAME : +.TS +tab(@); +lw(0.6i)eB leB leB leB leB leB. +T{ +.nf +atan2 +close +cos +exp +T}@T{ +.nf +gsub +index +int +length +T}@T{ +.nf +log +match +rand +sin +T}@T{ +.nf +split +sprintf +sqrt +srand +T}@T{ +.nf +sub +substr +system +tolower +T}@T{ +.nf +toupper +.fi +T} +.TE +.RS 4 +.P +The above-listed keywords and names of built-in functions are +considered reserved words. +.RE +.IP 12. 4 +The token +.BR NAME +shall consist of a word that is not a keyword or a name of a built-in +function and is not followed immediately (without any delimiters) by +the +.BR '(' +character. +.IP 13. 4 +The token +.BR FUNC_NAME +shall consist of a word that is not a keyword or a name of a built-in +function, followed immediately (without any delimiters) by the +.BR '(' +character. The +.BR '(' +character shall not be included as part of the token. +.IP 14. 4 +The following two-character sequences shall be recognized as the named +tokens: +.TS +box center tab(@); +cB | cB | cB | cB +lB | cf5 | lB | cf5. +Token Name@Sequence@Token Name@Sequence +_ +ADD_ASSIGN@+=@NO_MATCH@!~ +SUB_ASSIGN@\(mi=@EQ@== +MUL_ASSIGN@*=@LE@<= +DIV_ASSIGN@/=@GE@>= +MOD_ASSIGN@%=@NE@!= +POW_ASSIGN@^=@INCR@++ +OR@||@DECR@\(mi\|\(mi +AND@&&@APPEND@>> +.TE +.IP 15. 4 +The following single characters shall be recognized as tokens whose +names are the character: +.RS 4 +.sp +.RS 4 +.nf +\fB + { } ( ) [ ] , ; + \(mi * % ^ ! > < | ? : " " $ = +.fi \fR +.P +.RE +.RE +.P +There is a lexical ambiguity between the token +.BR ERE +and the tokens +.BR '/' +and +.BR DIV_ASSIGN . +When an input sequence begins with a + +character in any syntactic context where the token +.BR '/' +or +.BR DIV_ASSIGN +could appear as the next token in a valid program, the longer of those +two tokens that can be recognized shall be recognized. In any other +syntactic context where the token +.BR ERE +could appear as the next token in a valid program, the token +.BR ERE +shall be recognized. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All input files were processed successfully. +.IP >0 6 +An error occurred. +.P +The exit status can be altered within the program by using an +.BR exit +expression. +.SH "CONSEQUENCES OF ERRORS" +If any +.IR file +operand is specified and the named file cannot be accessed, +.IR awk +shall write a diagnostic message to standard error and terminate +without any further action. +.P +If the program specified by either the +.IR program +operand or a +.IR progfile +operand is not a valid +.IR awk +program (as specified in the EXTENDED DESCRIPTION section), the +behavior is undefined. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.BR index , +.BR length , +.BR match , +and +.BR substr +functions should not be confused with similar functions in the ISO\ C standard; +the +.IR awk +versions deal with characters, while the ISO\ C standard deals with bytes. +.P +Because the concatenation operation is represented by adjacent +expressions rather than an explicit operator, it is often necessary to +use parentheses to enforce the proper evaluation precedence. +.SH EXAMPLES +The +.IR awk +program specified in the command line is most easily specified within +single-quotes (for example, '\fIprogram\fP') for applications using +.IR sh , +because +.IR awk +programs commonly contain characters that are special to the shell, +including double-quotes. In the cases where an +.IR awk +program contains single-quote characters, it is usually easiest to +specify most of the program as strings within single-quotes +concatenated by the shell with quoted single-quote characters. For +example: +.sp +.RS 4 +.nf +\fB +awk '/'\e''/ { print "quote:", $0 }' +.fi \fR +.P +.RE +.P +prints all lines from the standard input containing a single-quote +character, prefixed with +.IR quote :. +.P +The following are examples of simple +.IR awk +programs: +.IP " 1." 4 +Write to the standard output all input lines for which field 3 is +greater than 5: +.RS 4 +.sp +.RS 4 +.nf +\fB +$3 > 5 +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +Write every tenth line: +.RS 4 +.sp +.RS 4 +.nf +\fB +(NR % 10) == 0 +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +Write any line with a substring matching the regular expression: +.RS 4 +.sp +.RS 4 +.nf +\fB +/(G|D)(2[0\(mi9][[:alpha:]]*)/ +.fi \fR +.P +.RE +.RE +.IP " 4." 4 +Print any line with a substring containing a +.BR 'G' +or +.BR 'D' , +followed by a sequence of digits and characters. This example uses +character classes +.BR digit +and +.BR alpha +to match language-independent digit and alphabetic characters +respectively: +.RS 4 +.sp +.RS 4 +.nf +\fB +/(G|D)([[:digit:][:alpha:]]*)/ +.fi \fR +.P +.RE +.RE +.IP " 5." 4 +Write any line in which the second field matches the regular expression +and the fourth field does not: +.RS 4 +.sp +.RS 4 +.nf +\fB +$2 " " /xyz/ && $4 ! " " /xyz/ +.fi \fR +.P +.RE +.RE +.IP " 6." 4 +Write any line in which the second field contains a +: +.RS 4 +.sp +.RS 4 +.nf +\fB +$2 " " /\e\e/ +.fi \fR +.P +.RE +.RE +.IP " 7." 4 +Write any line in which the second field contains a +. +Note that +-escapes +are interpreted twice; once in lexical processing of the string and once +in processing the regular expression: +.RS 4 +.sp +.RS 4 +.nf +\fB +$2 " " "\e\e\e\e" +.fi \fR +.P +.RE +.RE +.IP " 8." 4 +Write the second to the last and the last field in each line. Separate +the fields by a +: +.RS 4 +.sp +.RS 4 +.nf +\fB +{OFS=":";print $(NF\(mi1), $NF} +.fi \fR +.P +.RE +.RE +.IP " 9." 4 +Write the line number and number of fields in each line. The three +strings representing the line number, the +, +and the number of fields are concatenated and that string is written to +standard output: +.RS 4 +.sp +.RS 4 +.nf +\fB +{print NR ":" NF} +.fi \fR +.P +.RE +.RE +.IP 10. 4 +Write lines longer than 72 characters: +.RS 4 +.sp +.RS 4 +.nf +\fB +length($0) > 72 +.fi \fR +.P +.RE +.RE +.IP 11. 4 +Write the first two fields in opposite order separated by +.BR OFS : +.RS 4 +.sp +.RS 4 +.nf +\fB +{ print $2, $1 } +.fi \fR +.P +.RE +.RE +.IP 12. 4 +Same, with input fields separated by a + +or + +and + +characters, or both: +.RS 4 +.sp +.RS 4 +.nf +\fB +BEGIN { FS = ",[ \et]*|[ \et]+" } + { print $2, $1 } +.fi \fR +.P +.RE +.RE +.IP 13. 4 +Add up the first column, print sum, and average: +.RS 4 +.sp +.RS 4 +.nf +\fB + {s += $1 } +END {print "sum is ", s, " average is", s/NR} +.fi \fR +.P +.RE +.RE +.IP 14. 4 +Write fields in reverse order, one per line (many lines out for each +line in): +.RS 4 +.sp +.RS 4 +.nf +\fB +{ for (i = NF; i > 0; \(mi\|\(mii) print $i } +.fi \fR +.P +.RE +.RE +.IP 15. 4 +Write all lines between occurrences of the strings +.BR start +and +.BR stop : +.RS 4 +.sp +.RS 4 +.nf +\fB +/start/, /stop/ +.fi \fR +.P +.RE +.RE +.IP 16. 4 +Write all lines whose first field is different from the previous one: +.RS 4 +.sp +.RS 4 +.nf +\fB +$1 != prev { print; prev = $1 } +.fi \fR +.P +.RE +.RE +.IP 17. 4 +Simulate +.IR echo : +.RS 4 +.sp +.RS 4 +.nf +\fB +BEGIN { + for (i = 1; i < ARGC; ++i) + printf("%s%s", ARGV[i], i==ARGC\(mi1?"\en":" ") +} +.fi \fR +.P +.RE +.RE +.IP 18. 4 +Write the path prefixes contained in the +.IR PATH +environment variable, one per line: +.RS 4 +.sp +.RS 4 +.nf +\fB +BEGIN { + n = split (ENVIRON["PATH"], path, ":") + for (i = 1; i <= n; ++i) + print path[i] +} +.fi \fR +.P +.RE +.RE +.IP 19. 4 +If there is a file named +.BR input +containing page headers of the form: +Page # +.RS 4 +.P +and a file named +.BR program +that contains: +.sp +.RS 4 +.nf +\fB +/Page/ { $2 = n++; } + { print } +.fi \fR +.P +.RE +then the command line: +.sp +.RS 4 +.nf +\fB +awk \(mif program n=5 input +.fi \fR +.P +.RE +.P +prints the file +.BR input , +filling in page numbers starting at 5. +.RE +.SH RATIONALE +This description is based on the new +.IR awk , +``nawk'', (see the referenced \fIThe AWK Programming Language\fP), which introduced a number of new features to +the historical +.IR awk : +.IP " 1." 4 +New keywords: +.BR delete , +.BR do , +.BR function , +.BR return +.IP " 2." 4 +New built-in functions: +.BR atan2 , +.BR close , +.BR cos , +.BR gsub , +.BR match , +.BR rand , +.BR sin , +.BR srand , +.BR sub , +.BR system +.IP " 3." 4 +New predefined variables: +.BR FNR , +.BR ARGC , +.BR ARGV , +.BR RSTART , +.BR RLENGTH , +.BR SUBSEP +.IP " 4." 4 +New expression operators: +.BR ? , +.BR : , +.BR , , +.BR ^ +.IP " 5." 4 +The +.BR FS +variable and the third argument to +.BR split , +now treated as extended regular expressions. +.IP " 6." 4 +The operator precedence, changed to more closely match the C language. +Two examples of code that operate differently are: +.RS 4 +.sp +.RS 4 +.nf +\fB +while ( n /= 10 > 1) ... +if (!"wk" ~ /bwk/) ... +.fi \fR +.P +.RE +.RE +.P +Several features have been added based on newer implementations of +.IR awk : +.IP " *" 4 +Multiple instances of +.BR \(mif +.IR progfile +are permitted. +.IP " *" 4 +The new option +.BR \(miv +.IR assignment. +.IP " *" 4 +The new predefined variable +.BR ENVIRON . +.IP " *" 4 +New built-in functions +.BR toupper +and +.BR tolower . +.IP " *" 4 +More formatting capabilities are added to +.BR printf +to match the ISO\ C standard. +.P +The overall +.IR awk +syntax has always been based on the C language, with a few features +from the shell command language and other sources. Because of this, it +is not completely compatible with any other language, which has caused +confusion for some users. It is not the intent of the standard +developers to address such issues. A few relatively minor changes +toward making the language more compatible with the ISO\ C standard were +made; most of these changes are based on similar changes in recent +implementations, as described above. There remain several C-language +conventions that are not in +.IR awk . +One of the notable ones is the + +operator, which is commonly used to specify multiple expressions in the +C language +.BR for +statement. Also, there are various places where +.IR awk +is more restrictive than the C language regarding the type of +expression that can be used in a given context. These limitations are +due to the different features that the +.IR awk +language does provide. +.P +Regular expressions in +.IR awk +have been extended somewhat from historical implementations to make +them a pure superset of extended regular expressions, as defined by +POSIX.1\(hy2008 (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.4" ", " "Extended Regular Expressions"). +The main extensions are internationalization +features and interval expressions. Historical implementations of +.IR awk +have long supported +-escape +sequences as an extension to extended regular expressions, and +this extension has been retained despite inconsistency with other +utilities. The number of escape sequences recognized in both extended +regular expressions and strings has varied (generally increasing with +time) among implementations. The set specified by POSIX.1\(hy2008 includes most +sequences known to be supported by popular implementations and by the +ISO\ C standard. One sequence that is not supported is hexadecimal value escapes +beginning with +.BR '\ex' . +This would allow values expressed in more than 9 bits to be used within +.IR awk +as in the ISO\ C standard. However, because this syntax has a non-deterministic +length, it does not permit the subsequent character to be a hexadecimal +digit. This limitation can be dealt with in the C language by the use +of lexical string concatenation. In the +.IR awk +language, concatenation could also be a solution for strings, but not +for extended regular expressions (either lexical ERE tokens or strings +used dynamically as regular expressions). Because of this limitation, +the feature has not been added to POSIX.1\(hy2008. +.P +When a string variable is used in a context where an extended regular +expression normally appears (where the lexical token ERE is used in the +grammar) the string does not contain the literal + +characters. +.P +Some versions of +.IR awk +allow the form: +.sp +.RS 4 +.nf +\fB +func name(args, ... ) { statements } +.fi \fR +.P +.RE +.P +This has been deprecated by the authors of the language, who asked that +it not be specified. +.P +Historical implementations of +.IR awk +produce an error if a +.BR next +statement is executed in a +.BR BEGIN +action, and cause +.IR awk +to terminate if a +.BR next +statement is executed in an +.BR END +action. This behavior has not been documented, and it was not believed +that it was necessary to standardize it. +.P +The specification of conversions between string and numeric values is +much more detailed than in the documentation of historical +implementations or in the referenced \fIThe AWK Programming Language\fP. Although most of the behavior is +designed to be intuitive, the details are necessary to ensure +compatible behavior from different implementations. This is especially +important in relational expressions since the types of the operands +determine whether a string or numeric comparison is performed. From the +perspective of an application developer, it is usually sufficient to +expect intuitive behavior and to force conversions (by adding zero or +concatenating a null string) when the type of an expression does not +obviously match what is needed. The intent has been to specify +historical practice in almost all cases. The one exception is that, in +historical implementations, variables and constants maintain both +string and numeric values after their original value is converted by +any use. This means that referencing a variable or constant can have +unexpected side-effects. For example, with historical implementations +the following program: +.sp +.RS 4 +.nf +\fB +{ + a = "+2" + b = 2 + if (NR % 2) + c = a + b + if (a == b) + print "numeric comparison" + else + print "string comparison" +} +.fi \fR +.P +.RE +.P +would perform a numeric comparison (and output numeric comparison) for +each odd-numbered line, but perform a string comparison (and output +string comparison) for each even-numbered line. POSIX.1\(hy2008 ensures that +comparisons will be numeric if necessary. With historical +implementations, the following program: +.sp +.RS 4 +.nf +\fB +BEGIN { + OFMT = "%e" + print 3.14 + OFMT = "%f" + print 3.14 +} +.fi \fR +.P +.RE +.P +would output +.BR \(dq3.140000e+00\(dq +twice, because in the second +.BR print +statement the constant +.BR \(dq3.14\(dq +would have a string value from the previous conversion. POSIX.1\(hy2008 requires +that the output of the second +.BR print +statement be +.BR \(dq3.140000\(dq . +The behavior of historical implementations was seen as too unintuitive +and unpredictable. +.P +It was pointed out that with the rules contained in early drafts, the +following script would print nothing: +.sp +.RS 4 +.nf +\fB +BEGIN { + y[1.5] = 1 + OFMT = "%e" + print y[1.5] +} +.fi \fR +.P +.RE +.P +Therefore, a new variable, +.BR CONVFMT , +was introduced. The +.BR OFMT +variable is now restricted to affecting output conversions of numbers +to strings and +.BR CONVFMT +is used for internal conversions, such as comparisons or array +indexing. The default value is the same as that for +.BR OFMT , +so unless a program changes +.BR CONVFMT +(which no historical program would do), it will receive the historical +behavior associated with internal string conversions. +.P +The POSIX +.IR awk +lexical and syntactic conventions are specified more formally than in +other sources. Again the intent has been to specify historical +practice. One convention that may not be obvious from the formal +grammar as in other verbal descriptions is where + +characters are acceptable. There are several obvious placements such as +terminating a statement, and a + +can be used to escape + +characters between any lexical tokens. In addition, + +characters without + +characters can follow a comma, an open brace, a logical AND operator (\c +.BR \(dq&&\(dq ), +a logical OR operator (\c +.BR \(dq||\(dq ), +the +.BR do +keyword, the +.BR else +keyword, and the closing parenthesis of an +.BR if , +.BR for , +or +.BR while +statement. For example: +.sp +.RS 4 +.nf +\fB +{ print $1, + $2 } +.fi \fR +.P +.RE +.P +The requirement that +.IR awk +add a trailing + +to the program argument text is to simplify the grammar, making it +match a text file in form. There is no way for an application or test +suite to determine whether a literal + +is added or whether +.IR awk +simply acts as if it did. +.P +POSIX.1\(hy2008 requires several changes from historical implementations in order +to support internationalization. Probably the most subtle of these is +the use of the decimal-point character, defined by the +.IR LC_NUMERIC +category of the locale, in representations of floating-point numbers. +This locale-specific character is used in recognizing numeric input, in +converting between strings and numeric values, and in formatting +output. However, regardless of locale, the + +character (the decimal-point character of the POSIX locale) is the +decimal-point character recognized in processing +.IR awk +programs (including assignments in command line arguments). This is +essentially the same convention as the one used in the ISO\ C standard. The +difference is that the C language includes the +\fIsetlocale\fR() +function, which permits an application to modify its locale. Because of +this capability, a C application begins executing with its locale set +to the C locale, and only executes in the environment-specified locale +after an explicit call to +\fIsetlocale\fR(). +However, adding such an elaborate new feature to the +.IR awk +language was seen as inappropriate for POSIX.1\(hy2008. It is possible to execute +an +.IR awk +program explicitly in any desired locale by setting the environment in +the shell. +.P +The undefined behavior resulting from NULs in extended regular +expressions allows future extensions for the GNU +.IR gawk +program to process binary data. +.P +The behavior in the case of invalid +.IR awk +programs (including lexical, syntactic, and semantic errors) is +undefined because it was considered overly limiting on implementations +to specify. In most cases such errors can be expected to produce a +diagnostic and a non-zero exit status. However, some implementations +may choose to extend the language in ways that make use of certain +invalid constructs. Other invalid constructs might be deemed worthy of +a warning, but otherwise cause some reasonable behavior. Still other +constructs may be very difficult to detect in some implementations. +Also, different implementations might detect a given error during an +initial parsing of the program (before reading any input files) while +others might detect it when executing the program after reading some +input. Implementors should be aware that diagnosing errors as early as +possible and producing useful diagnostics can ease debugging of +applications, and thus make an implementation more usable. +.P +The unspecified behavior from using multi-character +.BR RS +values is to allow possible future extensions based on extended regular +expressions used for record separators. Historical implementations take +the first character of the string and ignore the others. +.P +Unspecified behavior when +.IR split (\c +.IR string ,\c +.IR array ,\c +) +is used is to allow a proposed future extension that would split up a +string into an array of individual characters. +.P +In the context of the +.BR getline +function, equally good arguments for different precedences of the +.BR | +and +.BR < +operators can be made. Historical practice has been that: +.sp +.RS 4 +.nf +\fB +getline < "a" "b" +.fi \fR +.P +.RE +.P +is parsed as: +.sp +.RS 4 +.nf +\fB +( getline < "a" ) "b" +.fi \fR +.P +.RE +.P +although many would argue that the intent was that the file +.BR ab +should be read. However: +.sp +.RS 4 +.nf +\fB +getline < "x" + 1 +.fi \fR +.P +.RE +.P +parses as: +.sp +.RS 4 +.nf +\fB +getline < ( "x" + 1 ) +.fi \fR +.P +.RE +.P +Similar problems occur with the +.BR | +version of +.BR getline , +particularly in combination with +.BR $ . +For example: +.sp +.RS 4 +.nf +\fB +$"echo hi" | getline +.fi \fR +.P +.RE +.P +(This situation is particularly problematic when used in a +.BR print +statement, where the +.BR |getline +part might be a redirection of the +.BR print .) +.P +Since in most cases such constructs are not (or at least should not) be +used (because they have a natural ambiguity for which there is no +conventional parsing), the meaning of these constructs has been made +explicitly unspecified. (The effect is that a conforming application that +runs into the problem must parenthesize to resolve the ambiguity.) +There appeared to be few if any actual uses of such constructs. +.P +Grammars can be written that would cause an error under these +circumstances. Where backwards-compatibility is not a large +consideration, implementors may wish to use such grammars. +.P +Some historical implementations have allowed some built-in functions to +be called without an argument list, the result being a default argument +list chosen in some ``reasonable'' way. Use of +.BR length +as a synonym for +.BR "length($0)" +is the only one of these forms that is thought to be widely known or +widely used; this particular form is documented in various places (for +example, most historical +.IR awk +reference pages, although not in the referenced \fIThe AWK Programming Language\fP) as legitimate practice. +With this exception, default argument lists have always been +undocumented and vaguely defined, and it is not at all clear how (or +if) they should be generalized to user-defined functions. They add no +useful functionality and preclude possible future extensions that might +need to name functions without calling them. Not standardizing them +seems the simplest course. The standard developers considered that +.BR length +merited special treatment, however, since it has been documented in the +past and sees possibly substantial use in historical programs. +Accordingly, this usage has been made legitimate, but Issue\ 5 +removed the obsolescent marking for XSI-conforming implementations +and many otherwise conforming applications depend on this feature. +.P +In +.BR sub +and +.BR gsub , +if +.IR repl +is a string literal (the lexical token +.BR STRING ), +then two consecutive + +characters should be used in the string to ensure a single + +will precede the + +when the resultant string is passed to the function. (For example, +to specify one literal + +in the replacement string, use +.BR gsub (\c +.BR ERE , +.BR \(dq\e\e&\(dq ).) +.P +Historically, the only special character in the +.IR repl +argument of +.BR sub +and +.BR gsub +string functions was the + +(\c +.BR '&' ) +character and preceding it with the + +character was used to turn off its special meaning. +.P +The description in the ISO\ POSIX\(hy2:\|1993 standard introduced behavior such that the + +character was another special character and it was unspecified whether +there were any other special characters. This description introduced +several portability problems, some of which are described below, and so +it has been replaced with the more historical description. Some of the +problems include: +.IP " *" 4 +Historically, to create the replacement string, a script could use +.BR gsub (\c +.BR ERE , +.BR \(dq\e\e&\(dq ), +but with the ISO\ POSIX\(hy2:\|1993 standard wording, it was necessary to use +.BR gsub (\c +.BR ERE , +.BR \(dq\e\e\e\e&\(dq ). +The + +characters are doubled here because all string literals are subject to +lexical analysis, which would reduce each pair of + +characters to a single + +before being passed to +.BR gsub . +.IP " *" 4 +Since it was unspecified what the special characters were, for portable +scripts to guarantee that characters are printed literally, each +character had to be preceded with a +. +(For example, a portable script had to use +.BR gsub (\c +.BR ERE , +.BR \(dq\e\eh\e\ei\(dq ) +to produce a replacement string of +.BR \(dqhi\(dq .) +.P +The description for comparisons in the ISO\ POSIX\(hy2:\|1993 standard did not properly describe +historical practice because of the way numeric strings are compared as +numbers. The current rules cause the following code: +.sp +.RS 4 +.nf +\fB +if (0 == "000") + print "strange, but true" +else + print "not true" +.fi \fR +.P +.RE +.P +to do a numeric comparison, causing the +.BR if +to succeed. It should be intuitively obvious that this is incorrect +behavior, and indeed, no historical implementation of +.IR awk +actually behaves this way. +.P +To fix this problem, the definition of +.IR "numeric string" +was enhanced to include only those values obtained from specific +circumstances (mostly external sources) where it is not possible to +determine unambiguously whether the value is intended to be a string or +a numeric. +.P +Variables that are assigned to a numeric string shall also be treated +as a numeric string. (For example, the notion of a numeric string can +be propagated across assignments.) In comparisons, all variables having +the uninitialized value are to be treated as a numeric operand +evaluating to the numeric value zero. +.P +Uninitialized variables include all types of variables including +scalars, array elements, and fields. The definition of an uninitialized +value in +.IR "Variables and Special Variables" +is necessary to describe the value placed on uninitialized variables +and on fields that are valid (for example, +.BR < +.BR $NF ) +but have no characters in them and to describe how these variables are +to be used in comparisons. A valid field, such as +.BR $1 , +that has no characters in it can be obtained from an input line of +.BR \(dq\et\et\(dq +when +.BR FS= \c +.BR '\et' . +Historically, the comparison (\c +.BR $1< 10) +was done numerically after evaluating +.BR $1 +to the value zero. +.P +The phrase ``.\|.\|. also shall have the numeric value of the numeric +string'' was removed from several sections of the ISO\ POSIX\(hy2:\|1993 standard because is +specifies an unnecessary implementation detail. It is not necessary for +POSIX.1\(hy2008 to specify that these objects be assigned two different values. +It is only necessary to specify that these objects may evaluate to two +different values depending on context. +.P +Historical implementations of +.IR awk +did not parse hexadecimal integer or floating constants like +.BR \(dq0xa\(dq +and +.BR \(dq0xap0\(dq . +Due to an oversight, the 2001 through 2004 editions of this standard +required support for hexadecimal floating constants. This was due to +the reference to +\fIatof\fR(). +This version of the standard allows but does not require implementations +to use +\fIatof\fR() +and includes a description of how floating-point numbers are recognized +as an alternative to match historic behavior. The intent of this change +is to allow implementations to recognize floating-point constants +according to either the ISO/IEC\ 9899:\|1990 standard or ISO/IEC\ 9899:\|1999 standard, and to allow (but not require) +implementations to recognize hexadecimal integer constants. +.P +Historical implementations of +.IR awk +did not support floating-point infinities and NaNs in +.IR "numeric strings" ; +e.g., +.BR \(dq\(miINF\(dq +and +.BR \(dqNaN\(dq . +However, implementations that use the +\fIatof\fR() +or +\fIstrtod\fR() +functions to do the conversion picked up support for these values if they +used a ISO/IEC\ 9899:\|1999 standard version of the function instead of a ISO/IEC\ 9899:\|1990 standard version. Due to +an oversight, the 2001 through 2004 editions of this standard did not +allow support for infinities and NaNs, but in this revision support is +allowed (but not required). This is a silent change to the behavior of +.IR awk +programs; for example, in the POSIX locale the expression: +.sp +.RS 4 +.nf +\fB +("-INF" + 0 < 0) +.fi \fR +.P +.RE +.P +formerly had the value 0 because +.BR \(dq\(miINF\(dq +converted to 0, but now it may have the value 0 or 1. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 1.3" ", " "Grammar Conventions", +.IR "\fIgrep\fR\^", +.IR "\fIlex\fR\^", +.IR "\fIsed\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation", +.IR "Section 6.1" ", " "Portable Character Set", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Chapter 9" ", " "Regular Expressions", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIatof\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIpopen\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIstrtod\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/basename.1p b/man-pages-posix-2013/man1p/basename.1p new file mode 100644 index 0000000..d5153f7 --- /dev/null +++ b/man-pages-posix-2013/man1p/basename.1p @@ -0,0 +1,288 @@ +'\" et +.TH BASENAME "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 non-directory portion of a pathname +.SH SYNOPSIS +.LP +.nf +basename \fIstring \fB[\fIsuffix\fB]\fR +.fi +.SH DESCRIPTION +The +.IR string +operand shall be treated as a pathname, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.267" ", " "Pathname". +The string +.IR string +shall be converted to the filename corresponding to the last pathname +component in +.IR string +and then the suffix string +.IR suffix , +if present, shall be removed. This shall be done by performing actions +equivalent to the following steps in order: +.IP " 1." 4 +If +.IR string +is a null string, it is unspecified whether the resulting string is +.BR '.' +or a null string. In either case, skip steps 2 through 6. +.IP " 2." 4 +If +.IR string +is +.BR \(dq//\(dq , +it is implementation-defined whether steps 3 to 6 are skipped or +processed. +.IP " 3." 4 +If +.IR string +consists entirely of + +characters, +.IR string +shall be set to a single + +character. In this case, skip steps 4 to 6. +.IP " 4." 4 +If there are any trailing + +characters in +.IR string , +they shall be removed. +.IP " 5." 4 +If there are any + +characters remaining in +.IR string , +the prefix of +.IR string +up to and including the last + +character in +.IR string +shall be removed. +.IP " 6." 4 +If the +.IR suffix +operand is present, is not identical to the characters remaining in +.IR string , +and is identical to a suffix of the characters remaining in +.IR string , +the suffix +.IR suffix +shall be removed from +.IR string . +Otherwise, +.IR string +is not modified by this step. It shall not be considered an error if +.IR suffix +is not found in +.IR string . +.P +The resulting string shall be written to standard output. +.SH OPTIONS +None. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIstring\fR" 10 +A string. +.IP "\fIsuffix\fR" 10 +A string. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR basename : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR basename +utility shall write a line to the standard output in the following +format: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIresulting string\fP> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The definition of +.IR pathname +specifies implementation-defined behavior for pathnames starting with +two + +characters. Therefore, applications shall not arbitrarily add + +characters to the beginning of a pathname unless they can ensure +that there are more or less than two or are prepared to deal with the +implementation-defined consequences. +.SH EXAMPLES +If the string +.IR string +is a valid pathname: +.sp +.RS 4 +.nf +\fB +$(basename -- "\fIstring\fP") +.fi \fR +.P +.RE +.P +produces a filename that could be used to open the file named by +.IR string +in the directory returned by: +.sp +.RS 4 +.nf +\fB +$(dirname -- "\fIstring\fP") +.fi \fR +.P +.RE +.P +If the string +.IR string +is not a valid pathname, the same algorithm is used, but the result +need not be a valid filename. The +.IR basename +utility is not expected to make any judgements about the validity of +.IR string +as a pathname; it just follows the specified algorithm to produce a +result string. +.P +The following shell script compiles +.BR /usr/src/cmd/cat.c +and moves the output to a file named +.BR cat +in the current directory when invoked with the argument +.BR /usr/src/cmd/cat +or with the argument +.BR /usr/src/cmd/cat.c : +.sp +.RS 4 +.nf +\fB +c99 -- "$(dirname -- "$1")/$(basename -- "$1" .c).c" && +mv a.out "$(basename -- "$1" .c)" +.fi \fR +.P +.RE +.SH RATIONALE +The behaviors of +.IR basename +and +.IR dirname +have been coordinated so that when +.IR string +is a valid pathname: +.sp +.RS 4 +.nf +\fB +$(basename -- "\fIstring\fP") +.fi \fR +.P +.RE +.P +would be a valid filename for the file in the directory: +.sp +.RS 4 +.nf +\fB +$(dirname -- "\fIstring\fP") +.fi \fR +.P +.RE +.P +This would not work for the early proposal versions of these utilities due +to the way it specified handling of trailing + +characters. +.P +Since the definition of +.IR pathname +specifies implementation-defined behavior for pathnames starting with +two + +characters, this volume of POSIX.1\(hy2008 specifies similar implementation-defined behavior +for the +.IR basename +and +.IR dirname +utilities. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Parameters and Variables", +.IR "\fIdirname\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.267" ", " "Pathname", +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/batch.1p b/man-pages-posix-2013/man1p/batch.1p new file mode 100644 index 0000000..1cbadf4 --- /dev/null +++ b/man-pages-posix-2013/man1p/batch.1p @@ -0,0 +1,275 @@ +'\" et +.TH BATCH "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +batch +\(em schedule commands to be executed in a batch queue +.SH SYNOPSIS +.LP +.nf +\fIbatch\fR +.fi +.SH DESCRIPTION +The +.IR batch +utility shall read commands from standard input and schedule them +for execution in a batch queue. It shall be the equivalent of +the command: +.sp +.RS 4 +.nf +\fB +at \(miq b \(mim now +.fi \fR +.P +.RE +.P +where queue +.IR b +is a special +.IR at +queue, specifically for batch jobs. Batch jobs shall be submitted to the +batch queue with no time constraints and shall be run by the system using +algorithms, based on unspecified factors, that may vary with each +invocation of +.IR batch . +.P +Users shall be permitted to use +.IR batch +if their name appears in the file +.BR at.allow +which is located in an implementation-defined directory. +If that file does not exist, the file +.BR at.deny , +which is located in an implementation-defined directory, +shall be checked to determine whether the user shall be denied access to +.IR batch . +If neither file exists, only a process with appropriate privileges +shall be allowed to submit a job. If only +.BR at.deny +exists and is empty, global usage shall be permitted. The +.BR at.allow +and +.BR at.deny +files shall consist of one user name per line. +.SH OPTIONS +None. +.SH OPERANDS +None. +.SH STDIN +The standard input shall be a text file consisting of commands +acceptable to the shell command language described in +.IR "Chapter 2" ", " "Shell Command Language". +.SH "INPUT FILES" +The text files +.BR at.allow +and +.BR at.deny , +which are located in an implementation-defined directory, +shall contain zero or more user names, one per line, of users who are, +respectively, authorized or denied access to the +.IR at +and +.IR batch +utilities. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR batch : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fILC_TIME\fP" 10 +Determine the format and contents for date and time strings written by +.IR batch . +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fISHELL\fP" 10 +Determine the name of a command interpreter to be used to invoke the +at-job. If the variable is unset or null, +.IR sh +shall be used. If it is set to a value other than a name for +.IR sh , +the implementation shall do one of the following: use that shell; use +.IR sh ; +use the login shell from the user database; any of the preceding +accompanied by a warning diagnostic about which was chosen. +.IP "\fITZ\fP" 10 +Determine the timezone. The job shall be submitted for execution at the +time specified by +.IR timespec +or +.BR \(mit +.IR time +relative to the timezone specified by the +.IR TZ +variable. If +.IR timespec +specifies a timezone, it overrides +.IR TZ . +If +.IR timespec +does not specify a timezone and +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +When standard input is a terminal, prompts of unspecified format for +each line of the user input described in the STDIN section may be +written to standard output. +.SH STDERR +The following shall be written to standard error when a job has been +successfully submitted: +.sp +.RS 4 +.nf +\fB +"job %s at %s\en", \fIat_job_id\fR, <\fIdate\fR> +.fi \fR +.P +.RE +.P +where +.IR date +shall be equivalent in format to the output of: +.sp +.RS 4 +.nf +\fB +date +"%a %b %e %T %Y" +.fi \fR +.P +.RE +.P +The date and time written shall be adjusted so that they appear in the +timezone of the user (as determined by the +.IR TZ +variable). +.P +Neither this, nor warning messages concerning the selection of the +command interpreter, are considered a diagnostic that changes the exit +status. +.P +Diagnostic messages, if any, shall be written to standard error. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +The job shall not be scheduled. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +It may be useful to redirect standard output within the specified +commands. +.SH EXAMPLES +.IP " 1." 4 +This sequence can be used at a terminal: +.RS 4 +.sp +.RS 4 +.nf +\fB +batch +sort < file >outfile +EOT +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +This sequence, which demonstrates redirecting standard error to a pipe, +is useful in a command procedure (the sequence of output redirection +specifications is significant): +.RS 4 +.sp +.RS 4 +.nf +\fB +batch <&1 >outfile | mailx mygroup +! +.fi \fR +.P +.RE +.RE +.SH RATIONALE +Early proposals described +.IR batch +in a manner totally separated from +.IR at , +even though the historical model treated it almost as a synonym for +.IR at +.BR \(miqb . +A number of features were added to list and control batch work +separately from those in +.IR at . +Upon further reflection, it was decided that the benefit of this did +not merit the change to the historical interface. +.P +The +.BR \(mim +option was included on the equivalent +.IR at +command because it is historical practice to mail results to the +submitter, even if all job-produced output is redirected. As explained +in the RATIONALE for +.IR at , +the +.BR now +keyword submits the job for immediate execution (after scheduling +delays), despite some historical systems where +.IR at +.BR now +would have been considered an error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIat\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/bc.1p b/man-pages-posix-2013/man1p/bc.1p new file mode 100644 index 0000000..a535d59 --- /dev/null +++ b/man-pages-posix-2013/man1p/bc.1p @@ -0,0 +1,1615 @@ +'\" et +.TH BC "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +bc +\(em arbitrary-precision arithmetic language +.SH SYNOPSIS +.LP +.nf +bc \fB[\fR\(mil\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR bc +utility shall implement an arbitrary precision calculator. It shall +take input from any files given, then read from the standard input. If +the standard input and standard output to +.IR bc +are attached to a terminal, the invocation of +.IR bc +shall be considered to be +.IR interactive , +causing behavioral constraints described in the following sections. +.SH OPTIONS +The +.IR bc +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(mil\fP" 10 +(The letter ell.) Define the math functions and initialize +.IR scale +to 20, instead of the default zero; see the EXTENDED DESCRIPTION +section. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a text file containing +.IR bc +program statements. After all +.IR file s +have been read, +.IR bc +shall read the standard input. +.SH STDIN +See the INPUT FILES section. +.SH "INPUT FILES" +Input files shall be text files containing a sequence of comments, +statements, and function definitions that shall be executed as they are +read. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR bc : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The output of the +.IR bc +utility shall be controlled by the program read, and consist of zero or +more lines containing the value of all executed expressions without +assignments. The radix and precision of the output shall be controlled +by the values of the +.BR obase +and +.BR scale +variables; see the EXTENDED DESCRIPTION section. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +.SS "Grammar" +.P +The grammar in this section and the lexical conventions in the +following section shall together describe the syntax for +.IR bc +programs. The general conventions for this style of grammar are +described in +.IR "Section 1.3" ", " "Grammar Conventions". +A valid program can be represented as the non-terminal symbol +.BR program +in the grammar. This formal syntax shall take precedence over the +text syntax description. +.sp +.RS 4 +.nf +\fB +%token EOF NEWLINE STRING LETTER NUMBER +.P +%token MUL_OP +/* '*', '/', '%' */ +.P +%token ASSIGN_OP +/* '=', '+=', '\(mi=', '*=', '/=', '%=', '^=' */ +.P +%token REL_OP +/* '==', '<=', '>=', '!=', '<', '>' */ +.P +%token INCR_DECR +/* '++', '\(mi\|\(mi' */ +.P +%token Define Break Quit Length +/* 'define', 'break', 'quit', 'length' */ +.P +%token Return For If While Sqrt +/* 'return', 'for', 'if', 'while', 'sqrt' */ +.P +%token Scale Ibase Obase Auto +/* 'scale', 'ibase', 'obase', 'auto' */ +.P +%start program +.P +%% +.P +program : EOF + | input_item program + ; +.P +input_item : semicolon_list NEWLINE + | function + ; +.P +semicolon_list : /* empty */ + | statement + | semicolon_list ';' statement + | semicolon_list ';' + ; +.P +statement_list : /* empty */ + | statement + | statement_list NEWLINE + | statement_list NEWLINE statement + | statement_list ';' + | statement_list ';' statement + ; +.P +statement : expression + | STRING + | Break + | Quit + | Return + | Return '(' return_expression ')' + | For '(' expression ';' + relational_expression ';' + expression ')' statement + | If '(' relational_expression ')' statement + | While '(' relational_expression ')' statement + | '{' statement_list '}' + ; +.P +function : Define LETTER '(' opt_parameter_list ')' + '{' NEWLINE opt_auto_define_list + statement_list '}' + ; +.P +opt_parameter_list : /* empty */ + | parameter_list + ; +.P +parameter_list : LETTER + | define_list ',' LETTER + ; +.P +opt_auto_define_list : /* empty */ + | Auto define_list NEWLINE + | Auto define_list ';' + ; +.P +define_list : LETTER + | LETTER '[' ']' + | define_list ',' LETTER + | define_list ',' LETTER '[' ']' + ; +.P +opt_argument_list : /* empty */ + | argument_list + ; +.P +argument_list : expression + | LETTER '[' ']' ',' argument_list + ; +.P +relational_expression : expression + | expression REL_OP expression + ; +.P +return_expression : /* empty */ + | expression + ; +.P +expression : named_expression + | NUMBER + | '(' expression ')' + | LETTER '(' opt_argument_list ')' + | '\(mi' expression + | expression '+' expression + | expression '\(mi' expression + | expression MUL_OP expression + | expression '^' expression + | INCR_DECR named_expression + | named_expression INCR_DECR + | named_expression ASSIGN_OP expression + | Length '(' expression ')' + | Sqrt '(' expression ')' + | Scale '(' expression ')' + ; +.P +named_expression : LETTER + | LETTER '[' expression ']' + | Scale + | Ibase + | Obase + ; +.fi \fR +.P +.RE +.SS "Lexical Conventions in bc" +.P +The lexical conventions for +.IR bc +programs, with respect to the preceding grammar, shall be as follows: +.IP " 1." 4 +Except as noted, +.IR bc +shall recognize the longest possible token or delimiter beginning at a +given point. +.IP " 2." 4 +A comment shall consist of any characters beginning with the two adjacent +characters +.BR \(dq/*\(dq +and terminated by the next occurrence of the two adjacent characters +.BR \(dq*/\(dq . +Comments shall have no effect except to delimit lexical tokens. +.IP " 3." 4 +The + +shall be recognized as the token +.BR NEWLINE . +.IP " 4." 4 +The token +.BR STRING +shall represent a string constant; it shall consist of any characters +beginning with the double-quote character (\c +.BR '\&"' ) +and terminated by another occurrence of the double-quote character. The +value of the string is the sequence of all characters between, but not +including, the two double-quote characters. All characters shall be +taken literally from the input, and there is no way to specify a string +containing a double-quote character. The length of the value of each +string shall be limited to +{BC_STRING_MAX} +bytes. +.IP " 5." 4 +A + +shall have no effect except as an ordinary character if it appears +within a +.BR STRING +token, or to delimit a lexical token other than +.BR STRING . +.IP " 6." 4 +The combination of a + +character immediately followed by a + +shall have no effect other than to delimit lexical tokens with the +following exceptions: +.RS 4 +.IP " *" 4 +It shall be interpreted as the character sequence +.BR \(dq\e\(dq +in +.BR STRING +tokens. +.IP " *" 4 +It shall be ignored as part of a multi-line +.BR NUMBER +token. +.RE +.IP " 7." 4 +The token +.BR NUMBER +shall represent a numeric constant. It shall be recognized by the +following grammar: +.RS 4 +.sp +.RS 4 +.nf +\fB +NUMBER : integer + | '.' integer + | integer '.' + | integer '.' integer + ; +.P +integer : digit + | integer digit + ; +.P +digit : 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 + | 8 | 9 | A | B | C | D | E | F + ; +.fi \fR +.P +.RE +.RE +.IP " 8." 4 +The value of a +.BR NUMBER +token shall be interpreted as a numeral in the base specified by the +value of the internal register +.BR ibase +(described below). Each of the +.BR digit +characters shall have the value from 0 to 15 in the order listed here, +and the + +character shall represent the radix point. The behavior is undefined if +digits greater than or equal to the value of +.BR ibase +appear in the token. However, note the exception for single-digit +values being assigned to +.BR ibase +and +.BR obase +themselves, in +.IR "Operations in bc". +.IP " 9." 4 +The following keywords shall be recognized as tokens: +.TS +tab(@); +lBw(0.6i)e lBe lBe lBe lBe. +T{ +.nf +auto +break +define +T}@T{ +.nf +ibase +if +for +T}@T{ +.nf +length +obase +quit +T}@T{ +.nf +return +scale +sqrt +T}@T{ +.nf +while +.fi +T} +.TE +.IP 10. 4 +Any of the following characters occurring anywhere except within a +keyword shall be recognized as the token +.BR LETTER : +.RS 4 +.sp +.RS 4 +.nf +\fB +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 +.fi \fR +.P +.RE +.RE +.IP 11. 4 +The following single-character and two-character sequences shall be +recognized as the token +.BR ASSIGN_OP : +.RS 4 +.sp +.RS 4 +.nf +\fB += += \(mi= *= /= %= ^= +.fi \fR +.P +.RE +.RE +.IP 12. 4 +If an +.BR '=' +character, as the beginning of a token, is followed by a +.BR '\(mi' +character with no intervening delimiter, the behavior is undefined. +.IP 13. 4 +The following single-characters shall be recognized as the token +.BR MUL_OP : +.RS 4 +.sp +.RS 4 +.nf +\fB +* / % +.fi \fR +.P +.RE +.RE +.IP 14. 4 +The following single-character and two-character sequences shall be +recognized as the token +.BR REL_OP : +.RS 4 +.sp +.RS 4 +.nf +\fB +== <= >= != < > +.fi \fR +.P +.RE +.RE +.IP 15. 4 +The following two-character sequences shall be recognized as the token +.BR INCR_DECR : +.RS 4 +.sp +.RS 4 +.nf +\fB +++ \(mi\|\(mi +.fi \fR +.P +.RE +.RE +.IP 16. 4 +The following single characters shall be recognized as tokens whose +names are the character: +.RS 4 +.sp +.RS 4 +.nf +\fB + ( ) , + \(mi ; [ ] ^ { } +.fi \fR +.P +.RE +.RE +.IP 17. 4 +The token +.BR EOF +is returned when the end of input is reached. +.SS "Operations in bc" +.P +There are three kinds of identifiers: ordinary identifiers, array +identifiers, and function identifiers. +All three types consist of single lowercase letters. Array identifiers +shall be followed by square brackets (\c +.BR \(dq[]\(dq ). +An array subscript is required except in an argument or auto list. +Arrays are singly dimensioned and can contain up to +{BC_DIM_MAX} +elements. Indexing shall begin at zero so an array is indexed from 0 to +{BC_DIM_MAX}\(mi1. +Subscripts shall be truncated to integers. The application shall ensure +that function identifiers are followed by parentheses, possibly +enclosing arguments. The three types of identifiers do not conflict. +.P +The following table summarizes the rules for precedence and +associativity of all operators. Operators on the same line shall have +the same precedence; rows are in order of decreasing precedence. +.sp +.ce 1 +\fBTable: Operators in \fIbc\fP\fR +.TS +center tab(@) box; +cB | cB +lf5 | l. +Operator@Associativity +_ +++, \(mi\|\(mi@N/A +unary \(mi@N/A +\&^@Right to left +*, /, %@Left to right ++, binary \(mi@Left to right +=, +=, \(mi=, *=, /=, %=, ^=@Right to left +==, <=, >=, !=, <, >@None +.TE +.P +Each expression or named expression has a +.IR scale , +which is the number of decimal digits that shall be maintained as the +fractional portion of the expression. +.P +.IR "Named expressions" +are places where values are stored. Named expressions shall be valid on +the left side of an assignment. The value of a named expression shall +be the value stored in the place named. Simple identifiers and array +elements are named expressions; they have an initial value of zero and +an initial scale of zero. +.P +The internal registers +.BR scale , +.BR ibase , +and +.BR obase +are all named expressions. The scale of an expression consisting of the +name of one of these registers shall be zero; values assigned to any of +these registers are truncated to integers. The +.BR scale +register shall contain a global value used in computing the scale of +expressions (as described below). The value of the register +.BR scale +is limited to 0 \(<= +.BR scale +\(<= +{BC_SCALE_MAX} +and shall have a default value of zero. The +.BR ibase +and +.BR obase +registers are the input and output number radix, respectively. The +value of +.BR ibase +shall be limited to: +.sp +.RS 4 +.nf +\fB +2 \(<= ibase \(<= 16 +.fi \fR +.P +.RE +.P +The value of +.BR obase +shall be limited to: +.sp +.RS 4 +.nf +\fB +2 \(<= obase \(<= {BC_BASE_MAX} +.fi \fR +.P +.RE +.P +When either +.BR ibase +or +.BR obase +is assigned a single +.BR digit +value from the list in +.IR "Lexical Conventions in bc", +the value shall be assumed in hexadecimal. (For example, +.BR ibase =A +sets to base ten, regardless of the current +.BR ibase +value.) Otherwise, the behavior is undefined when digits greater than +or equal to the value of +.BR ibase +appear in the input. Both +.BR ibase +and +.BR obase +shall have initial values of 10. +.P +Internal computations shall be conducted as if in decimal, regardless +of the input and output bases, to the specified number of decimal +digits. When an exact result is not achieved (for example, +.BR scale "=0;\ 3.2/1)", +the result shall be truncated. +.P +For all values of +.BR obase +specified by this volume of POSIX.1\(hy2008, +.IR bc +shall output numeric values by performing each of the following steps +in order: +.IP " 1." 4 +If the value is less than zero, a + +(\c +.BR '\(mi' ) +character shall be output. +.IP " 2." 4 +One of the following is output, depending on the numerical value: +.RS 4 +.IP " *" 4 +If the absolute value of the numerical value is greater than or equal +to one, the integer portion of the value shall be output as a series of +digits appropriate to +.BR obase +(as described below), most significant digit first. The most significant +non-zero digit shall be output next, followed by each successively +less significant digit. +.IP " *" 4 +If the absolute value of the numerical value is less than one but +greater than zero and the scale of the numerical value is greater than +zero, it is unspecified whether the character 0 is output. +.IP " *" 4 +If the numerical value is zero, the character 0 shall be output. +.RE +.IP " 3." 4 +If the scale of the value is greater than zero and the numeric value +is not zero, a + +character shall be output, followed by a series of digits appropriate to +.BR obase +(as described below) representing the most significant portion of the +fractional part of the value. If +.IR s +represents the scale of the value being output, the number of digits +output shall be +.IR s +if +.BR obase +is 10, less than or equal to +.IR s +if +.BR obase +is greater than 10, or greater than or equal to +.IR s +if +.BR obase +is less than 10. For +.BR obase +values other than 10, this should be the number of digits needed to +represent a precision of 10\u\s-3\fIs\fP\s+3\d. +.P +For +.BR obase +values from 2 to 16, valid digits are the first +.BR obase +of the single characters: +.sp +.RS 4 +.nf +\fB +0 1 2 3 4 5 6 7 8 9 A B C D E F +.fi \fR +.P +.RE +.P +which represent the values zero to 15, inclusive, respectively. +.P +For bases greater than 16, each digit shall be written as a separate +multi-digit decimal number. Each digit except the most significant +fractional digit shall be preceded by a single +. +For bases from 17 to 100, +.IR bc +shall write two-digit decimal numbers; for bases from 101 to 1\|000, +three-digit decimal strings, and so on. For example, the decimal number +1\|024 in base 25 would be written as: +.sp +.RS 4 +.nf +\fB + 01 15 24 +.fi \fR +.P +.RE +.P +and in base 125, as: +.sp +.RS 4 +.nf +\fB + 008 024 +.fi \fR +.P +.RE +.P +Very large numbers shall be split across lines with 70 characters per +line in the POSIX locale; other locales may split at different +character boundaries. Lines that are continued shall end with a +. +.P +A function call shall consist of a function name followed by +parentheses containing a +-separated +list of expressions, which are the function arguments. A whole array +passed as an argument shall be specified by the array name followed +by empty square brackets. All function arguments shall be passed by +value. As a result, changes made to the formal parameters shall have no +effect on the actual arguments. If the function terminates by executing a +.BR return +statement, the value of the function shall be the value of the +expression in the parentheses of the +.BR return +statement or shall be zero if no expression is provided or if there is +no +.BR return +statement. +.P +The result of +.BR sqrt (\c +.IR expression ) +shall be the square root of the expression. The result shall be +truncated in the least significant decimal place. The scale of the +result shall be the scale of the expression or the value of +.BR scale , +whichever is larger. +.P +The result of +.BR length (\c +.IR expression ) +shall be the total number of significant decimal digits in the +expression. The scale of the result shall be zero. +.P +The result of +.BR scale (\c +.IR expression ) +shall be the scale of the expression. The scale of the result shall be +zero. +.P +A numeric constant shall be an expression. The scale shall be the +number of digits that follow the radix point in the input representing +the constant, or zero if no radix point appears. +.P +The sequence (\ \fIexpression\fP\ ) shall be an expression with the +same value and scale as +.IR expression . +The parentheses can be used to alter the normal precedence. +.P +The semantics of the unary and binary operators are as follows: +.IP "\(mi\fIexpression\fP" 6 +.br +The result shall be the negative of the +.IR expression . +The scale of the result shall be the scale of +.IR expression . +.P +The unary increment and decrement operators shall not modify the scale +of the named expression upon which they operate. The scale of the +result shall be the scale of that named expression. +.IP "++\fInamed-expression\fP" 6 +.br +The named expression shall be incremented by one. The result shall be +the value of the named expression after incrementing. +.IP "\(mi\|\(mi\fInamed-expression\fP" 6 +.br +The named expression shall be decremented by one. The result shall be +the value of the named expression after decrementing. +.IP "\fInamed-expression\fP++" 6 +.br +The named expression shall be incremented by one. The result shall be +the value of the named expression before incrementing. +.IP "\fInamed-expression\fP\(mi\|\(mi" 6 +.br +The named expression shall be decremented by one. The result shall be +the value of the named expression before decrementing. +.P +The exponentiation operator, + +(\c +.BR '^' ), +shall bind right to left. +.IP "\fIexpression\fP^\fIexpression\fP" 6 +.br +The result shall be the first +.IR expression +raised to the power of the second +.IR expression . +If the second expression is not an integer, the behavior is undefined. +If +.IR a +is the scale of the left expression and +.IR b +is the absolute value of the right expression, the scale of the result +shall be: +.RS 6 +.sp +.RS 4 +.nf +\fB +if b >= 0 min(a * b, max(scale, a)) if b < 0 scale +.fi \fR +.P +.RE +.RE +The multiplicative operators (\c +.BR '*' , +.BR '/' , +.BR '%' ) +shall bind left to right. +.IP "\fIexpression\fP*\fIexpression\fP" 6 +.br +The result shall be the product of the two expressions. If +.IR a +and +.IR b +are the scales of the two expressions, then the scale of the result +shall be: +.RS 6 +.sp +.RS 4 +.nf +\fB +min(a+b,max(scale,a,b)) +.fi \fR +.P +.RE +.RE +.IP "\fIexpression\fP/\fIexpression\fP" 6 +.br +The result shall be the quotient of the two expressions. The scale of the +result shall be the value of +.BR scale . +.IP "\fIexpression\fP%\fIexpression\fP" 6 +.br +For expressions +.IR a +and +.IR b , +.IR a %\c +.IR b +shall be evaluated equivalent to the steps: +.RS 6 +.IP " 1." 4 +Compute +.IR a /\c +.IR b +to current scale. +.IP " 2." 4 +Use the result to compute: +.RS 4 +.sp +.RS 4 +.nf +\fB +a \(mi (a / b) * b +.fi \fR +.P +.RE +.P +to scale: +.sp +.RS 4 +.nf +\fB +max(scale + scale(b), scale(a)) +.fi \fR +.P +.RE +.RE +The scale of the result shall be: +.sp +.RS 4 +.nf +\fB +max(scale + scale(b), scale(a)) +.fi \fR +.P +.RE +.P +When +.BR scale +is zero, the +.BR '%' +operator is the mathematical remainder operator. +.RE +.P +The additive operators (\c +.BR '\(pl' , +.BR '\(mi' ) +shall bind left to right. +.IP "\fIexpression\fP+\fIexpression\fP" 6 +.br +The result shall be the sum of the two expressions. The scale of the +result shall be the maximum of the scales of the expressions. +.IP "\fIexpression\fP\(mi\fIexpression\fP" 6 +.br +The result shall be the difference of the two expressions. The scale of +the result shall be the maximum of the scales of the expressions. +.P +The assignment operators (\c +.BR '=' , +.BR \(dq+=\(dq , +.BR \(dq\(mi=\(dq , +.BR \(dq*=\(dq , +.BR \(dq/=\(dq , +.BR \(dq%=\(dq , +.BR \(dq^=\(dq ) +shall bind right to left. +.IP "\fInamed-expression\fP=\fIexpression\fP" 6 +.br +This expression shall result in assigning the value of the expression +on the right to the named expression on the left. The scale of both the +named expression and the result shall be the scale of +.IR expression . +.P +The compound assignment forms: +.sp +.RS 4 +.nf +\fB +\fInamed-expression\fR <\fIoperator\fR>= \fIexpression\fR +.fi \fR +.P +.RE +.P +shall be equivalent to: +.sp +.RS 4 +.nf +\fB +\fInamed-expression\fR=\fInamed-expression\fR <\fIoperator\fR> \fIexpression\fR +.fi \fR +.P +.RE +.P +except that the +.IR named-expression +shall be evaluated only once. +.P +Unlike all other operators, the relational operators (\c +.BR '<' , +.BR '>' , +.BR \(dq<=\(dq , +.BR \(dq>=\(dq , +.BR \(dq==\(dq , +.BR \(dq!=\(dq ) +shall be only valid as the object of an +.BR if , +.BR while , +or inside a +.BR for +statement. +.IP "\fIexpression1\fP<\fIexpression2\fR" 6 +.br +The relation shall be true if the value of +.IR expression1 +is strictly less than the value of +.IR expression2 . +.IP "\fIexpression1\fP>\fIexpression2\fP" 6 +.br +The relation shall be true if the value of +.IR expression1 +is strictly greater than the value of +.IR expression2 . +.IP "\fIexpression1\fP<=\fIexpression2\fR" 6 +.br +The relation shall be true if the value of +.IR expression1 +is less than or equal to the value of +.IR expression2 . +.IP "\fIexpression1\fP>=\fIexpression2\fR" 6 +.br +The relation shall be true if the value of +.IR expression1 +is greater than or equal to the value of +.IR expression2 . +.IP "\fIexpression1\fP=\|=\fIexpression2\fR" 6 +.br +The relation shall be true if the values of +.IR expression1 +and +.IR expression2 +are equal. +.IP "\fIexpression1\fP!=\fIexpression2\fR" 6 +.br +The relation shall be true if the values of +.IR expression1 +and +.IR expression2 +are unequal. +.P +There are only two storage classes in +.IR bc : +global and automatic (local). +Only identifiers that are local to a function need be declared +with the +.BR auto +command. The arguments to a function shall be local to the function. +All other identifiers are assumed to be global and available to all +functions. All identifiers, global and local, have initial values of +zero. Identifiers declared as auto shall be allocated on entry to the +function and released on returning from the function. They therefore do +not retain values between function calls. Auto arrays shall be +specified by the array name followed by empty square brackets. On entry +to a function, the old values of the names that appear as parameters +and as automatic variables shall be pushed onto a stack. Until the +function returns, reference to these names shall refer only to the new +values. +.P +References to any of these names from other functions that are called +from this function also refer to the new value until one of those +functions uses the same name for a local variable. +.P +When a statement is an expression, unless the main operator is an +assignment, execution of the statement shall write the value of the +expression followed by a +. +.P +When a statement is a string, execution of the statement shall write +the value of the string. +.P +Statements separated by + +or + +characters shall be executed sequentially. In an interactive invocation of +.IR bc , +each time a + +is read that satisfies the grammatical production: +.sp +.RS 4 +.nf +\fB +input_item : semicolon_list NEWLINE +.fi \fR +.P +.RE +.P +the sequential list of statements making up the +.BR semicolon_list +shall be executed immediately and any output produced by that execution +shall be written without any delay due to buffering. +.P +In an +.BR if +statement (\c +.BR if (\c +.IR relation ) +.IR statement ), +the +.IR statement +shall be executed if the relation is true. +.P +The +.BR while +statement (\c +.BR while (\c +.IR relation ) +.IR statement ) +implements a loop in which the +.IR relation +is tested; each time the +.IR relation +is true, the +.IR statement +shall be executed and the +.IR relation +retested. When the +.IR relation +is false, execution shall resume after +.IR statement . +.P +A +.BR for +statement(\c +.BR for (\c +.IR expression ; +.IR relation ; +.IR expression ) +.IR statement ) +shall be the same as: +.sp +.RS 4 +.nf +\fB +\fIfirst-expression\fP +while (\fIrelation\fP) { + \fIstatement\fP + \fIlast-expression\fR +} +.fi \fR +.P +.RE +The application shall ensure that all three expressions are present. +.P +The +.BR break +statement shall cause termination of a +.BR for +or +.BR while +statement. +.P +The +.BR auto +statement (\c +.BR auto +.IR identifier +.BR [ ,\c +.IR identifier \c +.BR ] +\&.\|.\|.) shall cause the values of the identifiers to be pushed down. +The identifiers can be ordinary identifiers or array identifiers. Array +identifiers shall be specified by following the array name by empty +square brackets. The application shall ensure that the +.BR auto +statement is the first statement in a function definition. +.P +A +.BR define +statement: +.sp +.RS 4 +.nf +\fB +define \fILETTER\fP ( \fIopt_parameter_list\fP ) { + \fIopt_auto_define_list\fP + \fIstatement_list\fR +} +.fi \fR +.P +.RE +.P +defines a function named +.BR LETTER . +If a function named +.BR LETTER +was previously defined, the +.BR define +statement shall replace the previous definition. The expression: +.sp +.RS 4 +.nf +\fB +LETTER ( \fIopt_argument_list\fR ) +.fi \fR +.P +.RE +.P +shall invoke the function named +.BR LETTER . +The behavior is undefined if the number of arguments in the invocation +does not match the number of parameters in the definition. Functions +shall be defined before they are invoked. A function shall be +considered to be defined within its own body, so recursive calls are +valid. The values of numeric constants within a function shall be +interpreted in the base specified by the value of the +.BR ibase +register when the function is invoked. +.P +The +.BR return +statements (\c +.BR return +and +.BR return (\c +.IR expression )) +shall cause termination of a function, popping of its auto variables, +and specification of the result of the function. The first form shall +be equivalent to +.BR return (0). +The value and scale of the result returned by the function shall be the +value and scale of the expression returned. +.P +The +.BR quit +statement (\c +.BR quit ) +shall stop execution of a +.IR bc +program at the point where the statement occurs in the input, even if +it occurs in a function definition, or in an +.BR if , +.BR for , +or +.BR while +statement. +.P +The following functions shall be defined when the +.BR \(mil +option is specified: +.IP "\fBs\fR(\ \fIexpression\fR\ )" 6 +.br +Sine of argument in radians. +.IP "\fBc\fR(\ \fIexpression\fR\ )" 6 +.br +Cosine of argument in radians. +.IP "\fBa\fR(\ \fIexpression\fR\ )" 6 +.br +Arctangent of argument. +.IP "\fBl\fR(\ \fIexpression\fR\ )" 6 +.br +Natural logarithm of argument. +.IP "\fBe\fR(\ \fIexpression\fR\ )" 6 +.br +Exponential function of argument. +.IP "\fBj\fR(\ \fIexpression\fR,\ \fIexpression\fR\ )" 6 +.br +Bessel function of integer order. +.P +The scale of the result returned by these functions shall be the value +of the +.BR scale +register at the time the function is invoked. The value of the +.BR scale +register after these functions have completed their execution shall be +the same value it had upon invocation. The behavior is undefined if +any of these functions is invoked with an argument outside the domain +of the mathematical function. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP 0 10 +All input files were processed successfully. +.IP "\fIunspecified\fR" 10 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If any +.IR file +operand is specified and the named file cannot be accessed, +.IR bc +shall write a diagnostic message to standard error and terminate +without any further action. +.P +In an interactive invocation of +.IR bc , +the utility should print an error message and recover following any +error in the input. In a non-interactive invocation of +.IR bc , +invalid input causes undefined behavior. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Automatic variables in +.IR bc +do not work in exactly the same way as in either C or PL/1. +.P +For historical reasons, the exit status from +.IR bc +cannot be relied upon to indicate that an error has occurred. +Returning zero after an error is possible. Therefore, +.IR bc +should be used primarily by interactive users (who can react to error +messages) or by application programs that can somehow validate the +answers returned as not including error messages. +.P +The +.IR bc +utility always uses the + +(\c +.BR '.' ) +character to represent a radix point, regardless of any decimal-point +character specified as part of the current locale. In languages like C or +.IR awk , +the + +character is used in program source, so it can be portable and +unambiguous, while the locale-specific character is used in input and +output. Because there is no distinction between source and input in +.IR bc , +this arrangement would not be possible. Using the locale-specific +character in +.IR bc 's +input would introduce ambiguities into the language; consider the +following example in a locale with a + +as the decimal-point character: +.sp +.RS 4 +.nf +\fB +define f(a,b) { + ... +} +\&... +.P +f(1,2,3) +.fi \fR +.P +.RE +.P +Because of such ambiguities, the + +character is used in input. Having input follow different conventions +from output would be confusing in either pipeline usage or interactive +usage, so the + +is also used in output. +.SH EXAMPLES +In the shell, the following assigns an approximation of the first ten +digits of +.BR '\(*p' +to the variable +.IR x : +.sp +.RS 4 +.nf +\fB +x=$(printf "%s\en" 'scale = 10; 104348/33215' | bc) +.fi \fR +.P +.RE +.P +The following +.IR bc +program prints the same approximation of +.BR '\(*p' , +with a label, to standard output: +.sp +.RS 4 +.nf +\fB +scale = 10 +"pi equals " +104348 / 33215 +.fi \fR +.P +.RE +.P +The following defines a function to compute an approximate value of the +exponential function (note that such a function is predefined if the +.BR \(mil +option is specified): +.sp +.RS 4 +.nf +\fB +scale = 20 +define e(x){ + auto a, b, c, i, s + a = 1 + b = 1 + s = 1 + for (i = 1; 1 == 1; i++){ + a = a*x + b = b*i + c = a/b + if (c == 0) { + return(s) + } + s = s+c + } +} +.fi \fR +.P +.RE +.P +The following prints approximate values of the exponential function of +the first ten integers: +.sp +.RS 4 +.nf +\fB +for (i = 1; i <= 10; ++i) { + e(i) +} +.fi \fR +.P +.RE +.SH RATIONALE +The +.IR bc +utility is implemented historically as a front-end processor for +.IR dc ; +.IR dc +was not selected to be part of this volume of POSIX.1\(hy2008 because +.IR bc +was thought to have a more intuitive programmatic interface. Current +implementations that implement +.IR bc +using +.IR dc +are expected to be compliant. +.P +The exit status for error conditions has been left unspecified for +several reasons: +.IP " *" 4 +The +.IR bc +utility is used in both interactive and non-interactive situations. +Different exit codes may be appropriate for the two uses. +.IP " *" 4 +It is unclear when a non-zero exit should be given; divide-by-zero, +undefined functions, and syntax errors are all possibilities. +.IP " *" 4 +It is not clear what utility the exit status has. +.IP " *" 4 +In the 4.3 BSD, System V, and Ninth Edition implementations, +.IR bc +works in conjunction with +.IR dc . +The +.IR dc +utility is the parent, +.IR bc +is the child. This was done to cleanly terminate +.IR bc +if +.IR dc +aborted. +.P +The decision to have +.IR bc +exit upon encountering an inaccessible input file is based on the +belief that +.IR bc +.IR file1 +.IR file2 +is used most often when at least +.IR file1 +contains data/function declarations/initializations. Having +.IR bc +continue with prerequisite files missing is probably not useful. There +is no implication in the CONSEQUENCES OF ERRORS section that +.IR bc +must check all its files for accessibility before opening any of them. +.P +There was considerable debate on the appropriateness of the language +accepted by +.IR bc . +Several reviewers preferred to see either a pure subset of the C +language or some changes to make the language more compatible with C. +While the +.IR bc +language has some obvious similarities to C, it has never claimed to be +compatible with any version of C. An interpreter for a subset of C +might be a very worthwhile utility, and it could potentially make +.IR bc +obsolete. However, no such utility is known in historical practice, and +it was not within the scope of this volume of POSIX.1\(hy2008 to define such a language and +utility. If and when they are defined, it may be appropriate to include +them in a future version of this standard. This left the following +alternatives: +.IP " 1." 4 +Exclude any calculator language from this volume of POSIX.1\(hy2008. +.RS 4 +.P +The consensus of the standard developers was that a simple programmatic +calculator language is very useful for both applications and +interactive users. The only arguments for excluding any calculator were +that it would become obsolete if and when a C-compatible one emerged, +or that the absence would encourage the development of such a +C-compatible one. These arguments did not sufficiently address the +needs of current application developers. +.RE +.IP " 2." 4 +Standardize the historical +.IR dc , +possibly with minor modifications. +.RS 4 +.P +The consensus of the standard developers was that +.IR dc +is a fundamentally less usable language and that that would be far too +severe a penalty for avoiding the issue of being similar to but +incompatible with C. +.RE +.IP " 3." 4 +Standardize the historical +.IR bc , +possibly with minor modifications. +.RS 4 +.P +This was the approach taken. Most of the proponents of changing the +language would not have been satisfied until most or all of the +incompatibilities with C were resolved. Since most of the changes +considered most desirable would break historical applications and +require significant modification to historical implementations, almost +no modifications were made. The one significant modification that was +made was the replacement of the historical +.IR bc +assignment operators +.BR \(dq=+\(dq , +and so on, with the more modern +.BR \(dq+=\(dq , +and so on. The older versions are considered to be fundamentally flawed +because of the lexical ambiguity in uses like +.IR a =\(mi1. +.P +In order to permit implementations to deal with backwards-compatibility +as they see fit, the behavior of this one ambiguous construct was made +undefined. (At least three implementations have been known to support +this change already, so the degree of change involved should not be +great.) +.RE +.P +The +.BR '%' +operator is the mathematical remainder operator when +.BR scale +is zero. The behavior of this operator for other values of +.BR scale +is from historical implementations of +.IR bc , +and has been maintained for the sake of historical applications despite +its non-intuitive nature. +.P +Historical implementations permit setting +.BR ibase +and +.BR obase +to a broader range of values. This includes values less than 2, which +were not seen as sufficiently useful to standardize. These +implementations do not interpret input properly for values of +.BR ibase +that are greater than 16. This is because numeric constants are +recognized syntactically, rather than lexically, as described in +\&this volume of POSIX.1\(hy2008. They are built from lexical tokens of single hexadecimal digits +and + +characters. Since + +characters between tokens are not visible at the syntactic level, it is +not possible to recognize the multi-digit ``digits'' used in the higher +bases properly. The ability to recognize input in these bases was not +considered useful enough to require modifying these implementations. +Note that the recognition of numeric constants at the syntactic level +is not a problem with conformance to this volume of POSIX.1\(hy2008, as it does not impact the +behavior of conforming applications (and correct +.IR bc +programs). Historical implementations also accept input with all of the +digits +.BR '0' \(mi\c +.BR '9' +and +.BR 'A' \(mi\c +.BR 'F' +regardless of the value of +.BR ibase ; +since digits with value greater than or equal to +.BR ibase +are not really appropriate, the behavior when they appear is undefined, +except for the common case of: +.sp +.RS 4 +.nf +\fB +ibase=8; + /* Process in octal base. */ +\&... +ibase=A + /* Restore decimal base. */ +.fi \fR +.P +.RE +.P +In some historical implementations, if the expression to be written is +an uninitialized array element, a leading + +and/or up to four leading 0 characters may be output before the +character zero. This behavior is considered a bug; it is unlikely that +any currently conforming application relies on: +.sp +.RS 4 +.nf +\fB +echo 'b[3]' | bc +.fi \fR +.P +.RE +.P +returning 00000 rather than 0. +.P +Exact calculation of the number of fractional digits to output for a +given value in a base other than 10 can be computationally expensive. +Historical implementations use a faster approximation, and this is +permitted. Note that the requirements apply only to values of +.BR obase +that this volume of POSIX.1\(hy2008 requires implementations to support (in particular, not to +1, 0, or negative bases, if an implementation supports them as an +extension). +.P +Historical implementations of +.IR bc +did not allow array parameters to be passed as the last parameter to a +function. New implementations are encouraged to remove this restriction +even though it is not required by the grammar. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 1.3" ", " "Grammar Conventions", +.IR "\fIawk\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/bg.1p b/man-pages-posix-2013/man1p/bg.1p new file mode 100644 index 0000000..44c09d3 --- /dev/null +++ b/man-pages-posix-2013/man1p/bg.1p @@ -0,0 +1,222 @@ +'\" et +.TH BG "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +bg +\(em run jobs in the background +.SH SYNOPSIS +.LP +.nf +bg \fB[\fIjob_id\fR...\fB]\fR +.fi +.SH DESCRIPTION +If job control is enabled (see the description of +.IR set +.BR \(mim ), +the +.IR bg +utility shall resume suspended jobs from the current environment (see +.IR "Section 2.12" ", " "Shell Execution Environment") +by running them as background jobs. If the job specified by +.IR job_id +is already a running background job, the +.IR bg +utility shall have no effect and shall exit successfully. +.P +Using +.IR bg +to place a job into the background shall cause its process ID to become +``known in the current shell execution environment'', as if it had been +started as an asynchronous list; see +.IR "Section 2.9.3.1" ", " "Examples". +.SH OPTIONS +None. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIjob_id\fR" 10 +Specify the job to be resumed as a background job. If no +.IR job_id +operand is given, the most recently suspended job shall be used. The +format of +.IR job_id +is described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.204" ", " "Job Control Job ID". +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR bg : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The output of +.IR bg +shall consist of a line in the format: +.sp +.RS 4 +.nf +\fB +"[%d] %s\en", <\fIjob-number\fR>, <\fIcommand\fR> +.fi \fR +.P +.RE +.P +where the fields are as follows: +.IP "<\fIjob-number\fR>" 10 +A number that can be used to identify the job to the +.IR wait , +.IR fg , +and +.IR kill +utilities. Using these utilities, the job can be identified by +prefixing the job number with +.BR '%' . +.IP "<\fIcommand\fR>" 10 +The associated command that was given to the shell. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If job control is disabled, the +.IR bg +utility shall exit with an error and no job shall be placed in the +background. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +A job is generally suspended by typing the SUSP character +(\(hyZ on most systems); see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +At that point, +.IR bg +can put the job into the background. This is most effective when the +job is expecting no terminal input and its output has been redirected +to non-terminal files. A background job can be forced to stop when it +has terminal output by issuing the command: +.sp +.RS 4 +.nf +\fB +stty tostop +.fi \fR +.P +.RE +.P +A background job can be stopped with the command: +.sp +.RS 4 +.nf +\fB +kill \(mis stop \fIjob ID\fR +.fi \fR +.P +.RE +.P +The +.IR bg +utility does not work as expected when it is operating in its own +utility execution environment because that environment has no suspended +jobs. In the following examples: +.sp +.RS 4 +.nf +\fB +\&... | xargs bg +(bg) +.fi \fR +.P +.RE +.P +each +.IR bg +operates in a different environment and does not share its parent +shell's understanding of jobs. For this reason, +.IR bg +is generally implemented as a shell regular built-in. +.SH EXAMPLES +None. +.SH RATIONALE +The extensions to the shell specified in this volume of POSIX.1\(hy2008 have mostly been based +on features provided by the KornShell. The job control features +provided by +.IR bg , +.IR fg , +and +.IR jobs +are also based on the KornShell. The standard developers examined the +characteristics of the C shell versions of these utilities and found +that differences exist. Despite widespread use of the C shell, the +KornShell versions were selected for this volume of POSIX.1\(hy2008 to maintain a degree of +uniformity with the rest of the KornShell features selected (such as +the very popular command line editing features). +.P +The +.IR bg +utility is expected to wrap its output if the output exceeds the number +of display columns. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.9.3.1" ", " "Examples", +.IR "\fIfg\fR\^", +.IR "\fIkill\fR\^", +.IR "\fIjobs\fR\^", +.IR "\fIwait\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.204" ", " "Job Control Job ID", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Chapter 11" ", " "General Terminal Interface" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/break.1p b/man-pages-posix-2013/man1p/break.1p new file mode 100644 index 0000000..77cf59a --- /dev/null +++ b/man-pages-posix-2013/man1p/break.1p @@ -0,0 +1,134 @@ +'\" et +.TH BREAK "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +break +\(em exit from for, while, or until loop +.SH SYNOPSIS +.LP +.nf +break \fB[\fIn\fB]\fR +.fi +.SH DESCRIPTION +The +.IR break +utility shall exit from the smallest enclosing +.BR for , +.BR while , +or +.BR until +loop, if any; or from the +.IR n th +enclosing loop if +.IR n +is specified. The value of +.IR n +is an unsigned decimal integer greater than or equal to 1. The default +shall be equivalent to +.IR n =1. +If +.IR n +is greater than the number of enclosing loops, the outermost enclosing +loop shall be exited. Execution shall continue with the command +immediately following the loop. +.SH OPTIONS +None. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +.IP "\00" 6 +Successful completion. +.IP >0 6 +The +.IR n +value was not an unsigned decimal integer greater than or equal to 1. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +.LP +.nf +for i in * +do + if test \(mid "$i" + then break + fi +done +.fi +.SH "RATIONALE" +In early proposals, consideration was given to expanding the syntax of +.IR break +and +.IR continue +to refer to a label associated with the appropriate loop as a +preferable alternative to the +.IR n +method. However, this volume of POSIX.1\(hy2008 does reserve the name space of command names +ending with a +. +It is anticipated that a future implementation could take advantage of +this and provide something like: +.sp +.RS 4 +.nf +\fB +outofloop: for i in a b c d e +do + for j in 0 1 2 3 4 5 6 7 8 9 + do + if test \(mir "${i}${j}" + then break outofloop + fi + done +done +.fi \fR +.P +.RE +.P +and that this might be standardized after implementation experience is +achieved. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/c99.1p b/man-pages-posix-2013/man1p/c99.1p new file mode 100644 index 0000000..386b094 --- /dev/null +++ b/man-pages-posix-2013/man1p/c99.1p @@ -0,0 +1,1152 @@ +'\" et +.TH C99 "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +c99 +\(em compile standard C programs +.SH SYNOPSIS +.LP +.nf +c99 \fB[\fIoptions\fR...\fB] \fIpathname \fB[[\fIpathname\fB] [\fR\(miI \fIdirectory\fB] + \fB[\fR\(miL \fIdirectory\fB] [\fR\(mil \fIlibrary\fB]]\fR... +.fi +.SH DESCRIPTION +The +.IR c99 +utility is an interface to the standard C compilation system; it shall +accept source code conforming to the ISO\ C standard. The system conceptually +consists of a compiler and link editor. The input files referenced by +.IR pathname +operands and +.BR \(mil +option-arguments shall be compiled and linked to produce an executable +file. (It is unspecified whether the linking occurs entirely within the +operation of +.IR c99 ; +some implementations may produce objects that are not fully resolved +until the file is executed.) +.P +If the +.BR \(mic +option is specified, for all pathname operands of the form +.IR file \c +.BR .c , +the files: +.sp +.RS 4 +.nf +\fB +$(basename \fIpathname\fR .c).o +.fi \fR +.P +.RE +.P +shall be created as the result of successful compilation. If the +.BR \(mic +option is not specified, it is unspecified whether such +.BR .o +files are created or deleted for the +.IR file \c +.BR .c +operands. +.P +If there are no options that prevent link editing (such as +.BR \(mic +or +.BR \(miE ), +and all input files compile and link without error, the resulting +executable file shall be written according to the +.BR \(mio +.IR outfile +option (if present) or to the file +.BR a.out . +.P +The executable file shall be created as specified in +.IR "Section 1.1.1.4" ", " "File Read" ", " "Write" ", " "and Creation", +except that the file permission bits shall be set to: +S_IRWXO | S_IRWXG | S_IRWXU +.P +and the bits specified by the +.IR umask +of the process shall be cleared. +.SH OPTIONS +The +.IR c99 +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that: +.IP " *" 4 +Options can be interspersed with operands. +.IP " *" 4 +The order of specifying the +.BR \(miL +and +.BR \(mil +options, and the order of specifying +.BR \(mil +options with respect to +.IR pathname +operands is significant. +.IP " *" 4 +Conforming applications shall specify each option separately; that is, +grouping option letters (for example, +.BR \(micO ) +need not be recognized by all implementations. +.P +The following options shall be supported: +.IP "\fB\(mic\fP" 10 +Suppress the link-edit phase of the compilation, and do not remove any +object files that are produced. +.IP "\fB\(miD\ \fIname\fB[=\fIvalue\fB]\fR" 10 +.br +Define +.IR name +as if by a C-language +.BR #define +directive. If no =\c +.IR value +is given, a value of 1 shall be used. The +.BR \(miD +option has lower precedence than the +.BR \(miU +option. That is, if +.IR name +is used in both a +.BR \(miU +and a +.BR \(miD +option, +.IR name +shall be undefined regardless of the order of the options. Additional +implementation-defined +.IR name s +may be provided by the compiler. Implementations shall support at least +2\|048 bytes of +.BR \(miD +definitions and 256 +.IR names . +.IP "\fB\(miE\fP" 10 +Copy C-language source files to standard output, expanding all +preprocessor directives; no compilation shall be performed. If any +operand is not a text file, the effects are unspecified. +.IP "\fB\(mig\fP" 10 +Produce symbolic information in the object or executable files; the +nature of this information is unspecified, and may be modified by +implementation-defined interactions with other options. +.IP "\fB\(miI\ \fIdirectory\fR" 10 +Change the algorithm for searching for headers whose names are not +absolute pathnames to look in the directory named by the +.IR directory +pathname before looking in the usual places. Thus, headers whose names +are enclosed in double-quotes (\c +.BR \(dq\^\(dq ) +shall be searched for first in the directory of the file with the +.BR #include +line, then in directories named in +.BR \(miI +options, and last in the usual places. For headers whose names are +enclosed in angle brackets (\c +.BR \(dq<\|>\(dq ), +the header shall be searched for only in directories named in +.BR \(miI +options and then in the usual places. Directories named in +.BR \(miI +options shall be searched in the order specified. If the +.BR \(miI +option is used to specify a directory that is one of the usual places +searched by default, the results are unspecified. Implementations shall +support at least ten instances of this option in a single +.IR c99 +command invocation. +.IP "\fB\(miL\ \fIdirectory\fR" 10 +Change the algorithm of searching for the libraries named in the +.BR \(mil +objects to look in the directory named by the +.IR directory +pathname before looking in the usual places. Directories named in +.BR \(miL +options shall be searched in the order specified. If the +.BR \(miL +option is used to specify a directory that is one of the usual places +searched by default, the results are unspecified. Implementations shall +support at least ten instances of this option in a single +.IR c99 +command invocation. If a directory specified by a +.BR \(miL +option contains files with names starting with any of the strings +.BR \(dqlibc.\(dq , +.BR \(dqlibl.\(dq , +.BR \(dqlibpthread.\(dq , +.BR \(dqlibm.\(dq , +.BR \(dqlibrt.\(dq , +.BR \(dqlibtrace.\(dq , +.BR \(dqlibxnet.\(dq , +or +.BR \(dqliby.\(dq , +the results are unspecified. +.IP "\fB\(mil\ \fIlibrary\fR" 10 +Search the library named +.BR liblibrary.a . +A library shall be searched when its name is encountered, so the +placement of a +.BR \(mil +option is significant. Several standard libraries can be +specified in this manner, as described in the EXTENDED DESCRIPTION +section. Implementations may recognize implementation-defined +suffixes other than +.BR .a +as denoting libraries. +.IP "\fB\(miO\ \fIoptlevel\fR" 10 +Specify the level of code optimization. If the +.IR optlevel +option-argument is the digit +.BR '0' , +all special code optimizations shall be disabled. If it is the digit +.BR '1' , +the nature of the optimization is unspecified. If the +.BR \(miO +option is omitted, the nature of the system's default optimization is +unspecified. It is unspecified whether code generated in the presence +of the +.BR \(miO +0 option is the same as that generated when +.BR \(miO +is omitted. Other +.IR optlevel +values may be supported. +.IP "\fB\(mio\ \fIoutfile\fR" 10 +Use the pathname +.IR outfile , +instead of the default +.BR a.out , +for the executable file produced. If the +.BR \(mio +option is present with +.BR \(mic +or +.BR \(miE , +the result is unspecified. +.IP "\fB\(mis\fP" 10 +Produce object or executable files, or both, from which symbolic and +other information not required for proper execution using the +.IR exec +family defined in the System Interfaces volume of POSIX.1\(hy2008 has been removed (stripped). If both +.BR \(mig +and +.BR \(mis +options are present, the action taken is unspecified. +.IP "\fB\(miU\ \fIname\fR" 10 +Remove any initial definition of +.IR name . +.P +Multiple instances of the +.BR \(miD , +.BR \(miI , +.BR \(miL , +.BR \(mil , +and +.BR \(miU +options can be specified. +.SH OPERANDS +The application shall ensure that at least one +.IR pathname +operand is specified. The following forms for +.IR pathname +operands shall be supported: +.IP "\fIfile.\fBc\fR" 10 +A C-language source file to be compiled and optionally linked. The +application shall ensure that the operand is of this form if the +.BR \(mic +option is used. +.IP "\fIfile.\fBa\fR" 10 +A library of object files typically produced by the +.IR ar +utility, and passed directly to the link editor. Implementations may +recognize implementation-defined suffixes other than +.BR .a +as denoting object file libraries. +.IP "\fIfile.\fBo\fR" 10 +An object file produced by +.IR c99 +.BR \(mic +and passed directly to the link editor. Implementations may recognize +implementation-defined suffixes other than +.BR .o +as denoting object files. +.P +The processing of other files is implementation-defined. +.SH STDIN +Not used. +.SH "INPUT FILES" +Each input file shall be one of the following: a text file containing a +C-language source program, an object file in the format produced by +.IR c99 +.BR \(mic , +or a library of object files, in the format produced by archiving zero +or more object files, using +.IR ar . +Implementations may supply additional utilities that produce files in +these formats. Additional input file formats are +implementation-defined. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR c99 : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITMPDIR\fP" 10 +Provide a pathname that should override the default directory for +temporary files, if any. +On XSI-conforming systems, provide a pathname that shall override the +default directory for temporary files, if any. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If more than one +.IR pathname +operand ending in +.BR .c +(or possibly other unspecified suffixes) is given, for each such file: +.sp +.RS 4 +.nf +\fB +"%s:\en", <\fIpathname\fR> +.fi \fR +.P +.RE +.P +may be written. These messages, if written, shall precede the +processing of each input file; they shall not be written to the +standard output if they are written to the standard error, as described +in the STDERR section. +.P +If the +.BR \(miE +option is specified, the standard output shall be a text file that +represents the results of the preprocessing stage of the language; it +may contain extra information appropriate for subsequent compilation +passes. +.SH STDERR +The standard error shall be used only for diagnostic messages. +If more than one +.IR pathname +operand ending in +.BR .c +(or possibly other unspecified suffixes) is given, for each such file: +.sp +.RS 4 +.nf +\fB +"%s:\en", <\fIpathname\fR> +.fi \fR +.P +.RE +.P +may be written to allow identification of the diagnostic and warning +messages with the appropriate input file. These messages, if written, +shall precede the processing of each input file; they shall not be +written to the standard error if they are written to the standard +output, as described in the STDOUT section. +.P +This utility may produce warning messages about certain conditions that +do not warrant returning an error (non-zero) exit value. +.SH "OUTPUT FILES" +Object files or executable files or both are produced in unspecified +formats. If the pathname of an object file or executable file to be +created by +.IR c99 +resolves to an existing directory entry for a file that is not a regular +file, it is unspecified whether +.IR c99 +shall attempt to create the file or shall issue a diagnostic and exit +with a non-zero exit status. +.SH "EXTENDED DESCRIPTION" +.SS "Standard Libraries" +.P +The +.IR c99 +utility shall recognize the following +.BR \(mil +options for standard libraries: +.IP "\fB\(mil\ c\fR" 10 +This option shall make available all interfaces referenced in the System Interfaces volume of POSIX.1\(hy2008, +with the possible exception of those interfaces listed as residing in +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +\fIpthread_kill\fR(), +and +\fIpthread_sigmask\fR() +in +.IR , +.IR , +interfaces marked as optional in +.IR , +interfaces marked as ADV (Advisory Information) in +.IR , +and interfaces beginning with the prefix clock_ or time_ in +.IR . +This option shall not be required to be present to cause a search of +this library. +.IP "\fB\(mil\ l\fR" 10 +This option shall make available all interfaces required by the +C-language output of +.IR lex +that are not made available through the +.BR "\(mil\ c" +option. +.IP "\fB\(mil\ pthread\fR" 10 +This option shall make available all interfaces referenced in +.IR +and +\fIpthread_kill\fR() +and +\fIpthread_sigmask\fR() +referenced in +.IR . +An implementation may search this library in the absence of this +option. +.IP "\fB\(mil\ m\fR" 10 +This option shall make available all interfaces referenced in +.IR , +.IR , +and +.IR . +An implementation may search this library in the absence of this +option. +.IP "\fB\(mil\ rt\fR" 10 +This option shall make available all interfaces referenced in +.IR , +.IR , +.IR , +.IR , +and +.IR , +interfaces marked as optional in +.IR , +interfaces marked as ADV (Advisory Information) in +.IR , +and interfaces beginning with the prefix clock_ and time_ in +.IR . +An implementation may search this library in the absence of this +option. +.IP "\fB\(mil\ trace\fR" 10 +This option shall make available all interfaces referenced in +.IR . +An implementation may search this library in the absence of this +option. +.IP "\fB\(mil\ xnet\fR" 10 +This option shall make available all interfaces referenced in +.IR , +.IR , +.IR , +.IR , +and +.IR . +An implementation may search this library in the absence of this +option. +.IP "\fB\(mil\ y\fR" 10 +This option shall make available all interfaces required by the +C-language output of +.IR yacc +that are not made available through the +.BR "\(mil\ c" +option. +.P +In the absence of options that inhibit invocation of the link editor, +such as +.BR \(mic +or +.BR \(miE , +the +.IR c99 +utility shall cause the equivalent of a +.BR "\(mil\ c" +option to be passed to the link editor after the last +.IR pathname +operand or +.BR \(mil +option, causing it to be searched after all other object files and +libraries are loaded. +.P +It is unspecified whether the libraries +.BR libc.a , +.BR libl.a , +.BR libm.a , +.BR libpthread.a , +.BR librt.a , +.BR libtrace.a , +.BR libxnet.a , +or +.BR liby.a +exist as regular files. The implementation may accept as +.BR \(mil +option-arguments names of objects that do not exist as regular files. +.SS "External Symbols" +.P +The C compiler and link editor shall support the significance of +external symbols up to a length of at least 31 bytes; the action taken +upon encountering symbols exceeding the implementation-defined +maximum symbol length is unspecified. +.P +The compiler and link editor shall support a minimum of 511 external +symbols per source or object file, and a minimum of 4\|095 external +symbols in total. A diagnostic message shall be written to the standard +output if the implementation-defined limit is exceeded; other actions +are unspecified. +.SS "Header Search" +.P +If a file with the same name as one of the standard headers defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 13" ", " "Headers", +not provided as part of the implementation, is placed in any of the +usual places that are searched by default for headers, the results are +unspecified. +.SS "Programming Environments" +.P +All implementations shall support one of the following programming +environments as a default. Implementations may support more than one +of the following programming environments. Applications can use +\fIsysconf\fR() +or +.IR getconf +to determine which programming environments are supported. +.br +.sp +.ce 1 +\fBTable 4-4: Programming Environments: Type Sizes\fR +.TS +center box tab(!); +cB | cB | cB | cB | cB +cB | cB | cB | cB | cB +l | n | n | n | n. +Programming Environment!Bits in!Bits in!Bits in!Bits in +\fIgetconf\fP Name!int!long!pointer!off_t +_ +_POSIX_V7_ILP32_OFF32!32!32!32!32 +_POSIX_V7_ILP32_OFFBIG!32!32!32!\(>=64 +_POSIX_V7_LP64_OFF64!32!64!64!64 +_POSIX_V7_LPBIG_OFFBIG!\(>=32!\(>=64!\(>=64!\(>=64 +.TE +.P +All implementations shall support one or more environments where the +widths of the following types are no greater than the width of type +.BR long : +.TS +tab(!) center; +lB lB lB. +T{ +.nf +blksize_t +cc_t +mode_t +nfds_t +pid_t +T}!T{ +.nf +ptrdiff_t +size_t +speed_t +ssize_t +suseconds_t +T}!T{ +.nf +tcflag_t +wchar_t +wint_t +.fi +T} +.TE +.P +The executable files created when these environments are selected shall +be in a proper format for execution by the +.IR exec +family of functions. Each environment may be one of the ones in +.IR "Table 4-4, Programming Environments: Type Sizes", +or it may be another environment. The names for the environments that +meet this requirement shall be output by a +.IR getconf +command using the POSIX_V7_WIDTH_RESTRICTED_ENVS argument, as a +-separated +list of names suitable for use with the +.IR getconf +.BR \(miv +option. If more than one environment meets the requirement, the names +of all such environments shall be output on separate lines. Any of +these names can then be used in a subsequent +.IR getconf +command to obtain the flags specific to that environment with the +following suffixes added as appropriate: +.IP _CFLAGS 10 +To get the C compiler flags. +.IP _LDFLAGS 10 +To get the linker/loader flags. +.IP _LIBS 10 +To get the libraries. +.P +This requirement may be removed in a future version. +.P +When this utility processes a file containing a function called +\fImain\fR(), +it shall be defined with a return type equivalent to +.BR int . +Using return from the initial call to +\fImain\fR() +shall be equivalent (other than with respect to language scope issues) +to calling +\fIexit\fR() +with the returned value. Reaching the end of the initial call to +\fImain\fR() +shall be equivalent to calling +.IR exit (0). +The implementation shall not declare a prototype for this function. +.P +Implementations provide configuration strings for C compiler flags, +linker/loader flags, and libraries for each supported environment. +When an application needs to use a specific programming environment +rather than the implementation default programming environment while +compiling, the application shall first verify that the implementation +supports the desired environment. If the desired programming +environment is supported, the application shall then invoke +.IR c99 +with the appropriate C compiler flags as the first options for the +compile, the appropriate linker/loader flags after any other options +except +.BR \(mil +but before any operands or +.BR \(mil +options, and the appropriate libraries at the end of the operands +and +.BR \(mil +options. +.P +Conforming applications shall not attempt to link together object files +compiled for different programming models. Applications shall also be +aware that binary data placed in shared memory or in files might not be +recognized by applications built for other programming models. +.br +.sp +.ce 1 +\fBTable 4-5: Programming Environments: \fIc99\fP Arguments\fR +.TS +center box tab(!); +cB | cB | cB +cB | cB | cB +l | l | l. +Programming Environment!!\fIc99\fP Arguments +\fIgetconf\fP Name!Use!\fIgetconf\fP Name +_ +_POSIX_V7_ILP32_OFF32!C Compiler Flags!POSIX_V7_ILP32_OFF32_CFLAGS +!Linker/Loader Flags!POSIX_V7_ILP32_OFF32_LDFLAGS +!Libraries!POSIX_V7_ILP32_OFF32_LIBS +_ +_POSIX_V7_ILP32_OFFBIG!C Compiler Flags!POSIX_V7_ILP32_OFFBIG_CFLAGS +!Linker/Loader Flags!POSIX_V7_ILP32_OFFBIG_LDFLAGS +!Libraries!POSIX_V7_ILP32_OFFBIG_LIBS +_ +_POSIX_V7_LP64_OFF64!C Compiler Flags!POSIX_V7_LP64_OFF64_CFLAGS +!Linker/Loader Flags!POSIX_V7_LP64_OFF64_LDFLAGS +!Libraries!POSIX_V7_LP64_OFF64_LIBS +_ +_POSIX_V7_LPBIG_OFFBIG!C Compiler Flags!POSIX_V7_LPBIG_OFFBIG_CFLAGS +!Linker/Loader Flags!POSIX_V7_LPBIG_OFFBIG_LDFLAGS +!Libraries!POSIX_V7_LPBIG_OFFBIG_LIBS +.TE +.P +In addition to the type size programming environments above, all +implementations also support a multi-threaded programming environment +that is orthogonal to all of the programming environments listed above. +The +.IR getconf +utility can be used to get flags for the threaded programming environment, +as indicated in +.IR "Table 4-6, Threaded Programming Environment: \fIc99\fP Arguments". +.sp +.ce 1 +\fBTable 4-6: Threaded Programming Environment: \fIc99\fP Arguments\fR +.TS +center box tab(!); +cB | cB | cB +cB | cB | cB +l | l | l. +Programming Environment!!\fIc99\fP Arguments +\fIgetconf\fP Name!Use!\fIgetconf\fP Name +_ +_POSIX_THREADS!C Compiler Flags!POSIX_V7_THREADS_CFLAGS +!Linker/Loader Flags!POSIX_V7_THREADS_LDFLAGS +.TE +.P +These programming environment flags may be used in conjunction with any +of the type size programming environments supported by the implementation. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful compilation or link edit. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +When +.IR c99 +encounters a compilation error that causes an object file not to be +created, it shall write a diagnostic to standard error and continue to +compile other source code operands, but it shall not perform the link +phase and return a non-zero exit status. If the link edit is +unsuccessful, a diagnostic message shall be written to standard error +and +.IR c99 +exits with a non-zero status. A conforming application shall rely on the +exit status of +.IR c99 , +rather than on the existence or mode of the executable file. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Since the +.IR c99 +utility usually creates files in the current directory during the +compilation process, it is typically necessary to run the +.IR c99 +utility in a directory in which a file can be created. +.P +On systems providing POSIX Conformance (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 2" ", " "Conformance"), +.IR c99 +is required only with the C-Language Development option; +XSI-conformant systems always provide +.IR c99 . +.P +Some historical implementations have created +.BR .o +files when +.BR \(mic +is not specified and more than one source file is given. Since this +area is left unspecified, the application cannot rely on +.BR .o +files being created, but it also must be prepared for any related +.BR .o +files that already exist being deleted at the completion of the link +edit. +.P +There is the possible implication that if a user supplies versions of +the standard functions (before they would be encountered by an implicit +.BR "\(mil\ c" +or explicit +.BR "\(mil\ m" ), +that those versions would be used in place of the standard versions. +There are various reasons this might not be true (functions defined as +macros, manipulations for clean name space, and so on), so the +existence of files named in the same manner as the standard libraries +within the +.BR \(miL +directories is explicitly stated to produce unspecified behavior. +.P +All of the functions specified in the System Interfaces volume of POSIX.1\(hy2008 may be made visible by +implementations when the Standard C Library is searched. Conforming +applications must explicitly request searching the other standard +libraries when functions made visible by those libraries are used. +.P +In the ISO\ C standard the mapping from physical source characters to the C +source character set is implementation-defined. Implementations may +strip white-space characters before the terminating + +of a (physical) line as part of this mapping and, as a consequence +of this, one or more white-space characters (and no other characters) +between a + +character and the + +character that terminates the line produces implementation-defined +results. Portable applications should not use such constructs. +.P +Some +.IR c99 +compilers not conforming to POSIX.1\(hy2008 do not support trigraphs by default. +.SH EXAMPLES +.IP " 1." 4 +The following usage example compiles +.BR foo.c +and creates the executable file +.BR foo : +.RS 4 +.sp +.RS 4 +.nf +\fB +c99 \(mio foo foo.c +.fi \fR +.P +.RE +.P +The following usage example compiles +.BR foo.c +and creates the object file +.BR foo.o : +.sp +.RS 4 +.nf +\fB +c99 \(mic foo.c +.fi \fR +.P +.RE +.P +The following usage example compiles +.BR foo.c +and creates the executable file +.BR a.out : +.sp +.RS 4 +.nf +\fB +c99 foo.c +.fi \fR +.P +.RE +.P +The following usage example compiles +.BR foo.c , +links it with +.BR bar.o , +and creates the executable file +.BR a.out . +It may also create and leave +.BR foo.o : +.sp +.RS 4 +.nf +\fB +c99 foo.c bar.o +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +The following example shows how an application using threads interfaces +can test for support of and use a programming environment supporting +32-bit +.BR int , +.BR long , +and +.BR pointer +types and an +.BR off_t +type using at least 64 bits: +.RS 4 +.sp +.RS 4 +.nf +\fB +offbig_env=$(getconf _POSIX_V7_ILP32_OFFBIG) +if [ $offbig_env != "-1" ] && [ $offbig_env != "undefined" ] +then + c99 $(getconf POSIX_V7_ILP32_OFFBIG_CFLAGS) \e + $(getconf POSIX_V7_THREADS_CFLAGS) -D_XOPEN_SOURCE=700 \e + $(getconf POSIX_V7_ILP32_OFFBIG_LDFLAGS) \e + $(getconf POSIX_V7_THREADS_LDFLAGS) foo.c -o foo \e + $(getconf POSIX_V7_ILP32_OFFBIG_LIBS) \e + -l pthread +else + echo ILP32_OFFBIG programming environment not supported + exit 1 +fi +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +The following examples clarify the use and interactions of +.BR \(miL +and +.BR \(mil +options. +.RS 4 +.P +Consider the case in which module +.BR a.c +calls function +\fIf\fR() +in library +.BR libQ.a , +and module +.BR b.c +calls function +\fIg\fR() +in library +.BR libp.a . +Assume that both libraries reside in +.BR /a/b/c . +The command line to compile and link in the desired way is: +.sp +.RS 4 +.nf +\fB +c99 \(miL /a/b/c main.o a.c \(mil Q b.c \(mil p +.fi \fR +.P +.RE +.P +In this case the +.BR \(miL +option need only precede the first +.BR \(mil +option, since both +.BR libQ.a +and +.BR libp.a +reside in the same directory. +.P +Multiple +.BR \(miL +options can be used when library name collisions occur. Building on +the previous example, suppose that the user wants to use a new +.BR libp.a , +in +.BR /a/a/a , +but still wants +\fIf\fR() +from +.BR /a/b/c/libQ.a : +.sp +.RS 4 +.nf +\fB +c99 \(miL /a/a/a \(miL /a/b/c main.o a.c \(mil Q b.c \(mil p +.fi \fR +.P +.RE +.P +In this example, the linker searches the +.BR \(miL +options in the order specified, and finds +.BR /a/a/a/libp.a +before +.BR /a/b/c/libp.a +when resolving references for +.BR b.c . +The order of the +.BR \(mil +options is still important, however. +.RE +.IP " 4." 4 +The following example shows how an application can use a programming +environment where the widths of the following types: +.BR blksize_t , +.BR cc_t , +.BR mode_t , +.BR nfds_t , +.BR pid_t , +.BR ptrdiff_t , +.BR size_t , +.BR speed_t , +.BR ssize_t , +.BR suseconds_t , +.BR tcflag_t , +.BR wchar_t , +.BR wint_t +.RS 4 +.P +are no greater than the width of type +.BR long : +.sp +.RS 4 +.nf +\fB +# First choose one of the listed environments ... +.P +# ... if there are no additional constraints, the first one will do: +CENV=$(getconf POSIX_V7_WIDTH_RESTRICTED_ENVS | head -n l) +.P +# ... or, if an environment that supports large files is preferred, +# look for names that contain "OFF64" or "OFFBIG". (This chooses +# the last one in the list if none match.) +for CENV in $(getconf POSIX_V7_WIDTH_RESTRICTED_ENVS) +do + case $CENV in + *OFF64*|*OFFBIG*) break ;; + esac +done +.P +# The chosen environment name can now be used like this: +.P +c99 $(getconf ${CENV}_CFLAGS) -D _POSIX_C_SOURCE=200809L \e +$(getconf ${CENV}_LDFLAGS) foo.c -o foo \e +$(getconf ${CENV}_LIBS) +.fi \fR +.P +.RE +.RE +.SH RATIONALE +The +.IR c99 +utility is based on the +.IR c89 +utility originally introduced in the ISO\ POSIX\(hy2:\|1993 standard. +.P +Some of the changes from +.IR c89 +include the ability to intersperse options and operands (which many +.IR c89 +implementations allowed despite it not being specified), +the description of +.BR \(mil +as an option instead of an operand, and the modification to the contents +of the Standard Libraries section to account for new headers and options; +for example, +.IR +added to the description of +.BR "\(mil\ rt" , +and +.BR "\(mil\ trace" +added for the Tracing option. +.P +POSIX.1\(hy2008 specifies that the +.IR c99 +utility must be able to use regular files for +.BR *.o +files and for +.BR a.out +files. Implementations are free to overwrite existing files of other +types when attempting to create object files and executable files, but +are not required to do so. If something other than a regular file is +specified and using it fails for any reason, +.IR c99 +is required to issue a diagnostic message and exit with a non-zero exit +status. But for some file types, the problem may not be noticed for a +long time. For example, if a FIFO named +.BR a.out +exists in the current directory, +.IR c99 +may attempt to open +.BR a.out +and will hang in the +\fIopen\fR() +call until another process opens the FIFO for reading. Then +.IR c99 +may write most of the +.BR a.out +to the FIFO and fail when it tries to seek back close to the start of +the file to insert a timestamp (FIFOs are not seekable files). The +.IR c99 +utility is also allowed to issue a diagnostic immediately if it +encounters an +.BR a.out +or +.BR *.o +file that is not a regular file. For portable use, applications should +ensure that any +.BR a.out , +.BR \(mio +option-argument, or +.BR *.o +files corresponding to any +.BR *.c +files do not conflict with names already in use that are not regular +files or symbolic links that point to regular files. +.P +On many systems, multi-threaded applications run in a programming +environment that is distinct from that used by single-threaded +applications. This multi-threaded programming environment (in addition +to needing to specify +.BR "\(mil pthread" +at link time) may require additional flags to be set when headers are +processed at compile time (\c +.BR \(miD_REENTRANT +being common). This programming environment is orthogonal to the type +size programming environments discussed above and listed in +.IR "Table 4-4, Programming Environments: Type Sizes". +This version of the standard adds +.IR getconf +utility calls to provide the C compiler flags and linker/loader flags +needed to support multi-threaded applications. Note that on a system +where single-threaded applications are a special case of a multi-threaded +application, both of these +.IR getconf +calls may return NULL strings; on other implementations both of +these strings may be non-NULL strings. +.P +The C standardization committee invented trigraphs (e.g., +.BR \(dq??!\(dq +to represent +.BR '|' ) +to address character portability problems in development environments +based on national variants of the 7-bit ISO/IEC\ 646:\|1991 standard character set. However, +these environments were already obsolete by the time the first ISO\ C standard was +published, and in practice trigraphs have not been used for their intended +purpose, and usually are intended to have their original meaning in K&R C. +For example, in practice a C-language source string like +.BR \(dqWhat??!\(dq +is usually intended to end in two + +characters and an +, +not in +.BR '|' . +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 1.1.1.4" ", " "File Read" ", " "Write" ", " "and Creation", +.IR "\fIar\fR\^", +.IR "\fIgetconf\fR\^", +.IR "\fImake\fR\^", +.IR "\fInm\fR\^", +.IR "\fIstrip\fR\^", +.IR "\fIumask\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +.IR "Chapter 13" ", " "Headers" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIexec\fR\^", +.IR "\fIsysconf\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/cal.1p b/man-pages-posix-2013/man1p/cal.1p new file mode 100644 index 0000000..dd71fc7 --- /dev/null +++ b/man-pages-posix-2013/man1p/cal.1p @@ -0,0 +1,162 @@ +'\" et +.TH CAL "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cal +\(em print a calendar +.SH SYNOPSIS +.LP +.nf +cal \fB[[\fImonth\fB] \fIyear\fB]\fR +.fi +.SH DESCRIPTION +The +.IR cal +utility shall write a calendar to standard output using the Julian +calendar for dates from January 1, 1 through September 2, 1752 and the +Gregorian calendar for dates from September 14, 1752 through December +31, 9999 as though the Gregorian calendar had been adopted on September +14, 1752. +.P +If no operands are given, +.IR cal +shall produce a one-month calendar for the current month in the +current year. If only the +.IR year +operand is given, +.IR cal +shall produce a calendar for all twelve months in the given calendar +year. If both +.IR month +and +.IR year +operands are given, +.IR cal +shall produce a one-month calendar for the given month in the given year. +.SH OPTIONS +None. +.SH OPERANDS +The following operands shall be supported: +.IP "\fImonth\fR" 10 +Specify the month to be displayed, represented as a decimal integer +from 1 (January) to 12 (December). +.IP "\fIyear\fR" 10 +Specify the year for which the calendar is displayed, represented as a +decimal integer from 1 to 9999. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR cal : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error, and +informative messages written to standard output. +.IP "\fILC_TIME\fP" 10 +Determine the format and contents of the calendar. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITZ\fP" 10 +Determine the timezone used to calculate the value of the current +month. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall be used to display the calendar, in an +unspecified format. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Note that: +.sp +.RS 4 +.nf +\fB +cal 83 +.fi \fR +.P +.RE +.P +refers to A.D. 83, not 1983. +.SH EXAMPLES +None. +.SH RATIONALE +Earlier versions of this standard incorrectly required that the command: +.sp +.RS 4 +.nf +\fB +cal 2000 +.fi \fR +.P +.RE +.P +write a one-month calendar for the current calendar month (no matter what +the current year is) in the year 2000 to standard output. This did not +match historic practice in any known version of the +.IR cal +utility. The description has been updated to match historic practice. +When only the +.IR year +operand is given, +.IR cal +writes a twelve-month calendar for the specified year. +.SH "FUTURE DIRECTIONS" +A future version of this standard may support locale-specific +recognition of the date of adoption of the Gregorian calendar. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/cat.1p b/man-pages-posix-2013/man1p/cat.1p new file mode 100644 index 0000000..1a79146 --- /dev/null +++ b/man-pages-posix-2013/man1p/cat.1p @@ -0,0 +1,325 @@ +'\" et +.TH CAT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cat +\(em concatenate and print files +.SH SYNOPSIS +.LP +.nf +cat \fB[\fR\(miu\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR cat +utility shall read files in sequence and shall write their contents +to the standard output in the same sequence. +.SH OPTIONS +The +.IR cat +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(miu\fP" 10 +Write bytes from the input file to the standard output without delay as +each is read. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an input file. If no +.IR file +operands are specified, the standard input shall be used. If a +.IR file +is +.BR '\(mi' , +the +.IR cat +utility shall read from the standard input at that point in the +sequence. The +.IR cat +utility shall not close and reopen standard input when it is referenced +in this way, but shall accept multiple occurrences of +.BR '\(mi' +as a +.IR file +operand. +.SH STDIN +The standard input shall be used only if no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' . +See the INPUT FILES section. +.SH "INPUT FILES" +The input files can be any file type. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR cat : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall contain the sequence of bytes read from the +input files. Nothing else shall be written to the standard output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All input files were output successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.BR \(miu +option has value in prototyping non-blocking reads from FIFOs. The +intent is to support the following sequence: +.sp +.RS 4 +.nf +\fB +mkfifo foo +cat \(miu foo > /dev/tty13 & +cat \(miu > foo +.fi \fR +.P +.RE +.P +It is unspecified whether standard output is or is not buffered in the +default case. This is sometimes of interest when standard output is +associated with a terminal, since buffering may delay the output. The +presence of the +.BR \(miu +option guarantees that unbuffered I/O is available. It is +implementation-defined whether the +.IR cat +utility buffers output if the +.BR \(miu +option is not specified. Traditionally, the +.BR \(miu +option is implemented using the equivalent of the +\fIsetvbuf\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008. +.SH EXAMPLES +The following command: +.sp +.RS 4 +.nf +\fB +cat myfile +.fi \fR +.P +.RE +.P +writes the contents of the file +.BR myfile +to standard output. +.P +The following command: +.sp +.RS 4 +.nf +\fB +cat doc1 doc2 > doc.all +.fi \fR +.P +.RE +.P +concatenates the files +.BR doc1 +and +.BR doc2 +and writes the result to +.BR doc.all . +.P +Because of the shell language mechanism used to perform output +redirection, a command such as this: +.sp +.RS 4 +.nf +\fB +cat doc doc.end > doc +.fi \fR +.P +.RE +.P +causes the original data in +.BR doc +to be lost. +.P +The command: +.sp +.RS 4 +.nf +\fB +cat start \(mi middle \(mi end > file +.fi \fR +.P +.RE +.P +when standard input is a terminal, gets two arbitrary pieces of input +from the terminal with a single invocation of +.IR cat . +Note, however, that if standard input is a regular file, this would be +equivalent to the command: +.sp +.RS 4 +.nf +\fB +cat start \(mi middle /dev/null end > file +.fi \fR +.P +.RE +.P +because the entire contents of the file would be consumed by +.IR cat +the first time +.BR '\(mi' +was used as a +.IR file +operand and an end-of-file condition would be detected immediately when +.BR '\(mi' +was referenced the second time. +.SH RATIONALE +Historical versions of the +.IR cat +utility include the +.BR \(mie , +.BR \(mit , +and +.BR \(miv , +options which permit the ends of lines, + +characters, and invisible characters, respectively, to be rendered visible +in the output. The standard developers omitted these options because +they provide too fine a degree of control over what is made visible, +and similar output can be obtained using a command such as: +.sp +.RS 4 +.nf +\fB +sed \(min l pathname +.fi \fR +.P +.RE +.P +The latter also has the advantage that its output is unambiguous, +whereas the output of historical +.IR cat +.BR \(mietv +is not. +.P +The +.BR \(mis +option was omitted because it corresponds to different functions in BSD +and System V-based systems. The BSD +.BR \(mis +option to squeeze blank lines can be accomplished by the shell script +shown in the following example: +.sp +.RS 4 +.nf +\fB +sed \(min ' +# Write non-empty lines. +/./ { + p + d + } +# Write a single empty line, then look for more empty lines. +/^$/ p +# Get next line, discard the held (empty line), +# and look for more empty lines. +:Empty +/^$/ { + N + s/.// + b Empty + } +# Write the non-empty line before going back to search +# for the first in a set of empty lines. + p +\&' +.fi \fR +.P +.RE +.P +The System V +.BR \(mis +option to silence error messages can be accomplished by redirecting the +standard error. Note that the BSD documentation for +.IR cat +uses the term ``blank line'' to mean the same as the POSIX ``empty +line'': a line consisting only of a +. +.P +The BSD +.BR \(min +option was omitted because similar functionality can be obtained from +the +.BR \(min +option of the +.IR pr +utility. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImore\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIsetvbuf\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/cd.1p b/man-pages-posix-2013/man1p/cd.1p new file mode 100644 index 0000000..7d5308e --- /dev/null +++ b/man-pages-posix-2013/man1p/cd.1p @@ -0,0 +1,507 @@ +'\" et +.TH CD "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cd +\(em change the working directory +.SH SYNOPSIS +.LP +.nf +cd \fB[\fR\(miL|\(miP\fB] [\fIdirectory\fB]\fR +.P +cd \(mi +.fi +.SH DESCRIPTION +The +.IR cd +utility shall change the working directory of the current shell +execution environment (see +.IR "Section 2.12" ", " "Shell Execution Environment") +by executing the following steps in sequence. (In the following steps, +the symbol +.BR curpath +represents an intermediate value used to simplify the description of +the algorithm used by +.IR cd . +There is no requirement that +.BR curpath +be made visible to the application.) +.IP " 1." 4 +If no +.IR directory +operand is given and the +.IR HOME +environment variable is empty or undefined, the default behavior is +implementation-defined and no further steps shall be taken. +.IP " 2." 4 +If no +.IR directory +operand is given and the +.IR HOME +environment variable is set to a non-empty value, the +.IR cd +utility shall behave as if the directory named in the +.IR HOME +environment variable was specified as the +.IR directory +operand. +.IP " 3." 4 +If the +.IR directory +operand begins with a + +character, set +.BR curpath +to the operand and proceed to step 7. +.IP " 4." 4 +If the first component of the +.IR directory +operand is dot or dot-dot, proceed to step 6. +.IP " 5." 4 +Starting with the first pathname in the +-separated +pathnames of +.IR CDPATH +(see the ENVIRONMENT VARIABLES section) if the pathname is non-null, +test if the concatenation of that pathname, a + +character if that pathname did not end with a + +character, and the +.IR directory +operand names a directory. If the pathname is null, test if the +concatenation of dot, a + +character, and the operand names a directory. In either case, if the +resulting string names an existing directory, set +.BR curpath +to that string and proceed to step 7. Otherwise, repeat this step with +the next pathname in +.IR CDPATH +until all pathnames have been tested. +.IP " 6." 4 +Set +.BR curpath +to the +.IR directory +operand. +.IP " 7." 4 +If the +.BR \(miP +option is in effect, proceed to step 10. If +.BR curpath +does not begin with a + +character, set +.BR curpath +to the string formed by the concatenation of the value of +.IR PWD , +a + +character if the value of +.IR PWD +did not end with a + +character, and +.BR curpath . +.IP " 8." 4 +The +.BR curpath +value shall then be converted to canonical form as follows, considering +each component from beginning to end, in sequence: +.RS 4 +.IP " a." 4 +Dot components and any + +characters that separate them from the next component shall be deleted. +.IP " b." 4 +For each dot-dot component, if there is a preceding component and it is +neither root nor dot-dot, then: +.RS 4 +.IP " i." 5 +If the preceding component does not refer (in the context of pathname +resolution with symbolic links followed) to a directory, then the +.IR cd +utility shall display an appropriate error message and no further steps +shall be taken. +.IP ii. 5 +The preceding component, all + +characters separating the preceding component from dot-dot, dot-dot, +and all + +characters separating dot-dot from the following component (if any) +shall be deleted. +.RE +.IP " c." 4 +An implementation may further simplify +.BR curpath +by removing any trailing + +characters that are not also leading + +characters, replacing multiple non-leading consecutive + +characters with a single +, +and replacing three or more leading + +characters with a single +. +If, as a result of this canonicalization, the +.BR curpath +variable is null, no further steps shall be taken. +.RE +.IP " 9." 4 +If +.BR curpath +is longer than +{PATH_MAX} +bytes (including the terminating null) and the +.IR directory +operand was not longer than +{PATH_MAX} +bytes (including the terminating null), then +.BR curpath +shall be converted from an absolute pathname to an equivalent relative +pathname if possible. This conversion shall always be considered +possible if the value of +.IR PWD , +with a trailing + +added if it does not already have one, is an initial substring of +.BR curpath . +Whether or not it is considered possible under other circumstances is +unspecified. Implementations may also apply this conversion if +.BR curpath +is not longer than +{PATH_MAX} +bytes or the +.IR directory +operand was longer than +{PATH_MAX} +bytes. +.IP 10. 4 +The +.IR cd +utility shall then perform actions equivalent to the +\fIchdir\fR() +function called with +.BR curpath +as the +.IR path +argument. If these actions fail for any reason, the +.IR cd +utility shall display an appropriate error message and the remainder of +this step shall not be executed. If the +.BR \(miP +option is not in effect, the +.IR PWD +environment variable shall be set to the value that +.BR curpath +had on entry to step 9 (i.e., before conversion to a relative +pathname). If the +.BR \(miP +option is in effect, the +.IR PWD +environment variable shall be set to the string that would be output by +.IR pwd +.BR \(miP . +If there is insufficient permission on the new directory, or on any +parent of that directory, to determine the current working directory, +the value of the +.IR PWD +environment variable is unspecified. +.P +If, during the execution of the above steps, the +.IR PWD +environment variable +is set, the +.IR OLDPWD +environment variable shall also be set to +the value of the old working directory (that is the current working +directory immediately prior to the call to +.IR cd ). +.SH OPTIONS +The +.IR cd +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported by the implementation: +.IP "\fB\(miL\fP" 10 +Handle the operand dot-dot logically; symbolic link components shall +not be resolved before dot-dot components are processed (see steps 8. +and 9. in the DESCRIPTION). +.IP "\fB\(miP\fP" 10 +Handle the operand dot-dot physically; symbolic link components shall +be resolved before dot-dot components are processed (see step 7. in the +DESCRIPTION). +.P +If both +.BR \(miL +and +.BR \(miP +options are specified, the last of these options shall be used and all +others ignored. If neither +.BR \(miL +nor +.BR \(miP +is specified, the operand shall be handled dot-dot logically; see the +DESCRIPTION. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIdirectory\fR" 10 +An absolute or relative pathname of the directory that shall become +the new working directory. The interpretation of a relative pathname +by +.IR cd +depends on the +.BR \(miL +option and the +.IR CDPATH +and +.IR PWD +environment variables. If +.IR directory +is an empty string, the results are unspecified. +.IP "\(mi" 10 +When a + +is used as the operand, this shall be equivalent to the command: +.RS 10 +.sp +.RS 4 +.nf +\fB +cd "$OLDPWD" && pwd +.fi \fR +.P +.RE +.P +which changes to the previous working directory and then writes its +name. +.RE +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR cd : +.IP "\fICDPATH\fP" 10 +A +-separated +list of pathnames that refer to directories. The +.IR cd +utility shall use this list in its attempt to change the directory, as +described in the DESCRIPTION. An empty string in place of a directory +pathname represents the current directory. If +.IR CDPATH +is not set, it shall be treated as if it were an empty string. +.IP "\fIHOME\fP" 10 +The name of the directory, used when no +.IR directory +operand is specified. +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIOLDPWD\fP" 10 +A pathname of the previous working directory, used by +.IR cd +.BR \(mi . +.IP "\fIPWD\fP" 10 +This variable shall be set as specified in the DESCRIPTION. If an +application sets or unsets the value of +.IR PWD , +the behavior of +.IR cd +is unspecified. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If a non-empty directory name from +.IR CDPATH +is used, or if +.IR cd +.BR \(mi +is used, an absolute pathname of the new working directory shall be +written to the standard output as follows: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fInew directory\fR> +.fi \fR +.P +.RE +.P +Otherwise, there shall be no output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The directory was successfully changed. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +The working directory shall remain unchanged. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Since +.IR cd +affects the current shell execution environment, it is always provided +as a shell regular built-in. If it is called in a subshell or separate +utility execution environment, such as one of the following: +.sp +.RS 4 +.nf +\fB +(cd /tmp) +nohup cd +find . \(miexec cd {} \e; +.fi \fR +.P +.RE +.P +it does not affect the working directory of the caller's environment. +.P +The user must have execute (search) permission in +.IR directory +in order to change to it. +.SH EXAMPLES +The following template can be used to perform processing in the directory +specified by +.IR location +and end up in the current working directory in use before the first +.IR cd +command was issued: +.sp +.RS 4 +.nf +\fB +cd \fIlocation\fP +if [ $? -ne 0 ] +then + print error message + exit 1 +fi +\&... do whatever is desired as long as the OLDPWD environment variable + is not modified +cd - +.fi \fR +.P +.RE +.SH RATIONALE +The use of the +.IR CDPATH +was introduced in the System V shell. Its use is analogous to the use +of the +.IR PATH +variable in the shell. The BSD C shell used a shell parameter +.IR cdpath +for this purpose. +.P +A common extension when +.IR HOME +is undefined is to get the login directory from the user database for +the invoking user. This does not occur on System V implementations. +.P +Some historical shells, such as the KornShell, took special actions +when the directory name contained a dot-dot component, selecting the +logical parent of the directory, rather than the actual parent +directory; that is, it moved up one level toward the +.BR '/' +in the pathname, remembering what the user typed, rather than +performing the equivalent of: +.sp +.RS 4 +.nf +\fB +chdir(".."); +.fi \fR +.P +.RE +.P +In such a shell, the following commands would not necessarily produce +equivalent output for all directories: +.sp +.RS 4 +.nf +\fB +cd .. && ls ls .. +.fi \fR +.P +.RE +.P +This behavior is now the default. It is not consistent with the +definition of dot-dot in most historical practice; that is, while this +behavior has been optionally available in the KornShell, other shells +have historically not supported this functionality. The logical +pathname is stored in the +.IR PWD +environment variable when the +.IR cd +utility completes and this value is used to construct the next +directory name if +.IR cd +is invoked with the +.BR \(miL +option. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.12" ", " "Shell Execution Environment", +.IR "\fIpwd\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIchdir\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/cflow.1p b/man-pages-posix-2013/man1p/cflow.1p new file mode 100644 index 0000000..8301c72 --- /dev/null +++ b/man-pages-posix-2013/man1p/cflow.1p @@ -0,0 +1,278 @@ +'\" et +.TH CFLOW "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cflow +\(em generate a C-language flowgraph (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +cflow \fB[\fR\(mir\fB] [\fR\(mid \fInum\fB] [\fR\(miD \fIname\fB[\fR=\fIdef\fB]]\fR...\fB [\fR\(mii \fIincl\fB] [\fR\(miI \fIdir\fB]\fR... + \fB[\fR\(miU \fIdir\fB]\fR... \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR cflow +utility shall analyze a collection of object files or assembler, +C-language, +.IR lex , +or +.IR yacc +source files, and attempt to build a graph, written to standard output, +charting the external references. +.SH OPTIONS +The +.IR cflow +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that the order of the +.BR \(miD , +.BR \(miI , +and +.BR \(miU +options (which are identical to their interpretation by +.IR c99 ) +is significant. +.P +The following options shall be supported: +.IP "\fB\(mid\ \fInum\fR" 10 +Indicate the depth at which the flowgraph is cut off. The application +shall ensure that the argument +.IR num +is a decimal integer. By default this is a very large number +(typically greater than 32\|000). Attempts to set the cut-off depth to +a non-positive integer shall be ignored. +.IP "\fB\(mii\ \fIincl\fR" 10 +Increase the number of included symbols. The +.IR incl +option-argument is one of the following characters: +.RS 10 +.IP "\fIx\fP" 6 +Include external and static data symbols. The default shall be to +include only functions in the flowgraph. +.IP "\fR_\fP" 6 +(Underscore) Include names that begin with an +. +The default shall be to exclude these functions (and data if +.BR "\(mii\ x" +is used). +.RE +.IP "\fB\(mir\fP" 10 +Reverse the caller:callee relationship, producing an inverted listing +showing the callers of each function. The listing shall also be sorted +in lexicographical order by callee. +.SH OPERANDS +The following operand is supported: +.IP "\fIfile\fR" 10 +The pathname of a file for which a graph is to be generated. +Filenames suffixed by +.BR .l +shall shall be taken to be +.IR lex +input, +.BR .y +as +.IR yacc +input, +.BR .c +as +.IR c99 +input, and +.BR .i +as the output of +.IR c99 +.BR \(miE . +Such files shall be processed as appropriate, determined by their +suffix. +.RS 10 +.P +Files suffixed by +.BR .s +(conventionally assembler source) may have more limited information +extracted from them. +.RE +.SH STDIN +Not used. +.SH "INPUT FILES" +The input files shall be object files or assembler, C-language, +.IR lex , +or +.IR yacc +source files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR cflow : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the ordering of the output when the +.BR \(mir +option is used. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The flowgraph written to standard output shall be formatted as follows: +.sp +.RS 4 +.nf +\fB +"%d %s:%s\en", <\fIreference number\fR>, <\fIglobal\fR>, <\fIdefinition\fR> +.fi \fR +.P +.RE +.P +Each line of output begins with a reference (that is, line) number, +followed by indentation of at least one column position per level. +This is followed by the name of the global, a +, +and its definition. Normally globals are only functions not defined as +an external or beginning with an +; +see the OPTIONS section for the +.BR \(mii +inclusion option. For information extracted from C-language source, the +definition consists of an abstract type declaration (for example, +.BR "char *" ) +and, delimited by angle brackets, the name of the source file and the +line number where the definition was found. Definitions extracted from +object files indicate the filename and location counter under which +the symbol appeared (for example, +.IR text ). +.P +Once a definition of a name has been written, subsequent references to +that name contain only the reference number of the line where the +definition can be found. For undefined references, only +.BR \(dq<\|>\(dq +shall be written. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Files produced by +.IR lex +and +.IR yacc +cause the reordering of line number declarations, and this can confuse +.IR cflow . +To obtain proper results, the input of +.IR yacc +or +.IR lex +must be directed to +.IR cflow . +.SH EXAMPLES +Given the following in +.BR file.c : +.sp +.RS 4 +.nf +\fB +int i; +int f(); +int g(); +int h(); +int +main() +{ + f(); + g(); + f(); +} +int +f() +{ + i = h(); +} +.fi \fR +.P +.RE +.P +The command: +.sp +.RS 4 +.nf +\fB +cflow \(mii x file.c +.fi \fR +.P +.RE +.P +produces the output: +.sp +.RS 4 +.nf +\fB +1 main: int(), +2 f: int(), +3 h: <> +4 i: int, +5 g: <> +.fi \fR +.P +.RE +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIc99\fR\^", +.IR "\fIlex\fR\^", +.IR "\fIyacc\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/chgrp.1p b/man-pages-posix-2013/man1p/chgrp.1p new file mode 100644 index 0000000..02b49bf --- /dev/null +++ b/man-pages-posix-2013/man1p/chgrp.1p @@ -0,0 +1,235 @@ +'\" et +.TH CHGRP "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +chgrp +\(em change the file group ownership +.SH SYNOPSIS +.LP +.nf +chgrp \fB[\fR\(mih\fB] \fIgroup file\fR... +.P +chgrp \(miR \fB[\fR\(miH|\(miL|\(miP\fB] \fIgroup file\fR... +.fi +.SH DESCRIPTION +The +.IR chgrp +utility shall set the group ID of the file named by each +.IR file +operand to the group ID specified by the +.IR group +operand. +.P +For each +.IR file +operand, or, if the +.BR \(miR +option is used, each file encountered while walking the directory +trees specified by the +.IR file +operands, the +.IR chgrp +utility shall perform actions equivalent to the +\fIchown\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008, called with the following arguments: +.IP " *" 4 +The +.IR file +operand shall be used as the +.IR path +argument. +.IP " *" 4 +The user ID of the file shall be used as the +.IR owner +argument. +.IP " *" 4 +The specified group ID shall be used as the +.IR group +argument. +.P +Unless +.IR chgrp +is invoked by a process with appropriate privileges, the set-user-ID +and set-group-ID bits of a regular file shall be cleared upon successful +completion; the set-user-ID and set-group-ID bits of other file types +may be cleared. +.SH OPTIONS +The +.IR chgrp +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported by the implementation: +.IP "\fB\(mih\fP" 10 +For each +.IR file +operand that names a file of type symbolic link, +.IR chgrp +shall attempt to set the group ID of the symbolic link instead of the +file referenced by the symbolic link. +.IP "\fB\(miH\fP" 10 +If the +.BR \(miR +option is specified and a symbolic link referencing a file of type +directory is specified on the command line, +.IR chgrp +shall change the group of the directory referenced by the symbolic link +and all files in the file hierarchy below it. +.IP "\fB\(miL\fP" 10 +If the +.BR \(miR +option is specified and a symbolic link referencing a file of type +directory is specified on the command line or encountered during the +traversal of a file hierarchy, +.IR chgrp +shall change the group of the directory referenced by the symbolic link +and all files in the file hierarchy below it. +.IP "\fB\(miP\fP" 10 +If the +.BR \(miR +option is specified and a symbolic link is specified on the command +line or encountered during the traversal of a file hierarchy, +.IR chgrp +shall change the group ID of the symbolic link. The +.IR chgrp +utility shall not follow the symbolic link to any other part of the +file hierarchy. +.IP "\fB\(miR\fP" 10 +Recursively change file group IDs. For each +.IR file +operand that names a directory, +.IR chgrp +shall change the group of the directory and all files in the +file hierarchy below it. Unless a +.BR \(miH , +.BR \(miL , +or +.BR \(miP +option is specified, it is unspecified which of these options will be +used as the default. +.P +Specifying more than one of the mutually-exclusive options +.BR \(miH , +.BR \(miL , +and +.BR \(miP +shall not be considered an error. The last option specified shall +determine the behavior of the utility. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIgroup\fR" 10 +A group name from the group database or a numeric group ID. Either +specifies a group ID to be given to each file named by one of the +.IR file +operands. If a numeric +.IR group +operand exists in the group database as a group name, the group ID +number associated with that group name is used as the group ID. +.IP "\fIfile\fR" 10 +A pathname of a file whose group ID is to be modified. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR chgrp : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The utility executed successfully and all requested changes were made. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Only the owner of a file or the user with appropriate privileges may +change the owner or group of a file. +.P +Some implementations restrict the use of +.IR chgrp +to a user with appropriate privileges when the +.IR group +specified is not the effective group ID or one of the supplementary +group IDs of the calling process. +.SH EXAMPLES +None. +.SH RATIONALE +The System V and BSD versions use different exit status codes. Some +implementations used the exit status as a count of the number of errors +that occurred; this practice is unworkable since it can overflow the +range of valid exit status values. The standard developers chose to +mask these by specifying only 0 and >0 as exit values. +.P +The functionality of +.IR chgrp +is described substantially through references to +\fIchown\fR(). +In this way, there is no duplication of effort required for describing +the interactions of permissions, multiple groups, and so on. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^", +.IR "\fIchown\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIchown\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/chmod.1p b/man-pages-posix-2013/man1p/chmod.1p new file mode 100644 index 0000000..3fcee04 --- /dev/null +++ b/man-pages-posix-2013/man1p/chmod.1p @@ -0,0 +1,679 @@ +'\" et +.TH CHMOD "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\(em change the file modes +.SH SYNOPSIS +.LP +.nf +chmod \fB[\fR\(miR\fB] \fImode file\fR... +.fi +.SH DESCRIPTION +The +.IR chmod +utility shall change any or all of the file mode bits of the file named +by each +.IR file +operand in the way specified by the +.IR mode +operand. +.P +It is implementation-defined whether and how the +.IR chmod +utility affects any alternate or additional file access control +mechanism (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.4" ", " "File Access Permissions") +being used for the specified file. +.P +Only a process whose effective user ID matches the user ID of the file, +or a process with appropriate privileges, shall be permitted to +change the file mode bits of a file. +.P +Upon successfully changing the file mode bits of a file, the +.IR chmod +utility shall mark for update the last file status change timestamp +of the file. +.SH OPTIONS +The +.IR chmod +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(miR\fP" 10 +Recursively change file mode bits. For each +.IR file +operand that names a directory, +.IR chmod +shall change the file mode bits of the directory and all files in the +file hierarchy below it. +.SH OPERANDS +The following operands shall be supported: +.IP "\fImode\fR" 10 +Represents the change to be made to the file mode bits of each +file named by one of the +.IR file +operands; see the EXTENDED DESCRIPTION section. +.IP "\fIfile\fR" 10 +A pathname of a file whose file mode bits shall be modified. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR chmod : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +The +.IR mode +operand shall be either a +.IR symbolic_mode +expression or a non-negative octal integer. The +.IR symbolic_mode +form is described by the grammar later in this section. +.P +Each +.BR clause +shall specify an operation to be performed on the current file mode +bits of each +.IR file . +The operations shall be performed on each +.IR file +in the order in which the +.BR clause s +are specified. +.P +The +.BR who +symbols +.BR u , +.BR g , +and +.BR o +shall specify the +.IR user , +.IR group , +and +.IR other +parts of the file mode bits, respectively. A +.BR who +consisting of the symbol +.BR a +shall be equivalent to +.BR ugo . +.P +The +.BR perm +symbols +.BR r , +.BR w , +and +.BR x +represent the +.IR read , +.IR write , +and +.IR execute /\c +.IR search +portions of file mode bits, respectively. The +.BR perm +symbol +.BR s +shall represent the +.IR "set-user-ID-on-execution" +(when +.BR who +contains or implies +.BR u ) +and +.IR "set-group-ID-on-execution" +(when +.BR who +contains or implies +.BR g ) +bits. +.P +The +.BR perm +symbol +.BR X +shall represent the execute/search portion of the file mode bits if the +file is a directory or if the current (unmodified) file mode bits have +at least one of the execute bits (S_IXUSR, S_IXGRP, or S_IXOTH) set. It +shall be ignored if the file is not a directory and none of the execute +bits are set in the current file mode bits. +.P +The +.BR permcopy +symbols +.BR u , +.BR g , +and +.BR o +shall represent the current permissions associated with the user, +group, and other parts of the file mode bits, respectively. For the +remainder of this section, +.BR perm +refers to the non-terminals +.BR perm +and +.BR permcopy +in the grammar. +.P +If multiple +.BR actionlist s +are grouped with a single +.BR wholist +in the grammar, each +.BR actionlist +shall be applied in the order specified with that +.BR wholist . +The +.IR op +symbols shall represent the operation performed, as follows: +.IP "\fR+\fP" 6 +If +.BR perm +is not specified, the +.BR '\(pl' +operation shall not change the file mode bits. +.RS 6 +.P +If +.BR who +is not specified, the file mode bits represented by +.BR perm +for the owner, group, and other permissions, except for those with +corresponding bits in the file mode creation mask of the invoking +process, shall be set. +.P +Otherwise, the file mode bits represented by the specified +.BR who +and +.BR perm +values shall be set. +.RE +.IP "\fR\(mi\fP" 6 +If +.BR perm +is not specified, the +.BR '\(mi' +operation shall not change the file mode bits. +.RS 6 +.P +If +.BR who +is not specified, the file mode bits represented by +.BR perm +for the owner, group, and other permissions, except for those with +corresponding bits in the file mode creation mask of the invoking +process, shall be cleared. +.P +Otherwise, the file mode bits represented by the specified +.BR who +and +.BR perm +values shall be cleared. +.RE +.IP "\fR=\fP" 6 +Clear the file mode bits specified by the +.BR who +value, or, if no +.BR who +value is specified, all of the file mode bits specified in this volume of POSIX.1\(hy2008. +.RS 6 +.P +If +.BR perm +is not specified, the +.BR '=' +operation shall make no further modifications to the file mode bits. +.P +If +.BR who +is not specified, the file mode bits represented by +.BR perm +for the owner, group, and other permissions, except for those with +corresponding bits in the file mode creation mask of the invoking +process, shall be set. +.P +Otherwise, the file mode bits represented by the specified +.BR who +and +.BR perm +values shall be set. +.RE +.P +When using the symbolic mode form on a regular file, it is +implementation-defined whether or not: +.IP " *" 4 +Requests to set the set-user-ID-on-execution or +set-group-ID-on-execution bit when all execute bits are currently clear +and none are being set are ignored. +.IP " *" 4 +Requests to clear all execute bits also clear the +set-user-ID-on-execution and set-group-ID-on-execution bits. +.IP " *" 4 +Requests to clear the set-user-ID-on-execution or +set-group-ID-on-execution bits when all execute bits are currently +clear are ignored. However, if the command +.IR ls +.BR \(mil +.IR file +writes an +.IR s +in the position indicating that the set-user-ID-on-execution or +set-group-ID-on-execution is set, the commands +.IR chmod +.BR u\(mis +.IR file +or +.IR chmod +.BR g\(mis +.IR file , +respectively, shall not be ignored. +.P +When using the symbolic mode form on other file types, it is +implementation-defined whether or not requests to set or clear the +set-user-ID-on-execution or set-group-ID-on-execution bits are +honored. +.P +If the +.BR who +symbol +.BR o +is used in conjunction with the +.BR perm +symbol +.BR s +with no other +.BR who +symbols being specified, the set-user-ID-on-execution and +set-group-ID-on-execution bits shall not be modified. It shall not be +an error to specify the +.BR who +symbol +.BR o +in conjunction with the +.BR perm +symbol +.BR s . +.P +The +.BR perm +symbol +.BR t +shall specify the S_ISVTX bit. When used with a file of type +directory, it can be used with the +.BR who +symbol +.BR a , +or with no +.BR who +symbol. It shall not be an error to specify a +.BR who +symbol of +.BR u , +.BR g , +or +.BR o +in conjunction with the +.BR perm +symbol +.BR t , +but the meaning of these combinations is unspecified. The effect when +using the +.BR perm +symbol +.BR t +with any file type other than directory is unspecified. +.P +For an octal integer +.IR mode +operand, the file mode bits shall be set absolutely. +.P +For each bit set in the octal number, the corresponding file permission +bit shown in the following table shall be set; all other file +permission bits shall be cleared. For regular files, for each bit set +in the octal number corresponding to the set-user-ID-on-execution or +the set-group-ID-on-execution, bits shown in the following table shall +be set; if these bits are not set in the octal number, they are +cleared. For other file types, it is implementation-defined whether +or not requests to set or clear the set-user-ID-on-execution or +set-group-ID-on-execution bits are honored. +.TS +center tab(@) box; +cB cB | cB cB | cB cB | cB cB +nB l | nB l | nB l | nB l. +Octal@Mode Bit@Octal@Mode Bit@Octal@Mode Bit@Octal@Mode Bit +_ +4000@S_ISUID@0400@S_IRUSR@0040@S_IRGRP@0004@S_IROTH +_ +2000@S_ISGID@0200@S_IWUSR@0020@S_IWGRP@0002@S_IWOTH +_ +1000@S_ISVTX@0100@S_IXUSR@0010@S_IXGRP@0001@S_IXOTH +.TE +.P +When bits are set in the octal number other than those listed in the +table above, the behavior is unspecified. +.SS "Grammar for chmod" +.P +The grammar and lexical conventions in this section describe the syntax +for the +.IR symbolic_mode +operand. The general conventions for this style of grammar are +described in +.IR "Section 1.3" ", " "Grammar Conventions". +A valid +.IR symbolic_mode +can be represented as the non-terminal symbol +.IR symbolic_mode +in the grammar. This formal syntax shall take precedence over the +preceding text syntax description. +.P +The lexical processing is based entirely on single characters. +Implementations need not allow + +characters within the single argument being processed. +.sp +.RS 4 +.nf +\fB +%start symbolic_mode +%% +.P +symbolic_mode : clause + | symbolic_mode ',' clause + ; +.P +clause : actionlist + | wholist actionlist + ; +.P +wholist : who + | wholist who + ; +.P +who : 'u' | 'g' | 'o' | 'a' + ; +.P +actionlist : action + | actionlist action + ; +.P +action : op + | op permlist + | op permcopy + ; +.P +permcopy : 'u' | 'g' | 'o' + ; +.P +op : '+' | '\(mi' | '=' + ; +.P +permlist : perm + | perm permlist + ; +.P +perm : 'r' | 'w' | 'x' | 'X' | 's' | 't' + ; +.fi \fR +.P +.RE +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The utility executed successfully and all requested changes were made. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Some implementations of the +.IR chmod +utility change the mode of a directory before the files in the +directory when performing a recursive (\c +.BR \(miR +option) change; others change the directory mode after the files in the +directory. If an application tries to remove read or search permission +for a file hierarchy, the removal attempt fails if the directory is +changed first; on the other hand, trying to re-enable permissions to a +restricted hierarchy fails if directories are changed last. Users +should not try to make a hierarchy inaccessible to themselves. +.P +Some implementations of +.IR chmod +never used the +.IR umask +of the process when changing modes; systems conformant with this volume of POSIX.1\(hy2008 +do so when +.BR who +is not specified. Note the difference between: +.sp +.RS 4 +.nf +\fB +chmod a\(miw file +.fi \fR +.P +.RE +.P +which removes all write permissions, and: +.sp +.RS 4 +.nf +\fB +chmod \(mi\|\(mi \(miw file +.fi \fR +.P +.RE +.P +which removes write permissions that would be allowed if +.BR file +was created with the same +.IR umask . +.P +Conforming applications should never assume that they know how the +set-user-ID and set-group-ID bits on directories are interpreted. +.SH EXAMPLES +.ad l +.TS +center tab(@) box; +cB | cB +l | lw(3i). +Mode@Results +_ +\fIa\fP+=@T{ +Equivalent to +.IR a +,\c +.IR a =; +clears all file mode bits. +T} +\fIgo\fP+\(miw@T{ +Equivalent to +.IR go +,\c +.IR go \(mi\c +.IR w ; +clears group and other write bits. +T} +\fIg\fR=\fIo\fR\(mi\fIw\fR@T{ +Equivalent to +.IR g =\c +.IR o ,\c +.IR g \(mi\c +.IR w ; +sets group bit to match other bits and then clears group write bit. +T} +\fIg\fR\(mi\fIr\fR+\fIw\fR@T{ +Equivalent to +.IR g \(mi\c +.IR r ,\c +.IR g +\c +.IR w ; +clears group read bit and sets group write bit. +T} +\fIuo\fR=\fIg\fR@T{ +Sets owner bits to match group bits and sets other bits to +match group bits. +T} +.TE +.ad b +.SH RATIONALE +The functionality of +.IR chmod +is described substantially through references to concepts defined in +the System Interfaces volume of POSIX.1\(hy2008. In this way, there is less duplication of effort required +for describing the interactions of permissions. However, the behavior +of this utility is not described in terms of the +\fIchmod\fR() +function from the System Interfaces volume of POSIX.1\(hy2008 because that specification requires certain +side-effects upon alternate file access control mechanisms that might +not be appropriate, depending on the implementation. +.P +Implementations that support mandatory file and record locking as +specified +by the 1984 /usr/group standard historically used the combination of set-group-ID bit set +and group execute bit clear to indicate mandatory locking. This +condition is usually set or cleared with the symbolic mode +.BR perm +symbol +.BR l +instead of the +.BR perm +symbols +.BR s +and +.BR x +so that the mandatory locking mode is not changed without explicit +indication that that was what the user intended. Therefore, the details +on how the implementation treats these conditions must be defined in +the documentation. This volume of POSIX.1\(hy2008 does not require mandatory locking (nor does +the System Interfaces volume of POSIX.1\(hy2008), but does allow it as an extension. However, this volume of POSIX.1\(hy2008 does +require that the +.IR ls +and +.IR chmod +utilities work consistently in this area. If +.IR ls +.BR \(mil +.IR file +indicates that the set-group-ID bit is set, +.IR chmod +.BR g\(mis +.IR file +must clear it (assuming appropriate privileges exist to change modes). +.P +The System V and BSD versions use different exit status codes. Some +implementations used the exit status as a count of the number of errors +that occurred; this practice is unworkable since it can overflow the +range of valid exit status values. This problem is avoided here by +specifying only 0 and >0 as exit values. +.P +The System Interfaces volume of POSIX.1\(hy2008 indicates that implementation-defined restrictions may cause +the S_ISUID and S_ISGID bits to be ignored. This volume of POSIX.1\(hy2008 allows the +.IR chmod +utility to choose to modify these bits before calling +\fIchmod\fR() +(or some function providing equivalent capabilities) for non-regular +files. Among other things, this allows implementations that use the +set-user-ID and set-group-ID bits on directories to enable extended +features to +handle these extensions in an intelligent manner. +.P +The +.BR X +.BR perm +symbol was adopted from BSD-based systems because it provides commonly +desired functionality when doing recursive (\c +.BR \(miR +option) modifications. Similar functionality is not provided by the +.IR find +utility. Historical BSD versions of +.IR chmod , +however, only supported +.BR X +with +.IR op +; +it has been extended in this volume of POSIX.1\(hy2008 because it is also useful with +.IR op =. +(It has also been added for +.IR op \(mi +even though it duplicates +.BR x , +in this case, because it is intuitive and easier to explain.) +.P +The grammar was extended with the +.IR permcopy +non-terminal to allow historical-practice forms of symbolic modes like +.BR o =\c +.BR u +.BR \(mig +(that is, set the ``other'' permissions to the permissions of ``owner'' +minus the permissions of ``group''). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIls\fR\^", +.IR "\fIumask\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.4" ", " "File Access Permissions", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIchmod\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/chown.1p b/man-pages-posix-2013/man1p/chown.1p new file mode 100644 index 0000000..4defb5f --- /dev/null +++ b/man-pages-posix-2013/man1p/chown.1p @@ -0,0 +1,301 @@ +'\" et +.TH CHOWN "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\(em change the file ownership +.SH SYNOPSIS +.LP +.nf +chown \fB[\fR\(mih\fB] \fIowner\fB[\fR:\fIgroup\fB] \fIfile\fR... +.P +chown \(miR \fB[\fR\(miH|\(miL|\(miP\fB] \fIowner\fB[\fR:\fIgroup\fB] \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR chown +utility shall set the user ID of the file named by each +.IR file +operand to the user ID specified by the +.IR owner +operand. +.P +For each +.IR file +operand, or, if the +.BR \(miR +option is used, each file encountered while walking the directory +trees specified by the +.IR file +operands, the +.IR chown +utility shall perform actions equivalent to the +\fIchown\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008, called with the following arguments: +.IP " 1." 4 +The +.IR file +operand shall be used as the +.IR path +argument. +.IP " 2." 4 +The user ID indicated by the +.IR owner +portion of the first operand shall be used as the +.IR owner +argument. +.IP " 3." 4 +If the +.IR group +portion of the first operand is given, the group ID indicated by it +shall be used as the +.IR group +argument; otherwise, the group ownership shall not be changed. +.P +Unless +.IR chown +is invoked by a process with appropriate privileges, the set-user-ID +and set-group-ID bits of a regular file shall be cleared upon +successful completion; the set-user-ID and set-group-ID bits of other +file types may be cleared. +.SH OPTIONS +The +.IR chown +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported by the implementation: +.IP "\fB\(mih\fP" 10 +For each file operand that names a file of type symbolic link, +.IR chown +shall attempt to set the user ID of the symbolic link. If a group ID +was specified, for each file operand that names a file of +type symbolic link, +.IR chown +shall attempt to set the group ID of the symbolic link. +.IP "\fB\(miH\fP" 10 +If the +.BR \(miR +option is specified and a symbolic link referencing a file of type +directory is specified on the command line, +.IR chown +shall change the user ID (and group ID, if specified) of the directory +referenced by the symbolic link and all files in the file hierarchy +below it. +.IP "\fB\(miL\fP" 10 +If the +.BR \(miR +option is specified and a symbolic link referencing a file of type +directory is specified on the command line or encountered during the +traversal of a file hierarchy, +.IR chown +shall change the user ID (and group ID, if specified) of the directory +referenced by the symbolic link and all files in the file hierarchy +below it. +.IP "\fB\(miP\fP" 10 +If the +.BR \(miR +option is specified and a symbolic link is specified on the command +line or encountered during the traversal of a file hierarchy, +.IR chown +shall change the owner ID (and group ID, if specified) of the symbolic +link. The +.IR chown +utility shall not follow the symbolic link to any other part of the +file hierarchy. +.IP "\fB\(miR\fP" 10 +Recursively change file user and group IDs. For each +.IR file +operand that names a directory, +.IR chown +shall change the user ID (and group ID, if specified) of the directory +and all files in the file hierarchy below it. Unless a +.BR \(miH , +.BR \(miL , +or +.BR \(miP +option is specified, it is unspecified which of these options will be +used as the default. +.P +Specifying more than one of the mutually-exclusive options +.BR \(miH , +.BR \(miL , +and +.BR \(miP +shall not be considered an error. The last option specified shall +determine the behavior of the utility. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIowner\fB[\fR:\fIgroup\fB]\fR" 10 +A user ID and optional group ID to be assigned to +.IR file . +The +.IR owner +portion of this operand shall be a user name from the user database or +a numeric user ID. Either specifies a user ID which shall be given to +each file named by one of the +.IR file +operands. If a numeric +.IR owner +operand exists in the user database as a user name, the user ID number +associated with that user name shall be used as the user ID. Similarly, +if the +.IR group +portion of this operand is present, it shall be a group name from the +group database or a numeric group ID. Either specifies a group ID which +shall be given to each file. If a numeric group operand exists in the +group database as a group name, the group ID number associated with +that group name shall be used as the group ID. +.IP "\fIfile\fR" 10 +A pathname of a file whose user ID is to be modified. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR chown : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The utility executed successfully and all requested changes were made. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Only the owner of a file or the user with appropriate privileges may +change the owner or group of a file. +.P +Some implementations restrict the use of +.IR chown +to a user with appropriate privileges. +.SH EXAMPLES +None. +.SH RATIONALE +The System V and BSD versions use different exit status codes. Some +implementations used the exit status as a count of the number of errors +that occurred; this practice is unworkable since it can overflow the +range of valid exit status values. These are masked by specifying only +0 and >0 as exit values. +.P +The functionality of +.IR chown +is described substantially through references to functions in the +System Interfaces volume of POSIX.1\(hy2008. In this way, there is no duplication of effort required for +describing the interactions of permissions, multiple groups, and so +on. +.P +The 4.3 BSD method of specifying both owner and group was included in +\&this volume of POSIX.1\(hy2008 because: +.IP " *" 4 +There are cases where the desired end condition could not be achieved +using the +.IR chgrp +and +.IR chown +(that only changed the user ID) utilities. (If the current owner is not +a member of the desired group and the desired owner is not a member of +the current group, the +\fIchown\fR() +function could fail unless both owner and group are changed at the same +time.) +.IP " *" 4 +Even if they could be changed independently, in cases where both are +being changed, there is a 100% performance penalty caused by being +forced to invoke both utilities. +.P +The BSD syntax +.IR user [.\c +.IR group ] +was changed to +.IR user [:\c +.IR group ] +in this volume of POSIX.1\(hy2008 because the + +is a valid character in login names (as specified by the Base Definitions volume of POSIX.1\(hy2008, login +names consist of characters in the portable filename character set). The + +character was chosen as the replacement for the + +character because it would never be allowed as a character in a user +name or group name on historical implementations. +.P +The +.BR \(miR +option is considered by some observers as an undesirable departure from +the historical UNIX system tools approach; since a tool, +.IR find , +already exists to recurse over directories, there seemed to be no good +reason to require other tools to have to duplicate that functionality. +However, the +.BR \(miR +option was deemed an important user convenience, is far more efficient +than forking a separate process for each element of the directory +hierarchy, and is in widespread historical use. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchgrp\fR\^", +.IR "\fIchmod\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIchown\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/cksum.1p b/man-pages-posix-2013/man1p/cksum.1p new file mode 100644 index 0000000..718ec6a --- /dev/null +++ b/man-pages-posix-2013/man1p/cksum.1p @@ -0,0 +1,373 @@ +'\" et +.TH CKSUM "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cksum +\(em write file checksums and sizes +.SH SYNOPSIS +.LP +.nf +cksum \fB[\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR cksum +utility shall calculate and write to standard output a cyclic +redundancy check (CRC) for each input file, and also write to standard +output the number of octets in each file. The CRC used is based on the +polynomial used for CRC error checking in the ISO/IEC\ 8802\(hy3:\|1996 standard (Ethernet). +.P +The encoding for the CRC checksum is defined by the generating +polynomial: +.sp +.RS 4 +.nf +\fB +\fIG\fR(\fIx\fR)=\fIx\fR\u\s-332\s+3\d+\fIx\fR\u\s-326\s+3\d+\fIx\fR\u\s-323\s+3\d+\fIx\fR\u\s-322\s+3\d+\fIx\fR\u\s-316\s+3\d+\fIx\fR\u\s-312\s+3\d+\fIx\fR\u\s-311\s+3\d+\fIx\fR\u\s-310\s+3\d+\fIx\fR\u\s-38\s+3\d+\fIx\fR\u\s-37\s+3\d+\fIx\fR\u\s-35\s+3\d+\fIx\fR\u\s-34\s+3\d+\fIx\fR\u\s-32\s+3\d+\fIx\fR+1 +.fi \fR +.P +.RE +.P +Mathematically, the CRC value corresponding to a given file shall be +defined by the following procedure: +.IP " 1." 4 +The +.IR n +bits to be evaluated are considered to be the coefficients of a mod 2 +polynomial +.IR M (\c +.IR x ) +of degree +.IR n \(mi1. +These +.IR n +bits are the bits from the file, with the most significant bit being +the most significant bit of the first octet of the file and the last +bit being the least significant bit of the last octet, padded with zero +bits (if necessary) to achieve an integral number of octets, followed +by one or more octets representing the length of the file as a binary +value, least significant octet first. The smallest number of octets +capable of representing this integer shall be used. +.IP " 2." 4 +.IR M (\c +.IR x ) +is multiplied by +.IR x \u\s-332\s+3\d +(that is, shifted left 32 bits) and divided by +.IR G (\c +.IR x ) +using mod 2 division, producing a remainder +.IR R (\c +.IR x ) +of degree \(<= 31. +.IP " 3." 4 +The coefficients of +.IR R (\c +.IR x ) +are considered to be a 32-bit sequence. +.IP " 4." 4 +The bit sequence is complemented and the result is the CRC. +.SH OPTIONS +None. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file to be checked. If no +.IR file +operands are specified, the standard input shall be used. +.SH STDIN +The standard input shall be used if no +.IR file +operands are specified, and shall be used if a +.IR file +operand is +.BR '\(mi' +and the implementation treats the +.BR '\(mi' +as meaning standard input. +Otherwise, the standard input shall not be used. +See the INPUT FILES section. +.SH "INPUT FILES" +The input files can be any file type. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR cksum : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +For each file processed successfully, the +.IR cksum +utility shall write in the following format: +.sp +.RS 4 +.nf +\fB +"%u %d %s\en", <\fIchecksum\fR>, <\fI# of octets\fR>, <\fIpathname\fR> +.fi \fR +.P +.RE +.P +If no +.IR file +operand was specified, the pathname and its leading + +shall be omitted. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All files were processed successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR cksum +utility is typically used to quickly compare a suspect file against a +trusted version of the same, such as to ensure that files transmitted +over noisy media arrive intact. However, this comparison cannot be +considered cryptographically secure. The chances of a damaged file +producing the same CRC as the original are small; deliberate deception +is difficult, but probably not impossible. +.P +Although input files to +.IR cksum +can be any type, the results need not be what would be expected on +character special device files or on file types not described by the +System Interfaces volume of POSIX.1\(hy2008. Since this volume of POSIX.1\(hy2008 does not specify the block size used when doing +input, checksums of character special files need not process all of the +data in those files. +.P +The algorithm is expressed in terms of a bitstream divided into octets. +If a file is transmitted between two systems and undergoes any data +transformation (such as changing little-endian byte ordering to +big-endian), identical CRC values cannot be expected. Implementations +performing such transformations may extend +.IR cksum +to handle such situations. +.SH EXAMPLES +None. +.SH RATIONALE +The following C-language program can be used as a model to describe the +algorithm. It assumes that a +.BR char +is one octet. It also assumes that the entire file is available for one +pass through the function. This was done for simplicity in +demonstrating the algorithm, rather than as an implementation model. +.sp +.RS 4 +.nf +\fB +static unsigned long crctab[] = { +0x00000000, +0x04c11db7, 0x09823b6e, 0x0d4326d9, 0x130476dc, 0x17c56b6b, +0x1a864db2, 0x1e475005, 0x2608edb8, 0x22c9f00f, 0x2f8ad6d6, +0x2b4bcb61, 0x350c9b64, 0x31cd86d3, 0x3c8ea00a, 0x384fbdbd, +0x4c11db70, 0x48d0c6c7, 0x4593e01e, 0x4152fda9, 0x5f15adac, +0x5bd4b01b, 0x569796c2, 0x52568b75, 0x6a1936c8, 0x6ed82b7f, +0x639b0da6, 0x675a1011, 0x791d4014, 0x7ddc5da3, 0x709f7b7a, +0x745e66cd, 0x9823b6e0, 0x9ce2ab57, 0x91a18d8e, 0x95609039, +0x8b27c03c, 0x8fe6dd8b, 0x82a5fb52, 0x8664e6e5, 0xbe2b5b58, +0xbaea46ef, 0xb7a96036, 0xb3687d81, 0xad2f2d84, 0xa9ee3033, +0xa4ad16ea, 0xa06c0b5d, 0xd4326d90, 0xd0f37027, 0xddb056fe, +0xd9714b49, 0xc7361b4c, 0xc3f706fb, 0xceb42022, 0xca753d95, +0xf23a8028, 0xf6fb9d9f, 0xfbb8bb46, 0xff79a6f1, 0xe13ef6f4, +0xe5ffeb43, 0xe8bccd9a, 0xec7dd02d, 0x34867077, 0x30476dc0, +0x3d044b19, 0x39c556ae, 0x278206ab, 0x23431b1c, 0x2e003dc5, +0x2ac12072, 0x128e9dcf, 0x164f8078, 0x1b0ca6a1, 0x1fcdbb16, +0x018aeb13, 0x054bf6a4, 0x0808d07d, 0x0cc9cdca, 0x7897ab07, +0x7c56b6b0, 0x71159069, 0x75d48dde, 0x6b93dddb, 0x6f52c06c, +0x6211e6b5, 0x66d0fb02, 0x5e9f46bf, 0x5a5e5b08, 0x571d7dd1, +0x53dc6066, 0x4d9b3063, 0x495a2dd4, 0x44190b0d, 0x40d816ba, +0xaca5c697, 0xa864db20, 0xa527fdf9, 0xa1e6e04e, 0xbfa1b04b, +0xbb60adfc, 0xb6238b25, 0xb2e29692, 0x8aad2b2f, 0x8e6c3698, +0x832f1041, 0x87ee0df6, 0x99a95df3, 0x9d684044, 0x902b669d, +0x94ea7b2a, 0xe0b41de7, 0xe4750050, 0xe9362689, 0xedf73b3e, +0xf3b06b3b, 0xf771768c, 0xfa325055, 0xfef34de2, 0xc6bcf05f, +0xc27dede8, 0xcf3ecb31, 0xcbffd686, 0xd5b88683, 0xd1799b34, +0xdc3abded, 0xd8fba05a, 0x690ce0ee, 0x6dcdfd59, 0x608edb80, +0x644fc637, 0x7a089632, 0x7ec98b85, 0x738aad5c, 0x774bb0eb, +0x4f040d56, 0x4bc510e1, 0x46863638, 0x42472b8f, 0x5c007b8a, +0x58c1663d, 0x558240e4, 0x51435d53, 0x251d3b9e, 0x21dc2629, +0x2c9f00f0, 0x285e1d47, 0x36194d42, 0x32d850f5, 0x3f9b762c, +0x3b5a6b9b, 0x0315d626, 0x07d4cb91, 0x0a97ed48, 0x0e56f0ff, +0x1011a0fa, 0x14d0bd4d, 0x19939b94, 0x1d528623, 0xf12f560e, +0xf5ee4bb9, 0xf8ad6d60, 0xfc6c70d7, 0xe22b20d2, 0xe6ea3d65, +0xeba91bbc, 0xef68060b, 0xd727bbb6, 0xd3e6a601, 0xdea580d8, +0xda649d6f, 0xc423cd6a, 0xc0e2d0dd, 0xcda1f604, 0xc960ebb3, +0xbd3e8d7e, 0xb9ff90c9, 0xb4bcb610, 0xb07daba7, 0xae3afba2, +0xaafbe615, 0xa7b8c0cc, 0xa379dd7b, 0x9b3660c6, 0x9ff77d71, +0x92b45ba8, 0x9675461f, 0x8832161a, 0x8cf30bad, 0x81b02d74, +0x857130c3, 0x5d8a9099, 0x594b8d2e, 0x5408abf7, 0x50c9b640, +0x4e8ee645, 0x4a4ffbf2, 0x470cdd2b, 0x43cdc09c, 0x7b827d21, +0x7f436096, 0x7200464f, 0x76c15bf8, 0x68860bfd, 0x6c47164a, +0x61043093, 0x65c52d24, 0x119b4be9, 0x155a565e, 0x18197087, +0x1cd86d30, 0x029f3d35, 0x065e2082, 0x0b1d065b, 0x0fdc1bec, +0x3793a651, 0x3352bbe6, 0x3e119d3f, 0x3ad08088, 0x2497d08d, +0x2056cd3a, 0x2d15ebe3, 0x29d4f654, 0xc5a92679, 0xc1683bce, +0xcc2b1d17, 0xc8ea00a0, 0xd6ad50a5, 0xd26c4d12, 0xdf2f6bcb, +0xdbee767c, 0xe3a1cbc1, 0xe760d676, 0xea23f0af, 0xeee2ed18, +0xf0a5bd1d, 0xf464a0aa, 0xf9278673, 0xfde69bc4, 0x89b8fd09, +0x8d79e0be, 0x803ac667, 0x84fbdbd0, 0x9abc8bd5, 0x9e7d9662, +0x933eb0bb, 0x97ffad0c, 0xafb010b1, 0xab710d06, 0xa6322bdf, +0xa2f33668, 0xbcb4666d, 0xb8757bda, 0xb5365d03, 0xb1f740b4 +}; +.P +unsigned long memcrc(const unsigned char *b, size_t n) +{ +/* Input arguments: + * const unsigned char* b == byte sequence to checksum + * size_t n == length of sequence + */ +.P + register size_t i; + register unsigned c, s = 0; +.P + for (i = n; i > 0; \(mi\|\(mii) { + c = *b++; + s = (s << 8) ^ crctab[(s >> 24) ^ c]; + } +.P + /* Extend with the length of the string. */ + while (n != 0) { + c = n & 0377; + n >>= 8; + s = (s << 8) ^ crctab[(s >> 24) ^ c]; + } +.P + return ~s; +} +.fi \fR +.P +.RE +.P +The historical practice of writing the number of ``blocks'' has been +changed to writing the number of octets, since the latter is not only +more useful, but also since historical implementations have not been +consistent in defining what a ``block'' meant. +.P +The algorithm used was selected to increase the operational robustness +of +.IR cksum . +Neither the System V nor BSD +.IR sum +algorithm was selected. Since each of these was different and each was +the default behavior on those systems, no realistic compromise was +available if either were selected\(emsome set of historical +applications would break. Therefore, the name was changed to +.IR cksum . +Although the historical +.IR sum +commands will probably continue to be provided for many years, programs +designed for portability across systems should use the new name. +.P +The algorithm selected is based on that used by the ISO/IEC\ 8802\(hy3:\|1996 standard (Ethernet) +for the frame check sequence field. The algorithm used does not match +the technical definition of a +.IR checksum ; +the term is used for historical reasons. The length of the file is +included in the CRC calculation because this parallels inclusion of a +length field by Ethernet in its CRC, but also because it guards against +inadvertent collisions between files that begin with different series +of zero octets. The chance that two different files produce identical +CRCs is much greater when their lengths are not considered. Keeping the +length and the checksum of the file itself separate would yield a +slightly more robust algorithm, but historical usage has always been +that a single number (the checksum as printed) represents the signature +of the file. It was decided that historical usage was the more +important consideration. +.P +Early proposals contained modifications to the Ethernet algorithm that +involved extracting table values whenever an intermediate result became +zero. This was demonstrated to be less robust than the current method +and mathematically difficult to describe or justify. +.P +The calculation used is identical to that given in pseudo-code in the +referenced Sarwate article. The pseudo-code rendition is: +.sp +.RS 4 +.nf +\fB +X <\(mi 0; Y <\(mi 0; +for i <\(mi m \(mi1 step \(mi1 until 0 do + begin + T <\(mi X(1) ^ A[i]; + X(1) <\(mi X(0); X(0) <\(mi Y(1); Y(1) <\(mi Y(0); Y(0) <\(mi 0; + comment: f[T] and f'[T] denote the T-th words in the + table f and f' ; + X <\(mi X ^ f[T]; Y <\(mi Y ^ f'[T]; + end +.fi \fR +.P +.RE +.P +The pseudo-code is reproduced exactly as given; however, note that in +the case of +.IR cksum , +.BR A[i] +represents a byte of the file, the words +.BR X +and +.BR Y +are treated as a single 32-bit value, and the tables +.BR f +and +.BR f' +are a single table containing 32-bit values. +.P +The referenced Sarwate article also discusses generating the table. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/cmp.1p b/man-pages-posix-2013/man1p/cmp.1p new file mode 100644 index 0000000..1157d60 --- /dev/null +++ b/man-pages-posix-2013/man1p/cmp.1p @@ -0,0 +1,269 @@ +'\" et +.TH CMP "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cmp +\(em compare two files +.SH SYNOPSIS +.LP +.nf +cmp \fB[\fR\(mil|\(mis\fB] \fIfile1 file2\fR +.fi +.SH DESCRIPTION +The +.IR cmp +utility shall compare two files. The +.IR cmp +utility shall write no output if the files are the same. Under default +options, if they differ, it shall write to standard output the byte and +line number at which the first difference occurred. Bytes and lines +shall be numbered beginning with 1. +.SH OPTIONS +The +.IR cmp +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mil\fP" 10 +(Lowercase ell.) Write the byte number (decimal) and the differing +bytes (octal) for each difference. +.IP "\fB\(mis\fP" 10 +Write nothing for differing files; return exit status only. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile1\fR" 10 +A pathname of the first file to be compared. If +.IR file1 +is +.BR '\(mi' , +the standard input shall be used. +.IP "\fIfile2\fR" 10 +A pathname of the second file to be compared. If +.IR file2 +is +.BR '\(mi' , +the standard input shall be used. +.P +If both +.IR file1 +and +.IR file2 +refer to standard input or refer to the same FIFO special, block +special, or character special file, the results are undefined. +.SH STDIN +The standard input shall be used only if the +.IR file1 +or +.IR file2 +operand refers to standard input. See the INPUT FILES section. +.SH "INPUT FILES" +The input files can be any file type. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR cmp : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +In the POSIX locale, results of the comparison shall be written to +standard output. When no options are used, the format shall be: +.sp +.RS 4 +.nf +\fB +"%s %s differ: char %d, line %d\en", \fIfile1\fR, \fIfile2\fR, + <\fIbyte number\fR>, <\fIline number\fR> +.fi \fR +.P +.RE +.P +When the +.BR \(mil +option is used, the format shall be: +.sp +.RS 4 +.nf +\fB +"%d %o %o\en", <\fIbyte number\fR>, <\fIdiffering byte\fR>, + <\fIdiffering byte\fR> +.fi \fR +.P +.RE +.P +for each byte that differs. The first <\fIdiffering\ byte\fP> number is +from +.IR file1 +while the second is from +.IR file2 . +In both cases, <\fIbyte\ number\fP> shall be relative to the beginning +of the file, beginning with 1. +.P +No output shall be written to standard output when the +.BR \(mis +option is used. +.SH STDERR +The standard error shall be used only for diagnostic messages. If the +.BR \(mil +option is used and +.IR file1 +and +.IR file2 +differ in length, or if the +.BR \(mis +option is not used and +.IR file1 +and +.IR file2 +are identical for the entire length of the shorter file, in the POSIX +locale the following diagnostic message shall be written: +.sp +.RS 4 +.nf +\fB +"cmp: EOF on %s%s\en", <\fIname of shorter file\fR>, <\fIadditional info\fR> +.fi \fR +.P +.RE +.P +The <\fIadditional\ info\fP> field shall either be null or a string +that starts with a + +and contains no + +characters. Some implementations report on the number of lines in +this case. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The files are identical. +.IP "\01" 6 +The files are different; this includes the case where one file is +identical to the first part of the other. +.IP >1 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Although input files to +.IR cmp +can be any type, the results might not be what would be expected on +character special device files or on file types not described by the +System Interfaces volume of POSIX.1\(hy2008. Since this volume of POSIX.1\(hy2008 does not specify the block size used when doing +input, comparisons of character special files need not compare all of +the data in those files. +.P +For files which are not text files, line numbers simply reflect the +presence of a +, +without any implication that the file is organized into lines. +.SH EXAMPLES +None. +.SH RATIONALE +The global language in +.IR "Section 1.4" ", " "Utility Description Defaults" +indicates that using two mutually-exclusive options together produces +unspecified results. Some System V implementations consider the option +usage: +.sp +.RS 4 +.nf +\fB +cmp \(mil \(mis ... +.fi \fR +.P +.RE +.P +to be an error. They also treat: +.sp +.RS 4 +.nf +\fB +cmp \(mis \(mil ... +.fi \fR +.P +.RE +.P +as if no options were specified. Both of these behaviors are +considered bugs, but are allowed. +.P +The word +.BR char +in the standard output format comes from historical usage, even though +it is actually a byte number. When +.IR cmp +is supported in other locales, implementations are encouraged to use +the word +.IR byte +or its equivalent in another language. Users should not interpret this +difference to indicate that the functionality of the utility changed +between locales. +.P +Some implementations report on the number of lines in the +identical-but-shorter file case. This is allowed by the inclusion of +the <\fIadditional\ info\fP> fields in the output format. The +restriction on having a leading + +and no + +characters is to make parsing for the filename easier. It is recognized +that some filenames containing white-space characters make parsing +difficult anyway, but the restriction does aid programs used on systems +where the names are predominantly well behaved. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcomm\fR\^", +.IR "\fIdiff\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/colon.1p b/man-pages-posix-2013/man1p/colon.1p new file mode 100644 index 0000000..0a4d835 --- /dev/null +++ b/man-pages-posix-2013/man1p/colon.1p @@ -0,0 +1,104 @@ +'\" et +.TH COLON "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +colon +\(em null utility +.SH SYNOPSIS +.LP +.nf +: \fB[\fIargument\fR...\fB]\fR +.fi +.SH DESCRIPTION +This utility shall only expand command +.IR argument s. +It is used when a command is needed, as in the +.BR then +condition of an +.BR if +command, but nothing is to be done by the command. +.SH OPTIONS +None. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +Zero. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +.LP +.nf +: ${X=abc} +if false +then : +else echo $X +fi +\fBabc\fR +.fi +.P +As with any of the special built-ins, the null utility can also have +variable assignments and redirections associated with it, such as: +.sp +.RS 4 +.nf +\fB +x=y : > z +.fi \fR +.P +.RE +.P +which sets variable +.IR x +to the value +.IR y +(so that it persists after the null utility completes) and creates or +truncates file +.BR z . +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/comm.1p b/man-pages-posix-2013/man1p/comm.1p new file mode 100644 index 0000000..86f4ed8 --- /dev/null +++ b/man-pages-posix-2013/man1p/comm.1p @@ -0,0 +1,287 @@ +'\" et +.TH COMM "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +comm +\(em select or reject lines common to two files +.SH SYNOPSIS +.LP +.nf +comm \fB[\fR\(mi123\fB] \fIfile1 file2\fR +.fi +.SH DESCRIPTION +The +.IR comm +utility shall read +.IR file1 +and +.IR file2 , +which should be ordered in the current collating sequence, and produce +three text columns as output: lines only in +.IR file1 , +lines only in +.IR file2 , +and lines in both files. +.P +If the lines in both files are not ordered according to the collating +sequence of the current locale, the results are unspecified. +.SH OPTIONS +The +.IR comm +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mi1\fP" 10 +Suppress the output column of lines unique to +.IR file1 . +.IP "\fB\(mi2\fP" 10 +Suppress the output column of lines unique to +.IR file2 . +.IP "\fB\(mi3\fP" 10 +Suppress the output column of lines duplicated in +.IR file1 +and +.IR file2 . +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile1\fR" 10 +A pathname of the first file to be compared. If +.IR file1 +is +.BR '\(mi' , +the standard input shall be used. +.IP "\fIfile2\fR" 10 +A pathname of the second file to be compared. If +.IR file2 +is +.BR '\(mi' , +the standard input shall be used. +.P +If both +.IR file1 +and +.IR file2 +refer to standard input or to the same FIFO special, block special, or +character special file, the results are undefined. +.SH STDIN +The standard input shall be used only if one of the +.IR file1 +or +.IR file2 +operands refers to standard input. See the INPUT FILES section. +.SH "INPUT FILES" +The input files shall be text files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR comm : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the collating sequence +.IR comm +expects to have been used when the input files were sorted. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR comm +utility shall produce output depending on the options selected. If the +.BR \(mi1 , +.BR \(mi2 , +and +.BR \(mi3 +options are all selected, +.IR comm +shall write nothing to standard output. +.P +If the +.BR \(mi1 +option is not selected, lines contained only in +.IR file1 +shall be written using the format: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIline in file1\fR> +.fi \fR +.P +.RE +.P +If the +.BR \(mi2 +option is not selected, lines contained only in +.IR file2 +are written using the format: +.sp +.RS 4 +.nf +\fB +"%s%s\en", <\fIlead\fR>, <\fIline in file2\fR> +.fi \fR +.P +.RE +.P +where the string <\fIlead\fP> is as follows: +.IP 10 +The +.BR \(mi1 +option is not selected. +.IP "null\ string" 10 +The +.BR \(mi1 +option is selected. +.P +If the +.BR \(mi3 +option is not selected, lines contained in both files shall be written +using the format: +.sp +.RS 4 +.nf +\fB +"%s%s\en", <\fIlead\fR>, <\fIline in both\fR> +.fi \fR +.P +.RE +.P +where the string <\fIlead\fP> is as follows: +.IP 10 +Neither the +.BR \(mi1 +nor the +.BR \(mi2 +option is selected. +.IP 10 +Exactly one of the +.BR \(mi1 +and +.BR \(mi2 +options is selected. +.IP "null\ string" 10 +Both the +.BR \(mi1 +and +.BR \(mi2 +options are selected. +.P +If the input files were ordered according to the collating sequence of +the current locale, the lines written shall be in the collating +sequence of the original lines. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All input files were successfully output as specified. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +If the input files are not properly presorted, the output of +.IR comm +might not be useful. +.SH EXAMPLES +If a file named +.BR xcu +contains a sorted list of the utilities in this volume of POSIX.1\(hy2008, a file named +.BR xpg3 +contains a sorted list of the utilities specified in the X/Open +Portability Guide, Issue 3, and a file named +.BR svid89 +contains a sorted list of the utilities in the System V Interface +Definition Third Edition: +.sp +.RS 4 +.nf +\fB +comm \(mi23 xcu xpg3 | comm \(mi23 \(mi svid89 +.fi \fR +.P +.RE +.P +would print a list of utilities in this volume of POSIX.1\(hy2008 not specified by either of the +other documents: +.sp +.RS 4 +.nf +\fB +comm \(mi12 xcu xpg3 | comm \(mi12 \(mi svid89 +.fi \fR +.P +.RE +.P +would print a list of utilities specified by all three documents, and: +.sp +.RS 4 +.nf +\fB +comm \(mi12 xpg3 svid89 | comm \(mi23 \(mi xcu +.fi \fR +.P +.RE +.P +would print a list of utilities specified by both XPG3 and the SVID, +but not specified in this volume of POSIX.1\(hy2008. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcmp\fR\^", +.IR "\fIdiff\fR\^", +.IR "\fIsort\fR\^", +.IR "\fIuniq\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/command.1p b/man-pages-posix-2013/man1p/command.1p new file mode 100644 index 0000000..c8683a2 --- /dev/null +++ b/man-pages-posix-2013/man1p/command.1p @@ -0,0 +1,560 @@ +'\" et +.TH COMMAND "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +command +\(em execute a simple command +.SH SYNOPSIS +.LP +.nf +command \fB[\fR\(mip\fB] \fIcommand_name \fB[\fIargument\fR...\fB]\fR +.P +command \fB[\fR\(mip\fB][\fR\(miv|\(miV\fB] \fIcommand_name\fR +.fi +.SH DESCRIPTION +The +.IR command +utility shall cause the shell to treat the arguments as a simple +command, suppressing the shell function lookup that is described in +.IR "Section 2.9.1.1" ", " "Command Search and Execution", +item 1b. +.P +If the +.IR command_name +is the same as the name of one of the special built-in utilities, the +special properties in the enumerated list at the beginning of +.IR "Section 2.14" ", " "Special Built-In Utilities" +shall not occur. In every other respect, if +.IR command_name +is not the name of a function, the effect of +.IR command +(with no options) shall be the same as omitting +.IR command . +.P +When the +.BR \(miv +or +.BR \(miV +option is used, the +.IR command +utility shall provide information concerning how a command name +is interpreted by the shell. +.SH OPTIONS +The +.IR command +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mip\fP" 10 +Perform the command search using a default value for +.IR PATH +that is guaranteed to find all of the standard utilities. +.IP "\fB\(miv\fP" 10 +Write a string to standard output that indicates the pathname or command +that will be used by the shell, in the current shell execution environment +(see +.IR "Section 2.12" ", " "Shell Execution Environment"), +to invoke +.IR command_name , +but do not invoke +.IR command_name . +.RS 10 +.IP " *" 4 +Utilities, regular built-in utilities, +.IR command_name s +including a + +character, and any implementation-defined functions that are found +using the +.IR PATH +variable (as described in +.IR "Section 2.9.1.1" ", " "Command Search and Execution"), +shall be written as absolute pathnames. +.IP " *" 4 +Shell functions, special built-in utilities, regular built-in utilities +not associated with a +.IR PATH +search, and shell reserved words shall be written as just their names. +.IP " *" 4 +An alias shall be written as a command line that represents its alias +definition. +.IP " *" 4 +Otherwise, no output shall be written and the exit status shall reflect +that the name was not found. +.RE +.IP "\fB\(miV\fP" 10 +Write a string to standard output that indicates how the name given in the +.IR command_name +operand will be interpreted by the shell, in the current shell +execution environment (see +.IR "Section 2.12" ", " "Shell Execution Environment"), +but do not invoke +.IR command_name . +Although the format of this string is unspecified, it shall indicate in +which of the following categories +.IR command_name +falls and shall include the information stated: +.RS 10 +.IP " *" 4 +Utilities, regular built-in utilities, and any implementation-defined +functions that are found using the +.IR PATH +variable (as described in +.IR "Section 2.9.1.1" ", " "Command Search and Execution"), +shall be identified as such and include the absolute pathname in the +string. +.IP " *" 4 +Other shell functions shall be identified as functions. +.IP " *" 4 +Aliases shall be identified as aliases and their definitions +included in the string. +.IP " *" 4 +Special built-in utilities shall be identified as special built-in +utilities. +.IP " *" 4 +Regular built-in utilities not associated with a +.IR PATH +search shall be identified as regular built-in utilities. (The term +``regular'' need not be used.) +.IP " *" 4 +Shell reserved words shall be identified as reserved words. +.RE +.SH OPERANDS +The following operands shall be supported: +.IP "\fIargument\fR" 10 +One of the strings treated as an argument to +.IR command_name . +.IP "\fIcommand_name\fR" 10 +.br +The name of a utility or a special built-in utility. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR command : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPATH\fP" 10 +Determine the search path used during the command search described in +.IR "Section 2.9.1.1" ", " "Command Search and Execution", +except as described under the +.BR \(mip +option. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +When the +.BR \(miv +option is specified, standard output shall be formatted as: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIpathname or command\fR> +.fi \fR +.P +.RE +.P +When the +.BR \(miV +option is specified, standard output shall be formatted as: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIunspecified\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +When the +.BR \(miv +or +.BR \(miV +options are specified, the following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +The +.IR command_name +could not be found or an error occurred. +.P +Otherwise, the following exit values shall be returned: +.IP 126 6 +The utility specified by +.IR command_name +was found but could not be invoked. +.IP 127 6 +An error occurred in the +.IR command +utility or the utility specified by +.IR command_name +could not be found. +.P +Otherwise, the exit status of +.IR command +shall be that of the simple command specified by the arguments to +.IR command . +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The order for command search allows functions to override regular +built-ins and path searches. This utility is necessary to allow +functions that have the same name as a utility to call the utility +(instead of a recursive call to the function). +.P +The system default path is available using +.IR getconf ; +however, since +.IR getconf +may need to have the +.IR PATH +set up before it can be called itself, the following can be used: +.sp +.RS 4 +.nf +\fB +command \(mip getconf PATH +.fi \fR +.P +.RE +.P +There are some advantages to suppressing the special characteristics of +special built-ins on occasion. For example: +.sp +.RS 4 +.nf +\fB +command exec > \fIunwritable-file\fR +.fi \fR +.P +.RE +.P +does not cause a non-interactive script to abort, so that the output +status can be checked by the script. +.P +The +.IR command , +.IR env , +.IR nohup , +.IR time , +and +.IR xargs +utilities have been specified to use exit code 127 if an error occurs +so that applications can distinguish ``failure to find a utility'' from +``invoked utility exited with an error indication''. The value 127 was +chosen because it is not commonly used for other meanings; most +utilities use small values for ``normal error conditions'' and the +values above 128 can be confused with termination due to receipt of a +signal. The value 126 was chosen in a similar manner to indicate that +the utility could be found, but not invoked. Some scripts produce +meaningful error messages differentiating the 126 and 127 cases. The +distinction between exit codes 126 and 127 is based on KornShell +practice that uses 127 when all attempts to +.IR exec +the utility fail with +.BR [ENOENT] , +and uses 126 when any attempt to +.IR exec +the utility fails for any other reason. +.P +Since the +.BR \(miv +and +.BR \(miV +options of +.IR command +produce output in relation to the current shell execution environment, +.IR command +is generally provided as a shell regular built-in. If it is called in a +subshell or separate utility execution environment, such as one of the +following: +.sp +.RS 4 +.nf +\fB +(PATH=foo command \(miv) + nohup command \(miv +.fi \fR +.P +.RE +.P +it does not necessarily produce correct results. For example, when +called with +.IR nohup +or an +.IR exec +function, in a separate utility execution environment, most +implementations are not able to identify aliases, functions, or special +built-ins. +.P +Two types of regular built-ins could be encountered on a system and +these are described separately by +.IR command . +The description of command search in +.IR "Section 2.9.1.1" ", " "Command Search and Execution" +allows for a standard utility to be implemented as a regular built-in +as long as it is found in the appropriate place in a +.IR PATH +search. So, for example, +.IR command +.BR \(miv +.IR true +might yield +.BR /bin/true +or some similar pathname. Other implementation-defined utilities that +are not defined by this volume of POSIX.1\(hy2008 might exist only as built-ins and have no +pathname associated with them. These produce output identified as +(regular) built-ins. Applications encountering these are not able to +count on +.IR exec ing +them, using them with +.IR nohup , +overriding them with a different +.IR PATH , +and so on. +.SH EXAMPLES +.IP " 1." 4 +Make a version of +.IR cd +that always prints out the new working directory exactly once: +.RS 4 +.sp +.RS 4 +.nf +\fB +cd() { + command cd "$@" >/dev/null + pwd +} +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +Start off a ``secure shell script'' in which the script avoids +being spoofed by its parent: +.RS 4 +.sp +.RS 4 +.nf +\fB +IFS=' +\&' +# The preceding value should be . +# Set IFS to its default value. +.P +\eunalias \(mia +# Unset all possible aliases. +# Note that unalias is escaped to prevent an alias +# being used for unalias. +.P +unset \(mif command +# Ensure command is not a user function. +.P +PATH="$(command \(mip getconf PATH):$PATH" +# Put on a reliable PATH prefix. +.P +# ... +.fi \fR +.P +.RE +.P +At this point, given correct permissions on the directories called by +.IR PATH , +the script has the ability to ensure that any utility it calls is the +intended one. It is being very cautious because it assumes that +implementation extensions may be present that would allow user +functions to exist when it is invoked; this capability is not specified +by this volume of POSIX.1\(hy2008, but it is not prohibited as an extension. For example, the +.IR ENV +variable precedes the invocation of the script with a user start-up +script. Such a script could define functions to spoof the application. +.RE +.SH RATIONALE +Since +.IR command +is a regular built-in utility it is always found prior to the +.IR PATH +search. +.P +There is nothing in the description of +.IR command +that implies the command line is parsed any differently from that of +any other simple command. For example: +.sp +.RS 4 +.nf +\fB +command a | b ; c +.fi \fR +.P +.RE +.P +is not parsed in any special way that causes +.BR '|' +or +.BR ';' +to be treated other than a pipe operator or + +or that prevents function lookup on +.BR b +or +.BR c . +.P +The +.IR command +utility is somewhat similar to the Eighth Edition shell +.IR builtin +command, but since +.IR command +also goes to the file system to search for utilities, the name +.IR builtin +would not be intuitive. +.P +The +.IR command +utility is most likely to be provided as a regular built-in. It is not +listed as a special built-in +for the following reasons: +.IP " *" 4 +The removal of exportable functions made the special precedence of a +special built-in unnecessary. +.IP " *" 4 +A special built-in has special properties (see +.IR "Section 2.14" ", " "Special Built-In Utilities") +that were inappropriate for invoking other utilities. For example, two +commands such as: +.RS 4 +.sp +.RS 4 +.nf +\fB +date > \fIunwritable-file\fR +.P +command date > \fIunwritable-file\fR +.fi \fR +.P +.RE +.P +would have entirely different results; in a non-interactive script, the +former would continue to execute the next command, the latter would +abort. Introducing this semantic difference along with suppressing +functions was seen to be non-intuitive. +.RE +.P +The +.BR \(mip +option is present because it is useful to be able to ensure a safe path +search that finds all the standard utilities. This search might not be +identical to the one that occurs through one of the +.IR exec +functions (as defined in the System Interfaces volume of POSIX.1\(hy2008) when +.IR PATH +is unset. At the very least, this feature is required to allow the +script to access the correct version of +.IR getconf +so that the value of the default path can be accurately retrieved. +.P +The +.IR command +.BR \(miv +and +.BR \(miV +options were added to satisfy requirements from users that are +currently accomplished by three different historical utilities: +.IR type +in the System V shell, +.IR whence +in the KornShell, and +.IR which +in the C shell. Since there is no historical agreement on how and what +to accomplish here, the POSIX +.IR command +utility was enhanced and the historical utilities were left unmodified. +The C shell +.IR which +merely conducts a path search. The KornShell +.IR whence +is more elaborate\(emin addition to the categories required by POSIX, +it also reports on tracked aliases, exported aliases, and undefined +functions. +.P +The output format of +.BR \(miV +was left mostly unspecified because human users are its only audience. +Applications should not be written to care about this information; they +can use the output of +.BR \(miv +to differentiate between various types of commands, but the additional +information that may be emitted by the more verbose +.BR \(miV +is not needed and should not be arbitrarily constrained in its +verbosity or localization for application parsing reasons. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.9.1.1" ", " "Command Search and Execution", +.IR "Section 2.12" ", " "Shell Execution Environment", +.IR "Section 2.14" ", " "Special Built-In Utilities", +.IR "\fIsh\fR\^", +.IR "\fItype\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIexec\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/compress.1p b/man-pages-posix-2013/man1p/compress.1p new file mode 100644 index 0000000..8ade608 --- /dev/null +++ b/man-pages-posix-2013/man1p/compress.1p @@ -0,0 +1,258 @@ +'\" et +.TH COMPRESS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +compress +\(em compress data +.SH SYNOPSIS +.LP +.nf +compress \fB[\fR\(mifv\fB] [\fR\(mib \fIbits\fB] [\fIfile\fR...\fB]\fR +.P +compress \fB[\fR\(micfv\fB] [\fR\(mib \fIbits\fB] [\fIfile\fB]\fR +.fi +.SH DESCRIPTION +The +.IR compress +utility shall attempt to reduce the size of the named files by using +adaptive Lempel-Ziv coding algorithm. +.TP 10 +.BR Note: +Lempel-Ziv is US Patent 4464650, issued to William Eastman, Abraham +Lempel, Jacob Ziv, Martin Cohn on August 7th, 1984, and assigned to +Sperry Corporation. +.RS 10 +.P +Lempel-Ziv-Welch compression is covered by US Patent 4558302, issued to +Terry A. Welch on December 10th, 1985, and assigned to Sperry +Corporation. +.RE +.P +On systems not supporting adaptive Lempel-Ziv coding algorithm, the +input files shall not be changed and an error value greater than two +shall be returned. Except when the output is to the standard output, +each file shall be replaced by one with the extension +.BR .Z . +If the invoking process has appropriate privileges, the ownership, +modes, access time, and modification time of the original file are +preserved. If appending the +.BR .Z +to the filename would make the name exceed +{NAME_MAX} +bytes, the command shall fail. If no files are specified, the standard +input shall be compressed to the standard output. +.SH OPTIONS +The +.IR compress +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mib\ \fIbits\fR" 10 +Specify the maximum number of bits to use in a code. For a conforming +application, the +.IR bits +argument shall be: +.RS 10 +.sp +.RS 4 +.nf +\fB +9 <= \fIbits\fP <= 14 +.fi \fR +.P +.RE +.P +The implementation may allow +.IR bits +values of greater than 14. The default is 14, 15, or 16. +.RE +.IP "\fB\(mic\fP" 10 +Cause +.IR compress +to write to the standard output; the input file is not changed, and no +.BR .Z +files are created. +.IP "\fB\(mif\fP" 10 +Force compression of +.IR file , +even if it does not actually reduce the size of the file, or if the +corresponding +.IR file \c +.BR .Z +file already exists. If the +.BR \(mif +option is not given, and the process is not running in the background, +the user is prompted as to whether an existing +.IR file \c +.BR .Z +file should be overwritten. If the response is affirmative, the existing +file will be overwritten. +.IP "\fB\(miv\fP" 10 +Write the percentage reduction of each file to standard error. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file to be compressed. +.SH STDIN +The standard input shall be used only if no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' . +.SH "INPUT FILES" +If +.IR file +operands are specified, the input files contain the data to be +compressed. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR compress : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements used in the extended regular +expression defined for the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of text +data as characters (for example, single-byte as opposed to multi-byte +characters in arguments), the behavior of character classes used in the +extended regular expression defined for the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale used to process affirmative responses, and the +locale used to affect the format and contents of diagnostic messages, +prompts, and the output from the +.BR \(miv +option written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' , +or if the +.BR \(mic +option is specified, the standard output contains the compressed +output. +.SH STDERR +The standard error shall be used only for diagnostic and prompt +messages and the output from +.BR \(miv . +.SH "OUTPUT FILES" +The output files shall contain the compressed output. The format of +compressed files is unspecified and interchange of such files between +implementations (including access via unspecified file sharing +mechanisms) is not required by POSIX.1\(hy2008. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP "\01" 6 +An error occurred. +.IP "\02" 6 +One or more files were not compressed because they would have increased +in size (and the +.BR \(mif +option was not specified). +.IP >2 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +The input file shall remain unmodified. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The amount of compression obtained depends on the size of the input, +the number of +.IR bits +per code, and the distribution of common substrings. Typically, text +such as source code or English is reduced by 50\(hy60%. Compression is +generally much better than that achieved by Huffman coding +or adaptive Huffman coding (\c +.IR compact ), +and takes less time to compute. +.P +Although +.IR compress +strictly follows the default actions upon receipt of a signal or when +an error occurs, some unexpected results may occur. In some +implementations it is likely that a partially compressed file is left +in place, alongside its uncompressed input file. Since the general +operation of +.IR compress +is to delete the uncompressed file only after the +.BR .Z +file has been successfully filled, an application should always +carefully check the exit status of +.IR compress +before arbitrarily deleting files that have like-named neighbors with +.BR .Z +suffixes. +.P +The limit of 14 on the +.IR bits +option-argument is to achieve portability to all systems (within the +restrictions imposed by the lack of an explicit published file +format). Some implementations based on 16-bit architectures cannot +support 15 or 16-bit uncompression. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIuncompress\fR\^", +.IR "\fIzcat\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/continue.1p b/man-pages-posix-2013/man1p/continue.1p new file mode 100644 index 0000000..c2cead3 --- /dev/null +++ b/man-pages-posix-2013/man1p/continue.1p @@ -0,0 +1,112 @@ +'\" et +.TH CONTINUE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +continue +\(em continue for, while, or until loop +.SH SYNOPSIS +.LP +.nf +continue \fB[\fIn\fB]\fR +.fi +.SH DESCRIPTION +The +.IR continue +utility shall return to the top of the smallest enclosing +.BR for , +.BR while , +or +.BR until +loop, or to the top of the +.IR n th +enclosing loop, if +.IR n +is specified. This involves repeating the condition list of a +.BR while +or +.BR until +loop or performing the next assignment of a +.BR for +loop, and re-executing the loop if appropriate. +.P +The value of +.IR n +is a decimal integer greater than or equal to 1. The default shall be +equivalent to +.IR n =1. +If +.IR n +is greater than the number of enclosing loops, the outermost enclosing +loop shall be used. +.SH OPTIONS +None. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +.IP "\00" 6 +Successful completion. +.IP >0 6 +The +.IR n +value was not an unsigned decimal integer greater than or equal to 1. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +.LP +.nf +for i in * +do + if test \(mid "$i" + then continue + fi + printf '"%s" is not a directory.\en' "$i" +done +.fi +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/cp.1p b/man-pages-posix-2013/man1p/cp.1p new file mode 100644 index 0000000..66193ad --- /dev/null +++ b/man-pages-posix-2013/man1p/cp.1p @@ -0,0 +1,806 @@ +'\" et +.TH CP "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cp +\(em copy files +.SH SYNOPSIS +.LP +.nf +cp \fB[\fR\(miPfip\fB] \fIsource_file target_file\fR +.P +cp \fB[\fR\(miPfip\fB] \fIsource_file\fR... \fItarget\fR +.P +cp \(miR \fB[\fR\(miH|\(miL|\(miP\fB] [\fR\(mifip\fB] \fIsource_file\fR... \fItarget\fR +.fi +.SH DESCRIPTION +The first synopsis form is denoted by two operands, neither of which +are existing files of type directory. The +.IR cp +utility shall copy the contents of +.IR source_file +(or, if +.IR source_file +is a file of type symbolic link, the contents of the file referenced by +.IR source_file ) +to the destination path named by +.IR target_file. +.P +The second synopsis form is denoted by two or more operands where the +.BR \(miR +option is not specified and the first synopsis form is not +applicable. It shall be an error if any +.IR source_file +is a file of type directory, if +.IR target +does not exist, or if +.IR target +does not name a directory. The +.IR cp +utility shall copy the contents of each +.IR source_file +(or, if +.IR source_file +is a file of type symbolic link, the contents of the file referenced by +.IR source_file ) +to the destination path named by the concatenation of +.IR target , +a single + +character if +.IR target +did not end in a +, +and the last component of +.IR source_file . +.P +The third synopsis form is denoted by two or more operands where the +.BR \(miR +option is specified. The +.IR cp +utility shall copy each file in the file hierarchy rooted in each +.IR source_file +to a destination path named as follows: +.IP " *" 4 +If +.IR target +exists and names an existing directory, the name of the corresponding +destination path for each file in the file hierarchy shall be the +concatenation of +.IR target , +a single + +character if +.IR target +did not end in a +, +and the pathname of the file relative to the directory containing +.IR source_file . +.IP " *" 4 +If +.IR target +does not exist and two operands are specified, the name of the +corresponding destination path for +.IR source_file +shall be +.IR target ; +the name of the corresponding destination path for all other files in +the file hierarchy shall be the concatenation of +.IR target , +a + +character, and the pathname of the file relative to +.IR source_file . +.P +It shall be an error if +.IR target +does not exist and more than two operands are specified, or if +.IR target +exists and does not name a directory. +.P +In the following description, the term +.IR dest_file +refers to the file named by the destination path. The term +.IR source_file +refers to the file that is being copied, whether specified as an +operand or a file in a file hierarchy rooted in a +.IR source_file +operand. If +.IR source_file +is a file of type symbolic link: +.IP " *" 4 +If the +.BR \(miR +option was not specified, +.IR cp +shall take actions based on the type and contents of the file referenced +by the symbolic link, and not by the symbolic link itself, unless the +.BR \(miP +option was specified. +.IP " *" 4 +If the +.BR \(miR +option was specified: +.RS 4 +.IP -- 4 +If none of the options +.BR \(miH , +.BR \(miL , +nor +.BR \(miP +were specified, it is unspecified which of +.BR \(miH , +.BR \(miL , +or +.BR \(miP +will be used as a default. +.IP -- 4 +If the +.BR \(miH +option was specified, +.IR cp +shall take actions based on the type and contents of the +file referenced by any symbolic link specified as a +.IR source_file +operand. +.IP -- 4 +If the +.BR \(miL +option was specified, +.IR cp +shall take actions based on the type and contents of the +file referenced by any symbolic link specified as a +.IR source_file +operand or any symbolic links encountered during traversal of a +file hierarchy. +.IP -- 4 +If the +.BR \(miP +option was specified, +.IR cp +shall copy any symbolic link specified as a +.IR source_file +operand and any symbolic links encountered during traversal of a +file hierarchy, and shall not follow any symbolic links. +.RE +.P +For each +.IR source_file , +the following steps shall be taken: +.IP " 1." 4 +If +.IR source_file +references the same file as +.IR dest_file , +.IR cp +may write a diagnostic message to standard error; it shall do nothing +more with +.IR source_file +and shall go on to any remaining files. +.IP " 2." 4 +If +.IR source_file +is of type directory, the following steps shall be taken: +.RS 4 +.IP " a." 4 +If the +.BR \(miR +option was not specified, +.IR cp +shall write a diagnostic message to standard error, do nothing more +with +.IR source_file , +and go on to any remaining files. +.IP " b." 4 +If +.IR source_file +was not specified as an operand and +.IR source_file +is dot or dot-dot, +.IR cp +shall do nothing more with +.IR source_file +and go on to any remaining files. +.IP " c." 4 +If +.IR dest_file +exists and it is a file type not specified by the System Interfaces volume of POSIX.1\(hy2008, the behavior +is implementation-defined. +.IP " d." 4 +If +.IR dest_file +exists and it is not of type directory, +.IR cp +shall write a diagnostic message to standard error, do nothing more +with +.IR source_file +or any files below +.IR source_file +in the file hierarchy, and go on to any remaining files. +.IP " e." 4 +If the directory +.IR dest_file +does not exist, it shall be created with file permission bits set to +the same value as those of +.IR source_file , +modified by the file creation mask of the user if the +.BR \(mip +option was not specified, and then bitwise-inclusively OR'ed with +S_IRWXU. If +.IR dest_file +cannot be created, +.IR cp +shall write a diagnostic message to standard error, do nothing more +with +.IR source_file , +and go on to any remaining files. It is unspecified if +.IR cp +attempts to copy files in the file hierarchy rooted in +.IR source_file . +.IP " f." 4 +The files in the directory +.IR source_file +shall be copied to the directory +.IR dest_file , +taking the four steps (1 to 4) listed here with the files as +.IR source_file s. +.IP " g." 4 +If +.IR dest_file +was created, its file permission bits shall be changed (if necessary) +to be the same as those of +.IR source_file , +modified by the file creation mask of the user if the +.BR \(mip +option was not specified. +.IP " h." 4 +The +.IR cp +utility shall do nothing more with +.IR source_file +and go on to any remaining files. +.RE +.IP " 3." 4 +If +.IR source_file +is of type regular file, the following steps shall be taken: +.RS 4 +.IP " a." 4 +The behavior is unspecified if +.IR dest_file +exists and was written by a previous step. Otherwise, if +.IR dest_file +exists, the following steps shall be taken: +.RS 4 +.IP " i." 5 +If the +.BR \(mii +option is in effect, the +.IR cp +utility shall write a prompt to the standard error and read a line from +the standard input. If the response is not affirmative, +.IR cp +shall do nothing more with +.IR source_file +and go on to any remaining files. +.IP ii. 5 +A file descriptor for +.IR dest_file +shall be obtained by performing actions equivalent to the +\fIopen\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008 called using +.IR dest_file +as the +.IR path +argument, and the bitwise-inclusive OR of O_WRONLY and O_TRUNC as the +.IR oflag +argument. +.IP iii. 5 +If the attempt to obtain a file descriptor fails and the +.BR \(mif +option is in effect, +.IR cp +shall attempt to remove the file by performing actions equivalent to +the +\fIunlink\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008 called using +.IR dest_file +as the +.IR path +argument. If this attempt succeeds, +.IR cp +shall continue with step 3b. +.RE +.IP " b." 4 +If +.IR dest_file +does not exist, a file descriptor shall be obtained by performing +actions equivalent to the +\fIopen\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008 called using +.IR dest_file +as the +.IR path +argument, and the bitwise-inclusive OR of O_WRONLY and O_CREAT as the +.IR oflag +argument. The file permission bits of +.IR source_file +shall be the +.IR mode +argument. +.IP " c." 4 +If the attempt to obtain a file descriptor fails, +.IR cp +shall write a diagnostic message to standard error, do nothing more with +.IR source_file , +and go on to any remaining files. +.IP " d." 4 +The contents of +.IR source_file +shall be written to the file descriptor. Any write errors shall cause +.IR cp +to write a diagnostic message to standard error and continue to step +3e. +.IP " e." 4 +The file descriptor shall be closed. +.IP " f." 4 +The +.IR cp +utility shall do nothing more with +.IR source_file . +If a write error occurred in step 3d, it is unspecified if +.IR cp +continues with any remaining files. If no write error occurred in step +3d, +.IR cp +shall go on to any remaining files. +.RE +.IP " 4." 4 +Otherwise, the +.BR \(miR +option was specified, and the following steps shall be taken: +.RS 4 +.IP " a." 4 +The +.IR dest_file +shall be created with the same file type as +.IR source_file . +.IP " b." 4 +If +.IR source_file +is a file of type FIFO, the file permission bits shall be the same as +those of +.IR source_file, +modified by the file creation mask of the user if the +.BR \(mip +option was not specified. Otherwise, the permissions, owner ID, and +group ID of +.IR dest_file +are implementation-defined. +.RS 4 +.P +If this creation fails for any reason, +.IR cp +shall write a diagnostic message to standard error, do nothing more +with +.IR source_file , +and go on to any remaining files. +.RE +.IP " c." 4 +If +.IR source_file +is a file of type symbolic link, and the options require the symbolic +link itself to be acted upon, the pathname contained in +.IR dest_file +shall be the same as the pathname contained in +.IR source_file . +.RS 4 +.P +If this fails for any reason, +.IR cp +shall write a diagnostic message to standard error, do nothing more +with +.IR source_file , +and go on to any remaining files. +.RE +.RE +.P +If the implementation provides additional or alternate access control +mechanisms (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.4" ", " "File Access Permissions"), +their effect on copies of files is implementation-defined. +.SH OPTIONS +The +.IR cp +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mif\fP" 10 +If a file descriptor for a destination file cannot be obtained, as +described in step 3.a.ii., attempt to unlink the destination file and +proceed. +.IP "\fB\(miH\fP" 10 +Take actions based on the type and contents of the file referenced by +any symbolic link specified as a +.IR source_file +operand. +.IP "\fB\(mii\fP" 10 +Write a prompt to standard error before copying to any existing +non-directory destination file. If the response from the standard input +is affirmative, the copy shall be attempted; otherwise, it shall not. +.IP "\fB\(miL\fP" 10 +Take actions based on the type and contents of the file referenced by +any symbolic link specified as a +.IR source_file +operand or any symbolic links encountered during traversal of a +file hierarchy. +.IP "\fB\(miP\fP" 10 +Take actions on any symbolic link specified as a +.IR source_file +operand or any symbolic link encountered during traversal of a +file hierarchy. +.IP "\fB\(mip\fP" 10 +Duplicate the following characteristics of each source file in the +corresponding destination file: +.RS 10 +.IP " 1." 4 +The time of last data modification and time of last access. If this +duplication fails for any reason, +.IR cp +shall write a diagnostic message to standard error. +.IP " 2." 4 +The user ID and group ID. If this duplication fails for any reason, it +is unspecified whether +.IR cp +writes a diagnostic message to standard error. +.IP " 3." 4 +The file permission bits and the S_ISUID and S_ISGID bits. Other, +implementation-defined, bits may be duplicated as well. If this +duplication fails for any reason, +.IR cp +shall write a diagnostic message to standard error. +.P +If the user ID or the group ID cannot be duplicated, the file +permission bits S_ISUID and S_ISGID shall be cleared. If these bits are +present in the source file but are not duplicated in the destination +file, it is unspecified whether +.IR cp +writes a diagnostic message to standard error. +.P +The order in which the preceding characteristics are duplicated is +unspecified. The +.IR dest_file +shall not be deleted if these characteristics cannot be preserved. +.RE +.IP "\fB\(miR\fR" 10 +Copy file hierarchies. +.P +Specifying more than one of the mutually-exclusive options +.BR \(miH , +.BR \(miL , +and +.BR \(miP +shall not be considered an error. The last option specified shall +determine the behavior of the utility. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIsource_file\fR" 10 +A pathname of a file to be copied. If a +.IR source_file +operand is +.BR '\(mi' , +it shall refer to a file named +.BR \(mi ; +implementations shall not treat it as meaning standard input. +.IP "\fItarget_file\fR" 10 +A pathname of an existing or nonexistent file, used for the output when +a single file is copied. If a +.IR target_file +operand is +.BR '\(mi' , +it shall refer to a file named +.BR \(mi ; +implementations shall not treat it as meaning standard output. +.IP "\fItarget\fR" 10 +A pathname of a directory to contain the copied files. +.SH STDIN +The standard input shall be used to read an input line in response to +each prompt specified in the STDERR section. Otherwise, the standard +input shall not be used. +.SH "INPUT FILES" +The input files specified as operands may be of any file type. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR cp : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements used in the extended regular +expression defined for the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files) and the behavior of +character classes used in the extended regular expression defined for +the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale used to process affirmative responses, and the +locale used to affect the format and contents of diagnostic messages +and prompts written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +A prompt shall be written to standard error under the conditions +specified in the DESCRIPTION section. The prompt shall contain the +destination pathname, but its format is otherwise unspecified. +Otherwise, the standard error shall be used only for diagnostic +messages. +.SH "OUTPUT FILES" +The output files may be of any type. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All files were copied successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If +.IR cp +is prematurely terminated by a signal or error, files or file +hierarchies may be only partially copied and files and directories may +have incorrect permissions or access and modification times. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The set-user-ID and set-group-ID bits are explicitly cleared when files +are created. This is to prevent users from creating programs that are +set-user-ID or set-group-ID to them when copying files or to make +set-user-ID or set-group-ID files accessible to new groups of users. +For example, if a file is set-user-ID and the copy has a different +group ID than the source, a new group of users has execute permission +to a set-user-ID program than did previously. In particular, this is a +problem for superusers copying users' trees. +.SH EXAMPLES +None. +.SH RATIONALE +The +.BR \(mii +option exists on BSD systems, giving applications and users a way to +avoid accidentally removing files when copying. Although the 4.3 BSD +version does not prompt if the standard input is not a terminal, the +standard developers decided that use of +.BR \(mii +is a request for interaction, so when the destination path exists, the +utility takes instructions from whatever responds on standard input. +.P +The exact format of the interactive prompts is unspecified. Only the +general nature of the contents of prompts are specified because +implementations may desire more descriptive prompts than those used on +historical implementations. Therefore, an application using the +.BR \(mii +option relies on the system to provide the most suitable dialog +directly with the user, based on the behavior specified. +.P +The +.BR \(mip +option is historical practice on BSD systems, duplicating the time of +last data modification and time of last access. This volume of POSIX.1\(hy2008 extends it to +preserve the user and group IDs, as well as the file permissions. This +requirement has obvious problems in that the directories are almost +certainly modified after being copied. This volume of POSIX.1\(hy2008 requires that the +modification times be preserved. The statement that the order in which +the characteristics are duplicated is unspecified is to permit +implementations to provide the maximum amount of security for the user. +Implementations should take into account the obvious security issues +involved in setting the owner, group, and mode in the wrong order or +creating files with an owner, group, or mode different from the final +value. +.P +It is unspecified whether +.IR cp +writes diagnostic messages when the user and group IDs cannot be set +due to the widespread practice of users using +.BR \(mip +to duplicate some portion of the file characteristics, indifferent to +the duplication of others. Historic implementations only write +diagnostic messages on errors other than +.BR [EPERM] . +.P +Earlier versions of this standard included support for the +.BR \(mir +option to copy file hierarchies. The +.BR \(mir +option is historical practice on BSD and BSD-derived systems. This +option is no longer specified by POSIX.1\(hy2008 but may be present +in some implementations. The +.BR \(miR +option was added as a close synonym to the +.BR \(mir +option, selected for consistency with all other options in this volume of POSIX.1\(hy2008 that +do recursive directory descent. +.P +The difference between +.BR \(miR +and the removed +.BR \(mir +option is in the treatment by +.IR cp +of file types other than regular and directory. It was +implementation-defined how the +.BR \(mi +option treated special files to allow both historical implementations +and those that chose to support +.BR \(mir +with the same abilities as +.BR \(miR +defined by this volume of POSIX.1\(hy2008. The original +.BR \(mir +flag, for historic reasons, did not handle special files any differently +from regular files, but always read the file and copied its contents. This +had obvious problems in the presence of special file types; for example, +character devices, FIFOs, and sockets. +.P +When a failure occurs during the copying of a file hierarchy, +.IR cp +is required to attempt to copy files that are on the same level in the +hierarchy or above the file where the failure occurred. It is +unspecified if +.IR cp +shall attempt to copy files below the file where the failure occurred +(which cannot succeed in any case). +.P +Permissions, owners, and groups of created special file types have been +deliberately left as implementation-defined. This is to allow systems +to satisfy special requirements (for example, allowing users to create +character special devices, but requiring them to be owned by a certain +group). In general, it is strongly suggested that the permissions, +owner, and group be the same as if the user had run the historical +.IR mknod , +.IR ln , +or other utility to create the file. It is also probable that +additional privileges are required to create block, character, or +other implementation-defined special file types. +.P +Additionally, the +.BR \(mip +option explicitly requires that all set-user-ID +and set-group-ID permissions be +discarded if any of the owner or group IDs cannot be set. This is to +keep users from unintentionally giving away special privilege when +copying programs. +.P +When creating regular files, historical versions of +.IR cp +use the mode of the source file as modified by the file mode creation +mask. Other choices would have been to use the mode of the source file +unmodified by the creation mask or to use the same mode as would be +given to a new file created by the user (plus the execution bits of the +source file) and then modify it by the file mode creation mask. In the +absence of any strong reason to change historic practice, it was in +large part retained. +.P +When creating directories, historical versions of +.IR cp +use the mode of the source directory, plus read, write, and search bits +for the owner, as modified by the file mode creation mask. This is done +so that +.IR cp +can copy trees where the user has read permission, but the owner does +not. A side-effect is that if the file creation mask denies the owner +permissions, +.IR cp +fails. Also, once the copy is done, historical versions of +.IR cp +set the permissions on the created directory to be the same as the +source directory, unmodified by the file creation mask. +.P +This behavior has been modified so that +.IR cp +is always able to create the contents of the directory, regardless of +the file creation mask. After the copy is done, the permissions are set +to be the same as the source directory, as modified by the file +creation mask. This latter change from historical behavior is to +prevent users from accidentally creating directories with permissions +beyond those they would normally set and for consistency with the +behavior of +.IR cp +in creating files. +.P +It is not a requirement that +.IR cp +detect attempts to copy a file to itself; however, implementations are +strongly encouraged to do so. Historical implementations have detected +the attempt in most cases. +.P +There are two methods of copying subtrees in this volume of POSIX.1\(hy2008. The other method is +described as part of the +.IR pax +utility (see +.IR "\fIpax\fR\^"). +Both methods are historical practice. The +.IR cp +utility provides a simpler, more intuitive interface, while +.IR pax +offers a finer granularity of control. Each provides additional +functionality to the other; in particular, +.IR pax +maintains the hard-link structure of the hierarchy, while +.IR cp +does not. It is the intention of the standard developers that the +results be similar (using appropriate option combinations in both +utilities). The results are not required to be identical; there seemed +insufficient gain to applications to balance the difficulty of +implementations having to guarantee that the results would be exactly +identical. +.P +The wording allowing +.IR cp +to copy a directory to implementation-defined file types not +specified by the System Interfaces volume of POSIX.1\(hy2008 is provided so that implementations supporting +symbolic links are not required to prohibit copying directories to +symbolic links. Other extensions to the System Interfaces volume of POSIX.1\(hy2008 file types may need to +use this loophole as well. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImv\fR\^", +.IR "\fIfind\fR\^", +.IR "\fIln\fR\^", +.IR "\fIpax\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.4" ", " "File Access Permissions", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIopen\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/crontab.1p b/man-pages-posix-2013/man1p/crontab.1p new file mode 100644 index 0000000..6a0d791 --- /dev/null +++ b/man-pages-posix-2013/man1p/crontab.1p @@ -0,0 +1,360 @@ +'\" et +.TH CRONTAB "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +crontab +\(em schedule periodic background work +.SH SYNOPSIS +.LP +.nf +crontab \fB[\fIfile\fB]\fR +.P +crontab \fB[\fR\(mie\||\(mil|\(mir\fB]\fR +.fi +.SH DESCRIPTION +The +.IR crontab +utility shall create, replace, +or edit a user's crontab entry; +a crontab entry is a list of commands and the times at which they +shall be executed. The new crontab entry can be input by specifying +.IR file +or input from standard input if no +.IR file +operand is specified, +or by using an editor, if +.BR \(mie +is specified. +.P +Upon execution of a command from a crontab entry, the implementation +shall supply a default environment, defining at least the following +environment variables: +.IP "\fIHOME\fP" 10 +A pathname of the user's home directory. +.IP "\fILOGNAME\fP" 10 +The user's login name. +.IP "\fIPATH\fP" 10 +A string representing a search path guaranteed to find all of the +standard utilities. +.IP "\fISHELL\fP" 10 +A pathname of the command interpreter. When +.IR crontab +is invoked as specified by this volume of POSIX.1\(hy2008, the value shall be a pathname for +.IR sh . +.P +The values of these variables when +.IR crontab +is invoked as specified by this volume of POSIX.1\(hy2008 shall not affect the default +values provided when the scheduled command is run. +.P +If standard output and standard error are not redirected by commands +executed from the crontab entry, any generated output or errors shall +be mailed, via an implementation-defined method, to the user. +.P +Users shall be permitted to use +.IR crontab +if their names appear in the file +.BR cron.allow +which is located in an implementation-defined directory. +If that file does not exist, the file +.BR cron.deny , +which is located in an implementation-defined directory, +shall be checked to determine whether the user shall be denied access to +.IR crontab . +If neither file exists, only a process with appropriate privileges shall be +allowed to submit a job. If only +.BR cron.deny +exists and is empty, global usage shall be permitted. The +.BR cron.allow +and +.BR cron.deny +files shall consist of one user name per line. +.SH OPTIONS +The +.IR crontab +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mie\fP" 10 +Edit a copy of the invoking user's crontab entry, or create an empty +entry to edit if the crontab entry does not exist. When editing is +complete, the entry shall be installed as the user's crontab entry. +.IP "\fB\(mil\fP" 10 +(The letter ell.) List the invoking user's crontab entry. +.IP "\fB\(mir\fP" 10 +Remove the invoking user's crontab entry. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +The pathname of a file that contains specifications, in the format +defined in the INPUT FILES section, for crontab entries. +.SH STDIN +See the INPUT FILES section. +.SH "INPUT FILES" +In the POSIX locale, the user or application shall ensure that a +crontab entry is a text file consisting of lines of six fields each. +The fields shall be separated by + +characters. The first five fields shall be integer patterns that specify +the following: +.IP " 1." 4 +Minute [0,59] +.IP " 2." 4 +Hour [0,23] +.IP " 3." 4 +Day of the month [1,31] +.IP " 4." 4 +Month of the year [1,12] +.IP " 5." 4 +Day of the week ([0,6] with 0=Sunday) +.P +Each of these patterns can be either an + +(meaning all valid values), an element, or a list of elements separated by + +characters. An element shall be either a number or two numbers separated +by a + +(meaning an inclusive range). The specification of days can be made by +two fields (day of the month and day of the week). If month, day of +month, and day of week are all + +characters, every day shall be matched. If either the month or day of +month is specified as an element or list, but the day of week is an +, +the month and day of month fields shall specify the days that match. If +both month and day of month are specified as an +, +but day of week is an element or list, then only the specified days of the +week match. Finally, if either the month or day of month is specified as +an element or list, and the day of week is also specified as an element +or list, then any day matching either the month and day of month, or +the day of week, shall be matched. +.P +The sixth field of a line in a crontab entry is a string that shall be +executed by +.IR sh +at the specified times. A + +character in this field shall be translated to a +. +Any character preceded by a + +(including the +.BR '%' ) +shall cause that character to be treated literally. Only the first line +(up to a +.BR '%' +or end-of-line) of the command field shall be executed by the command +interpreter. The other lines shall be made available to the command as +standard input. +.P +Blank lines and those whose first non-\c + +is +.BR '#' +shall be ignored. +.P +The text files +.BR cron.allow +and +.BR cron.deny , +which are located in an implementation-defined directory, +shall contain zero or more user names, one per line, of users who are, +respectively, authorized or denied access to the service underlying the +.IR crontab +utility. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR crontab : +.IP "\fIEDITOR\fP" 10 +Determine the editor to be invoked when the +.BR \(mie +option is specified. The default editor shall be +.IR vi . +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If the +.BR \(mil +option is specified, the crontab entry shall be written to the standard +output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +The user's crontab entry is not submitted, removed, +edited, +or listed. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The format of the crontab entry shown here is guaranteed only for the +POSIX locale. Other cultures may be supported with substantially +different interfaces, although implementations are encouraged to +provide comparable levels of functionality. +.P +The default settings of the +.IR HOME , +.IR LOGNAME , +.IR PATH , +and +.IR SHELL +variables that are given to the scheduled job are not affected by the +settings of those variables when +.IR crontab +is run; as stated, they are defaults. The text about ``invoked as +specified by this volume of POSIX.1\(hy2008'' means that the implementation may provide +extensions that allow these variables to be affected at runtime, but +that the user has to take explicit action in order to access the +extension, such as give a new option flag or modify the format of the +crontab entry. +.P +A typical user error is to type only +.IR crontab ; +this causes the system to wait for the new crontab entry on standard +input. If end-of-file is typed (generally \(hyD), the crontab +entry is replaced by an empty file. In this case, the user should type +the interrupt character, which prevents the crontab entry from being +replaced. +.SH EXAMPLES +.IP " 1." 4 +Clean up +.BR core +files every weekday morning at 3:15 am: +.RS 4 +.sp +.RS 4 +.nf +\fB +15 3 * * 1-5 find "$HOME" \(miname core \(miexec rm \(mif {} + 2>/dev/null +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +Mail a birthday greeting: +.RS 4 +.sp +.RS 4 +.nf +\fB +0 12 14 2 * mailx john%Happy Birthday!%Time for lunch. +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +As an example of specifying the two types of days: +.RS 4 +.sp +.RS 4 +.nf +\fB +0 0 1,15 * 1 +.fi \fR +.P +.RE +.P +would run a command on the first and fifteenth of each month, as well +as on every Monday. To specify days by only one field, the other field +should be set to +.BR '*' ; +for example: +.sp +.RS 4 +.nf +\fB +0 0 * * 1 +.fi \fR +.P +.RE +.P +would run a command only on Mondays. +.RE +.SH RATIONALE +All references to a +.IR cron +daemon and to +.IR cron +.IR files +have been omitted. Although historical implementations have used this +arrangement, there is no reason to limit future implementations. +.P +This description of +.IR crontab +is designed to support only users with normal privileges. The format of +the input is based on the System V +.IR crontab ; +however, there is no requirement here that the actual system database +used by the +.IR cron +daemon (or a similar mechanism) use this format internally. For +example, systems derived from BSD are likely to have an additional +field appended that indicates the user identity to be used when the job +is submitted. +.P +The +.BR \(mie +option was adopted from the SVID as a user convenience, although it +does not exist in all historical implementations. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIat\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/csplit.1p b/man-pages-posix-2013/man1p/csplit.1p new file mode 100644 index 0000000..6c36dbc --- /dev/null +++ b/man-pages-posix-2013/man1p/csplit.1p @@ -0,0 +1,315 @@ +'\" et +.TH CSPLIT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +csplit +\(em split files based on context +.SH SYNOPSIS +.LP +.nf +csplit \fB[\fR\(miks\fB] [\fR\(mif \fIprefix\fB] [\fR\(min \fInumber\fB] \fIfile arg\fR... +.fi +.SH DESCRIPTION +The +.IR csplit +utility shall read the file named by the +.IR file +operand, write all or part of that file into other files as directed +by the +.IR arg +operands, and write the sizes of the files. +.SH OPTIONS +The +.IR csplit +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mif\ \fIprefix\fR" 10 +Name the created files +.IR prefix \c +.BR 00 , +.IR prefix \c +.BR 01 , +\&.\|.\|., +.IR prefixn . +The default is +.BR xx00 +\&.\|.\|. +.BR xx \c +.IR n . +If the +.IR prefix +argument would create a filename exceeding +{NAME_MAX} +bytes, an error shall result, +.IR csplit +shall exit with a diagnostic message, and no files shall be created. +.IP "\fB\(mik\fP" 10 +Leave previously created files intact. By default, +.IR csplit +shall remove created files if an error occurs. +.IP "\fB\(min\ \fInumber\fR" 10 +Use +.IR number +decimal digits to form filenames for the file pieces. The default +shall be 2. +.IP "\fB\(mis\fP" 10 +Suppress the output of file size messages. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile\fR" 10 +The pathname of a text file to be split. If +.IR file +is +.BR '\(mi' , +the standard input shall be used. +.P +Each +.IR arg +operand can be one of the following: +.IP "/\fIrexp\fR/\fB[\fIoffset\fB]\fR" 10 +.br +A file shall be created using the content of the lines from the current +line up to, but not including, the line that results from the +evaluation of the regular expression with +.IR offset , +if any, applied. The regular expression +.IR rexp +shall follow the rules for basic regular expressions described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.3" ", " "Basic Regular Expressions". +The application shall use the sequence +.BR \(dq\e/\(dq +to specify a + +character within the +.IR rexp . +The optional offset shall be a positive or negative integer value +representing a number of lines. A positive integer value can be +preceded by +.BR '\(pl' . +If the selection of lines from an +.IR offset +expression of this type would create a file with zero lines, or one +with greater than the number of lines left in the input file, the +results are unspecified. After the section is created, the current line +shall be set to the line that results from the evaluation of the +regular expression with any offset applied. If the current line is the +first line in the file and a regular expression operation has not yet +been performed, the pattern match of +.IR rexp +shall be applied from the current line to the end of the file. +Otherwise, the pattern match of +.IR rexp +shall be applied from the line following the current line to the end of +the file. +.IP "%\fIrexp\fR%\fB[\fIoffset\fB]\fR" 10 +.br +Equivalent to /\fIrexp\fR/\fB[\fIoffset\fB]\fR, except that no +file shall be created for the selected section of the input file. The +application shall use the sequence +.BR \(dq\e%\(dq +to specify a + +character within the +.IR rexp . +.IP "\fIline_no\fR" 10 +Create a file from the current line up to (but not including) the line +number +.IR line_no . +Lines in the file shall be numbered starting at one. The current line +becomes +.IR line_no . +.IP "{\fInum\fR}" 10 +Repeat operand. This operand can follow any of the operands described +previously. If it follows a +.IR rexp +type operand, that operand shall be applied +.IR num +more times. If it follows a +.IR line_no +operand, the file shall be split every +.IR line_no +lines, +.IR num +times, from that point. +.P +An error shall be reported if an operand does not reference a line +between the current position and the end of the file. +.SH STDIN +See the INPUT FILES section. +.SH "INPUT FILES" +The input file shall be a text file. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR csplit : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular expressions. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files) and the behavior of +character classes within regular expressions. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +If the +.BR \(mik +option is specified, created files shall be retained. Otherwise, the +default action occurs. +.SH STDOUT +Unless the +.BR \(mis +option is used, the standard output shall consist of one line per +file created, with a format as follows: +.sp +.RS 4 +.nf +\fB +"%d\en", <\fIfile size in bytes\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The output files shall contain portions of the original input file; +otherwise, unchanged. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +By default, created files shall be removed if an error occurs. When the +.BR \(mik +option is specified, created files shall not be removed if an error +occurs. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +.IP " 1." 4 +This example creates four files, +.BR cobol00 +\&.\|.\|. +.BR cobol03 : +.RS 4 +.sp +.RS 4 +.nf +\fB +csplit \(mif cobol file '/procedure division/' /par5./ /par16./ +.fi \fR +.P +.RE +.P +After editing the split files, they can be recombined as follows: +.sp +.RS 4 +.nf +\fB +cat cobol0[0\(mi3] > file +.fi \fR +.P +.RE +.P +Note that this example overwrites the original file. +.RE +.IP " 2." 4 +This example would split the file after the first 99 lines, and every +100 lines thereafter, up to 9\|999 lines; this is because lines in the +file are numbered from 1 rather than zero, for historical reasons: +.RS 4 +.sp +.RS 4 +.nf +\fB +csplit \(mik file 100 {99} +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +Assuming that +.BR prog.c +follows the C-language coding convention of ending routines with a +.BR '}' +at the beginning of the line, this example creates a file containing +each separate C routine (up to 21) in +.BR prog.c : +.RS 4 +.sp +.RS 4 +.nf +\fB +csplit \(mik prog.c '%main(%' '/^}/+1' {20} +.fi \fR +.P +.RE +.RE +.SH RATIONALE +The +.BR \(min +option was added to extend the range of filenames that could be +handled. +.P +Consideration was given to adding a +.BR \(mia +flag to use the alphabetic filename generation used by the historical +.IR split +utility, but the functionality added by the +.BR \(min +option was deemed to make alphabetic naming unnecessary. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsed\fR\^", +.IR "\fIsplit\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 9.3" ", " "Basic Regular Expressions", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/ctags.1p b/man-pages-posix-2013/man1p/ctags.1p new file mode 100644 index 0000000..aa190b1 --- /dev/null +++ b/man-pages-posix-2013/man1p/ctags.1p @@ -0,0 +1,477 @@ +'\" et +.TH CTAGS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ctags +\(em create a tags file (\fBDEVELOPMENT\fR, \fBFORTRAN\fR) +.SH SYNOPSIS +.LP +.nf +ctags \fB[\fR\(mia\fB] [\fR\(mif \fItagsfile\fB] \fIpathname\fR... +.P +ctags \(mix \fIpathname\fR... +.fi +.SH DESCRIPTION +The +.IR ctags +utility shall be provided on systems that support the the Software +Development Utilities option, and either or both of the C-Language +Development Utilities option and FORTRAN Development Utilities option. On +other systems, it is optional. +.P +The +.IR ctags +utility shall write a +.IR tagsfile +or an index of objects from C-language or FORTRAN source files +specified by the +.IR pathname +operands. The +.IR tagsfile +shall list the locators of language-specific objects within the source +files. A locator consists of a name, pathname, and either a search +pattern +or a line number that can be used in searching for the object +definition. The objects that shall be recognized are specified in the +EXTENDED DESCRIPTION section. +.SH OPTIONS +The +.IR ctags +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mia\fP" 10 +Append to +.IR tagsfile . +.IP "\fB\(mif\ \fItagsfile\fR" 10 +Write the object locator lists into +.IR tagsfile +instead of the default file named +.BR tags +in the current directory. +.IP "\fB\(mix\fP" 10 +Produce a list of object names, the line number, and filename in which +each is defined, as well as the text of that line, and write this to +the standard output. A +.IR tagsfile +shall not be created when +.BR \(mix +is specified. +.SH OPERANDS +The following +.IR pathname +operands are supported: +.IP "\fIfile\fB.c\fR" 10 +Files with basenames ending with the +.BR .c +suffix shall be treated as C-language source code. Such files that are +not valid input to +.IR c99 +produce unspecified results. +.IP "\fIfile\fB.h\fR" 10 +Files with basenames ending with the +.BR .h +suffix shall be treated as C-language source code. Such files that are +not valid input to +.IR c99 +produce unspecified results. +.IP "\fIfile\fB.f\fR" 10 +Files with basenames ending with the +.BR .f +suffix shall be treated as FORTRAN-language source code. Such files +that are not valid input to +.IR fort77 +produce unspecified results. +.P +The handling of other files is implementation-defined. +.SH STDIN +See the INPUT FILES section. +.SH "INPUT FILES" +The input files shall be text files containing source code in the +language indicated by the operand filename suffixes. +.br +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR ctags : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the order in which output is sorted for the +.BR \(mix +option. The POSIX locale determines the order in which the +.IR tagsfile +is written. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). When processing +C-language source code, if the locale is not compatible with the C +locale described by the ISO\ C standard, the results are unspecified. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The list of object name information produced by the +.BR \(mix +option shall be written to standard output in the following format: +.sp +.RS 4 +.nf +\fB +"%s %d %s %s", <\fIobject-name\fR>, <\fIline-number\fR>, <\fIfilename\fR>, <\fItext\fR> +.fi \fR +.P +.RE +.P +where <\fItext\fP> is the text of line <\fIline-number\fP> of file +<\fIfilename\fP>. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +When the +.BR \(mix +option is not specified, the format of the output file shall be: +.sp +.RS 4 +.nf +\fB +"%s\et%s\et/%s/\en", <\fIidentifier\fR>, <\fIfilename\fR>, <\fIpattern\fR> +.fi \fR +.P +.RE +.P +where <\fIpattern\fP> is a search pattern that could be used by an +editor to find the defining instance of <\fIidentifier\fP> in +<\fIfilename\fP> (where +.IR "defining instance" +is indicated by the declarations listed in the EXTENDED DESCRIPTION). +.P +An optional + +(\c +.BR '^' ) +can be added as a prefix to <\fIpattern\fP>, and an optional + +can be appended to <\fIpattern\fP> to indicate that the pattern is +anchored to the beginning (end) of a line of text. Any + +or + +characters in <\fIpattern\fP> shall be preceded by a + +character. The anchoring +, +, +and escaping + +characters shall not be considered part of the search pattern. All other +characters in the search pattern shall be considered literal characters. +.br +.P +An alternative format is: +.sp +.RS 4 +.nf +\fB +"%s\et%s\et?%s?\en", <\fIidentifier\fR>, <\fIfilename\fR>, <\fIpattern\fR> +.fi \fR +.P +.RE +.P +which is identical to the first format except that + +characters in <\fIpattern\fP> shall not be preceded by escaping + +characters, and + +characters in <\fIpattern\fP> shall be preceded by + +characters. +.P +A second alternative format is: +.sp +.RS 4 +.nf +\fB +"%s\et%s\et%d\en", <\fIidentifier\fR>, <\fIfilename\fR>, <\fIlineno\fR> +.fi \fR +.P +.RE +.P +where <\fIlineno\fP> is a decimal line number that could be used by an +editor to find <\fIidentifier\fP> in <\fIfilename\fP>. +.P +Neither alternative format shall be produced by +.IR ctags +when it is used as described by POSIX.1\(hy2008, but the standard utilities that +process tags files shall be able to process those formats as well as +the first format. +.P +In any of these formats, the file shall be sorted by identifier, based +on the collation sequence in the POSIX locale. +.SH "EXTENDED DESCRIPTION" +If the operand identifies C-language source, the +.IR ctags +utility shall attempt to produce an output line for each of the +following objects: +.IP " *" 4 +Function definitions +.IP " *" 4 +Type definitions +.IP " *" 4 +Macros with arguments +.P +It may also produce output for any of the following objects: +.IP " *" 4 +Function prototypes +.IP " *" 4 +Structures +.IP " *" 4 +Unions +.IP " *" 4 +Global variable definitions +.IP " *" 4 +Enumeration types +.IP " *" 4 +Macros without arguments +.IP " *" 4 +.BR #define +statements +.IP " *" 4 +.BR #line +statements +.P +Any +.BR #if +and +.BR #ifdef +statements shall produce no output. The tag +.BR main +is treated specially in C programs. The tag formed shall be created by +prefixing +.BR M +to the name of the file, with the trailing +.BR .c , +and leading pathname components (if any) removed. +.P +On systems that do not support the C-Language Development Utilities +option, +.IR ctags +produces unspecified results for C-language source code files. It should +write to standard error a message identifying this condition and cause +a non-zero exit status to be produced. +.P +If the operand identifies FORTRAN source, the +.IR ctags +utility shall produce an output line for each function definition. It +may also produce output for any of the following objects: +.IP " *" 4 +Subroutine definitions +.IP " *" 4 +COMMON statements +.IP " *" 4 +PARAMETER statements +.IP " *" 4 +DATA and BLOCK DATA statements +.IP " *" 4 +Statement numbers +.P +On systems that do not support the FORTRAN Development Utilities +option, +.IR ctags +produces unspecified results for FORTRAN source code files. It should +write to standard error a message identifying this condition and cause +a non-zero exit status to be produced. +.P +It is implementation-defined what other objects (including duplicate +identifiers) produce output. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The output with +.BR \(mix +is meant to be a simple index that can be written out as an off-line +readable function index. If the input files to +.IR ctags +(such as +.BR .c +files) were not created using the same locale as that in effect when +.IR ctags +.BR \(mix +is run, results might not be as expected. +.P +The description of C-language processing says ``attempts to'' because +the C language can be greatly confused, especially through the use of +.BR #define s, +and this utility would be of no use if the real C preprocessor were run +to identify them. The output from +.IR ctags +may be fooled and incorrect for various constructs. +.SH EXAMPLES +None. +.SH RATIONALE +The option list was significantly reduced from that provided by +historical implementations. The +.BR \(miF +option was omitted as redundant, since it is the default. The +.BR \(miB +option was omitted as being of very limited usefulness. The +.BR \(mit +option was omitted since the recognition of +.BR typedef s +is now required for C source files. The +.BR \(miu +option was omitted because the update function was judged to be not +only inefficient, but also rarely needed. +.P +An early proposal included a +.BR \(miw +option to suppress warning diagnostics. Since the types of such +diagnostics could not be described, the option was omitted as being not +useful. +.P +The text for +.IR LC_CTYPE +about compatibility with the C locale acknowledges that the ISO\ C standard +imposes requirements on the locale used to process C source. This could +easily be a superset of that known as ``the C locale'' by way of +implementation extensions, or one of a few alternative locales for +systems supporting different codesets. No statement is made for FORTRAN +because the ANSI\ X3.9\(hy1978 standard (FORTRAN 77) does not (yet) define a similar locale +concept. However, a general rule in this volume of POSIX.1\(hy2008 is that any time that locales +do not match (preparing a file for one locale and processing it in +another), the results are suspect. +.P +The collation sequence of the tags file is not affected by +.IR LC_COLLATE +because it is typically not used by human readers, but only by programs +such as +.IR vi +to locate the tag within the source files. Using the POSIX locale +eliminates some of the problems of coordinating locales between the +.IR ctags +file creator and the +.IR vi +file reader. +.P +Historically, the tags file has been used only by +.IR ex +and +.IR vi . +However, the format of the tags file has been published to encourage +other programs to use the tags in new ways. The format allows either +patterns or line numbers to find the identifiers because the historical +.IR vi +recognizes either. The +.IR ctags +utility does not produce the format using line numbers because it is +not useful following any source file changes that add or delete lines. +The documented search patterns match historical practice. It should be +noted that literal leading + +or trailing + +characters in the search pattern will only behave correctly if anchored +to the beginning of the line or end of the line by an additional + +or + +character. +.P +Historical implementations also understand the objects used by the +languages Pascal and sometimes LISP, and they understand the C source +output by +.IR lex +and +.IR yacc . +The +.IR ctags +utility is not required to accommodate these languages, although +implementors are encouraged to do so. +.P +The following historical option was not specified, as +.IR vgrind +is not included in this volume of POSIX.1\(hy2008: +.IP "\fB\(miv\fP" 10 +If the +.BR \(miv +flag is given, an index of the form expected by +.IR vgrind +is produced on the standard output. This listing contains the function +name, filename, and page number (assuming 64-line pages). Since the +output is sorted into lexicographic order, it may be desired to run the +output through +.IR sort +.BR \(mif . +Sample use: +.RS 10 +.sp +.RS 4 +.nf +\fB +ctags \(miv files | sort \(mif > index vgrind \(mix index +.fi \fR +.P +.RE +.RE +.P +The special treatment of the tag +.BR main +makes the use of +.IR ctags +practical in directories with more than one program. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIc99\fR\^", +.IR "\fIfort77\fR\^", +.IR "\fIvi\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/cut.1p b/man-pages-posix-2013/man1p/cut.1p new file mode 100644 index 0000000..d5cfbc2 --- /dev/null +++ b/man-pages-posix-2013/man1p/cut.1p @@ -0,0 +1,496 @@ +'\" et +.TH CUT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cut +\(em cut out selected fields of each line of a file +.SH SYNOPSIS +.LP +.nf +cut \(mib \fIlist \fB[\fR\(min\fB] [\fIfile\fR...\fB]\fR +.P +cut \(mic \fIlist \fB[\fIfile\fR...\fB]\fR +.P +cut \(mif \fIlist \fB[\fR\(mid \fIdelim\fB] [\fR\(mis\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR cut +utility shall cut out bytes (\c +.BR \(mib +option), characters (\c +.BR \(mic +option), or character-delimited fields (\c +.BR \(mif +option) from each line in one or more files, concatenate them, and +write them to standard output. +.SH OPTIONS +The +.IR cut +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The application shall ensure that the option-argument +.IR list +(see options +.BR \(mib , +.BR \(mic , +and +.BR \(mif +below) is a +-separated +list or +-separated +list of positive numbers and ranges. Ranges can be in three forms. The +first is two positive numbers separated by a + +(\c +.IR low \(mi\c +.IR high ), +which represents all fields from the first number to the second +number. The second is a positive number preceded by a + +(\(mi\c +.IR high ), +which represents all fields from field number 1 to that number. The +third is a positive number followed by a + +(\c +.IR low \(mi), +which represents that number to the last field, inclusive. The elements +in +.IR list +can be repeated, can overlap, and can be specified in any order, but +the bytes, characters, or fields selected shall be written in the order +of the input data. If an element appears in the selection list more +than once, it shall be written exactly once. +.P +The following options shall be supported: +.IP "\fB\(mib\ \fIlist\fR" 10 +Cut based on a +.IR list +of bytes. Each selected byte shall be output unless the +.BR \(min +option is also specified. It shall not be an error to select bytes not +present in the input line. +.IP "\fB\(mic\ \fIlist\fR" 10 +Cut based on a +.IR list +of characters. Each selected character shall be output. It shall not +be an error to select characters not present in the input line. +.IP "\fB\(mid\ \fIdelim\fR" 10 +Set the field delimiter to the character +.IR delim . +The default is the +. +.IP "\fB\(mif\ \fIlist\fR" 10 +Cut based on a +.IR list +of fields, assumed to be separated in the file by a delimiter character +(see +.BR \(mid ). +Each selected field shall be output. Output fields shall be separated +by a single occurrence of the field delimiter character. Lines with no +field delimiters shall be passed through intact, unless +.BR \(mis +is specified. It shall not be an error to select fields not present in +the input line. +.IP "\fB\(min\fP" 10 +Do not split characters. When specified with the +.BR \(mib +option, each element in +.IR list +of the form +.IR low \(mi\c +.IR high +(\c +-separated +numbers) shall be modified as follows: +.RS 10 +.IP " *" 4 +If the byte selected by +.IR low +is not the first byte of a character, +.IR low +shall be decremented to select the first byte of the character +originally selected by +.IR low . +If the byte selected by +.IR high +is not the last byte of a character, +.IR high +shall be decremented to select the last byte of the character prior to +the character originally selected by +.IR high , +or zero if there is no prior character. If the resulting range element +has +.IR high +equal to zero or +.IR low +greater than +.IR high , +the list element shall be dropped from +.IR list +for that input line without causing an error. +.P +Each element in +.IR list +of the form +.IR low \(mi +shall be treated as above with +.IR high +set to the number of bytes in the current line, not including the +terminating +. +Each element in +.IR list +of the form \(mi\c +.IR high +shall be treated as above with +.IR low +set to 1. Each element in +.IR list +of the form +.IR num +(a single number) shall be treated as above with +.IR low +set to +.IR num +and +.IR high +set to +.IR num . +.RE +.IP "\fB\(mis\fP" 10 +Suppress lines with no delimiter characters, when used with the +.BR \(mif +option. Unless specified, lines with no delimiters shall be passed +through untouched. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an input file. If no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' , +the standard input shall be used. +.SH STDIN +The standard input shall be used only if no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' . +See the INPUT FILES section. +.SH "INPUT FILES" +The input files shall be text files, except that line lengths shall be +unlimited. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR cut : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR cut +utility output shall be a concatenation of the selected bytes, +characters, or fields (one of the following): +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIconcatenation of bytes\fR> +.P +"%s\en", <\fIconcatenation of characters\fR> +.P +"%s\en", <\fIconcatenation of fields and field delimiters\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All input files were output successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR cut +and +.IR fold +utilities can be used to create text files out of files with +arbitrary line lengths. The +.IR cut +utility should be used when the number of lines (or records) needs +to remain constant. The +.IR fold +utility should be used when the contents of long lines need to be +kept contiguous. +.P +Earlier versions of the +.IR cut +utility worked in an environment where bytes and characters were +considered equivalent (modulo + +and + +processing in some implementations). In the extended world of +multi-byte characters, the new +.BR \(mib +option has been added. The +.BR \(min +option (used with +.BR \(mib ) +allows it to be used to act on bytes rounded to character boundaries. +The algorithm specified for +.BR \(min +guarantees that: +.sp +.RS 4 +.nf +\fB +cut \(mib 1\(mi500 \(min file > file1 +cut \(mib 501\(mi \(min file > file2 +.fi \fR +.P +.RE +.P +ends up with all the characters in +.BR file +appearing exactly once in +.BR file1 +or +.BR file2 . +(There is, however, a + +in both +.BR file1 +and +.BR file2 +for each + +in +.BR file .) +.SH EXAMPLES +Examples of the option qualifier list: +.IP 1,4,7 8 +Select the first, fourth, and seventh bytes, characters, or fields and +field delimiters. +.IP "1\(mi3,8" 8 +Equivalent to 1,2,3,8. +.IP "\(mi5,10" 8 +Equivalent to 1,2,3,4,5,10. +.IP "3\(mi" 8 +Equivalent to third to last, inclusive. +.P +The +.IR low \(mi\c +.IR high +forms are not always equivalent when used with +.BR \(mib +and +.BR \(min +and multi-byte characters; see the description of +.BR \(min . +.P +The following command: +.sp +.RS 4 +.nf +\fB +cut \(mid : \(mif 1,6 /etc/passwd +.fi \fR +.P +.RE +.P +reads the System V password file (user database) and produces lines of +the form: +.sp +.RS 4 +.nf +\fB +<\fIuser ID\fR>:<\fIhome directory\fR> +.fi \fR +.P +.RE +.P +Most utilities in this volume of POSIX.1\(hy2008 work on text files. The +.IR cut +utility can be used to turn files with arbitrary line lengths into a +set of text files containing the same data. The +.IR paste +utility can be used to create (or recreate) files with arbitrary line +lengths. For example, if +.BR file +contains long lines: +.sp +.RS 4 +.nf +\fB +cut \(mib 1\(mi500 \(min file > file1 +cut \(mib 501\(mi \(min file > file2 +.fi \fR +.P +.RE +.P +creates +.BR file1 +(a text file) with lines no longer than 500 bytes (plus the +) +and +.BR file2 +that contains the remainder of the data from +.BR file . +(Note that +.BR file2 +is not a text file if there are lines in +.BR file +that are longer than 500 + +{LINE_MAX} +bytes.) The original file can be recreated from +.BR file1 +and +.BR file2 +using the command: +.sp +.RS 4 +.nf +\fB +paste \(mid "\e0" file1 file2 > file +.fi \fR +.P +.RE +.SH RATIONALE +Some historical implementations do not count + +characters in determining character counts with the +.BR \(mic +option. This may be useful for using +.IR cut +for processing +.IR nroff +output. It was deliberately decided not to have the +.BR \(mic +option treat either + +or + +characters in any special fashion. The +.IR fold +utility does treat these characters specially. +.P +Unlike other utilities, some historical implementations of +.IR cut +exit after not finding an input file, rather than continuing to process +the remaining +.IR file +operands. This behavior is prohibited by this volume of POSIX.1\(hy2008, where only the exit +status is affected by this problem. +.P +The behavior of +.IR cut +when provided with either mutually-exclusive options or options that do +not work logically together has been deliberately left unspecified in +favor of global wording in +.IR "Section 1.4" ", " "Utility Description Defaults". +.P +The OPTIONS section was changed in response to IEEE PASC Interpretation +1003.2 #149. The change represents historical practice on all known +systems. The original standard was ambiguous on the nature of the +output. +.P +The +.IR list +option-arguments are historically used to select the portions of the +line to be written, but do not affect the order of the data. For +example: +.sp +.RS 4 +.nf +\fB +echo abcdefghi | cut \(mic6,2,4\(mi7,1 +.fi \fR +.P +.RE +.P +yields +.BR \(dqabdefg\(dq . +.P +A proposal to enhance +.IR cut +with the following option: +.IP "\fB\(mio\fP" 6 +Preserve the selected field order. When this option is specified, each +byte, character, or field (or ranges of such) shall be written in the +order specified by the +.IR list +option-argument, even if this requires multiple outputs of the same +bytes, characters, or fields. +.P +was rejected because this type of enhancement is outside the scope of +the IEEE\ P1003.2b draft standard. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Parameters and Variables", +.IR "\fIfold\fR\^", +.IR "\fIgrep\fR\^", +.IR "\fIpaste\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/cxref.1p b/man-pages-posix-2013/man1p/cxref.1p new file mode 100644 index 0000000..a53c599 --- /dev/null +++ b/man-pages-posix-2013/man1p/cxref.1p @@ -0,0 +1,180 @@ +'\" et +.TH CXREF "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +cxref +\(em generate a C-language program cross-reference table +(\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +cxref \fB[\fR\(mics\fB] [\fR\(mio \fIfile\fB] [\fR\(miw \fInum\fB] [\fR\(miD \fIname\fB[\fR=\fIdef\fB]]\fR...\fB [\fR\(miI \fIdir\fB]\fR... + \fB[\fR\(miU \fIname\fB]\fR... \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR cxref +utility shall analyze a collection of C-language +.IR file s +and attempt to build a cross-reference table. Information from +.BR #define +lines shall be included in the symbol table. A sorted listing shall be +written to standard output of all symbols (auto, static, and global) in +each +.IR file +separately, or with the +.BR \(mic +option, in combination. Each symbol shall contain an + +before the declaring reference. +.SH OPTIONS +The +.IR cxref +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that the order of the +.BR \(miD , +.BR \(miI , +and +.BR \(miU +options (which are identical to their interpretation by +.IR c99 ) +is significant. The following options shall be supported: +.IP "\fB\(mic\fP" 10 +Write a combined cross-reference of all input files. +.IP "\fB\(mis\fP" 10 +Operate silently; do not print input filenames. +.IP "\fB\(mio\ \fIfile\fR" 10 +Direct output to named +.IR file . +.IP "\fB\(miw\ \fInum\fR" 10 +Format output no wider than +.IR num +(decimal) columns. This option defaults to 80 if +.IR num +is not specified or is less than 51. +.IP "\fB\(miD\fP" 10 +Equivalent to +.IR c99 . +.IP "\fB\(miI\fP" 10 +Equivalent to +.IR c99 . +.IP "\fB\(miU\fP" 10 +Equivalent to +.IR c99 . +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a C-language source file. +.SH STDIN +Not used. +.SH "INPUT FILES" +The input files are C-language source files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR cxref : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the ordering of the output. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall be used for the cross-reference listing, +unless the +.BR \(mio +option is used to select a different output file. +.P +The format of standard output is unspecified, except that the following +information shall be included: +.IP " *" 4 +If the +.BR \(mic +option is not specified, each portion of the listing shall start +with the name of the input file on a separate line. +.IP " *" 4 +The name line shall be followed by a sorted list of symbols, each with +its associated location pathname, the name of the function in which it +appears (if it is not a function name itself), and line number +references. +.IP " *" 4 +Each line number may be preceded by an + +(\c +.BR '*' ) +flag, meaning that this is the declaring reference. Other +single-character flags, with implementation-defined meanings, may be +included. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The output file named by the +.BR \(mio +option shall be used instead of standard output. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIc99\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/date.1p b/man-pages-posix-2013/man1p/date.1p new file mode 100644 index 0000000..52d4639 --- /dev/null +++ b/man-pages-posix-2013/man1p/date.1p @@ -0,0 +1,627 @@ +'\" et +.TH DATE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +date +\(em write the date and time +.SH SYNOPSIS +.LP +.nf +date \fB[\fR\(miu\fB] [\fR+\fIformat\fB]\fR +.P +date \fB[\fR\(miu\fB] \fImmddhhmm\fB[[\fIcc\fB]\fIyy\fB]\fR +.fi +.SH DESCRIPTION +The +.IR date +utility shall write the date and time to standard output +or attempt to set the system date and time. +By default, the current date and time shall be written. If an operand +beginning with +.BR '\(pl' +is specified, the output format of +.IR date +shall be controlled by the conversion specifications and other text +in the operand. +.SH OPTIONS +The +.IR date +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(miu\fP" 10 +Perform operations as if the +.IR TZ +environment variable was set to the string +.BR \(dqUTC0\(dq , +or its equivalent historical value of +.BR \(dqGMT0\(dq . +Otherwise, +.IR date +shall use the timezone indicated by the +.IR TZ +environment variable or the system default if that variable is +unset or null. +.SH OPERANDS +The following operands shall be supported: +.IP "+\fIformat\fR" 10 +When the format is specified, each conversion specifier shall be +replaced in the standard output by its corresponding value. All other +characters shall be copied to the output without change. The output +shall always be terminated with a +. +.SS "Conversion Specifications" +.RS 10 +.IP "\fR%a\fR" 8 +Locale's abbreviated weekday name. +.IP "\fR%A\fR" 8 +Locale's full weekday name. +.IP "\fR%b\fR" 8 +Locale's abbreviated month name. +.IP "\fR%B\fR" 8 +Locale's full month name. +.IP "\fR%c\fR" 8 +Locale's appropriate date and time representation. +.IP "\fR%C\fR" 8 +Century (a year divided by 100 and truncated to an integer) as a +decimal number [00,99]. +.IP "\fR%d\fR" 8 +Day of the month as a decimal number [01,31]. +.IP "\fR%D\fR" 8 +Date in the format \fImm\fP/\fIdd\fP/\fIyy\fR. +.IP "\fR%e\fR" 8 +Day of the month as a decimal number [1,31] in a two-digit field +with leading + +character fill. +.IP "\fR%h\fR" 8 +A synonym for +.BR %b . +.IP "\fR%H\fR" 8 +Hour (24-hour clock) as a decimal number [00,23]. +.IP "\fR%I\fR" 8 +Hour (12-hour clock) as a decimal number [01,12]. +.IP "\fR%j\fR" 8 +Day of the year as a decimal number [001,366]. +.IP "\fR%m\fR" 8 +Month as a decimal number [01,12]. +.IP "\fR%M\fR" 8 +Minute as a decimal number [00,59]. +.IP "\fR%n\fR" 8 +A +. +.IP "\fR%p\fR" 8 +Locale's equivalent of either AM or PM. +.IP "\fR%r\fR" 8 +12-hour clock time [01,12] using the AM/PM notation; in the POSIX +locale, this shall be equivalent to +.BR %I :\c +.BR %M :\c +.BR %S +.BR %p . +.IP "\fR%S\fR" 8 +Seconds as a decimal number [00,60]. +.IP "\fR%t\fR" 8 +A +. +.IP "\fR%T\fR" 8 +24-hour clock time [00,23] in the format \fIHH\fP:\fIMM\fP:\fISS\fP. +.IP "\fR%u\fR" 8 +Weekday as a decimal number [1,7] (1=Monday). +.IP "\fR%U\fR" 8 +Week of the year (Sunday as the first day of the week) as a decimal +number [00,53]. All days in a new year preceding the first Sunday +shall be considered to be in week 0. +.IP "\fR%V\fR" 8 +Week of the year (Monday as the first day of the week) as a decimal +number [01,53]. If the week containing January 1 has four or more +days in the new year, then it shall be considered week 1; otherwise, it +shall be the last week of the previous year, and the next week shall be +week 1. +.IP "\fR%w\fR" 8 +Weekday as a decimal number [0,6] (0=Sunday). +.IP "\fR%W\fR" 8 +Week of the year (Monday as the first day of the week) as a decimal +number [00,53]. All days in a new year preceding the first Monday +shall be considered to be in week 0. +.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 [00,99]. +.IP "\fR%Y\fR" 8 +Year with century as a decimal number. +.IP "\fR%Z\fR" 8 +Timezone name, or no characters if no timezone is determinable. +.IP "\fR%%\fR" 8 +A + +character. +.P +See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 7.3.5" ", " "LC_TIME" +for the conversion specifier values in the POSIX locale. +.SS "Modified Conversion Specifications" +.P +Some conversion specifiers can be modified by the +.BR E +and +.BR O +modifier characters to indicate a different format or specification as +specified in the +.IR LC_TIME +locale description (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 7.3.5" ", " "LC_TIME"). +If the corresponding keyword (see +.BR era , +.BR era_year , +.BR era_d_fmt , +and +.BR alt_digits +in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 7.3.5" ", " "LC_TIME") +is not specified or not supported for the current locale, +the unmodified conversion specifier value shall be used. +.IP "\fR%Ec\fR" 8 +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 +Locale's alternative date representation. +.IP "\fR%EX\fR" 8 +Locale's alternative time representation. +.IP "\fR%Ey\fR" 8 +Offset from +.BR %EC +(year only) in the locale's alternative representation. +.IP "\fR%EY\fR" 8 +Full alternative year representation. +.IP "\fR%Od\fR" 8 +Day of month using the locale's alternative numeric symbols. +.IP "\fR%Oe\fR" 8 +Day of month using the locale's alternative numeric symbols. +.IP "\fR%OH\fR" 8 +Hour (24-hour clock) using the locale's alternative numeric symbols. +.IP "\fR%OI\fR" 8 +Hour (12-hour clock) using the locale's alternative numeric symbols. +.IP "\fR%Om\fR" 8 +Month using the locale's alternative numeric symbols. +.IP "\fR%OM\fR" 8 +Minutes using the locale's alternative numeric symbols. +.IP "\fR%OS\fR" 8 +Seconds using the locale's alternative numeric symbols. +.IP "\fR%Ou\fR" 8 +Weekday as a number in the locale's alternative representation (Monday += 1). +.IP "\fR%OU\fR" 8 +Week number of the year (Sunday as the first day of the week) using the +locale's alternative numeric symbols. +.IP "\fR%OV\fR" 8 +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 +Weekday as a number in the locale's alternative representation (Sunday += 0). +.IP "\fR%OW\fR" 8 +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 +Year (offset from +.BR %C ) +in alternative representation. +.RE +.IP "\fImmddhhmm\fB[[\fIcc\fB]\fIyy\fB]\fR" 10 +.br +Attempt to set the system date and time from the value given in the +operand. This is only possible if the user has appropriate privileges +and the system permits the setting of the system date and time. The +first +.IR mm +is the month (number); +.IR dd +is the day (number); +.IR hh +is the hour (number, 24-hour system); the second +.IR mm +is the minute (number); +.IR cc +is the century and is the first two digits of the year (this is +optional); +.IR yy +is the last two digits of the year and is optional. If century is not +specified, then 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. The current year is the default if +.IR yy +is omitted. +.RS 10 +.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 +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR date : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILC_TIME\fP" 10 +Determine the format and contents of date and time strings written by +.IR date . +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITZ\fP" 10 +Determine the timezone in which the time and date are written, unless +the +.BR \(miu +option is specified. If the +.IR TZ +variable is unset or null and +.BR \(miu +is not specified, an unspecified system default timezone is used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +When no formatting operand is specified, the output in the POSIX locale +shall be equivalent to specifying: +.sp +.RS 4 +.nf +\fB +date "+%a %b %e %H:%M:%S %Z %Y" +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The date was written successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Conversion specifiers are of unspecified format when not in the POSIX +locale. Some of them can contain + +characters in some locales, so it may be difficult to use the format +shown in standard output for parsing the output of +.IR date +in those locales. +.P +The range of values for +.BR %S +extends from 0 to 60 seconds to accommodate the occasional leap second. +.P +Although certain of the conversion specifiers in the POSIX locale (such +as the name of the month) are shown with initial capital letters, this +need not be the case in other locales. Programs using these fields may +need to adjust the capitalization if the output is going to be used at +the beginning of a sentence. +.P +The date string formatting capabilities are intended for use in +Gregorian-style calendars, possibly with a different starting year (or +years). The +.BR %x +and +.BR %c +conversion specifications, however, are intended for local +representation; these may be based on a different, non-Gregorian +calendar. +.P +The +.BR %C +conversion specification was introduced to allow a fallback for the +.BR %EC +(alternative year format base year); it can be viewed as the base of +the current subdivision in the Gregorian calendar. The century number +is calculated as the year divided by 100 and truncated to an integer; +it should not be confused with the use of ordinal numbers for centuries +(for example, ``twenty-first century''.) Both the +.BR %Ey +and +.BR %y +can then be viewed as the offset from +.BR %EC +and +.BR %C , +respectively. +.P +The +.BR E +and +.BR O +modifiers modify the traditional conversion specifiers, so that they +can always be used, even if the implementation (or the current locale) +does not support the modifier. +.P +The +.BR E +modifier supports alternative date formats, such as the Japanese +Emperor's Era, as long as these are based on the Gregorian calendar +system. Extending the +.BR E +modifiers to other date elements may provide an implementation-defined +extension capable of supporting other calendar systems, especially in +combination with the +.BR O +modifier. +.P +The +.BR O +modifier supports time and date formats using the locale's alternative +numerical symbols, such as Kanji or Hindi digits or ordinal number +representation. +.P +Non-European locales, whether they use Latin digits in computational +items or not, often have local forms of the digits for use in date +formats. This is not totally unknown even in Europe; a variant of dates +uses Roman numerals for the months: the third day of September 1991 +would be written as 3.IX.1991. In Japan, Kanji digits are regularly +used for dates; in Arabic-speaking countries, Hindi digits are used. +The +.BR %d , +.BR %e , +.BR %H , +.BR %I , +.BR %m , +.BR %S , +.BR %U , +.BR %w , +.BR %W , +and +.BR %y +conversion specifications always return the date and time field in +Latin digits (that is, 0 to 9). The +.BR %O +modifier was introduced to support the use for display purposes of +non-Latin digits. In the +.IR LC_TIME +category in +.IR localedef , +the optional +.BR alt_digits +keyword is intended for this purpose. As an example, assume the +following (partial) +.IR localedef +source: +.sp +.RS 4 +.nf +\fB +alt_digits "";"I";"II";"III";"IV";"V";"VI";"VII";"VIII" \e + "IX";"X";"XI";"XII" +d_fmt "%e.%Om.%Y" +.fi \fR +.P +.RE +.P +With the above date, the command: +.sp +.RS 4 +.nf +\fB +date "+%x" +.fi \fR +.P +.RE +.P +would yield 3.IX.1991. With the same +.BR d_fmt , +but without the +.BR alt_digits , +the command would yield 3.9.1991. +.SH EXAMPLES +.IP " 1." 4 +The following are input/output examples of +.IR date +used at arbitrary times in the POSIX locale: +.RS 4 +.sp +.RS 4 +.nf +\fB +\fB$ \fRdate +\fBTue Jun 26 09:58:10 PDT 1990 +.P +\fB$ \fRdate "+DATE: %m/%d/%y%nTIME: %H:%M:%S" +\fBDATE: 11/02/91 +\fBTIME: 13:36:16 +.P +\fB$ \fRdate "+TIME: %r" +\fBTIME: 01:36:32 PM\fR +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +Examples for Denmark, where the default date and time format is +.BR %a +.BR %d +.BR %b +.BR %Y +.BR %T +.BR %Z : +.RS 4 +.sp +.RS 4 +.nf +\fB +\fB$ \fRLANG=da_DK.iso_8859\(mi1 date +\fBons 02 okt 1991 15:03:32 CET +.P +\fB$ \fRLANG=da_DK.iso_8859\(mi1 \e + date "+DATO: %A den %e. %B %Y%nKLOKKEN: %H:%M:%S" +\fBDATO: onsdag den 2. oktober 1991 +\fBKLOKKEN: 15:03:56\fR +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +Examples for Germany, where the default date and time format is +.BR %a +.BR %d .\c +.BR %h .\c +.BR %Y , +.BR %T +.BR %Z : +.RS 4 +.sp +.RS 4 +.nf +\fB +\fB$ \fRLANG=De_DE.88591 date +\fBMi 02.Okt.1991, 15:01:21 MEZ +.P +\fB$ \fRLANG=De_DE.88591 date "+DATUM: %A, %d. %B %Y%nZEIT: %H:%M:%S" +\fBDATUM: Mittwoch, 02. Oktober 1991 +\fBZEIT: 15:02:02\fR +.fi \fR +.P +.RE +.RE +.IP " 4." 4 +Examples for France, where the default date and time format is +.BR %a +.BR %d +.BR %h +.BR %Y +.BR %Z +.BR %T : +.RS 4 +.sp +.RS 4 +.nf +\fB +\fB$ \fRLANG=Fr_FR.88591 date +\fBMer 02 oct 1991 MET 15:03:32 +.P +\fB$ \fRLANG=Fr_FR.88591 date "+JOUR: %A %d %B %Y%nHEURE: %H:%M:%S" +\fBJOUR: Mercredi 02 octobre 1991 +\fBHEURE: 15:03:56\fR +.fi \fR +.P +.RE +.RE +.SH RATIONALE +Some of the new options for formatting are from the ISO\ C standard. The +.BR \(miu +option was introduced to allow portable access to Coordinated Universal +Time (UTC). +The string +.BR \(dqGMT0\(dq +is allowed as an equivalent +.IR TZ +value to be compatible with all of the systems using the BSD +implementation, where this option originated. +.P +The +.BR %e +format conversion specification (adopted from System V) was added +because the ISO\ C standard conversion specifications did not provide any way to +produce the historical default +.IR date +output during the first nine days of any month. +.P +There are two varieties of day and week numbering supported (in +addition to any others created with the locale-dependent +.BR %E +and +.BR %O +modifier characters): +.IP " *" 4 +The historical variety in which Sunday is the first day of the week and +the weekdays preceding the first Sunday of the year are considered week +0. These are represented by +.BR %w +and +.BR %U . +A variant of this is +.BR %W , +using Monday as the first day of the week, but still referring to week +0. This view of the calendar was retained because so many historical +applications depend on it and the ISO\ C standard +\fIstrftime\fR() +function, on which many +.IR date +implementations are based, was defined in this way. +.IP " *" 4 +The international standard, based on the ISO\ 8601:\|2004 standard where Monday is the +first weekday and the algorithm for the first week number is more +complex: If the week (Monday to Sunday) containing January 1 has four +or more days in the new year, then it is week 1; otherwise, it is week +53 of the previous year, and the next week is week 1. These are +represented by the new conversion specifications +.BR %u +and +.BR %V , +added as a result of international comments. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 7.3.5" ", " "LC_TIME", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIfprintf\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/dd.1p b/man-pages-posix-2013/man1p/dd.1p new file mode 100644 index 0000000..aedaa34 --- /dev/null +++ b/man-pages-posix-2013/man1p/dd.1p @@ -0,0 +1,769 @@ +'\" et +.TH DD "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +dd +\(em convert and copy a file +.SH SYNOPSIS +.LP +.nf +dd \fB[\fIoperand\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR dd +utility shall copy the specified input file to the specified output +file with possible conversions using specific input and output block +sizes. It shall read the input one block at a time, using the +specified input block size; it shall then process the block of data +actually returned, which could be smaller than the requested block +size. It shall apply any conversions that have been specified and write +the resulting data to the output in blocks of the specified output +block size. If the +.BR bs =\c +.IR expr +operand is specified and no conversions other than +.BR sync , +.BR noerror , +or +.BR notrunc +are requested, the data returned from each input block shall be written +as a separate output block; if the read returns less than a full block +and the +.BR sync +conversion is not specified, the resulting output block shall be the +same size as the input block. If the +.BR bs =\c +.IR expr +operand is not specified, or a conversion other than +.BR sync , +.BR noerror , +or +.BR notrunc +is requested, the input shall be processed and collected into +full-sized output blocks until the end of the input is reached. +.P +The processing order shall be as follows: +.IP " 1." 4 +An input block is read. +.IP " 2." 4 +If the input block is shorter than the specified input block size and +the +.BR sync +conversion is specified, null bytes shall be appended to the input data +up to the specified size. (If either +.BR block +or +.BR unblock +is also specified, + +characters shall be appended instead of null bytes.) The remaining +conversions and output shall include the pad characters as if they had +been read from the input. +.IP " 3." 4 +If the +.BR bs =\c +.IR expr +operand is specified and no conversion other than +.BR sync +or +.BR noerror +is requested, the resulting data shall be written to the output as a +single block, and the remaining steps are omitted. +.IP " 4." 4 +If the +.BR swab +conversion is specified, each pair of input data bytes shall be +swapped. If there is an odd number of bytes in the input block, the +last byte in the input record shall not be swapped. +.IP " 5." 4 +Any remaining conversions (\c +.BR block , +.BR unblock , +.BR lcase , +and +.BR ucase ) +shall be performed. These conversions shall operate on the input data +independently of the input blocking; an input or output fixed-length +record may span block boundaries. +.IP " 6." 4 +The data resulting from input or conversion or both shall be aggregated +into output blocks of the specified size. After the end of input is +reached, any remaining output shall be written as a block without +padding if +.BR conv =\c +.BR sync +is not specified; thus, the final output block may be shorter than the +output block size. +.SH OPTIONS +None. +.SH OPERANDS +All of the operands shall be processed before any input is read. +The following operands shall be supported: +.IP "\fBif\fR=\fIfile\fR" 10 +Specify the input pathname; the default is standard input. +.IP "\fBof\fR=\fIfile\fR" 10 +Specify the output pathname; the default is standard output. If the +.BR seek =\c +.IR expr +conversion is not also specified, the output file shall be truncated +before the copy begins if an explicit +.BR of =\c +.IR file +operand is specified, unless +.BR conv =\c +.BR notrunc +is specified. If +.BR seek =\c +.IR expr +is specified, but +.BR conv =\c +.BR notrunc +is not, the effect of the copy shall be to preserve the blocks in the +output file over which +.IR dd +seeks, but no other portion of the output file shall be preserved. (If +the size of the seek plus the size of the input file is less than the +previous size of the output file, the output file shall be shortened by +the copy. If the input file is empty and either the size of the seek is +greater than the previous size of the output file or the output file +did not previously exist, the size of the output file shall be set to +the file offset after the seek.) +.IP "\fBibs\fR=\fIexpr\fR" 10 +Specify the input block size, in bytes, by +.IR expr +(default is 512). +.IP "\fBobs\fR=\fIexpr\fR" 10 +Specify the output block size, in bytes, by +.IR expr +(default is 512). +.IP "\fBbs\fR=\fIexpr\fR" 10 +Set both input and output block sizes to +.IR expr +bytes, superseding +.BR ibs = +and +.BR obs =. +If no conversion other than +.BR sync , +.BR noerror , +and +.BR notrunc +is specified, each input block shall be copied to the output as a +single block without aggregating short blocks. +.IP "\fBcbs\fR=\fIexpr\fR" 10 +Specify the conversion block size for +.BR block +and +.BR unblock +in bytes by +.IR expr +(default is zero). If +.BR cbs = +is omitted or given a value of zero, using +.BR block +or +.BR unblock +produces unspecified results. +.RS 10 +.P +The application shall ensure that this operand is also specified if the +.BR conv = +operand is specified with a value of +.BR ascii , +.BR ebcdic , +or +.BR ibm . +For a +.BR conv = +operand with an +.BR ascii +value, the input is handled as described for the +.BR unblock +value, except that characters are converted to ASCII before any +trailing + +characters are deleted. For +.BR conv = +operands with +.BR ebcdic +or +.BR ibm +values, the input is handled as described for the +.BR block +value except that the characters are converted to EBCDIC or IBM EBCDIC, +respectively, after any trailing + +characters are added. +.RE +.IP "\fBskip\fR=\fIn\fR" 10 +Skip +.IR n +input blocks (using the specified input block size) before starting to +copy. On seekable files, the implementation shall read the blocks or +seek past them; on non-seekable files, the blocks shall be read and the +data shall be discarded. +.IP "\fBseek\fR=\fIn\fR" 10 +Skip +.IR n +blocks (using the specified output block size) from the beginning of the +output file before copying. On non-seekable files, existing blocks +shall be read and space from the current end-of-file to the specified +offset, if any, filled with null bytes; on seekable files, the +implementation shall seek to the specified offset or read the blocks as +described for non-seekable files. +.IP "\fBcount\fR=\fIn\fR" 10 +Copy only +.IR n +input blocks. +.IP "\fBconv\fR=\fIvalue\fB[\fR,\fIvalue\fR\ .\|.\|.\fB]\fR" 10 +.br +Where +.IR value s +are +-separated +symbols from the following list: +.RS 10 +.IP "\fBascii\fR" 9 +Convert EBCDIC to ASCII; see +.IR "Table 4-7, ASCII to EBCDIC Conversion". +.IP "\fBebcdic\fR" 9 +Convert ASCII to EBCDIC; see +.IR "Table 4-7, ASCII to EBCDIC Conversion". +.IP "\fBibm\fR" 9 +Convert ASCII to a different EBCDIC set; see +.IR "Table 4-8, ASCII to IBM EBCDIC Conversion". +.P +The +.BR ascii , +.BR ebcdic , +and +.BR ibm +values are mutually-exclusive. +.IP "\fBblock\fR" 9 +Treat the input as a sequence of +-terminated +or end-of-file-terminated variable-length records independent of the +input block boundaries. Each record shall be converted to a record with +a fixed length specified by the conversion block size. Any + +shall be removed from the input line; + +characters shall be appended to lines that are shorter than their +conversion block size to fill the block. Lines that are longer than +the conversion block size shall be truncated to the largest number of +characters that fit into that size; the number of truncated lines shall +be reported (see the STDERR section). +.RS 9 +.P +The +.BR block +and +.BR unblock +values are mutually-exclusive. +.RE +.IP "\fBunblock\fR" 9 +Convert fixed-length records to variable length. Read a number of bytes +equal to the conversion block size (or the number of bytes remaining in +the input, if less than the conversion block size), delete all trailing + +characters, and append a +. +.IP "\fBlcase\fR" 9 +Map uppercase characters specified by the +.IR LC_CTYPE +keyword +.BR tolower +to the corresponding lowercase character. Characters for which no +mapping is specified shall not be modified by this conversion. +.RS 9 +.P +The +.BR lcase +and +.BR ucase +symbols are mutually-exclusive. +.RE +.IP "\fBucase\fR" 9 +Map lowercase characters specified by the +.IR LC_CTYPE +keyword +.BR toupper +to the corresponding uppercase character. Characters for which no +mapping is specified shall not be modified by this conversion. +.IP "\fBswab\fR" 9 +Swap every pair of input bytes. +.IP "\fBnoerror\fR" 9 +Do not stop processing on an input error. When an input error occurs, a +diagnostic message shall be written on standard error, followed by the +current input and output block counts in the same format as used at +completion (see the STDERR section). If the +.BR sync +conversion is specified, the missing input shall be replaced with null +bytes and processed normally; otherwise, the input block shall be +omitted from the output. +.IP "\fBnotrunc\fR" 9 +Do not truncate the output file. Preserve blocks in the output +file not explicitly written by this invocation of the +.IR dd +utility. (See also the preceding +.BR of =\c +.IR file +operand.) +.IP "\fBsync\fR" 9 +Pad every input block to the size of the +.BR ibs = +buffer, appending null bytes. (If either +.BR block +or +.BR unblock +is also specified, append + +characters, rather than null bytes.) +.RE +.P +The behavior is unspecified if operands other than +.BR conv = +are specified more than once. +.P +For the +.BR bs =, +.BR cbs =, +.BR ibs =, +and +.BR obs = +operands, the application shall supply an expression specifying a size +in bytes. The expression, +.IR expr , +can be: +.IP " 1." 4 +A positive decimal number +.IP " 2." 4 +A positive decimal number followed by +.IR k , +specifying multiplication by 1\|024 +.IP " 3." 4 +A positive decimal number followed by +.IR b , +specifying multiplication by 512 +.IP " 4." 4 +Two or more positive decimal numbers (with or without +.IR k +or +.IR b ) +separated by +.IR x , +specifying the product of the indicated values +.P +All of the operands are processed before any input is read. +.P +The following two tables display the octal number character values used +for the +.BR ascii +and +.BR ebcdic +conversions (first table) and for the +.BR ibm +conversion (second table). In both tables, the ASCII values are the row +and column headers and the EBCDIC values are found at their +intersections. For example, ASCII 0012 (LF) is the second row, third +column, yielding 0045 in EBCDIC. The inverted tables (for EBCDIC to +ASCII conversion) are not shown, but are in one-to-one correspondence +with these tables. The differences between the two tables are +highlighted by small boxes drawn around five entries. +.br +.sp +.ce 1 +\fBTable 4-7: ASCII to EBCDIC Conversion\fR +.bp +.sp +.ce 1 +\fBTable 4-8: ASCII to IBM EBCDIC Conversion\fR +.SH STDIN +If no +.BR if = +operand is specified, the standard input shall be used. See the INPUT +FILES section. +.SH "INPUT FILES" +The input file can be any file type. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR dd : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files), the classification +of characters as uppercase or lowercase, and the mapping of characters +from one case to the other. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +For SIGINT, the +.IR dd +utility shall interrupt its current processing, write status +information to standard error, and exit as though terminated by +SIGINT. It shall take the standard action for all other signals; see +the ASYNCHRONOUS EVENTS section in +.IR "Section 1.4" ", " "Utility Description Defaults". +.SH STDOUT +If no +.BR of = +operand is specified, the standard output shall be used. The nature of +the output depends on the operands selected. +.SH STDERR +On completion, +.IR dd +shall write the number of input and output blocks to standard error. In +the POSIX locale the following formats shall be used: +.sp +.RS 4 +.nf +\fB +"%u+%u records in\en", <\fInumber of whole input blocks\fR>, + <\fInumber of partial input blocks\fR> +.P +"%u+%u records out\en", <\fInumber of whole output blocks\fR>, + <\fInumber of partial output blocks\fR> +.fi \fR +.P +.RE +.P +A partial input block is one for which +\fIread\fR() +returned less than the input block size. A partial output block is one +that was written with fewer bytes than specified by the output block +size. +.P +In addition, when there is at least one truncated block, the number of +truncated blocks shall be written to standard error. In the POSIX +locale, the format shall be: +.sp +.RS 4 +.nf +\fB +"%u truncated %s\en", <\fInumber of truncated blocks\fR>, "record" (if + <\fInumber of truncated blocks\fR> is one) "records" (otherwise) +.fi \fR +.P +.RE +.P +Diagnostic messages may also be written to standard error. +.SH "OUTPUT FILES" +If the +.BR of = +operand is used, the output shall be the same as described in the +STDOUT section. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The input file was copied successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If an input error is detected and the +.BR noerror +conversion has not been specified, any partial output block shall be +written to the output file, a diagnostic message shall be written, and +the copy operation shall be discontinued. If some other error is +detected, a diagnostic message shall be written and the copy operation +shall be discontinued. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The input and output block size can be specified to take advantage of +raw physical I/O. +.P +There are many different versions of the EBCDIC codesets. The ASCII and +EBCDIC conversions specified for the +.IR dd +utility perform conversions for the version specified by the tables. +.SH EXAMPLES +The following command: +.sp +.RS 4 +.nf +\fB +dd if=/dev/rmt0h of=/dev/rmt1h +.fi \fR +.P +.RE +.P +copies from tape drive 0 to tape drive 1, using a common historical +device naming convention. +.P +The following command: +.sp +.RS 4 +.nf +\fB +dd ibs=10 skip=1 +.fi \fR +.P +.RE +.P +strips the first 10 bytes from standard input. +.P +This example reads an EBCDIC tape blocked ten 80-byte EBCDIC card +images per block into the ASCII file +.BR x : +.sp +.RS 4 +.nf +\fB +dd if=/dev/tape of=x ibs=800 cbs=80 conv=ascii,lcase +.fi \fR +.P +.RE +.SH RATIONALE +The OPTIONS section is listed as ``None'' because there are no options +recognized by historical +.IR dd +utilities. Certainly, many of the operands could have been designed to +use the Utility Syntax Guidelines, which would have resulted in the +classic hyphenated option letters. In this version of this volume of POSIX.1\(hy2008, +.IR dd +retains its curious JCL-like syntax due to the large number of +applications that depend on the historical implementation. +.P +A suggested implementation technique for +.BR conv =\c +.BR noerror ,\c +.BR sync +is to zero (or +-fill, +if +.BR block ing +or +.BR unblock ing) +the input buffer before each read and to write the contents of the +input buffer to the output even after an error. In this manner, any +data transferred to the input buffer before the error was detected is +preserved. Another point is that a failed read on a regular file or a +disk generally does not increment the file offset, and +.IR dd +must then seek past the block on which the error occurred; otherwise, +the input error occurs repetitively. When the input is a magnetic tape, +however, the tape normally has passed the block containing the error +when the error is reported, and thus no seek is necessary. +.P +The default +.BR ibs = +and +.BR obs = +sizes are specified as 512 bytes because there are historical (largely +portable) scripts that assume these values. If they were left +unspecified, unusual results could occur if an implementation chose an +odd block size. +.P +Historical implementations of +.IR dd +used +\fIcreat\fR() +when processing +.BR of =\c +.IR file . +This makes the +.BR seek = +operand unusable except on special files. The +.BR conv =\c +.BR notrunc +feature was added because more recent BSD-based implementations use +\fIopen\fR() +(without O_TRUNC) instead of +\fIcreat\fR(), +but they fail to delete output file contents after the data copied. +.P +The +.IR w +multiplier (historically meaning +.IR word ), +is used in System V to mean 2 and in 4.2 BSD to mean 4. Since +.IR word +is inherently non-portable, its use is not supported by this volume of POSIX.1\(hy2008. +.P +Standard EBCDIC does not have the characters +.BR '[' +and +.BR ']' . +The values used in the table are taken from a common print train that +does contain them. Other than those characters, the print train values +are not filled in, but appear to provide some of the motivation for the +historical choice of translations reflected here. +.P +The Standard EBCDIC table provides a 1:1 translation for all 256 +bytes. +.P +The IBM EBCDIC table does not provide such a translation. The marked +cells in the tables differ in such a way that: +.IP " 1." 4 +EBCDIC 0112 (\c +.BR '\(ct' ) +and 0152 (broken pipe) do not appear in the table. +.IP " 2." 4 +EBCDIC 0137 (\c +.BR '\(no' ) +translates to/from ASCII 0236 (\c +.BR '^' ). +In the standard table, EBCDIC 0232 (no graphic) is used. +.IP " 3." 4 +EBCDIC 0241 (\c +.BR '~' ) +translates to/from ASCII 0176 (\c +.BR '~' ). +In the standard table, EBCDIC 0137 (\c +.BR '\(no' ) +is used. +.IP " 4." 4 +0255 (\c +.BR '[' ) +and 0275 (\c +.BR ']' ) +appear twice, once in the same place as for the standard table and once +in place of 0112 (\c +.BR '\(ct' ) +and 0241 (\c +.BR '~' ). +.P +In net result: +.sp +.RS +EBCDIC 0275 (\c +.BR ']' ) +displaced EBCDIC 0241 (\c +.BR '~' ) +in cell 0345. +.P +\0\0\0\0That displaced EBCDIC 0137 (\c +.BR '\(no' ) +in cell 0176. +.P +\0\0\0\0That displaced EBCDIC 0232 (no graphic) in cell 0136. +.P +\0\0\0\0That replaced EBCDIC 0152 (broken pipe) in cell 0313. +.P +EBCDIC 0255 (\c +.BR '[' ) +replaced EBCDIC 0112 (\c +.BR '\(ct' ). +.RE +.P +This translation, however, reflects historical practice that (ASCII) +.BR '~' +and +.BR '\(no' +were often mapped to each other, as were +.BR '[' +and +.BR '\(ct' ; +and +.BR ']' +and (EBCDIC) +.BR '~' . +.P +The +.BR cbs +operand is required if any of the +.BR ascii , +.BR ebcdic , +or +.BR ibm +operands are specified. For the +.BR ascii +operand, the input is handled as described for the +.BR unblock +operand except that characters are converted to ASCII before the +trailing + +characters are deleted. For the +.BR ebcdic +and +.BR ibm +operands, the input is handled as described for the +.BR block +operand except that the characters are converted to EBCDIC or IBM +EBCDIC after the trailing + +characters are added. +.P +The +.BR block +and +.BR unblock +keywords are from historical BSD practice. +.P +The consistent use of the word +.BR record +in standard error messages matches most historical practice. An +earlier version of System V used +.BR block , +but this has been updated in more recent releases. +.P +Early proposals only allowed two numbers separated by +.BR x +to be used in a product when specifying +.BR bs =, +.BR cbs =, +.BR ibs =, +and +.BR obs = +sizes. This was changed to reflect the historical practice of allowing +multiple numbers in the product as provided by Version 7 and all +releases of System V and BSD. +.P +A change to the +.BR swab +conversion is required to match historical practice and is the result +of IEEE PASC Interpretations 1003.2 #03 and #04, submitted for the +ISO\ POSIX\(hy2:\|1993 standard. +.P +A change to the handling of SIGINT is required to match historical +practice and is the result of IEEE PASC Interpretation 1003.2 #06 +submitted for the ISO\ POSIX\(hy2:\|1993 standard. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 1.4" ", " "Utility Description Defaults", +.IR "\fIsed\fR\^", +.IR "\fItr\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/delta.1p b/man-pages-posix-2013/man1p/delta.1p new file mode 100644 index 0000000..2350903 --- /dev/null +++ b/man-pages-posix-2013/man1p/delta.1p @@ -0,0 +1,342 @@ +'\" et +.TH DELTA "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +delta +\(em make a delta (change) to an SCCS file (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +delta \fB[\fR\(minps\fB] [\fR\(mig \fIlist\fB] [\fR\(mim \fImrlist\fB] [\fR\(mir \fISID\fB] [\fR\(miy\fB[\fIcomment\fB]] \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR delta +utility shall be used to permanently introduce into the named SCCS +files changes that were made to the files retrieved by +.IR get +(called the +.IR g-files , +or generated files). +.SH OPTIONS +The +.IR delta +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that the +.BR \(miy +option has an optional option-argument. This optional option-argument +shall not be presented as a separate argument. +.P +The following options shall be supported: +.IP "\fB\(mir\ \fISID\fR" 10 +Uniquely identify which delta is to be made to the SCCS file. The use +of this option shall be necessary only if two or more outstanding +.IR get +commands for editing (\c +.IR get +.BR \(mie ) +on the same SCCS file were done by the same person (login name). The +SID value specified with the +.BR \(mir +option can be either the SID specified on the +.IR get +command line or the SID to be made as reported by the +.IR get +utility; see +.IR "\fIget\fR\^". +.IP "\fB\(mis\fP" 10 +Suppress the report to standard output of the activity associated with +each +.IR file . +See the STDOUT section. +.IP "\fB\(min\fP" 10 +Specify retention of the edited +.IR g-file +(normally removed at completion of delta processing). +.IP "\fB\(mig\ \fIlist\fR" 10 +Specify a +.IR list +(see +.IR "\fIget\fR\^" +for the definition of +.IR list ) +of deltas that shall be ignored when the file is accessed at the +change level (SID) created by this delta. +.IP "\fB\(mim\ \fImrlist\fR" 10 +Specify a modification request (MR) number that the application shall +supply as the reason for creating the new delta. This shall be used if +the SCCS file has the +.BR v +flag set; see +.IR "\fIadmin\fR\^". +.RS 10 +.P +If +.BR \(mim +is not used and +.BR '\(mi' +is not specified as a file argument, and the standard input is a +terminal, the prompt described in the STDOUT section shall be written +to standard output before the standard input is read; if the standard +input is not a terminal, no prompt shall be issued. +.P +MRs in a list shall be separated by + +characters or escaped + +characters. An unescaped + +shall terminate the MR list. The escape character is +. +.P +If the +.BR v +flag has a value, it shall be taken to be the name of a program which +validates the correctness of the MR numbers. If a non-zero exit status +is returned from the MR number validation program, the +.IR delta +utility shall terminate. (It is assumed that the MR numbers were not +all valid.) +.RE +.IP "\fB\(miy\fB[\fIcomment\fB]\fR" 10 +Describe the reason for making the delta. The +.IR comment +shall be an arbitrary group of lines that would meet the definition of +a text file. Implementations shall support +.IR comment s +from zero to 512 bytes and may support longer values. A null string +(specified as either +.BR \(miy , +.BR \(miy \c +.BR \(dq\^\(dq , +or in response to a prompt for a comment) shall be considered a valid +.IR comment . +.RS 10 +.P +If +.BR \(miy +is not specified and +.BR '\(mi' +is not specified as a file argument, and the standard input is a +terminal, the prompt described in the STDOUT section shall be written +to standard output before the standard input is read; if the standard +input is not a terminal, no prompt shall be issued. An unescaped + +shall terminate the comment text. The escape character is +. +.P +The +.BR \(miy +option shall be required if the +.IR file +operand is specified as +.BR '\(mi' . +.RE +.IP "\fB\(mip\fP" 10 +Write (to standard output) the SCCS file differences before and after +the delta is applied in +.IR diff +format; see +.IR "\fIdiff\fR\^". +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an existing SCCS file or a directory. If +.IR file +is a directory, the +.IR delta +utility shall behave as though each file in the directory were +specified as a named file, except that non-SCCS files (last component +of the pathname does not begin with +.BR s. ) +and unreadable files shall be silently ignored. +.RS 10 +.P +If exactly one +.IR file +operand appears, and it is +.BR '\(mi' , +the standard input shall be read; each line of the standard input shall +be taken to be the name of an SCCS file to be processed. Non-SCCS files +and unreadable files shall be silently ignored. +.RE +.SH STDIN +The standard input shall be a text file used only in the following +cases: +.IP " *" 4 +To read an +.IR mrlist +or a +.IR comment +(see the +.BR \(mim +and +.BR \(miy +options). +.IP " *" 4 +A +.IR file +operand shall be specified as +.BR '\(mi' . +In this case, the +.BR \(miy +option must be used to specify the comment, and if the SCCS file has +the +.BR v +flag set, the +.BR \(mim +option must also be used to specify the MR list. +.SH "INPUT FILES" +Input files shall be text files whose data is to be included in the +SCCS files. If the first character of any line of an input file is + +in the POSIX locale, the results are unspecified. If this file contains +more than 99\|999 lines, the number of lines recorded in the header for +this file shall be 99\|999 for this delta. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR delta : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error, and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITZ\fP" 10 +Determine the timezone in which the time and date are written in the +SCCS file. If the +.IR TZ +variable is unset or NULL, an unspecified system default timezone is +used. +.SH "ASYNCHRONOUS EVENTS" +If SIGINT is caught, temporary files shall be cleaned up and +.IR delta +shall exit with a non-zero exit code. The standard action shall +be taken for all other signals; see +.IR "Section 1.4" ", " "Utility Description Defaults". +.SH STDOUT +The standard output shall be used only for the following messages in +the POSIX locale: +.IP " *" 4 +Prompts (see the +.BR \(mim +and +.BR \(miy +options) in the following formats: +.RS 4 +.sp +.RS 4 +.nf +\fB +"MRs? " +.P +"comments? " +.fi \fR +.P +.RE +.P +The MR prompt, if written, shall always precede the comments prompt. +.RE +.IP " *" 4 +A report of each file's activities (unless the +.BR \(mis +option is specified) in the following format: +.RS 4 +.sp +.RS 4 +.nf +\fB +"%s\en%d inserted\en%d deleted\en%d unchanged\en", <\fINew SID\fR>, + <\fInumber of lines inserted\fR>, <\fInumber of lines deleted\fR>, + <\fInumber of lines unchanged\fR> +.fi \fR +.P +.RE +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +Any SCCS files updated shall be files of an unspecified format. +.SH "EXTENDED DESCRIPTION" +.SS "System Date and Time" +.P +When a delta is added to an SCCS file, the system date and time shall +be recorded for the new delta. If a +.IR get +is performed using an SCCS file with a date recorded apparently in the +future, the behavior is unspecified. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Problems can arise if the system date and time have been modified (for +example, put forward and then back again, or unsynchronized clocks +across a network) and can also arise when different values of the +.IR TZ +environment variable are used. +.P +Problems of a similar nature can also arise for the operation of the +.IR get +utility, which records the date and time in the file body. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 1.4" ", " "Utility Description Defaults", +.IR "\fIadmin\fR\^", +.IR "\fIdiff\fR\^", +.IR "\fIget\fR\^", +.IR "\fIprs\fR\^", +.IR "\fIrmdel\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/df.1p b/man-pages-posix-2013/man1p/df.1p new file mode 100644 index 0000000..ef1579d --- /dev/null +++ b/man-pages-posix-2013/man1p/df.1p @@ -0,0 +1,332 @@ +'\" et +.TH DF "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +df +\(em report free disk space +.SH SYNOPSIS +.LP +.nf +df \fB[\fR\(mik\fB] [\fR\(miP|\(mit\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR df +utility shall write the amount of available space +and file slots +for file systems on which the invoking user has appropriate read +access. File systems shall be specified by the +.IR file +operands; when none are specified, information shall be written for all +file systems. The format of the default output from +.IR df +is unspecified, but all space figures are reported in 512-byte units, +unless the +.BR \(mik +option is specified. This output shall contain at least the file system +names, amount of available space on each of these file systems, +and, if no options other than +.BR \(mit +are specified, the number of free file slots, or +.IR inode s, +available; when +.BR \(mit +is specified, the output shall contain the total allocated space as well. +.SH OPTIONS +The +.IR df +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mik\fP" 10 +Use 1\|024-byte units, instead of the default 512-byte units, when +writing space figures. +.IP "\fB\(miP\fP" 10 +Produce output in the format described in the STDOUT section. +.IP "\fB\(mit\fP" 10 +Include total allocated-space figures in the output. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file within the hierarchy of the desired file system. +If a file other than a FIFO, a regular file, a directory, +or a special file representing the device containing the file system +(for example, +.BR /dev/dsk/0s1 ) +is specified, the results are unspecified. If the +.IR file +operand names a file other than a special file containing a file +system, +.IR df +shall write the amount of free space in the file system containing the +specified +.IR file +operand. +Otherwise, +.IR df +shall write the amount of free space in that file system. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR df : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +When both the +.BR \(mik +and +.BR \(miP +options are specified, the following header line shall be written (in +the POSIX locale): +.sp +.RS 4 +.nf +\fB +"Filesystem 1024-blocks Used Available Capacity Mounted on\en" +.fi \fR +.P +.RE +.P +When the +.BR \(miP +option is specified without the +.BR \(mik +option, the following header line shall be written (in the POSIX +locale): +.sp +.RS 4 +.nf +\fB +"Filesystem 512-blocks Used Available Capacity Mounted on\en" +.fi \fR +.P +.RE +.P +The implementation may adjust the spacing of the header line and the +individual data lines so that the information is presented in orderly +columns. +.P +The remaining output with +.BR \(miP +shall consist of one line of information for each specified +file system. These lines shall be formatted as follows: +.sp +.RS 4 +.nf +\fB +"%s %d %d %d %d%% %s\en", <\fIfile system name\fR>, <\fItotal space\fR>, + <\fIspace used\fR>, <\fIspace free\fR>, <\fIpercentage used\fR>, + <\fIfile system root\fR> +.fi \fR +.P +.RE +.P +In the following list, all quantities expressed in 512-byte units +(1\|024-byte when +.BR \(mik +is specified) shall be rounded up to the next higher unit. The fields +are: +.IP "<\fIfile\ system\ name\fP>" 10 +.br +The name of the file system, in an implementation-defined format. +.IP "<\fItotal\ space\fP>" 10 +The total size of the file system in 512-byte units. The exact meaning +of this figure is implementation-defined, but should include +<\fIspace\ used\fP>, <\fIspace\ free\fP>, plus any space reserved by +the system not normally available to a user. +.IP "<\fIspace\ used\fP>" 10 +The total amount of space allocated to existing files in the +file system, in 512-byte units. +.IP "<\fIspace\ free\fP>" 10 +The total amount of space available within the file system for the +creation of new files by unprivileged users, in 512-byte units. When +this figure is less than or equal to zero, it shall not be possible to +create any new files on the file system without first deleting others, +unless the process has appropriate privileges. The figure written may +be less than zero. +.IP "<\fIpercentage\ used\fP>" 10 +.br +The percentage of the normally available space that is currently +allocated to all files on the file system. This shall be calculated +using the fraction: +.RS 10 +.sp +.RS 4 +.nf +\fB +<\fIspace used\fR>/( <\fIspace used\fR>+ <\fIspace free\fR>) +.fi \fR +.P +.RE +.P +expressed as a percentage. This percentage may be greater than 100 if +<\fIspace\ free\fP> is less than zero. The percentage value shall be +expressed as a positive integer, with any fractional result causing it +to be rounded to the next highest integer. +.RE +.IP "<\fIfile\ system\ root\fP>" 10 +.br +The directory below which the file system hierarchy appears. +.P +The output format is unspecified when +.BR \(mit +is used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +On most systems, the ``name of the file system, in an +implementation-defined format'' is the special file on which the +file system is mounted. +.P +On large file systems, the calculation specified for percentage used +can create huge rounding errors. +.SH EXAMPLES +.IP " 1." 4 +The following example writes portable information about the +.BR /usr +file system: +.RS 4 +.sp +.RS 4 +.nf +\fB +df \(miP /usr +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +Assuming that +.BR /usr/src +is part of the +.BR /usr +file system, the following produces the same output as the previous +example: +.RS 4 +.sp +.RS 4 +.nf +\fB +df \(miP /usr/src +.fi \fR +.P +.RE +.RE +.SH RATIONALE +The behavior of +.IR df +with the +.BR \(miP +option is the default action of the 4.2 BSD +.IR df +utility. The uppercase +.BR \(miP +was selected to avoid collision with a known industry extension using +.BR \(mip . +.P +Historical +.IR df +implementations vary considerably in their default output. It was +therefore necessary to describe the default output in a loose manner to +accommodate all known historical implementations and to add a portable +option (\c +.BR \(miP ) +to provide information in a portable format. +.P +The use of 512-byte units is historical practice and maintains +compatibility with +.IR ls +and other utilities in this volume of POSIX.1\(hy2008. This does not mandate that the +file system itself be based on 512-byte blocks. The +.BR \(mik +option was added as a compromise measure. It was agreed by the standard +developers that 512 bytes was the best default unit because of its +complete historical consistency on System V (\fIversus\fP the mixed +512/1\|024-byte usage on BSD systems), and that a +.BR \(mik +option to switch to 1\|024-byte units was a good compromise. Users who +prefer the more logical 1\|024-byte quantity can easily alias +.IR df +to +.IR df +.BR \(mik +without breaking many historical scripts relying on the 512-byte +units. +.P +It was suggested that +.IR df +and the various related utilities be modified to access a +.IR BLOCKSIZE +environment variable to achieve consistency and user acceptance. Since +this is not historical practice on any system, it is left as a possible +area for system extensions and will be re-evaluated in a future version +if it is widely implemented. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfind\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/diff.1p b/man-pages-posix-2013/man1p/diff.1p new file mode 100644 index 0000000..d41c898 --- /dev/null +++ b/man-pages-posix-2013/man1p/diff.1p @@ -0,0 +1,1001 @@ +'\" et +.TH DIFF "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +diff +\(em compare two files +.SH SYNOPSIS +.LP +.nf +diff \fB[\fR\(mic|\(mie|\(mif|\(miu|\(miC \fIn\fR|\(miU \fIn\fB] [\fR\(mibr\fB] \fIfile1 file2\fR +.fi +.SH DESCRIPTION +The +.IR diff +utility shall compare the contents of +.IR file1 +and +.IR file2 +and write to standard output a list of changes necessary to convert +.IR file1 +into +.IR file2 . +This list should be minimal. No output shall be produced if the files +are identical. +.SH OPTIONS +The +.IR diff +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mib\fP" 10 +Cause any amount of white space at the end of a line to be treated as a +single + +(that is, the white-space characters preceding the + +are ignored) and other strings of white-space characters, not including + +characters, to compare equal. +.IP "\fB\(mic\fP" 10 +Produce output in a form that provides three lines of copied context. +.IP "\fB\(miC\ \fIn\fR" 10 +Produce output in a form that provides +.IR n +lines of copied context (where +.IR n +shall be interpreted as a positive decimal integer). +.IP "\fB\(mie\fP" 10 +Produce output in a form suitable as input for the +.IR ed +utility, which can then be used to convert +.IR file1 +into +.IR file2 . +.IP "\fB\(mif\fP" 10 +Produce output in an alternative form, similar in format to +.BR \(mie , +but not intended to be suitable as input for the +.IR ed +utility, and in the opposite order. +.IP "\fB\(mir\fP" 10 +Apply +.IR diff +recursively to files and directories of the same name when +.IR file1 +and +.IR file2 +are both directories. +.RS 10 +.P +The +.IR diff +utility shall detect infinite loops; that is, entering a previously +visited directory that is an ancestor of the last file encountered. +When it detects an infinite loop, +.IR diff +shall write a diagnostic message to standard error and shall either +recover its position in the hierarchy or terminate. +.RE +.IP "\fB\(miu\fP" 10 +Produce output in a form that provides three lines of unified context. +.IP "\fB\(miU\ \fIn\fR" 10 +Produce output in a form that provides +.IR n +lines of unified context (where +.IR n +shall be interpreted as a non-negative decimal integer). +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile1\fR,\ \fIfile2\fR" 10 +A pathname of a file to be compared. If either the +.IR file1 +or +.IR file2 +operand is +.BR '\(mi' , +the standard input shall be used in its place. +.P +If both +.IR file1 +and +.IR file2 +are directories, +.IR diff +shall not compare block special files, character special files, or FIFO +special files to any files and shall not compare regular files to +directories. +Further details are as specified in +.IR "Diff Directory Comparison Format". +The behavior of +.IR diff +on other file types is implementation-defined when found in directories. +.P +If only one of +.IR file1 +and +.IR file2 +is a directory, +.IR diff +shall be applied to the non-directory file and the file contained in +the directory file with a filename that is the same as the last +component of the non-directory file. +.SH STDIN +The standard input shall be used only if one of the +.IR file1 +or +.IR file2 +operands references standard input. See the INPUT FILES section. +.SH "INPUT FILES" +The input files may be of any type. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR diff : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fILC_TIME\fP" 10 +Determine the locale for affecting the format of file timestamps +written with the +.BR \(miC +and +.BR \(mic +options. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITZ\fP" 10 +Determine the timezone used for calculating file timestamps written +with a context format. If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +.SS "Diff Directory Comparison Format" +.P +If both +.IR file1 +and +.IR file2 +are directories, the following output formats shall be used. +.P +In the POSIX locale, each file that is present in only one directory +shall be reported using the following format: +.sp +.RS 4 +.nf +\fB +"Only in %s: %s\en", <\fIdirectory pathname\fP>, <\fIfilename\fR> +.fi \fR +.P +.RE +.P +In the POSIX locale, subdirectories that are common to the two +directories may be reported with the following format: +.sp +.RS 4 +.nf +\fB +"Common subdirectories: %s and %s\en", <\fIdirectory1 pathname\fR>, + <\fIdirectory2 pathname\fR> +.fi \fR +.P +.RE +.P +For each file common to the two directories, if the two files are not to +be compared: if the two files have the same device ID and file +serial number, or are both block special files that refer to the +same device, or are both character special files that refer to the +same device, in the POSIX locale the output format is unspecified. +Otherwise, in the POSIX locale an unspecified format shall be used +that contains the pathnames of the two files. +.P +For each file common to the two directories, if the files are +compared and are identical, no output shall be written. If the two +files differ, the following format is written: +.sp +.RS 4 +.nf +\fB +"diff %s %s %s\en", <\fIdiff_options\fR>, <\fIfilename1\fR>, <\fIfilename2\fR> +.fi \fR +.P +.RE +.P +where <\fIdiff_options\fP> are the options as specified on the command +line. +.P +All directory pathnames listed in this section shall be relative to the +original command line arguments. All other names of files listed in +this section shall be filenames (pathname components). +.SS "Diff Binary Output Format" +.P +In the POSIX locale, if one or both of the files being compared are not +text files, it is implementation-defined whether +.IR diff +uses the binary file output format or the other formats as specified +below. The binary file output format shall contain the pathnames of +two files being compared and the string +.BR \(dqdiffer\(dq . +.P +If both files being compared are text files, depending on the options +specified, one of the following formats shall be used to write the +differences. +.SS "Diff Default Output Format" +.P +The default (without +.BR \(mie , +.BR \(mif , +.BR \(mic , +.BR \(miC , +.BR \(miu , +or +.BR \(miU +options) +.IR diff +utility output shall contain lines of these forms: +.sp +.RS 4 +.nf +\fB +"%da%d\en", <\fInum1\fR>, <\fInum2\fR> +.P +"%da%d,%d\en", <\fInum1\fR>, <\fInum2\fR>, <\fInum3\fR> +.P +"%dd%d\en", <\fInum1\fR>, <\fInum2\fR> +.P +"%d,%dd%d\en", <\fInum1\fR>, <\fInum2\fR>, <\fInum3\fR> +.P +"%dc%d\en", <\fInum1\fR>, <\fInum2\fR> +.P +"%d,%dc%d\en", <\fInum1\fR>, <\fInum2\fR>, <\fInum3\fR> +.P +"%dc%d,%d\en", <\fInum1\fR>, <\fInum2\fR>, <\fInum3\fR> +.P +"%d,%dc%d,%d\en", <\fInum1\fR>, <\fInum2\fR>, <\fInum3\fR>, <\fInum4\fR> +.fi \fR +.P +.RE +.P +These lines resemble +.IR ed +subcommands to convert +.IR file1 +into +.IR file2 . +The line numbers before the action letters shall pertain to +.IR file1 ; +those after shall pertain to +.IR file2 . +Thus, by exchanging +.IR a +for +.IR d +and reading the line in reverse order, one can also determine how to +convert +.IR file2 +into +.IR file1 . +As in +.IR ed , +identical pairs (where +.IR num1 = +.IR num2 ) +are abbreviated as a single number. +.P +Following each of these lines, +.IR diff +shall write to standard output all lines affected in the first +file using the format: +.sp +.RS 4 +.nf +\fB +"< %s", <\fIline\fR> +.fi \fR +.P +.RE +.P +and all lines affected in the second file using the format: +.sp +.RS 4 +.nf +\fB +"> %s", <\fIline\fR> +.fi \fR +.P +.RE +.P +If there are lines affected in both +.IR file1 +and +.IR file2 +(as with the +.BR c +subcommand), the changes are separated with a line consisting of three + +characters: +.sp +.RS 4 +.nf +\fB +"\(mi\|\(mi\|\(mi\en" +.fi \fR +.P +.RE +.SS "Diff \(mie Output Format" +.P +With the +.BR \(mie +option, a script shall be produced that shall, when provided as input +to +.IR ed , +along with an appended +.BR w +(write) command, convert +.IR file1 +into +.IR file2 . +Only the +.BR a +(append), +.BR c +(change), +.BR d +(delete), +.BR i +(insert), and +.BR s +(substitute) commands of +.IR ed +shall be used in this script. Text lines, except those consisting of +the single character + +(\c +.BR '.' ), +shall be output as they appear in the file. +.SS "Diff \(mif Output Format" +.P +With the +.BR \(mif +option, an alternative format of script shall be produced. It is +similar to that produced by +.BR \(mie , +with the following differences: +.IP " 1." 4 +It is expressed in reverse sequence; the output of +.BR \(mie +orders changes from the end of the file to the beginning; the +.BR \(mif +from beginning to end. +.IP " 2." 4 +The command form <\fIlines\fP> <\fIcommand-letter\fR> used by +.BR \(mie +is reversed. For example, 10\fIc\fP with +.BR \(mie +would be +.IR c 10 +with +.BR \(mif . +.IP " 3." 4 +The form used for ranges of line numbers is +-separated, +rather than +-separated. +.SS "Diff \(mic or \(miC Output Format" +.P +With the +.BR \(mic +or +.BR \(miC +option, the output format shall consist of affected lines along with +surrounding lines of context. The affected lines shall show which ones +need to be deleted or changed in +.IR file1 , +and those added from +.IR file2 . +With the +.BR \(mic +option, three lines of context, if available, shall be written before +and after the affected lines. With the +.BR \(miC +option, the user can specify how many lines of context are written. +The exact format follows. +.P +The name and last modification time of each file shall be output in the +following format: +.sp +.RS 4 +.nf +\fB +"*** %s %s\en", \fIfile1\fR, <\fIfile1 timestamp\fR> +"\(mi\|\(mi\|\(mi %s %s\en", \fIfile2\fR, <\fIfile2 timestamp\fR> +.fi \fR +.P +.RE +.P +Each <\fIfile\fP> field shall be the pathname of the corresponding +file being compared. The pathname written for standard input is +unspecified. +.P +In the POSIX locale, each <\fItimestamp\fP> field shall be equivalent +to the output from the following command: +.sp +.RS 4 +.nf +\fB +date "+%a %b %e %T %Y" +.fi \fR +.P +.RE +.P +without the trailing +, +executed at the time of last modification of the corresponding file (or +the current time, if the file is standard input). +.P +Then, the following output formats shall be applied for every set of +changes. +.P +First, a line shall be written in the following format: +.sp +.RS 4 +.nf +\fB +"***************\en" +.fi \fR +.P +.RE +.P +Next, the range of lines in +.IR file1 +shall be written in the following format if the range contains +two or more lines: +.sp +.RS 4 +.nf +\fB +"*** %d,%d ****\en", <\fIbeginning line number\fR>, <\fIending line number\fR> +.fi \fR +.P +.RE +.P +and the following format otherwise: +.sp +.RS 4 +.nf +\fB +"*** %d ****\en", <\fIending line number\fR> +.fi \fR +.P +.RE +.P +The ending line number of an empty range shall be the number of the +preceding line, or 0 if the range is at the start of the file. +.P +Next, the affected lines along with lines of context (unaffected lines) +shall be written. Unaffected lines shall be written in the following +format: +.sp +.RS 4 +.nf +\fB +" %s", <\fIunaffected_line\fR> +.fi \fR +.P +.RE +.P +Deleted lines shall be written as: +.sp +.RS 4 +.nf +\fB +"\(mi %s", <\fIdeleted_line\fR> +.fi \fR +.P +.RE +.P +Changed lines shall be written as: +.sp +.RS 4 +.nf +\fB +"! %s", <\fIchanged_line\fR> +.fi \fR +.P +.RE +.P +Next, the range of lines in +.IR file2 +shall be written in the following format if the range contains two +or more lines: +.sp +.RS 4 +.nf +\fB +"\(mi\|\(mi\|\(mi %d,%d \(mi\|\(mi\|\(mi\|\(mi\en", <\fIbeginning line number\fR>, <\fIending line number\fR> +.fi \fR +.P +.RE +.P +and the following format otherwise: +.sp +.RS 4 +.nf +\fB +"\(mi\|\(mi\|\(mi %d \(mi\|\(mi\|\(mi\|\(mi\en", <\fIending line number\fR> +.fi \fR +.P +.RE +.P +Then, lines of context and changed lines shall be written as described in +the previous formats. Lines added from +.IR file2 +shall be written in the following format: +.sp +.RS 4 +.nf +\fB +"+ %s", <\fIadded_line\fR> +.fi \fR +.P +.RE +.SS "Diff \(miu or \(miU Output Format" +.P +The +.BR \(miu +or +.BR \(miU +options behave like the +.BR \(mic +or +.BR \(miC +options, except that the context lines are not repeated; instead, +the context, deleted, and added lines are shown together, interleaved. +The exact format follows. +.P +The name and last modification time of each file shall be output +in the following format: +.sp +.RS 4 +.nf +\fB +"--- %s\t%s%s %s\n", file1, , , +"+++ %s\t%s%s %s\n", file2, , , +.fi \fR +.P +.RE +.P +Each <\fIfile\fR> field shall be the pathname of the corresponding file +being compared, or the single character +.BR '\(mi' +if standard input is being compared. However, if the pathname contains +a + +or a +, +or if it does not consist entirely of characters taken +from the portable character set, the behavior is implementation-defined. +.P +Each <\fItimestamp\fR> field shall be equivalent to the output from the +following command: +.sp +.RS 4 +.nf +\fB +date '+%Y-%m-%d %H:%M:%S' +.fi \fR +.P +.RE +.P +without the trailing +, +executed at the time of last modification of the corresponding file +(or the current time, if the file is standard input). +.P +Each <\fIfrac\fR> field shall be either empty, or a decimal point +followed by at least one decimal digit, indicating the +fractional-seconds part (if any) of the file timestamp. The +number of fractional digits shall be at least the number needed to +represent the file's timestamp without loss of information. +.P +Each <\fIzone\fR> field shall be of the form +.BR \(dqshhmm\(dq , +where +.BR \(dqshh\(dq +is a signed two-digit decimal number in the range \(mi24 through +25, and +.BR \(dqmm\(dq +is an unsigned two-digit decimal number in the range 00 through 59. +It represents the timezone of the timestamp as the number of hours +(hh) and minutes (mm) east (+) or west (\(mi) of UTC for the timestamp. +If the hours and minutes are both zero, the sign shall be +.BR '+' . +However, if the timezone is not an integral number of minutes away +from UTC, the <\fIzone\fR> field is implementation-defined. +.P +Then, the following output formats shall be applied for every set +of changes. +.P +First, the range of lines in each file shall be written in the +following format: +.sp +.RS 4 +.nf +\fB +"@@ -%s +%s @@", , +.fi \fR +.P +.RE +.P +Each <\fIrange\fR> field shall be of the form: +.sp +.RS 4 +.nf +\fB +"%1d", +.fi \fR +.P +.RE +.P +if the range contains exactly one line, and: +.sp +.RS 4 +.nf +\fB +"%1d,%1d", , +.fi \fR +.P +.RE +.P +otherwise. If a range is empty, its beginning line number shall be +the number of the line just before the range, or 0 if the empty +range starts the file. +.P +Next, the affected lines along with lines of context shall be written. +Each non-empty unaffected line shall be written in the following format: +.sp +.RS 4 +.nf +\fB +" %s", +.fi \fR +.P +.RE +.P +where the contents of the unaffected line shall be taken from +.IR file1 . +It is implementation-defined whether an empty unaffected line is written +as an empty line or a line containing a single + +character. This line also represents the same line of +.IR file2 , +even though +.IR file2 's +line may contain different contents due to the +.BR \(mib . +Deleted lines shall be written as: +.sp +.RS 4 +.nf +\fB +"-%s", +.fi \fR +.P +.RE +.P +Added lines shall be written as: +.sp +.RS 4 +.nf +\fB +"+%s", +.fi \fR +.P +.RE +.P +The order of lines written shall be the same as that of the +corresponding file. A deleted line shall never be written +immediately after an added line. +.P +If +.BR \(miU +.IR n +is specified, the output shall contain no more than +.IR n +consecutive unaffected lines; and if the output contains an +affected line and this line is adjacent to up to +.IR n +consecutive unaffected lines in the corresponding file, the output shall +contain these unaffected lines. +.BR \(miu +shall act like +.BR \(miU 3. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +No differences were found. +.IP "\01" 6 +Differences were found. +.IP >1 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +If lines at the end of a file are changed and other lines are added, +.IR diff +output may show this as a delete and add, as a change, or as a change +and add; +.IR diff +is not expected to know which happened and users should not care about +the difference in output as long as it clearly shows the differences +between the files. +.SH EXAMPLES +If +.BR dir1 +is a directory containing a directory named +.BR x , +.BR dir2 +is a directory containing a directory named +.BR x , +.BR dir1/x +and +.BR dir2/x +both contain files named +.BR date.out , +and +.BR dir2/x +contains a file named +.BR y , +the command: +.sp +.RS 4 +.nf +\fB +diff \(mir dir1 dir2 +.fi \fR +.P +.RE +.P +could produce output similar to: +.sp +.RS 4 +.nf +\fB +Common subdirectories: dir1/x and dir2/x +Only in dir2/x: y +diff \(mir dir1/x/date.out dir2/x/date.out +1c1 +< Mon Jul 2 13:12:16 PDT 1990 +\(mi\|\(mi\|\(mi +> Tue Jun 19 21:41:39 PDT 1990 +.fi \fR +.P +.RE +.SH RATIONALE +The +.BR \(mih +option was omitted because it was insufficiently specified and does not +add to applications portability. +.P +Historical implementations employ algorithms that do not always produce +a minimum list of differences; the current language about making every +effort is the best this volume of POSIX.1\(hy2008 can do, as there is no metric that could be +employed to judge the quality of implementations against any and all +file contents. The statement ``This list should be minimal'' clearly +implies that implementations are not expected to provide the following +output when comparing two 100-line files that differ in only one +character on a single line: +.sp +.RS 4 +.nf +\fB +1,100c1,100 +all 100 lines from file1 preceded with "< " +\(mi\|\(mi\|\(mi +all 100 lines from file2 preceded with "> " +.fi \fR +.P +.RE +.P +The ``Only in'' messages required when the +.BR \(mir +option is specified are not used by most historical implementations if +the +.BR \(mie +option is also specified. It is required here because it provides +useful information that must be provided to update a target directory +hierarchy to match a source hierarchy. The ``Common subdirectories'' +messages are written by System V and 4.3 BSD when the +.BR \(mir +option is specified. They are allowed here but are not required because +they are reporting on something that is the same, not reporting a +difference, and are not needed to update a target hierarchy. +.P +The +.BR \(mic +option, which writes output in a format using lines of context, has +been included. The format is useful for a variety of reasons, among +them being much improved readability and the ability to understand +difference changes when the target file has line numbers that differ +from another similar, but slightly different, copy. The +.IR patch +utility is most valuable when working with difference listings using +a context format. The BSD version of +.BR \(mic +takes an optional argument specifying the amount of context. Rather +than overloading +.BR \(mic +and breaking the Utility Syntax Guidelines for +.IR diff , +the standard developers decided to add a separate option for specifying +a context diff with a specified amount of context (\c +.BR \(miC ). +Also, the format for context +.IR diff s +was extended slightly in 4.3 BSD to allow multiple changes that are +within context lines from each other to be merged together. The output +format contains an additional four + +characters after the range of affected lines in the first filename. This +was to provide a flag for old programs (like old versions of +.IR patch ) +that only understand the old context format. The version of context +described here does not require that multiple changes within context +lines be merged, but it does not prohibit it either. The extension is +upwards-compatible, so any vendors that wish to retain the old version +of +.IR diff +can do so by adding the extra four + +characters (that is, utilities that currently use +.IR diff +and understand the new merged format will also understand the old +unmerged format, but not \fIvice versa\fP). +.P +The +.BR \(miu +and +.BR \(miU +options of GNU +.IR diff +have been included. Their output format, designed by Wayne Davison, +takes up less space than +.BR \(mic +and +.BR \(miC +format, and in many cases is easier to read. The format's timestamps +do not vary by locale, so +.IR LC_TIME +does not affect it. The format's line numbers are rendered with the +.BR %1d +format, not +.BR %d , +because the file format notation rules would allow extra + +characters to appear around the numbers. +.P +The substitute command was added as an additional format for the +.BR \(mie +option. This was added to provide implementations with a way to fix the +classic ``dot alone on a line'' bug present in many versions of +.IR diff . +Since many implementations have fixed this bug, the standard developers +decided not to standardize broken behavior, but rather to provide the +necessary tool for fixing the bug. One way to fix this bug is to output +two periods whenever a lone period is needed, then terminate the append +command with a period, and then use the substitute command to convert +the two periods into one period. +.P +The BSD-derived +.BR \(mir +option was added to provide a mechanism for using +.IR diff +to compare two file system trees. This behavior is useful, is standard +practice on all BSD-derived systems, and is not easily reproducible +with the +.IR find +utility. +.P +The requirement that +.IR diff +not compare files in some circumstances, even though they have the same +name, is based on the actual output of historical implementations. +The specified behavior precludes the problems arising from running +into FIFOs and other files that would cause +.IR diff +to hang waiting for input with no indication to the user that +.IR diff +was hung. An earlier version of this standard specified the output +format more precisely, but in practice this requirement was widely +ignored and the benefit of standardization seemed small, so it is now +unspecified. In most common usage, +.IR diff +.BR \(mir +should indicate differences in the file hierarchies, not the difference +of contents of devices pointed to by the hierarchies. +.P +Many early implementations of +.IR diff +require seekable files. Since the System Interfaces volume of POSIX.1\(hy2008 supports named pipes, the +standard developers decided that such a restriction was unreasonable. +Note also that the allowed filename +.BR \(mi +almost always refers to a pipe. +.P +No directory search order is specified for +.IR diff . +The historical ordering is, in fact, not optimal, in that it prints out +all of the differences at the current level, including the statements +about all common subdirectories before recursing into those +subdirectories. +.P +The message: +.sp +.RS 4 +.nf +\fB +"diff %s %s %s\en", <\fIdiff_options\fP>, <\fIfilename1\fP>, <\fIfilename2\fP> +.fi \fR +.P +.RE +.P +does not vary by locale because it is the representation of a command, +not an English sentence. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcmp\fR\^", +.IR "\fIcomm\fR\^", +.IR "\fIed\fR\^", +.IR "\fIfind\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/dirname.1p b/man-pages-posix-2013/man1p/dirname.1p new file mode 100644 index 0000000..6e1e187 --- /dev/null +++ b/man-pages-posix-2013/man1p/dirname.1p @@ -0,0 +1,260 @@ +'\" et +.TH DIRNAME "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 return the directory portion of a pathname +.SH SYNOPSIS +.LP +.nf +dirname \fIstring\fR +.fi +.SH DESCRIPTION +The +.IR string +operand shall be treated as a pathname, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.267" ", " "Pathname". +The string +.IR string +shall be converted to the name of the directory containing the +filename corresponding to the last pathname component in +.IR string , +performing actions equivalent to the following steps in order: +.IP " 1." 4 +If +.IR string +is +.BR // , +skip steps 2 to 5. +.IP " 2." 4 +If +.IR string +consists entirely of + +characters, +.IR string +shall be set to a single + +character. In this case, skip steps 3 to 8. +.IP " 3." 4 +If there are any trailing + +characters in +.IR string , +they shall be removed. +.IP " 4." 4 +If there are no + +characters remaining in +.IR string , +.IR string +shall be set to a single + +character. In this case, skip steps 5 to 8. +.IP " 5." 4 +If there are any trailing non-\c + +characters in +.IR string , +they shall be removed. +.IP " 6." 4 +If the remaining +.IR string +is +.BR // , +it is implementation-defined whether steps 7 and 8 are skipped or +processed. +.IP " 7." 4 +If there are any trailing + +characters in +.IR string , +they shall be removed. +.IP " 8." 4 +If the remaining +.IR string +is empty, +.IR string +shall be set to a single + +character. +.P +The resulting string shall be written to standard output. +.SH OPTIONS +None. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIstring\fR" 10 +A string. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR dirname : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR dirname +utility shall write a line to the standard output in the following +format: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIresulting string\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The definition of +.IR pathname +specifies implementation-defined behavior for pathnames starting with +two + +characters. Therefore, applications shall not arbitrarily add + +characters to the beginning of a pathname unless they can ensure +that there are more or less than two or are prepared to deal with the +implementation-defined consequences. +.SH EXAMPLES +.TS +center tab(@) box; +cB | cB +l | l. +Command@Results +_ +\fIdirname\fR /@/ +\fIdirname\fR //@/ or // +\fIdirname\fR /\fIa\fR/\fIb\fR/@/\fIa\fR +\fIdirname\fR //\fIa\fR//\fIb\fR//@//\fIa\fR +\fIdirname\fR@Unspecified +\fIdirname a\fR@. ($? = 0) +\fIdirname\fR ""@. ($? = 0) +\fIdirname\fR /\fIa\fR@/ +\fIdirname\fR /\fIa\fR/\fIb\fR@/\fIa\fR +\fIdirname\fR \fIa\fR/\fIb\fR@\fIa\fR +.TE +.P +See also the examples for the +.IR basename +utility. +.SH RATIONALE +The +.IR dirname +utility originated in System III. It has evolved through the System V +releases to a version that matches the requirements specified in this +description in System V Release 3. 4.3 BSD and earlier versions did +not include +.IR dirname . +.P +The behaviors of +.IR basename +and +.IR dirname +in this volume of POSIX.1\(hy2008 have been coordinated so that when +.IR string +is a valid pathname: +.sp +.RS 4 +.nf +\fB +$(basename -- "\fIstring\fP") +.fi \fR +.P +.RE +.P +would be a valid filename for the file in the directory: +.sp +.RS 4 +.nf +\fB +$(dirname -- "\fIstring\fP") +.fi \fR +.P +.RE +.P +This would not work for the versions of these utilities in early proposals +due to the way processing of trailing + +characters was specified. Consideration was given to leaving processing +unspecified if there were trailing + +characters, but this cannot be done; the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.267" ", " "Pathname" +allows trailing + +characters. The +.IR basename +and +.IR dirname +utilities have to specify consistent handling for all valid pathnames. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Parameters and Variables", +.IR "\fIbasename\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.267" ", " "Pathname", +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/dot.1p b/man-pages-posix-2013/man1p/dot.1p new file mode 100644 index 0000000..5d2c527 --- /dev/null +++ b/man-pages-posix-2013/man1p/dot.1p @@ -0,0 +1,116 @@ +'\" et +.TH DOT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +dot +\(em execute commands in the current environment +.SH SYNOPSIS +.LP +.nf +\&. \fIfile\fR +.fi +.SH DESCRIPTION +The shell shall execute commands from the +.IR file +in the current environment. +.P +If +.IR file +does not contain a +, +the shell shall use the search path specified by +.IR PATH +to find the directory containing +.IR file . +Unlike normal command search, however, the file searched for by the +.IR dot +utility need not be executable. If no readable file is found, a +non-interactive shell shall abort; an interactive shell shall write a +diagnostic message to standard error, but this condition shall not be +considered a syntax error. +.SH OPTIONS +None. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +See the DESCRIPTION. +.SH "ENVIRONMENT VARIABLES" +See the DESCRIPTION. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +If no readable file was found or if the commands in the file could not +be parsed, and the shell is interactive (and therefore does not abort; see +.IR "Section 2.8.1" ", " "Consequences of Shell Errors"), +the exit status shall be non-zero. Otherwise, return the value of the +last command executed, or a zero exit status if no command is executed. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +.LP +.nf +cat foobar +\fBfoo=hello bar=world\fR +\&. ./foobar +echo $foo $bar +\fBhello world\fR +.fi +.SH "RATIONALE" +Some older implementations searched the current directory for the +.IR file , +even if the value of +.IR PATH +disallowed it. This behavior was omitted from this volume of POSIX.1\(hy2008 due to concerns +about introducing the susceptibility to trojan horses that the user +might be trying to avoid by leaving +.BR dot +out of +.IR PATH . +.P +The KornShell version of +.IR dot +takes optional arguments that are set to the positional parameters. +This is a valid extension that allows a +.IR dot +script to behave identically to a function. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities", +.IR "\fIreturn\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/du.1p b/man-pages-posix-2013/man1p/du.1p new file mode 100644 index 0000000..cf0854a --- /dev/null +++ b/man-pages-posix-2013/man1p/du.1p @@ -0,0 +1,279 @@ +'\" et +.TH DU "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +du +\(em estimate file space usage +.SH SYNOPSIS +.LP +.nf +du \fB[\fR\(mia|\(mis\fB] [\fR\(mikx\fB] [\fR\(miH|\(miL\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +By default, the +.IR du +utility shall write to standard output the size of the file space +allocated to, and the size of the file space allocated to each +subdirectory of, the file hierarchy rooted in each of the specified +files. By default, when a symbolic link is encountered on the command +line or in the file hierarchy, +.IR du +shall count the size of the symbolic link (rather than the file +referenced by the link), and shall not follow the link to another +portion of the file hierarchy. The size of the file space allocated to +a file of type directory shall be defined as the sum total of space +allocated to all files in the file hierarchy rooted in the directory +plus the space allocated to the directory itself. +.P +When +.IR du +cannot +\fIstat\fR() +files or +\fIstat\fR() +or read directories, it shall report an error condition and the final +exit status is affected. Files with multiple links shall be counted and +written for only one entry. The directory entry that is selected in the +report is unspecified. By default, file sizes shall be written in +512-byte units, rounded up to the next 512-byte unit. +.SH OPTIONS +The +.IR du +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mia\fP" 10 +In addition to the default output, report the size of each file not of +type directory in the file hierarchy rooted in the specified file. +Regardless of the presence of the +.BR \(mia +option, non-directories given as +.IR file +operands shall always be listed. +.IP "\fB\(miH\fP" 10 +If a symbolic link is specified on the command line, +.IR du +shall count the size of the file or file hierarchy referenced by the +link. +.IP "\fB\(mik\fP" 10 +Write the files sizes in units of 1\|024 bytes, rather than the default +512-byte units. +.IP "\fB\(miL\fP" 10 +If a symbolic link is specified on the command line or encountered +during the traversal of a file hierarchy, +.IR du +shall count the size of the file or file hierarchy referenced by the +link. +.IP "\fB\(mis\fP" 10 +Instead of the default output, report only the total sum for each of +the specified files. +.IP "\fB\(mix\fP" 10 +When evaluating file sizes, evaluate only those files that have the +same device as the file specified by the +.IR file +operand. +.P +Specifying more than one of the mutually-exclusive options +.BR \(miH +and +.BR \(miL +shall not be considered an error. The last option specified shall +determine the behavior of the utility. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +The pathname of a file whose size is to be written. If no +.IR file +is specified, the current directory shall be used. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR du : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The output from +.IR du +shall consist of the amount of space allocated to a file and the +name of the file, in the following format: +.sp +.RS 4 +.nf +\fB +"%d %s\en", <\fIsize\fR>, <\fIpathname\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The use of 512-byte units is historical practice and maintains +compatibility with +.IR ls +and other utilities in this volume of POSIX.1\(hy2008. This does not mandate that the +file system itself be based on 512-byte blocks. The +.BR \(mik +option was added as a compromise measure. It was agreed by the standard +developers that 512 bytes was the best default unit because of its +complete historical consistency on System V (\fIversus\fP the mixed +512/1\|024-byte usage on BSD systems), and that a +.BR \(mik +option to switch to 1\|024-byte units was a good compromise. Users who +prefer the 1\|024-byte quantity can easily alias +.IR du +to +.IR du +.BR \(mik +without breaking the many historical scripts relying on the 512-byte +units. +.P +The +.BR \(mib +option was added to an early proposal to provide a resolution to the +situation where System V and BSD systems give figures for file sizes in +.IR blocks , +which is an implementation-defined concept. (In common usage, the +block size is 512 bytes for System V and 1\|024 bytes for BSD systems.) +However, +.BR \(mib +was later deleted, since the default was eventually decided as 512-byte +units. +.P +Historical file systems provided no way to obtain exact figures for the +space allocation given to files. There are two known areas of +inaccuracies in historical file systems: cases of +.IR "indirect blocks" +being used by the file system or +.IR "sparse" +files yielding incorrectly high values. An indirect block is space used +by the file system in the storage of the file, but that need not be +counted in the space allocated to the file. A +.IR sparse +file is one in which an +\fIlseek\fR() +call has been made to a position beyond the end of the file and data +has subsequently been written at that point. A file system need not +allocate all the intervening zero-filled blocks to such a file. It is +up to the implementation to define exactly how accurate its methods +are. +.P +The +.BR \(mia +and +.BR \(mis +options were mutually-exclusive in the original version of +.IR du . +The POSIX Shell and Utilities description is implied by the language in +the SVID where +.BR \(mis +is described as causing ``only the grand total'' to be reported. Some +systems may produce output for +.BR \(misa , +but a Strictly Conforming POSIX Shell and Utilities Application cannot +use that combination. +.P +The +.BR \(mia +and +.BR \(mis +options were adopted from the SVID except that the System V behavior of +not listing non-directories explicitly given as operands, unless the +.BR \(mia +option is specified, was considered a bug; the BSD-based behavior +(report for all operands) is mandated. The default behavior of +.IR du +in the SVID with regard to reporting the failure to read files (it +produces no messages) was considered counter-intuitive, and thus it was +specified that the POSIX Shell and Utilities default behavior shall be +to produce such messages. These messages can be turned off with shell +redirection to achieve the System V behavior. +.P +The +.BR \(mix +option is historical practice on recent BSD systems. It has been +adopted by this volume of POSIX.1\(hy2008 because there was no other historical method of +limiting the +.IR du +search to a single file hierarchy. This limitation of the search is +necessary to make it possible to obtain file space usage information +about a file system on which other file systems are mounted, without +having to resort to a lengthy +.IR find +and +.IR awk +script. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIls\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIfstatat\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/echo.1p b/man-pages-posix-2013/man1p/echo.1p new file mode 100644 index 0000000..da31e54 --- /dev/null +++ b/man-pages-posix-2013/man1p/echo.1p @@ -0,0 +1,266 @@ +'\" et +.TH ECHO "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +echo +\(em write arguments to standard output +.SH SYNOPSIS +.LP +.nf +echo \fB[\fIstring\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR echo +utility writes its arguments to standard output, followed by a +. +If there are no arguments, only the + +is written. +.SH OPTIONS +The +.IR echo +utility shall not recognize the +.BR \(dq\(mi\|\(mi\(dq +argument in the manner specified by Guideline 10 of the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines"; +.BR \(dq\(mi\|\(mi\(dq +shall be recognized as a string operand. +.P +Implementations shall not support any options. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIstring\fR" 10 +A string to be written to standard output. If the first operand is +.BR \(min , +or if any of the operands contain a + +character, the results are implementation-defined. +.RS 10 +.P +On XSI-conformant systems, if the first operand is +.BR \(min , +it shall be treated as a string, not an option. The following character +sequences shall be recognized on XSI-conformant systems within any of +the arguments: +.IP "\fR\ea\fR" 8 +Write an +. +.IP "\fR\eb\fR" 8 +Write a +. +.IP "\fR\ec\fR" 8 +Suppress the + +that otherwise follows the final argument in the output. All +characters following the +.BR '\ec' +in the arguments shall be ignored. +.IP "\fR\ef\fR" 8 +Write a +. +.IP "\fR\en\fR" 8 +Write a +. +.IP "\fR\er\fR" 8 +Write a +. +.IP "\fR\et\fR" 8 +Write a +. +.IP "\fR\ev\fR" 8 +Write a +. +.IP "\fR\e\e\fR" 8 +Write a + +character. +.IP "\fR\e0\fInum\fR" 8 +Write an 8-bit value that is the zero, one, two, or three-digit octal +number +.IR num . +.RE +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR echo : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR echo +utility arguments shall be separated by single + +characters and a + +character shall follow the last argument. +Output transformations shall occur based on the escape sequences in +the input. See the OPERANDS section. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +It is not possible to use +.IR echo +portably across all POSIX systems unless both +.BR \(min +(as the first argument) and escape sequences are omitted. +.P +The +.IR printf +utility can be used portably to emulate any of the traditional +behaviors of the +.IR echo +utility as follows (assuming that +.IR IFS +has its standard value or is unset): +.IP " *" 4 +The historic System V +.IR echo +and the requirements on XSI implementations in this volume of POSIX.1\(hy2008 are equivalent to: +.RS 4 +.sp +.RS 4 +.nf +\fB +printf "%b\en$*" +.fi \fR +.P +.RE +.RE +.IP " *" 4 +The BSD +.IR echo +is equivalent to: +.RS 4 +.sp +.RS 4 +.nf +\fB +if [ "X$1" = "X\(min" ] +then + shift + printf "%s$*" +else + printf "%s\en$*" +fi +.fi \fR +.P +.RE +.RE +.P +New applications are encouraged to use +.IR printf +instead of +.IR echo . +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR echo +utility has not been made obsolescent because of its extremely +widespread use in historical applications. Conforming applications that +wish to do prompting without + +characters or that could possibly be expecting to echo a +.BR \(min , +should use the +.IR printf +utility derived from the Ninth Edition system. +.P +As specified, +.IR echo +writes its arguments in the simplest of ways. The two different +historical versions of +.IR echo +vary in fatally incompatible ways. +.P +The BSD +.IR echo +checks the first argument for the string +.BR \(min +which causes it to suppress the + +that would otherwise follow the final argument in the output. +.P +The System V +.IR echo +does not support any options, but allows escape sequences within its +operands, as described for XSI implementations in the OPERANDS section. +.P +The +.IR echo +utility does not support Utility Syntax Guideline 10 because historical +applications depend on +.IR echo +to echo +.IR all +of its arguments, except for the +.BR \(min +option in the BSD version. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIprintf\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/ed.1p b/man-pages-posix-2013/man1p/ed.1p new file mode 100644 index 0000000..dd071cf --- /dev/null +++ b/man-pages-posix-2013/man1p/ed.1p @@ -0,0 +1,2097 @@ +'\" et +.TH ED "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ed +\(em edit text +.SH SYNOPSIS +.LP +.nf +ed \fB[\fR\(mip \fIstring\fB] [\fR\(mis\fB] [\fIfile\fB]\fR +.fi +.SH DESCRIPTION +The +.IR ed +utility is a line-oriented text editor that uses two modes: +.IR "command mode" +and +.IR "input mode" . +In command mode the input characters shall be interpreted as commands, +and in input mode they shall be interpreted as text. See the EXTENDED +DESCRIPTION section. +.P +If an operand is +.BR '\(mi' , +the results are unspecified. +.SH OPTIONS +The +.IR ed +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except for the unspecified usage of +.BR '\(mi' . +.P +The following options shall be supported: +.IP "\fB\(mip\ \fIstring\fR" 10 +Use +.IR string +as the prompt string when in command mode. By default, there shall be +no prompt string. +.IP "\fB\(mis\fP" 10 +Suppress the writing of byte counts by +.BR e , +.BR E , +.BR r , +and +.BR w +commands and of the +.BR '!' +prompt after a !\fIcommand\fR. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +If the +.IR file +argument is given, +.IR ed +shall simulate an +.BR e +command on the file named by the pathname, +.IR file , +before accepting commands from the standard input. +.SH STDIN +The standard input shall be a text file consisting of commands, as +described in the EXTENDED DESCRIPTION section. +.SH "INPUT FILES" +The input files shall be text files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR ed : +.IP "\fIHOME\fP" 10 +Determine the pathname of the user's home directory. +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular expressions. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files) and the behavior of +character classes within regular expressions. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +The +.IR ed +utility shall take the standard action for all signals (see the +ASYNCHRONOUS EVENTS section in +.IR "Section 1.4" ", " "Utility Description Defaults") +with the following exceptions: +.IP SIGINT 10 +The +.IR ed +utility shall interrupt its current activity, write the string +.BR \(dq?\en\(dq +to standard output, and return to command mode (see the EXTENDED +DESCRIPTION section). +.IP SIGHUP 10 +If the buffer is not empty and has changed since the last write, the +.IR ed +utility shall attempt to write a copy of the buffer in a file. First, +the file named +.BR ed.hup +in the current directory shall be used; if that fails, the file named +.BR ed.hup +in the directory named by the +.IR HOME +environment variable shall be used. In any case, the +.IR ed +utility shall exit without writing the file to the currently +remembered pathname and without returning to command mode. +.IP SIGQUIT 10 +The +.IR ed +utility shall ignore this event. +.SH STDOUT +Various editing commands and the prompting feature (see +.BR \(mip ) +write to standard output, as described in the EXTENDED DESCRIPTION +section. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The output files shall be text files whose formats are dependent on the +editing commands given. +.SH "EXTENDED DESCRIPTION" +The +.IR ed +utility shall operate on a copy of the file it is editing; changes made +to the copy shall have no effect on the file until a +.BR w +(write) command is given. The copy of the text is called the +.IR buffer . +.P +Commands to +.IR ed +have a simple and regular structure: zero, one, or two +.IR addresses +followed by a single-character +.IR command , +possibly followed by parameters to that command. These addresses +specify one or more lines in the buffer. Every command that requires +addresses has default addresses, so that the addresses very often can +be omitted. If the +.BR \(mip +option is specified, the prompt string shall be written to standard +output before each command is read. +.P +In general, only one command can appear on a line. Certain commands +allow text to be input. This text is placed in the appropriate place in +the buffer. While +.IR ed +is accepting text, it is said to be in \fIinput mode\fR. In this mode, +no commands shall be recognized; all input is merely collected. Input +mode is terminated by entering a line consisting of two characters: a + +(\c +.BR '.' ) +followed by a +. +This line is not considered part of the input text. +.SS "Regular Expressions in ed" +.P +The +.IR ed +utility shall support basic regular expressions, as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.3" ", " "Basic Regular Expressions". +Since regular expressions in +.IR ed +are always matched against single lines (excluding the terminating + +characters), never against any larger section of text, there is no way +for a regular expression to match a +. +.P +A null RE shall be equivalent to the last RE encountered. +.P +Regular expressions are used in addresses to specify lines, and in some +commands (for example, the +.BR s +substitute command) to specify portions of a line to be substituted. +.SS "Addresses in ed" +.P +Addressing in +.IR ed +relates to the current line. Generally, the current line is the last +line affected by a command. The current line number is the address of +the current line. If the edit buffer is not empty, the initial value +for the current line shall be the last line in the edit buffer; +otherwise, zero. +.P +Addresses shall be constructed as follows: +.IP " 1." 4 +The + +character (\c +.BR '.' ) +shall address the current line. +.IP " 2." 4 +The + +character (\c +.BR '$' ) +shall address the last line of the edit buffer. +.IP " 3." 4 +The positive decimal number +.IR n +shall address the +.IR n th +line of the edit buffer. +.IP " 4." 4 +The +-x +character pair (\c +.BR \(dq'x\(dq ) +shall address the line marked with the mark name character +.IR x , +which shall be a lowercase letter from the portable character set. It +shall be an error if the character has not been set to mark a line or +if the line that was marked is not currently present in the edit +buffer. +.IP " 5." 4 +A BRE enclosed by + +characters (\c +.BR '/' ) +shall address the first line found by searching forwards from the line +following the current line toward the end of the edit buffer and +stopping at the first line for which the line excluding the +terminating + +matches the BRE. The BRE consisting of a null BRE delimited by a pair of + +characters shall address the next line for which the line excluding +the terminating + +matches the last BRE encountered. In addition, the second + +can be omitted at the end of a command line. Within the BRE, a +-\c + +pair (\c +.BR \(dq\e/\(dq ) +shall represent a literal + +instead of the BRE delimiter. If necessary, the search shall wrap around +to the beginning of the buffer and continue up to and including the +current line, so that the entire buffer is searched. +.IP " 6." 4 +A BRE enclosed by + +characters (\c +.BR '?' ) +shall address the first line found by searching backwards from the line +preceding the current line toward the beginning of the edit buffer and +stopping at the first line for which the line excluding the terminating + +matches the BRE. The BRE consisting of a null BRE delimited by a pair +of + +characters (\c +.BR \(dq??\(dq ) +shall address the previous line for which the line excluding the +terminating + +matches the last BRE encountered. In addition, the second + +can be omitted at the end of a command line. Within the +BRE, a +-\c + +pair (\c +.BR \(dq\e?\(dq ) +shall represent a literal + +instead of the BRE delimiter. If necessary, the search shall wrap around +to the end of the buffer and continue up to and including the current +line, so that the entire buffer is searched. +.IP " 7." 4 +A + +(\c +.BR '\(pl' ) +or + +character (\c +.BR '\(mi' ) +followed by a decimal number shall address the current line plus or +minus the number. A + +or + +character not followed by a decimal number shall address the current +line plus or minus 1. +.P +Addresses can be followed by zero or more address offsets, optionally +-separated. +Address offsets are constructed as follows: +.IP " *" 4 +A + +or + +character followed by a decimal number shall add or subtract, +respectively, the indicated number of lines to or from the address. A + +or + +character not followed by a decimal number shall add or subtract 1 to +or from the address. +.IP " *" 4 +A decimal number shall add the indicated number of lines to the +address. +.P +It shall not be an error for an intermediate address value to be less +than zero or greater than the last line in the edit buffer. It shall be +an error for the final address value to be less than zero or greater +than the last line in the edit buffer. It shall be an error if a search +for a BRE fails to find a matching line. +.P +Commands accept zero, one, or two addresses. If more than the required +number of addresses are provided to a command that requires zero +addresses, it shall be an error. Otherwise, if more than the required +number of addresses are provided to a command, the addresses specified +first shall be evaluated and then discarded until the maximum number of +valid addresses remain, for the specified command. +.P +Addresses shall be separated from each other by a + +(\c +.BR ',' ) +or + +character (\c +.BR ';' ). +In the case of a + +separator, the current line (\c +.BR '.' ) +shall be set to the first address, and only then will the second +address be calculated. This feature can be used to determine the +starting line for forwards and backwards searches; see rules 5. and +6. +.P +Addresses can be omitted on either side of the + +or + +separator, in which case the resulting address pairs shall be as +follows: +.TS +center box tab(!); +cB | cB +lf5 | lf5. +Specified!Resulting +_ +\&,!1 , $ +\&, addr!1 , addr +addr ,!addr , addr +;!. ; $ +; addr!. ; addr +addr ;!addr ; addr +.TE +.P +Any + +characters included between addresses, address separators, or address +offsets shall be ignored. +.SS "Commands in ed" +.P +In the following list of +.IR ed +commands, the default addresses are shown in parentheses. The number of +addresses shown in the default shall be the number expected by the +command. The parentheses are not part of the address; they show that +the given addresses are the default. +.P +It is generally invalid for more than one command to appear on a line. +However, any command (except +.BR e , +.BR E , +.BR f , +.BR q , +.BR Q , +.BR r , +.BR w , +and +.BR ! ) +can be suffixed by the letter +.BR l , +.BR n , +or +.BR p ; +in which case, except for the +.BR l , +.BR n , +and +.BR p +commands, the command shall be executed and then the new current line +shall be written as described below under the +.BR l , +.BR n , +and +.BR p +commands. When an +.BR l , +.BR n , +or +.BR p +suffix is used with an +.BR l , +.BR n , +or +.BR p +command, the command shall write to standard output as described below, +but it is unspecified whether the suffix writes the current line again +in the requested format or whether the suffix has no effect. For +example, the +.BR pl +command (base +.BR p +command with an +.BR l +suffix) shall either write just the current line or write it +twice\(emonce as specified for +.BR p +and once as specified for +.BR l . +Also, the +.BR g , +.BR G , +.BR v , +and +.BR V +commands shall take a command as a parameter. +.P +Each address component can be preceded by zero or more + +characters. The command letter can be preceded by zero or more + +characters. If a suffix letter (\c +.BR l , +.BR n , +or +.BR p ) +is given, the application shall ensure that it immediately follows the +command. +.P +The +.BR e , +.BR E , +.BR f , +.BR r , +and +.BR w +commands shall take an optional +.IR file +parameter, separated from the command letter by one or more + +characters. +.P +If changes have been made in the buffer since the last +.BR w +command that wrote the entire buffer, +.IR ed +shall warn the user if an attempt is made to destroy the editor buffer +via the +.BR e +or +.BR q +commands. The +.IR ed +utility shall write the string: +.sp +.RS 4 +.nf +\fB +"?\en" +.fi \fR +.P +.RE +.P +(followed by an explanatory message if +.IR "help mode" +has been enabled via the +.BR H +command) to standard output and shall continue in command mode with the +current line number unchanged. If the +.BR e +or +.BR q +command is repeated with no intervening command, it shall take effect. +.P +If a terminal disconnect (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface", +Modem Disconnect and Closing a Device Terminal), is detected: +.IP " *" 4 +If accompanied by a SIGHUP signal, the +.IR ed +utility shall operate as described in the ASYNCHRONOUS EVENTS section +for a SIGHUP signal. +.IP " *" 4 +If not accompanied by a SIGHUP signal, the +.IR ed +utility shall act as if an end-of-file had been detected on standard +input. +.P +If an end-of-file is detected on standard input: +.IP " *" 4 +If the +.IR ed +utility is in input mode, +.IR ed +shall terminate input mode and return to command mode. It is +unspecified if any partially entered lines (that is, input text without +a terminating +) +are discarded from the input text. +.IP " *" 4 +If the +.IR ed +utility is in command mode, it shall act as if a +.BR q +command had been entered. +.P +If the closing delimiter of an RE or of a replacement string (for +example, +.BR '/' ) +in a +.BR g , +.BR G , +.BR s , +.BR v , +or +.BR V +command would be the last character before a +, +that delimiter can be omitted, in which case the addressed line shall +be written. For example, the following pairs of commands are +equivalent: +.sp +.RS 4 +.nf +\fB +s/s1/s2 s/s1/s2/p +g/s1 g/s1/p +?s1 ?s1? +.fi \fR +.P +.RE +.P +If an invalid command is entered, +.IR ed +shall write the string: +.sp +.RS 4 +.nf +\fB +"?\en" +.fi \fR +.P +.RE +.P +(followed by an explanatory message if +.IR "help mode" +has been enabled via the +.BR H +command) to standard output and shall continue in command mode with the +current line number unchanged. +.SS "Append Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(.)a +<\fItext\fR> +\&. +.fi \fR +.P +.RE +.RE +.P +The +.BR a +command shall read the given text and append it after the addressed +line; the current line number shall become the address of the last +inserted line or, if there were none, the addressed line. Address 0 +shall be valid for this command; it shall cause the appended text to be +placed at the beginning of the buffer. +.SS "Change Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(.,.)c +<\fItext\fR> +\&. +.fi \fR +.P +.RE +.RE +.P +The +.BR c +command shall delete the addressed lines, then accept input text that +replaces these lines; the current line shall be set to the address of +the last line input; or, if there were none, at the line after the last +line deleted; if the lines deleted were originally at the end of the +buffer, the current line number shall be set to the address of the new +last line; if no lines remain in the buffer, the current line number +shall be set to zero. Address 0 shall be valid for this command; it +shall be interpreted as if address 1 were specified. +.SS "Delete Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(.,.)d +.fi \fR +.P +.RE +.RE +.P +The +.BR d +command shall delete the addressed lines from the buffer. The address +of the line after the last line deleted shall become the current line +number; if the lines deleted were originally at the end of the buffer, +the current line number shall be set to the address of the new last +line; if no lines remain in the buffer, the current line number shall +be set to zero. +.SS "Edit Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +e \fB[\fIfile\fB]\fR +.fi \fR +.P +.RE +.RE +.P +The +.BR e +command shall delete the entire contents of the buffer and then read in +the file named by the pathname +.IR file . +The current line number shall be set to the address of the last line of +the buffer. If no pathname is given, the currently remembered pathname, +if any, shall be used (see the +.BR f +command). The number of bytes read shall be written to standard output, +unless the +.BR \(mis +option was specified, in the following format: +.sp +.RS 4 +.nf +\fB +"%d\en", <\fInumber of bytes read\fR> +.fi \fR +.P +.RE +.P +The name \fIfile\fR shall be remembered for possible use as a default +pathname in subsequent +.BR e , +.BR E , +.BR r , +and +.BR w +commands. If +.IR file +is replaced by +.BR '!' , +the rest of the line shall be taken to be a shell command line whose +output is to be read. Such a shell command line shall not be remembered +as the current +.IR file . +All marks shall be discarded upon the completion of a successful +.BR e +command. If the buffer has changed since the last time the entire +buffer was written, the user shall be warned, as described previously. +.SS "Edit Without Checking Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +E \fB[\fIfile\fB]\fR +.fi \fR +.P +.RE +.RE +.P +The +.BR E +command shall possess all properties and restrictions of the +.BR e +command except that the editor shall not check to see whether any +changes have been made to the buffer since the last +.BR w +command. +.SS "Filename Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +f \fB[\fIfile\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If +.IR file +is given, the +.BR f +command shall change the currently remembered pathname to +.IR file ; +whether the name is changed or not, it shall then write the (possibly +new) currently remembered pathname to the standard output in the +following format: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIpathname\fR> +.fi \fR +.P +.RE +.P +The current line number shall be unchanged. +.SS "Global Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(1,$)g/\fIRE\fR/\fIcommand list\fR +.fi \fR +.P +.RE +.RE +.P +In the +.BR g +command, the first step shall be to mark every line for which the +line excluding the terminating + +matches the given RE. Then, going sequentially from the beginning of +the file to the end of the file, the given +.IR "command list" +shall be executed for each marked line, with the current line number +set to the address of that line. Any line modified by the +.IR "command list" +shall be unmarked. When the +.BR g +command completes, the current line number shall have the value +assigned by the last command in the +.IR "command list" . +If there were no matching lines, the current line number shall not be +changed. A single command or the first of a list of commands shall +appear on the same line as the global command. All lines of a +multi-line list except the last line shall be ended with a + +preceding the terminating +; +the +.BR a , +.BR i , +and +.BR c +commands and associated input are permitted. The +.BR '.' +terminating input mode can be omitted if it would be the last line of +the \fIcommand list\fR. An empty \fIcommand list\fR shall be equivalent +to the +.BR p +command. The use of the +.BR g , +.BR G , +.BR v , +.BR V , +and +.BR ! +commands in the +.IR "command list" +produces undefined results. Any character other than + +or + +can be used instead of a + +to delimit the RE. Within the RE, the RE delimiter itself can be used +as a literal character if it is preceded by a +. +.SS "Interactive Global Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(1,$)G/\fIRE\fR/ +.fi \fR +.P +.RE +.RE +.P +In the +.BR G +command, the first step shall be to mark every line for which the line +excluding the terminating + +matches the given RE. Then, for every such line, that line shall be +written, the current line number shall be set to the address of that +line, and any one command (other than one of the +.BR a , +.BR c , +.BR i , +.BR g , +.BR G , +.BR v , +and +.BR V +commands) shall be read and executed. A + +shall act as a null command (causing no action to be taken on +the current line); an +.BR '&' +shall cause the re-execution of the most recent non-null command +executed within the current invocation of +.BR G . +Note that the commands input as part of the execution of the +.BR G +command can address and affect any lines in the buffer. Any line +modified by the command shall be unmarked. The final value +of the current line number shall be the value set by the last command +successfully executed. (Note that the last command successfully +executed shall be the +.BR G +command itself if a command fails or the null command is specified.) If +there were no matching lines, the current line number shall not be +changed. The +.BR G +command can be terminated by a SIGINT signal. Any character other than + +or + +can be used instead of a + +to delimit the RE and the replacement. Within the RE, the RE delimiter +itself can be used as a literal character if it is preceded by a +. +.SS "Help Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +h +.fi \fR +.P +.RE +.RE +.P +The +.BR h +command shall write a short message to standard output that explains +the reason for the most recent +.BR '?' +notification. The current line number shall be unchanged. +.SS "Help-Mode Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +H +.fi \fR +.P +.RE +.RE +.P +The +.BR H +command shall cause +.IR ed +to enter a mode in which help messages (see the +.BR h +command) shall be written to standard output for all subsequent +.BR '?' +notifications. The +.BR H +command alternately shall turn this mode on and off; it is initially +off. If the help-mode is being turned on, the +.BR H +command also explains the previous +.BR '?' +notification, if there was one. The current line number shall be +unchanged. +.SS "Insert Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(.)i +<\fItext\fR> +\&. +.fi \fR +.P +.RE +.RE +.P +The +.BR i +command shall insert the given text before the addressed line; the +current line is set to the last inserted line or, if there was none, to +the addressed line. This command differs from the +.BR a +command only in the placement of the input text. Address 0 shall be +valid for this command; it shall be interpreted as if address 1 were +specified. +.SS "Join Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(.,.+1)j +.fi \fR +.P +.RE +.RE +.P +The +.BR j +command shall join contiguous lines by removing the appropriate + +characters. If exactly one address is given, this command shall do +nothing. If lines are joined, the current line number shall be set to +the address of the joined line; otherwise, the current line number shall +be unchanged. +.SS "Mark Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(.)k\fIx\fR +.fi \fR +.P +.RE +.RE +.P +The +.BR k +command shall mark the addressed line with name +.IR x , +which the application shall ensure is a lowercase letter from the +portable character set. The address +.BR \(dq'x\(dq +shall then refer to this line; the current line number shall be +unchanged. +.SS "List Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(.,.)l +.fi \fR +.P +.RE +.RE +.P +The +.BR l +command shall write to standard output the addressed lines in a +visually unambiguous form. The characters listed in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Table 5-1" ", " "Escape Sequences and Associated Actions" +(\c +.BR '\e\e' , +.BR '\ea' , +.BR '\eb' , +.BR '\ef' , +.BR '\er' , +.BR '\et' , +.BR '\ev' ) +shall be written as the corresponding escape sequence; the +.BR '\en' +in that table is not applicable. Non-printable characters not in the +table shall be written as one three-digit octal number (with a +preceding + +character) for each byte in the character (most significant byte first). +.P +Long lines shall be folded, with the point of folding indicated by + +preceded by a +; +the length at which folding occurs is unspecified, but should be +appropriate for the output device. The end of each line shall be marked +with a +.BR '$' , +and +.BR '$' +characters within the text shall be written with a preceding +. +An +.BR l +command can be appended to any other command other than +.BR e , +.BR E , +.BR f , +.BR q , +.BR Q , +.BR r , +.BR w , +or +.BR ! . +The current line number shall be set to the address of the last line +written. +.SS "Move Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(.,.)m\fIaddress\fR +.fi \fR +.P +.RE +.RE +.P +The +.BR m +command shall reposition the addressed lines after the line addressed +by +.IR address . +Address 0 shall be valid for +.IR address +and cause the addressed lines to be moved to the beginning of the +buffer. It shall be an error if address +.IR address +falls within the range of moved lines. The current line number shall be +set to the address of the last line moved. +.SS "Number Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(.,.)n +.fi \fR +.P +.RE +.RE +.P +The +.BR n +command shall write to standard output the addressed lines, preceding +each line by its line number and a +; +the current line number shall be set to the address of the last line +written. The +.BR n +command can be appended to any command other than +.BR e , +.BR E , +.BR f , +.BR q , +.BR Q , +.BR r , +.BR w , +or +.BR ! . +.SS "Print Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(.,.)p +.fi \fR +.P +.RE +.RE +.P +The +.BR p +command shall write to standard output the addressed lines; the current +line number shall be set to the address of the last line written. The +.BR p +command can be appended to any command other than +.BR e , +.BR E , +.BR f , +.BR q , +.BR Q , +.BR r , +.BR w , +or +.BR ! . +.SS "Prompt Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +P +.fi \fR +.P +.RE +.RE +.P +The +.BR P +command shall cause +.IR ed +to prompt with an + +(\c +.BR '*' ) +(or +.IR string , +if +.BR \(mip +is specified) for all subsequent commands. The +.BR P +command alternatively shall turn this mode on and off; it shall be +initially on if the +.BR \(mip +option is specified; otherwise, off. The current line number shall be +unchanged. +.SS "Quit Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +q +.fi \fR +.P +.RE +.RE +.P +The +.BR q +command shall cause +.IR ed +to exit. If the buffer has changed since the last time the entire +buffer was written, the user shall be warned, as described previously. +.SS "Quit Without Checking Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +Q +.fi \fR +.P +.RE +.RE +.P +The +.BR Q +command shall cause +.IR ed +to exit without checking whether changes have been made in the buffer +since the last +.BR w +command. +.SS "Read Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +($)r\fB [\fIfile\fB]\fR +.fi \fR +.P +.RE +.RE +.P +The +.BR r +command shall read in the file named by the pathname +.IR file +and append it after the addressed line. If no +.IR file +argument is given, the currently remembered pathname, if any, shall be +used (see the +.BR e +and +.BR f +commands). The currently remembered pathname shall not be changed +unless there is no remembered pathname. Address 0 shall be valid for +.BR r +and shall cause the file to be read at the beginning of the buffer. If +the read is successful, and +.BR \(mis +was not specified, the number of bytes read shall be written to +standard output in the following format: +.sp +.RS 4 +.nf +\fB +"%d\en", <\fInumber of bytes read\fR> +.fi \fR +.P +.RE +.P +The current line number shall be set to the address of the last line +read in. If +.IR file +is replaced by +.BR '!' , +the rest of the line shall be taken to be a shell command line whose +output is to be read. Such a shell command line shall not be remembered +as the current pathname. +.SS "Substitute Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(.,.)s/\fIRE\fR/\fIreplacement\fR/\fIflags\fR +.fi \fR +.P +.RE +.RE +.P +The +.BR s +command shall search each addressed line for an occurrence of the +specified RE and replace either the first or all (non-overlapped) +matched strings with the +.IR replacement ; +see the following description of the +.BR g +suffix. It is an error if the substitution fails on every addressed +line. Any character other than + +or + +can be used instead of a + +to delimit the RE and the replacement. Within the RE, the RE delimiter +itself can be used as a literal character if it is preceded by a +. +The current line shall be set to the address of the last line on which +a substitution occurred. +.P +An + +(\c +.BR '&' ) +appearing in the +.IR replacement +shall be replaced by the string matching the RE on the current line. +The special meaning of +.BR '&' +in this context can be suppressed by preceding it by +. +As a more general feature, the characters +.BR '\en' , +where +.IR n +is a digit, shall be replaced by the text matched by the corresponding +back-reference expression. If the corresponding back-reference +expression does not match, then the characters +.BR '\en' +shall be replaced by the empty string. When the character +.BR '%' +is the only character in the +.IR replacement , +the +.IR replacement +used in the most recent substitute command shall be used as the +.IR replacement +in the current substitute command; if there was no previous substitute +command, the use of +.BR '%' +in this manner shall be an error. The +.BR '%' +shall lose its special meaning when it is in a replacement string of +more than one character or is preceded by a +. +For each + +encountered in scanning +.IR replacement +from beginning to end, the following character shall lose its special +meaning (if any). It is unspecified what special meaning is given to +any character other than +, +.BR '&' , +.BR '%' , +or digits. +.P +A line can be split by substituting a + +into it. The application shall ensure it escapes the + +in the +.IR replacement +by preceding it by +. +Such substitution cannot be done as part of a +.BR g +or +.BR v +.IR "command list" . +The current line number shall be set to the address of the last line on +which a substitution is performed. If no substitution is performed, the +current line number shall be unchanged. If a line is split, a +substitution shall be considered to have been performed on each of the +new lines for the purpose of determining the new current line number. A +substitution shall be considered to have been performed even if the +replacement string is identical to the string that it replaces. +.P +The application shall ensure that the value of +.IR flags +is zero or more of: +.IP "\fIcount\fR" 8 +Substitute for the +.IR count th +occurrence only of the RE found on each addressed line. +.IP "\fBg\fR" 8 +Globally substitute for all non-overlapping instances of the RE rather +than just the first one. If both +.BR g +and +.IR count +are specified, the results are unspecified. +.IP "\fBl\fR" 8 +Write to standard output the final line in which a substitution was +made. The line shall be written in the format specified for the +.BR l +command. +.IP "\fBn\fR" 8 +Write to standard output the final line in which a substitution was +made. The line shall be written in the format specified for the +.BR n +command. +.IP "\fBp\fR" 8 +Write to standard output the final line in which a substitution was +made. The line shall be written in the format specified for the +.BR p +command. +.SS "Copy Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(.,.)t\fIaddress\fR +.fi \fR +.P +.RE +.RE +.P +The +.BR t +command shall be equivalent to the +.BR m +command, except that a copy of the addressed lines shall be placed +after address +.IR address +(which can be 0); the current line number shall be set to the address +of the last line added. +.SS "Undo Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +u +.fi \fR +.P +.RE +.RE +.P +The +.BR u +command shall nullify the effect of the most recent command that +modified anything in the buffer, namely the most recent +.BR a , +.BR c , +.BR d , +.BR g , +.BR i , +.BR j , +.BR m , +.BR r , +.BR s , +.BR t , +.BR u , +.BR v , +.BR G , +or +.BR V +command. All changes made to the buffer by a +.BR g , +.BR G , +.BR v , +or +.BR V +global command shall be undone as a single change; if no changes were +made by the global command (such as with +.BR g /RE/\c +.BR p ), +the +.BR u +command shall have no effect. The current line number shall be set to +the value it had immediately before the command being undone started. +.SS "Global Non-Matched Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(1,$)v\fR/\fIRE\fR/\fIcommand list\fR +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the global command +.BR g +except that the lines that are marked during the first step shall be +those for which the line excluding the terminating + +does not match the RE. +.SS "Interactive Global Not-Matched Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(1,$)V\fR/\fIRE\fR/ +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the interactive global command +.BR G +except that the lines that are marked during the first step shall be +those for which the line excluding the terminating + +does not match the RE. +.SS "Write Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(1,$)w\fB [\fIfile\fB] +.fi \fR +.P +.RE +.RE +.P +The +.BR w +command shall write the addressed lines into the file named by the +pathname +.IR file . +The command shall create the file, if it does not exist, or shall +replace the contents of the existing file. The currently remembered +pathname shall not be changed unless there is no remembered pathname. +If no pathname is given, the currently remembered pathname, if any, +shall be used (see the +.BR e +and +.BR f +commands); the current line number shall be unchanged. If the command +is successful, the number of bytes written shall be written to standard +output, unless the +.BR \(mis +option was specified, in the following format: +.sp +.RS 4 +.nf +\fB +"%d\en", <\fInumber of bytes written\fR> +.fi \fR +.P +.RE +.P +If +.IR file +begins with +.BR '!' , +the rest of the line shall be taken to be a shell command line whose +standard input shall be the addressed lines. Such a shell command line +shall not be remembered as the current pathname. This usage of the +write command with +.BR '!' +shall not be considered as a ``last +.BR w +command that wrote the entire buffer'', as described previously; thus, +this alone shall not prevent the warning to the user if an attempt is +made to destroy the editor buffer via the +.BR e +or +.BR q +commands. +.SS "Line Number Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +($)= +.fi \fR +.P +.RE +.RE +.P +The line number of the addressed line shall be written to standard +output in the following format: +.sp +.RS 4 +.nf +\fB +"%d\en", <\fIline number\fR> +.fi \fR +.P +.RE +.P +The current line number shall be unchanged by this command. +.SS "Shell Escape Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +!\fIcommand\fR +.fi \fR +.P +.RE +.RE +.P +The remainder of the line after the +.BR '!' +shall be sent to the command interpreter to be interpreted as a shell +command line. Within the text of that shell command line, the unescaped +character +.BR '%' +shall be replaced with the remembered pathname; if a +.BR '!' +appears as the first character of the command, it shall be replaced +with the text of the previous shell command executed via +.BR '!' . +Thus, +.BR \(dq!!\(dq +shall repeat the previous !\fIcommand\fP. If any replacements of +.BR '%' +or +.BR '!' +are performed, the modified line shall be written to the standard +output before +.IR command +is executed. The +.BR ! +command shall write: +.sp +.RS 4 +.nf +\fB +"!\en" +.fi \fR +.P +.RE +.P +to standard output upon completion, unless the +.BR \(mis +option is specified. The current line number shall be unchanged. +.SS "Null Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +(.+1) +.fi \fR +.P +.RE +.RE +.P +An address alone on a line shall cause the addressed line to be +written. A + +alone shall be equivalent to +.BR \(dq+1p\(dq . +The current line number shall be set to the address of the written +line. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion without any file or command errors. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +When an error in the input script is encountered, or when an error is +detected that is a consequence of the data (not) present in the file or +due to an external condition such as a read or write error: +.IP " *" 4 +If the standard input is a terminal device file, all input shall be +flushed, and a new command read. +.IP " *" 4 +If the standard input is a regular file, +.IR ed +shall terminate with a non-zero exit status. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Because of the extremely terse nature of the default error messages, +the prudent script writer begins the +.IR ed +input commands with an +.BR H +command, so that if any errors do occur at least some clue as to the +cause is made available. +.P +In earlier versions of this standard, an obsolescent +.BR \(mi +option was described. This is no longer specified. Applications should +use the +.BR \(mis +option. Using +.BR \(mi +as a +.IR file +operand now produces unspecified results. This allows implementations +to continue to support the former required behavior. +.SH EXAMPLES +None. +.SH RATIONALE +The initial description of this utility was adapted from the SVID. It +contains some features not found in Version 7 or BSD-derived systems. +Some of the differences between the POSIX and BSD +.IR ed +utilities include, but need not be limited to: +.IP " *" 4 +The BSD +.BR \(mi +option does not suppress the +.BR '!' +prompt after a +.BR ! +command. +.IP " *" 4 +BSD does not support the special meanings of the +.BR '%' +and +.BR '!' +characters within a +.BR ! +command. +.IP " *" 4 +BSD does not support the +.IR addresses +.BR ';' +and +.BR ',' . +.IP " *" 4 +BSD allows the command/suffix pairs +.BR pp , +.BR ll , +and so on, which are unspecified in this volume of POSIX.1\(hy2008. +.IP " *" 4 +BSD does not support the +.BR '!' +character part of the +.BR e , +.BR r , +or +.BR w +commands. +.IP " *" 4 +A failed +.BR g +command in BSD sets the line number to the last line searched if there +are no matches. +.IP " *" 4 +BSD does not default the +.IR "command list" +to the +.BR p +command. +.IP " *" 4 +BSD does not support the +.BR G , +.BR h , +.BR H , +.BR n , +or +.BR V +commands. +.IP " *" 4 +On BSD, if there is no inserted text, the insert command changes the +current line to the referenced line \(mi1; that is, the line before the +specified line. +.IP " *" 4 +On BSD, the +.IR join +command with only a single address changes the current line to that +address. +.IP " *" 4 +BSD does not support the +.BR P +command; moreover, in BSD it is synonymous with the +.BR p +command. +.IP " *" 4 +BSD does not support the +.IR undo +of the commands +.BR j , +.BR m , +.BR r , +.BR s , +or +.BR t . +.IP " *" 4 +The Version 7 +.IR ed +command +.BR W , +and the BSD +.IR ed +commands +.BR W , +.BR wq , +and +.BR z +are not present in this volume of POSIX.1\(hy2008. +.P +The +.BR \(mis +option was added to allow the functionality of the removed +.BR \(mi +option in a manner compatible with the Utility Syntax Guidelines. +.P +In early proposals there was a limit, +{ED_FILE_MAX}, +that described the historical limitations of some +.IR ed +utilities in their handling of large files; some of these have had +problems with files larger than 100\|000 bytes. It was this limitation +that prompted much of the desire to include a +.IR split +command in this volume of POSIX.1\(hy2008. Since this limit was removed, this volume of POSIX.1\(hy2008 requires that +implementations document the file size limits imposed by +.IR ed +in the conformance document. The limit +{ED_LINE_MAX} +was also removed; therefore, the global limit +{LINE_MAX} +is used for input and output lines. +.P +The manner in which the +.BR l +command writes non-printable characters was changed to avoid +the historical backspace-overstrike method. On video display terminals, +the overstrike is ambiguous because most terminals simply replace +overstruck characters, making the +.BR l +format not useful for its intended purpose of unambiguously +understanding the content of the line. The historical +-escapes +were also ambiguous. (The string +.BR \(dqa\e0011\(dq +could represent a line containing those six characters or a line +containing the three characters +.BR 'a' , +a byte with a binary value of 1, and a 1.) In the format required here, +a + +appearing in the line is written as +.BR \(dq\e\e\(dq +so that the output is truly unambiguous. The method of marking the ends +of lines was adopted from the +.IR ex +editor and is required for any line ending in + +characters; the +.BR '$' +is placed on all lines so that a real +.BR '$' +at the end of a line cannot be misinterpreted. +.P +Earlier versions of this standard allowed for implementations +with bytes other than eight bits, but this has been modified in this +version. +.P +The description of how a NUL is written was removed. The NUL character +cannot be in text files, and this volume of POSIX.1\(hy2008 should not dictate behavior in the +case of undefined, erroneous input. +.P +Unlike some of the other editing utilities, the filenames accepted by +the +.BR E , +.BR e , +.BR R , +and +.BR r +commands are not patterns. +.P +Early proposals stated that the +.BR \(mip +option worked only when standard input was associated with a terminal +device. This has been changed to conform to historical implementations, +thereby allowing applications to interpose themselves between a user +and the +.IR ed +utility. +.P +The form of the substitute command that uses the +.BR n +suffix was limited in some historical documentation (where this was +described incorrectly as ``backreferencing''). This limit has been +omitted because there is no reason why an editor processing lines of +{LINE_MAX} +length should have this restriction. The command +.BR "s/x/X/2047" +should be able to substitute the 2\|047th occurrence of +.BR 'x' +on a line. +.P +The use of printing commands with printing suffixes (such as +.BR pn , +.BR lp , +and so on) was made unspecified because BSD-based systems allow this, +whereas System V does not. +.P +Some BSD-based systems exit immediately upon receipt of end-of-file if +all of the lines in the file have been deleted. Since this volume of POSIX.1\(hy2008 refers +to the +.BR q +command in this instance, such behavior is not allowed. +.P +Some historical implementations returned exit status zero even if +command errors had occurred; this is not allowed by this volume of POSIX.1\(hy2008. +.P +Some historical implementations contained a bug that allowed a single + +to be entered in input mode as + + +. +This is not allowed by +.IR ed +because there is no description of escaping any of the characters in +input mode; + +characters are entered into the buffer exactly as typed. The typical +method of entering a single + +has been to precede it with another character and then use the substitute +command to delete that character. +.P +It is difficult under some modes of some versions of historical +operating system terminal drivers to distinguish between an end-of-file +condition and terminal disconnect. POSIX.1\(hy2008 does not require +implementations to distinguish between the two situations, which +permits historical implementations of the +.IR ed +utility on historical platforms to conform. Implementations are +encouraged to distinguish between the two, if possible, and take +appropriate action on terminal disconnect. +.P +Historically, +.IR ed +accepted a zero address for the +.BR a +and +.BR r +commands in order to insert text at the start of the edit buffer. When +the buffer was empty the command +.BR .= +returned zero. POSIX.1\(hy2008 requires conformance to historical practice. +.P +For consistency with the +.BR a +and +.BR r +commands and better user functionality, the +.BR i +and +.BR c +commands must also accept an address of 0, in which case 0\fIi\fP is +treated as 1\fIi\fP and likewise for the +.BR c +command. +.P +All of the following are valid addresses: +.IP "\fR+++\fP" 12 +Three lines after the current line. +.IP "\fR/\fIpattern\fR/\(mi\fR" 12 +One line before the next occurrence of pattern. +.IP "\fR\(mi2\fR" 12 +Two lines before the current line. +.IP "\fR3\ \(mi\|\(mi\|\(mi\|\(mi\ 2\fR" 12 +Line one (note the intermediate negative address). +.IP "\fR1\ 2\ 3\fR" 12 +Line six. +.P +Any number of addresses can be provided to commands taking addresses; +for example, +.BR \(dq1,2,3,4,5p\(dq +prints lines 4 and 5, because two is the greatest valid number of +addresses accepted by the +.BR print +command. This, in combination with the + +delimiter, permits users to create commands based on ordered patterns +in the file. For example, the command +.BR \(dq3;/foo/;+2p\(dq +will display the first line after line 3 that contains the pattern +.IR foo , +plus the next two lines. Note that the address +.BR \(dq3;\(dq +must still be evaluated before being discarded, because the search +origin for the +.BR \(dq/foo/\(dq +command depends on this. +.P +Historically, +.IR ed +disallowed address chains, as discussed above, consisting solely of + +or + +separators; for example, +.BR \(dq,,,\(dq +or +.BR \(dq;;;\(dq +were considered an error. For consistency of address specification, +this restriction is removed. The following table lists some of the +address forms now possible: +.TS +center box tab(!); +cB | cB | cB | cB | cB +lf5 | nf5 | nf5 | l | l. +Address!Addr1!Addr2!Status!Comment +_ +7,!7!7!Historical +7,5,!5!5!Historical +7,5,9!5!9!Historical +7,9!7!9!Historical +7,+!7!8!Historical +\&,!1!$!Historical +\&,7!1!7!Extension +\&,,!$!$!Extension +\&,;!$!$!Extension +7;!7!7!Historical +7;5;!5!5!Historical +7;5;9!5!9!Historical +7;5,9!5!9!Historical +7;$;4!$!4!Historical!Valid, but erroneous. +7;9!7!9!Historical +7;+!7!8!Historical +;!.!$!Historical +;7!.!7!Extension +;;!$!$!Extension +;,!$!$!Extension +.TE +.P +Historically, +.IR ed +accepted the +.BR '^' +character as an address, in which case it was identical to the + +character. POSIX.1\(hy2008 does not require or prohibit this behavior. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 1.4" ", " "Utility Description Defaults", +.IR "\fIex\fR\^", +.IR "\fIsed\fR\^", +.IR "\fIsh\fR\^", +.IR "\fIvi\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Table 5-1" ", " "Escape Sequences and Associated Actions", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 9.3" ", " "Basic Regular Expressions", +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/env.1p b/man-pages-posix-2013/man1p/env.1p new file mode 100644 index 0000000..14f628e --- /dev/null +++ b/man-pages-posix-2013/man1p/env.1p @@ -0,0 +1,330 @@ +'\" et +.TH ENV "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +env +\(em set the environment for command invocation +.SH SYNOPSIS +.LP +.nf +env \fB[\fR\(mii\fB] [\fIname\fR=\fIvalue\fB]\fR... \fB[\fIutility\fB [\fIargument\fR...\fB]]\fR +.fi +.SH DESCRIPTION +The +.IR env +utility shall obtain the current environment, modify it according to +its arguments, then invoke the utility named by the +.IR utility +operand with the modified environment. +.P +Optional arguments shall be passed to +.IR utility . +.P +If no +.IR utility +operand is specified, the resulting environment shall be written to the +standard output, with one +.IR name =\c +.IR value +pair per line. +.P +If the first argument is +.BR '\(mi' , +the results are unspecified. +.SH OPTIONS +The +.IR env +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except for the unspecified usage of +.BR '\(mi' . +.P +The following options shall be supported: +.IP "\fB\(mii\fP" 10 +Invoke +.IR utility +with exactly the environment specified by the arguments; the inherited +environment shall be ignored completely. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIname\fR=\fIvalue\fR" 10 +Arguments of the form +.IR name =\c +.IR value +shall modify the execution environment, and shall be placed into the +inherited environment before the +.IR utility +is invoked. +.IP "\fIutility\fR" 10 +The name of the utility to be invoked. If the +.IR utility +operand names any of the special built-in utilities in +.IR "Section 2.14" ", " "Special Built-In Utilities", +the results are undefined. +.IP "\fIargument\fR" 10 +A string to pass as an argument for the invoked utility. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR env : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPATH\fP" 10 +Determine the location of the +.IR utility , +as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +If +.IR PATH +is specified as a +.IR name =\c +.IR value +operand to +.IR env , +the +.IR value +given shall be used in the search for +.IR utility . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If no +.IR utility +operand is specified, each +.IR name =\c +.IR value +pair in the resulting environment shall be written in the form: +.sp +.RS 4 +.nf +\fB +"%s=%s\en", <\fIname\fR>, <\fIvalue\fR> +.fi \fR +.P +.RE +.P +If the +.IR utility +operand is specified, the +.IR env +utility shall not write to standard output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +If +.IR utility +is invoked, the exit status of +.IR env +shall be the exit status of +.IR utility ; +otherwise, the +.IR env +utility shall exit with one of the following values: +.IP "\0\0\0\00" 8 +The +.IR env +utility completed successfully. +.IP "1\(mi125" 8 +An error occurred in the +.IR env +utility. +.IP "\0\0126" 8 +The utility specified by +.IR utility +was found but could not be invoked. +.IP "\0\0127" 8 +The utility specified by +.IR utility +could not be found. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR command , +.IR env , +.IR nice , +.IR nohup , +.IR time , +and +.IR xargs +utilities have been specified to use exit code 127 if an error occurs +so that applications can distinguish ``failure to find a utility'' from +``invoked utility exited with an error indication''. The value 127 was +chosen because it is not commonly used for other meanings; most +utilities use small values for ``normal error conditions'' and the +values above 128 can be confused with termination due to receipt of a +signal. The value 126 was chosen in a similar manner to indicate that +the utility could be found, but not invoked. Some scripts produce +meaningful error messages differentiating the 126 and 127 cases. The +distinction between exit codes 126 and 127 is based on KornShell +practice that uses 127 when all attempts to +.IR exec +the utility fail with +.BR [ENOENT] , +and uses 126 when any attempt to +.IR exec +the utility fails for any other reason. +.P +Historical implementations of the +.IR env +utility use the +\fIexecvp\fR() +or +\fIexeclp\fR() +functions defined in the System Interfaces volume of POSIX.1\(hy2008 to invoke the specified utility; this +provides better performance and keeps users from having to escape +characters with special meaning to the shell. Therefore, shell +functions, special built-ins, and built-ins that are only provided by +the shell are not found. +.SH EXAMPLES +The following command: +.sp +.RS 4 +.nf +\fB +env \(mii PATH=/mybin:"$PATH" $(getconf V7_ENV) mygrep xyz myfile +.fi \fR +.P +.RE +.P +invokes the command +.IR mygrep +with a new +.IR PATH +value as the only entry in its environment other than any variables +required by the implementation for conformance. In this case, +.IR PATH +is used to locate +.IR mygrep , +which is expected to reside in +.BR /mybin . +.SH RATIONALE +As with all other utilities that invoke other utilities, this volume of POSIX.1\(hy2008 only +specifies what +.IR env +does with standard input, standard output, standard error, input files, +and output files. If a utility is executed, it is not constrained by +the specification of input and output by +.IR env . +.P +The +.BR \(mii +option was added to allow the functionality of the removed +.BR \(mi +option in a manner compatible with the Utility Syntax Guidelines. It +is possible to create a non-conforming environment using the +.BR \(mii +option, as it may remove environment variables required by the +implementation for conformance. The following will preserve these +environment variables as well as preserve the +.IR PATH +for conforming utilities: +.sp +.RS 4 +.nf +\fB +IFS=' +\&' +# The preceding value should be . +# Set IFS to its default value. +.P +set \(mif +# disable pathname expansion +.P +\eunalias \(mia +# Unset all possible aliases. +# Note that unalias is escaped to prevent an alias +# being used for unalias. +# This step is not strictly necessary, since aliases are not inherited, +# and the ENV environment variable is only used by interactive shells, +# the only way any aliases can exist in a script is if it defines them +# itself. +.P +unset \(mif env getconf +# Ensure env and getconf are not user functions. +.P +env \(mii $(getconf V7_ENV) PATH="$(getconf PATH)" command +.fi \fR +.P +.RE +.P +Some have suggested that +.IR env +is redundant since the same effect is achieved by: +.sp +.RS 4 +.nf +\fB +name=value ... utility \fB[\fR argument ... \fB]\fR +.fi \fR +.P +.RE +.P +The example is equivalent to +.IR env +when an environment variable is being added to the environment of the +command, but not when the environment is being set to the given value. +The +.IR env +utility also writes out the current environment if invoked without +arguments. There is sufficient functionality beyond what the example +provides to justify inclusion of +.IR env . +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities", +.IR "Section 2.5" ", " "Parameters and Variables" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/eval.1p b/man-pages-posix-2013/man1p/eval.1p new file mode 100644 index 0000000..7414d5b --- /dev/null +++ b/man-pages-posix-2013/man1p/eval.1p @@ -0,0 +1,138 @@ +'\" et +.TH EVAL "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +eval +\(em construct command by concatenating arguments +.SH SYNOPSIS +.LP +.nf +eval \fB[\fIargument\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR eval +utility shall construct a command by concatenating +.IR argument s +together, separating each with a + +character. +The constructed command shall be read and executed by the shell. +.SH OPTIONS +None. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +If there are no +.IR argument s, +or only null +.IR argument s, +.IR eval +shall return a zero exit status; otherwise, it shall return the exit +status of the command defined by the string of concatenated +.IR argument s +separated by + +characters, or a non-zero exit status if the concatenation could not +be parsed as a command and the shell is interactive (and therefore did +not abort). +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Since +.IR eval +is not required to recognize the +.BR \(dq--\(dq +end of options delimiter, in cases where the argument(s) to +.IR eval +might begin with +.BR '-' +it is recommended that the first argument is prefixed by a string that +will not alter the commands to be executed, such as a + +character: +.sp +.RS 4 +.nf +\fB +eval " $commands" +.fi \fR +.P +.RE +.P +or: +.sp +.RS 4 +.nf +\fB +eval " $(some_command)" +.fi \fR +.P +.RE +.SH EXAMPLES +.LP +.nf +foo=10 x=foo +y='$'$x +echo $y +\fB$foo\fR +eval y='$'$x +echo $y +\fB10\fR +.fi +.SH "RATIONALE" +This standard allows, but does not require, +.IR eval +to recognize +.BR \(dq--\(dq . +Although this means applications cannot use +.BR \(dq--\(dq +to protect against options supported as an extension (or errors reported +for unsupported options), the nature of the +.IR eval +utility is such that other means can be used to provide this protection +(see APPLICATION USAGE above). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/ex.1p b/man-pages-posix-2013/man1p/ex.1p new file mode 100644 index 0000000..a3be3e9 --- /dev/null +++ b/man-pages-posix-2013/man1p/ex.1p @@ -0,0 +1,9025 @@ +'\" et +.TH EX "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ex +\(em text editor +.SH SYNOPSIS +.LP +.nf +ex \fB[\fR\(mirR\fB] [\fR\(mis|\(miv\fB] [\fR\(mic \fIcommand\fB] [\fR\(mit \fItagstring\fB] [\fR\(miw \fIsize\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR ex +utility is a line-oriented text editor. There are two other modes of +the editor\(emopen and visual\(emin which screen-oriented editing is +available. This is described more fully by the +.IR ex +.BR open +and +.BR visual +commands and in +.IR "\fIvi\fR\^". +.P +If an operand is +.BR '\(mi' , +the results are unspecified. +.P +This section uses the term +.IR "edit buffer" +to describe the current working text. No specific implementation is +implied by this term. All editing changes are performed on the edit +buffer, and no changes to it shall affect any file until an editor +command writes the file. +.P +Certain terminals do not have all the capabilities necessary to support +the complete +.IR ex +definition, such as the full-screen editing commands (\c +.IR "visual mode" +or +.IR "open mode" ). +When these commands cannot be supported on such terminals, this +condition shall not produce an error message such as ``not an editor +command'' or report a syntax error. The implementation may either +accept the commands and produce results on the screen that are the +result of an unsuccessful attempt to meet the requirements of this volume of POSIX.1\(hy2008 or +report an error describing the terminal-related deficiency. +.SH OPTIONS +The +.IR ex +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except for the unspecified usage of +.BR '\(mi' , +and that +.BR '\(pl' +may be recognized as an option delimiter as well as +.BR '\(mi' . +.P +The following options shall be supported: +.IP "\fB\(mic\ \fIcommand\fR" 10 +Specify an initial command to be executed in the first edit buffer +loaded from an existing file (see the EXTENDED DESCRIPTION section). +Implementations may support more than a single +.BR \(mic +option. In such implementations, the specified commands shall be +executed in the order specified on the command line. +.IP "\fB\(mir\fP" 10 +Recover the named files (see the EXTENDED DESCRIPTION section). +Recovery information for a file shall be saved during an editor or +system crash (for example, when the editor is terminated by a signal +which the editor can catch), or after the use of an +.IR ex +.BR preserve +command. +.RS 10 +.P +A +.IR crash +in this context is an unexpected failure of the system or utility that +requires restarting the failed system or utility. A system crash +implies that any utilities running at the time also crash. In the case +of an editor or system crash, the number of changes to the edit buffer +(since the most recent +.BR preserve +command) that will be recovered is unspecified. +.P +If no +.IR file +operands are given and the +.BR \(mit +option is not specified, all other options, the +.IR EXINIT +variable, and any +.BR .exrc +files shall be ignored; a list of all recoverable files available to +the invoking user shall be written, and the editor shall exit normally +without further action. +.RE +.IP "\fB\(miR\fP" 10 +Set +.BR readonly +edit option. +.IP "\fB\(mis\fP" 10 +Prepare +.IR ex +for batch use by taking the following actions: +.RS 10 +.IP " *" 4 +Suppress writing prompts and informational (but not diagnostic) +messages. +.IP " *" 4 +Ignore the value of +.IR TERM +and any implementation default terminal type and assume the terminal is +a type incapable of supporting open or visual modes; see the +.BR visual +command and the description of +.IR "\fIvi\fR\^". +.IP " *" 4 +Suppress the use of the +.IR EXINIT +environment variable and the reading of any +.BR .exrc +file; see the EXTENDED DESCRIPTION section. +.IP " *" 4 +Suppress autoindentation, ignoring the value of the +.BR autoindent +edit option. +.RE +.IP "\fB\(mit\ \fItagstring\fR" 10 +Edit the file containing the specified +.IR tagstring ; +see +.IR "\fIctags\fR\^". +The tags feature represented by +.BR \(mit +.IR tagstring +and the +.BR tag +command is optional. It shall be provided on any system that also +provides a conforming implementation of +.IR ctags ; +otherwise, the use of +.BR \(mit +produces undefined results. On any system, it shall be an error to +specify more than a single +.BR \(mit +option. +.IP "\fB\(miv\fP" 10 +Begin in visual mode (see +.IR "\fIvi\fR\^"). +.IP "\fB\(miw\ \fIsize\fR" 10 +Set the value of the +.IR window +editor option to +.IR size . +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file to be edited. +.SH STDIN +The standard input consists of a series of commands and input text, as +described in the EXTENDED DESCRIPTION section. The implementation may +limit each line of standard input to a length of +{LINE_MAX}. +.P +If the standard input is not a terminal device, it shall be as if the +.BR \(mis +option had been specified. +.P +If a read from the standard input returns an error, or if the editor +detects an end-of-file condition from the standard input, it shall be +equivalent to a SIGHUP asynchronous event. +.SH "INPUT FILES" +Input files shall be text files or files that would be text files +except for an incomplete last line that is not longer than +{LINE_MAX}\(mi1 +bytes in length and contains no NUL characters. By default, any +incomplete last line shall be treated as if it had a trailing +. +The editing of other forms of files may optionally be allowed by +.IR ex +implementations. +.P +The +.BR .exrc +files and source files shall be text files consisting of +.IR ex +commands; see the EXTENDED DESCRIPTION section. +.P +By default, the editor shall read lines from the files to be edited +without interpreting any of those lines as any form of editor command. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR ex : +.IP "\fICOLUMNS\fP" 10 +Override the system-selected horizontal screen size. See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +for valid values and results when it is unset or null. +.IP "\fIEXINIT\fP" 10 +Determine a list of +.IR ex +commands that are executed on editor start-up. See the EXTENDED +DESCRIPTION section for more details of the initialization phase. +.IP "\fIHOME\fP" 10 +Determine a pathname of a directory that shall be searched for an +editor start-up file named +.BR .exrc ; +see the EXTENDED DESCRIPTION section. +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular expressions. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files), the behavior of +character classes within regular expressions, the classification of +characters as uppercase or lowercase letters, the case conversion of +letters, and the detection of word boundaries. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILINES\fP" 10 +Override the system-selected vertical screen size, used as the number +of lines in a screenful and the vertical screen size in visual mode. +See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +for valid values and results when it is unset or null. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPATH\fP" 10 +Determine the search path for the shell command specified in the +.IR ex +editor commands +.BR ! , +.BR shell , +.BR read , +and +.BR write , +and the open and visual mode command +.BR ! ; +see the description of command search and execution in +.IR "Section 2.9.1.1" ", " "Command Search and Execution". +.IP "\fISHELL\fP" 10 +Determine the preferred command line interpreter for use as the default +value of the +.BR shell +edit option. +.IP "\fITERM\fP" 10 +Determine the name of the terminal type. If this variable is unset or +null, an unspecified default terminal type shall be used. +.SH "ASYNCHRONOUS EVENTS" +The following term is used in this and following sections to specify +command and asynchronous event actions: +.IP "\fIcomplete\ write\fP" 10 +.br +A complete write is a write of the entire contents of the edit buffer +to a file of a type other than a terminal device, or the saving of the +edit buffer caused by the user executing the +.IR ex +.BR preserve +command. Writing the contents of the edit buffer to a temporary file +that will be removed when the editor exits shall not be considered a +complete write. +.P +The following actions shall be taken upon receipt of signals: +.IP SIGINT 10 +If the standard input is not a terminal device, +.IR ex +shall not write the file or return to command or text input mode, and +shall exit with a non-zero exit status. +.RS 10 +.P +Otherwise, if executing an open or visual text input mode command, +.IR ex +in receipt of SIGINT shall behave identically to its receipt of the + +character. +.P +Otherwise: +.IP " 1." 4 +If executing an +.IR ex +text input mode command, all input lines that have been completely +entered shall be resolved into the edit buffer, and any partially +entered line shall be discarded. +.IP " 2." 4 +If there is a currently executing command, it shall be aborted and a +message displayed. Unless otherwise specified by the +.IR ex +or +.IR vi +command descriptions, it is unspecified whether any lines modified by +the executing command appear modified, or as they were before being +modified by the executing command, in the buffer. +.RS 4 +.P +If the currently executing command was a motion command, its associated +command shall be discarded. +.RE +.IP " 3." 4 +If in open or visual command mode, the terminal shall be alerted. +.IP " 4." 4 +The editor shall then return to command mode. +.RE +.IP SIGCONT 10 +The screen shall be refreshed if in open or visual mode. +.IP SIGHUP 10 +If the edit buffer has been modified since the last complete write, +.IR ex +shall attempt to save the edit buffer so that it can be recovered later +using the +.BR \(mir +option or the +.IR ex +.BR recover +command. The editor shall not write the file or return to command or +text input mode, and shall terminate with a non-zero exit status. +.IP SIGTERM 10 +Refer to SIGHUP. +.P +The action taken for all other signals is unspecified. +.SH STDOUT +The standard output shall be used only for writing prompts to the user, +for informational messages, and for writing lines from the file. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The output from +.IR ex +shall be text files. +.SH "EXTENDED DESCRIPTION" +Only the +.IR ex +mode of the editor is described in this section. See +.IR "\fIvi\fR\^" +for additional editing capabilities available in +.IR ex . +.P +When an error occurs, +.IR ex +shall write a message. If the terminal supports a standout mode (such +as inverse video), the message shall be written in standout mode. If +the terminal does not support a standout mode, and the edit option +.BR errorbells +is set, an alert action shall precede the error message. +.P +By default, +.IR ex +shall start in command mode, which shall be indicated by a +.BR : +prompt; see the +.BR prompt +command. Text input mode can be entered by the +.BR append , +.BR insert , +or +.BR change +commands; it can be exited (and command mode re-entered) by typing a + +(\c +.BR '.' ) +alone at the beginning of a line. +.SS "Initialization in ex and vi" +.P +The following symbols are used in this and following sections to +specify locations in the edit buffer: +.IP "\fIalternate\ and\ current\ pathnames\fP" 6 +.br +Two pathnames, named +.IR current +and +.IR alternate , +are maintained by the editor. Any +.IR ex +commands that take filenames as arguments shall set them as follows: +.RS 6 +.IP " 1." 4 +If a +.IR file +argument is specified to the +.IR ex +.BR edit , +.BR ex , +or +.BR recover +commands, or if an +.IR ex +.BR tag +command replaces the contents of the edit buffer. +.RS 4 +.IP " a." 4 +If the command replaces the contents of the edit buffer, the current +pathname shall be set to the +.IR file +argument or the file indicated by the tag, and the alternate pathname +shall be set to the previous value of the current pathname. +.IP " b." 4 +Otherwise, the alternate pathname shall be set to the +.IR file +argument. +.RE +.IP " 2." 4 +If a +.IR file +argument is specified to the +.IR ex +.BR next +command: +.RS 4 +.IP " a." 4 +If the command replaces the contents of the edit buffer, the current +pathname shall be set to the first +.IR file +argument, and the alternate pathname shall be set to the previous +value of the current pathname. +.RE +.IP " 3." 4 +If a +.IR file +argument is specified to the +.IR ex +.BR file +command, the current pathname shall be set to the +.IR file +argument, and the alternate pathname shall be set to the previous +value of the current pathname. +.IP " 4." 4 +If a +.IR file +argument is specified to the +.IR ex +.BR read +and +.BR write +commands (that is, when reading or writing a file, and not to the +program named by the +.BR shell +edit option), or a +.IR file +argument is specified to the +.IR ex +.BR xit +command: +.RS 4 +.IP " a." 4 +If the current pathname has no value, the current pathname shall be +set to the +.IR file +argument. +.IP " b." 4 +Otherwise, the alternate pathname shall be set to the +.IR file +argument. +.RE +.P +If the alternate pathname is set to the previous value of the current +pathname when the current pathname had no previous value, then the +alternate pathname shall have no value as a result. +.RE +.IP "\fIcurrent\ line\fP" 6 +.br +The line of the edit buffer referenced by the cursor. Each command +description specifies the current line after the command has been +executed, as the +.IR "current line value" . +When the edit buffer contains no lines, the current line shall be zero; +see +.IR "Addressing in ex". +.IP "\fIcurrent\ column\fP" 6 +.br +The current display line column occupied by the cursor. (The columns +shall be numbered beginning at 1.) Each command description specifies +the current column after the command has been executed, as the +.IR "current column" +value. This column is an +.IR ideal +column that is remembered over the lifetime of the editor. The actual +display line column upon which the cursor rests may be different from +the current column; see the cursor positioning discussion in +.IR "Command Descriptions in vi". +.IP "\fIset\ to\ non-\fP" 6 +.br +A description for a current column value, meaning that the current +column shall be set to the last display line column on which is +displayed any part of the first non-\c + +of the line. If the line has no non-\c + +non-\c + +characters, the current column shall be set to the last display line +column on which is displayed any part of the last non-\c + +character in the line. If the line is empty, the current column shall +be set to column position 1. +.P +The length of lines in the edit buffer may be limited to +{LINE_MAX} +bytes. In open and visual mode, the length of lines in the edit buffer +may be limited to the number of characters that will fit in the +display. If either limit is exceeded during editing, an error message +shall be written. If either limit is exceeded by a line read in from a +file, an error message shall be written and the edit session may be +terminated. +.P +If the editor stops running due to any reason other than a user +command, and the edit buffer has been modified since the last complete +write, it shall be equivalent to a SIGHUP asynchronous event. If the +system crashes, it shall be equivalent to a SIGHUP asynchronous event. +.P +During initialization (before the first file is copied into the edit +buffer or any user commands from the terminal are processed) the +following shall occur: +.IP " 1." 4 +If the environment variable +.IR EXINIT +is set, the editor shall execute the +.IR ex +commands contained in that variable. +.IP " 2." 4 +If the +.IR EXINIT +variable is not set, and all of the following are true: +.RS 4 +.IP " a." 4 +The +.IR HOME +environment variable is not null and not empty. +.IP " b." 4 +The file +.BR .exrc +in the directory referred to by the +.IR HOME +environment variable: +.RS 4 +.IP " i." 5 +Exists +.IP ii. 5 +Is owned by the same user ID as the real user ID of the process or the +process has appropriate privileges +.IP iii. 5 +Is not writable by anyone other than the owner +.RE +.P +the editor shall execute the +.IR ex +commands contained in that file. +.RE +.IP " 3." 4 +If and only if all of the following are true: +.RS 4 +.IP " a." 4 +The current directory is not referred to by the +.IR HOME +environment variable. +.IP " b." 4 +A command in the +.IR EXINIT +environment variable or a command in the +.BR .exrc +file in the directory referred to by the +.IR HOME +environment variable sets the editor option +.BR exrc . +.IP " c." 4 +The +.BR .exrc +file in the current directory: +.RS 4 +.IP " i." 5 +Exists +.IP ii. 5 +Is owned by the same user ID as the real user ID of the process, or by +one of a set of implementation-defined user IDs +.IP iii. 5 +Is not writable by anyone other than the owner +.RE +.P +the editor shall attempt to execute the +.IR ex +commands contained in that file. +.RE +.P +Lines in any +.BR .exrc +file that are blank lines shall be ignored. If any +.BR .exrc +file exists, but is not read for ownership or permission reasons, it +shall be an error. +.P +After the +.IR EXINIT +variable and any +.BR .exrc +files are processed, the first file specified by the user shall be +edited, as follows: +.IP " 1." 4 +If the user specified the +.BR \(mit +option, the effect shall be as if the +.IR ex +.BR tag +command was entered with the specified argument, with the exception +that if tag processing does not result in a file to edit, the effect +shall be as described in step 3. below. +.IP " 2." 4 +Otherwise, if the user specified any command line +.IR file +arguments, the effect shall be as if the +.IR ex +.BR edit +command was entered with the first of those arguments as its +.IR file +argument. +.IP " 3." 4 +Otherwise, the effect shall be as if the +.IR ex +.BR edit +command was entered with a nonexistent filename as its +.IR file +argument. It is unspecified whether this action shall set the current +pathname. In an implementation where this action does not set the +current pathname, any editor command using the current pathname shall +fail until an editor command sets the current pathname. +.P +If the +.BR \(mir +option was specified, the first time a file in the initial argument +list or a file specified by the +.BR \(mit +option is edited, if recovery information has previously been saved +about it, that information shall be recovered and the editor shall +behave as if the contents of the edit buffer have already been +modified. If there are multiple instances of the file to be recovered, +the one most recently saved shall be recovered, and an informational +message that there are previous versions of the file that can be +recovered shall be written. If no recovery information about a file is +available, an informational message to this effect shall be written, +and the edit shall proceed as usual. +.P +If the +.BR \(mic +option was specified, the first time a file that already exists +(including a file that might not exist but for which recovery +information is available, when the +.BR \(mir +option is specified) replaces or initializes the contents of the edit +buffer, the current line shall be set to the last line of the edit +buffer, the current column shall be set to non-\c +, +and the +.IR ex +commands specified with the +.BR \(mic +option shall be executed. In this case, the current line and current +column shall not be set as described for the command associated with +the replacement or initialization of the edit buffer contents. However, +if the +.BR \(mit +option or a +.BR tag +command is associated with this action, the +.BR \(mic +option commands shall be executed and then the movement to the tag +shall be performed. +.P +The current argument list shall initially be set to the filenames +specified by the user on the command line. If no filenames are +specified by the user, the current argument list shall be empty. If the +.BR \(mit +option was specified, it is unspecified whether any filename resulting +from tag processing shall be prepended to the current argument list. In +the case where the filename is added as a prefix to the current +argument list, the current argument list reference shall be set to that +filename. In the case where the filename is not added as a prefix to +the current argument list, the current argument list reference shall +logically be located before the first of the filenames specified on +the command line (for example, a subsequent +.IR ex +.BR next +command shall edit the first filename from the command line). If the +.BR \(mit +option was not specified, the current argument list reference shall be +to the first of the filenames on the command line. +.SS "Addressing in ex" +.P +Addressing in +.IR ex +relates to the current line and the current column; the address of a +line is its 1-based line number, the address of a column is its 1-based +count from the beginning of the line. Generally, the current line is +the last line affected by a command. The current line number is the +address of the current line. In each command description, the effect of +the command on the current line number and the current column is +described. +.P +Addresses are constructed as follows: +.IP " 1." 4 +The character +.BR '.' +(period) shall address the current line. +.IP " 2." 4 +The character +.BR '$' +shall address the last line of the edit buffer. +.IP " 3." 4 +The positive decimal number +.IR n +shall address the +.IR n th +line of the edit buffer. +.IP " 4." 4 +The address +.BR \(dq'x\(dq +refers to the line marked with the mark name character +.BR 'x' , +which shall be a lowercase letter from the portable character set, +the backquote character, or the single-quote character. It shall be an +error if the line that was marked is not currently present in the edit +buffer or the mark has not been set. Lines can be marked with the +.IR ex +.BR mark +or +.BR k +commands, or the +.IR vi +.BR m +command. +.IP " 5." 4 +A regular expression enclosed by + +characters (\c +.BR '/' ) +shall address the first line found by searching forwards from the line +following the current line toward the end of the edit buffer and +stopping at the first line for which the line excluding the terminating + +matches the regular expression. As stated in +.IR "Regular Expressions in ex", +an address consisting of a null regular expression delimited by + +characters (\c +.BR \(dq//\(dq ) +shall address the next line for which the line excluding the +terminating + +matches the last regular expression encountered. In addition, the second + +can be omitted at the end of a command line. If the +.BR wrapscan +edit option is set, the search shall wrap around to the beginning of +the edit buffer and continue up to and including the current line, so +that the entire edit buffer is searched. Within the regular expression, +the sequence +.BR \(dq\e/\(dq +shall represent a literal + +instead of the regular expression delimiter. +.IP " 6." 4 +A regular expression enclosed in + +characters (\c +.BR '?' ) +shall address the first line found by searching backwards from the line +preceding the current line toward the beginning of the edit buffer and +stopping at the first line for which the line excluding the terminating + +matches the regular expression. An address consisting of a null regular +expression delimited by + +characters (\c +.BR \(dq??\(dq ) +shall address the previous line for which the line excluding the +terminating + +matches the last regular expression encountered. In addition, the second + +can be omitted at the end of a command line. If the +.BR wrapscan +edit option is set, the search shall wrap around from the beginning of +the edit buffer to the end of the edit buffer and continue up to and +including the current line, so that the entire edit buffer is +searched. Within the regular expression, the sequence +.BR \(dq\e?\(dq +shall represent a literal + +instead of the RE delimiter. +.IP " 7." 4 +A + +(\c +.BR '\(pl' ) +or a minus-sign (\c +.BR '\(mi' ) +followed by a decimal number shall address the current line plus or +minus the number. A +.BR '\(pl' +or +.BR '\(mi' +not followed by a decimal number shall address the current line plus or +minus 1. +.P +Addresses can be followed by zero or more address offsets, optionally +-separated. +Address offsets are constructed as follows: +.IP " 1." 4 +A +.BR '\(pl' +or +.BR '\(mi' +immediately followed by a decimal number shall add (subtract) the +indicated number of lines to (from) the address. A +.BR '\(pl' +or +.BR '\(mi' +not followed by a decimal number shall add (subtract) 1 to (from) the +address. +.IP " 2." 4 +A decimal number shall add the indicated number of lines to the +address. +.P +It shall not be an error for an intermediate address value to be less +than zero or greater than the last line in the edit buffer. It shall be +an error for the final address value to be less than zero or greater +than the last line in the edit buffer. +.P +Commands take zero, one, or two addresses; see the descriptions of +.IR 1addr +and +.IR 2addr +in +.IR "Command Descriptions in ex". +If more than the required number of addresses are provided to a command +that requires zero addresses, it shall be an error. Otherwise, if more +than the required number of addresses are provided to a command, the +addresses specified first shall be evaluated and then discarded until +the maximum number of valid addresses remain. +.P +Addresses shall be separated from each other by a + +(\c +.BR ',' ) +or a + +(\c +.BR ';' ). +If no address is specified before or after a + +or + +separator, it shall be as if the address of the current line was +specified before or after the separator. In the case of a + +separator, the current line (\c +.BR '.' ) +shall be set to the first address, and only then will the next address +be calculated. This feature can be used to determine the starting line +for forwards and backwards searches (see rules 5. and 6.). +.P +A + +(\c +.BR '%' ) +shall be equivalent to entering the two addresses +.BR \(dq1,$\(dq . +.P +Any delimiting + +characters between addresses, address separators, or address offsets +shall be discarded. +.SS "Command Line Parsing in ex" +.P +The following symbol is used in this and following sections to describe +parsing behavior: +.IP "\fIescape\fP" 10 +If a character is referred to as ``\c +-escaped'' +or ``\c +\(hyV-escaped'', +it shall mean that the character acquired or lost a special +meaning by virtue of being preceded, respectively, by a + +or +\(hyV +character. Unless otherwise specified, the escaping character shall be +discarded at that time and shall not be further considered for any +purpose. +.P +Command-line parsing shall be done in the following steps. For each +step, characters already evaluated shall be ignored; that is, the +phrase ``leading character'' refers to the next character that has not +yet been evaluated. +.IP " 1." 4 +Leading + +characters shall be skipped. +.IP " 2." 4 +Leading + +characters shall be skipped. +.IP " 3." 4 +If the leading character is a double-quote character, the characters up +to and including the next non-\c +-escaped + +shall be discarded, and any subsequent characters shall be parsed as a +separate command. +.IP " 4." 4 +Leading characters that can be interpreted as addresses shall be +evaluated; see +.IR "Addressing in ex". +.IP " 5." 4 +Leading + +characters shall be skipped. +.IP " 6." 4 +If the next character is a + +character or a +: +.RS 4 +.IP " a." 4 +If the next character is a +: +.RS 4 +.IP " i." 5 +If +.IR ex +is in open or visual mode, the current line shall be set to the last +address specified, if any. +.IP ii. 5 +Otherwise, if the last command was terminated by a + +character, no action shall be taken; for example, the command +.BR \(dq||\(dq +shall execute two implied commands, not three. +.IP iii. 5 +Otherwise, step 6.b. shall apply. +.RE +.IP " b." 4 +Otherwise, the implied command shall be the +.BR print +command. The last +.BR # , +.BR p , +and +.BR l +flags specified to any +.IR ex +command shall be remembered and shall apply to this implied command. +Executing the +.IR ex +.BR number , +.BR print , +or +.BR list +command shall set the remembered flags to +.BR # , +nothing, and +.BR l , +respectively, plus any other flags specified for that execution of the +.BR number , +.BR print , +or +.BR list +command. +.RS 4 +.P +If +.IR ex +is not currently performing a +.BR global +or +.BR v +command, and no address or count is specified, the current line shall +be incremented by 1 before the command is executed. If incrementing the +current line would result in an address past the last line in the edit +buffer, the command shall fail, and the increment shall not happen. +.RE +.IP " c." 4 +The + +or + +character shall be discarded and any subsequent characters shall be +parsed as a separate command. +.RE +.IP " 7." 4 +The command name shall be comprised of the next character (if the +character is not alphabetic), or the next character and any subsequent +alphabetic characters (if the character is alphabetic), with the +following exceptions: +.RS 4 +.IP " a." 4 +Commands that consist of any prefix of the characters in the command +name +.BR delete , +followed immediately by any of the characters +.BR 'l' , +.BR 'p' , +.BR '\(pl' , +.BR '\(mi' , +or +.BR '#' +shall be interpreted as a +.BR delete +command, followed by a +, +followed by the characters that were not part of the prefix of the +.BR delete +command. The maximum number of characters shall be matched to the +command name +.BR delete ; +for example, +.BR \(dqdel\(dq +shall not be treated as +.BR \(dqde\(dq +followed by the flag +.BR l . +.IP " b." 4 +Commands that consist of the character +.BR 'k' , +followed by a character that can be used as the name of a mark, shall +be equivalent to the mark command followed by a +, +followed by the character that followed the +.BR 'k' . +.IP " c." 4 +Commands that consist of the character +.BR 's' , +followed by characters that could be interpreted as valid options to +the +.BR s +command, shall be the equivalent of the +.BR s +command, without any pattern or replacement values, followed by a +, +followed by the characters after the +.BR 's' . +.RE +.IP " 8." 4 +The command name shall be matched against the possible command names, +and a command name that contains a prefix matching the characters +specified by the user shall be the executed command. In the case of +commands where the characters specified by the user could be ambiguous, +the executed command shall be as follows: +.TS +center tab(!) box; +lB | lB || lB | lB || lB | lB. +a!append!n!next!t!t +c!change!p!print!u!undo +ch!change!pr!print!un!undo +e!edit!r!read!v!v +m!move!re!read!w!write +ma!mark!s!s +.TE +.RS 4 +.P +Implementation extensions with names causing similar ambiguities shall +not be checked for a match until all possible matches for commands +specified by POSIX.1\(hy2008 have been checked. +.RE +.IP " 9." 4 +If the command is a +.BR ! +command, or if the command is a +.BR read +command followed by zero or more + +characters and a +.BR ! , +or if the command is a +.BR write +command followed by one or more + +characters and a +.BR ! , +the rest of the command shall include all characters up to a non-\c +-escaped +. +The + +shall be discarded and any subsequent characters shall be parsed as a +separate +.IR ex +command. +.IP 10. 4 +Otherwise, if the command is an +.BR edit , +.BR ex , +or +.BR next +command, or a +.BR visual +command while in open or visual mode, the next part of the command +shall be parsed as follows: +.RS 4 +.IP " a." 4 +Any +.BR '!' +character immediately following the command shall be skipped and be +part of the command. +.IP " b." 4 +Any leading + +characters shall be skipped and be part of the command. +.IP " c." 4 +If the next character is a +.BR '\(pl' , +characters up to the first non-\c +-escaped + +or non-\c +-escaped + +shall be skipped and be part of the command. +.IP " d." 4 +The rest of the command shall be determined by the steps specified in +paragraph 12. +.RE +.IP 11. 4 +Otherwise, if the command is a +.BR global , +.BR open , +.BR s , +or +.BR v +command, the next part of the command shall be parsed as follows: +.RS 4 +.IP " a." 4 +Any leading + +characters shall be skipped and be part of the command. +.IP " b." 4 +If the next character is not an alphanumeric, double-quote, +, +, +or + +character: +.RS 4 +.IP " i." 5 +The next character shall be used as a command delimiter. +.IP ii. 5 +If the command is a +.BR global , +.BR open , +or +.BR v +command, characters up to the first non-\c +-escaped +, +or first non-\c +-escaped +delimiter character, shall be skipped and be part of the command. +.IP iii. 5 +If the command is an +.BR s +command, characters up to the first non-\c +-escaped +, +or second non-\c +-escaped +delimiter character, shall be skipped and be part of the command. +.RE +.IP " c." 4 +If the command is a +.BR global +or +.BR v +command, characters up to the first non-\c +-escaped + +shall be skipped and be part of the command. +.IP " d." 4 +Otherwise, the rest of the command shall be determined by the steps +specified in paragraph 12. +.RE +.IP 12. 4 +Otherwise: +.RS 4 +.IP " a." 4 +If the command was a +.BR map , +.BR unmap , +.BR abbreviate , +or +.BR unabbreviate +command, characters up to the first non-\c +\(hyV-escaped +, +, +or double-quote character shall be skipped and be part of the command. +.IP " b." 4 +Otherwise, characters up to the first non-\c +-escaped +, +, +or double-quote character shall be skipped and be part of the command. +.IP " c." 4 +If the command was an +.BR append , +.BR change , +or +.BR insert +command, and the step 12.b. ended at a + +character, any subsequent characters, up to the next non-\c +-escaped + +shall be used as input text to the command. +.IP " d." 4 +If the command was ended by a double-quote character, all subsequent +characters, up to the next non-\c +-escaped +, +shall be discarded. +.IP " e." 4 +The terminating + +or + +character shall be discarded and any subsequent characters shall be +parsed as a separate +.IR ex +command. +.RE +.P +Command arguments shall be parsed as described by the Synopsis and +Description of each individual +.IR ex +command. This parsing shall not be +-sensitive, +except for the +.BR ! +argument, which must follow the command name without intervening + +characters, and where it would otherwise be ambiguous. For example, +.IR count +and +.IR flag +arguments need not be +-separated +because +.BR \(dqd22p\(dq +is not ambiguous, but +.IR file +arguments to the +.IR ex +.BR next +command must be separated by one or more + +characters. Any + +in command arguments for the +.BR abbreviate , +.BR unabbreviate , +.BR map , +and +.BR unmap +commands can be +\(hyV-escaped, +in which case the + +shall not be used as an argument delimiter. Any + +in the command argument for any other command can be +-escaped, +in which case that + +shall not be used as an argument delimiter. +.P +Within command arguments for the +.BR abbreviate , +.BR unabbreviate , +.BR map , +and +.BR unmap +commands, any character can be +\(hyV-escaped. +All such escaped characters shall be treated literally and shall have +no special meaning. Within command arguments for all other +.IR ex +commands that are not regular expressions or replacement strings, any +character that would otherwise have a special meaning can be +-escaped. +Escaped characters shall be treated literally, without special meaning +as shell expansion characters or +.BR '!' , +.BR '%' , +and +.BR '#' +expansion characters. See +.IR "Regular Expressions in ex" +and +.IR "Replacement Strings in ex" +for descriptions of command arguments that are regular expressions or +replacement strings. +.P +Non-\c +-escaped +.BR '%' +characters appearing in +.IR file +arguments to any +.IR ex +command shall be replaced by the current pathname; unescaped +.BR '#' +characters shall be replaced by the alternate pathname. It shall be an +error if +.BR '%' +or +.BR '#' +characters appear unescaped in an argument and their corresponding +values are not set. +.P +Non-\c +-escaped +.BR '!' +characters in the arguments to either the +.IR ex +.BR ! +command or the open and visual mode +.BR ! +command, or in the arguments to the +.IR ex +.BR read +command, where the first non-\c + +after the command name is a +.BR '!' +character, or in the arguments to the +.IR ex +.BR write +command where the command name is followed by one or more + +characters and the first non-\c + +after the command name is a +.BR '!' +character, shall be replaced with the arguments to the last of those +three commands as they appeared after all unescaped +.BR '%' , +.BR '#' , +and +.BR '!' +characters were replaced. It shall be an error if +.BR '!' +characters appear unescaped in one of these commands and there has been +no previous execution of one of these commands. +.P +If an error occurs during the parsing or execution of an +.IR ex +command: +.IP " *" 4 +An informational message to this effect shall be written. Execution of +the +.IR ex +command shall stop, and the cursor (for example, the current line and +column) shall not be further modified. +.IP " *" 4 +If the +.IR ex +command resulted from a map expansion, all characters from that map +expansion shall be discarded, except as otherwise specified by the +.BR map +command. +.IP " *" 4 +Otherwise, if the +.IR ex +command resulted from the processing of an +.IR EXINIT +environment variable, a +.BR .exrc +file, a +.BR :source +command, a +.BR \(mic +option, or a +.BR + \c +.IR command +specified to an +.IR ex +.BR edit , +.BR ex , +.BR next , +or +.BR visual +command, no further commands from the source of the commands shall be +executed. +.IP " *" 4 +Otherwise, if the +.IR ex +command resulted from the execution of a buffer or a +.BR global +or +.BR v +command, no further commands caused by the execution of the buffer or +the +.BR global +or +.BR v +command shall be executed. +.IP " *" 4 +Otherwise, if the +.IR ex +command was not terminated by a +, +all characters up to and including the next non-\c +-escaped + +shall be discarded. +.SS "Input Editing in ex" +.P +The following symbol is used in this and the following sections to +specify command actions: +.IP "\fIword\fP" 10 +In the POSIX locale, a word consists of a maximal sequence of letters, +digits, and underscores, delimited at both ends by characters other +than letters, digits, or underscores, or by the beginning or end of a +line or the edit buffer. +.P +When accepting input characters from the user, in either +.IR ex +command mode or +.IR ex +text input mode, +.IR ex +shall enable canonical mode input processing, as defined in the System Interfaces volume of POSIX.1\(hy2008. +.br +.P +If in +.IR ex +text input mode: +.IP " 1." 4 +If the +.BR number +edit option is set, +.IR ex +shall prompt for input using the line number that would be assigned to +the line if it is entered, in the format specified for the +.IR ex +.BR number +command. +.IP " 2." 4 +If the +.BR autoindent +edit option is set, +.IR ex +shall prompt for input using +.BR autoindent +characters, as described by the +.BR autoindent +edit option. +.BR autoindent +characters shall follow the line number, if any. +.P +If in +.IR ex +command mode: +.IP " 1." 4 +If the +.BR prompt +edit option is set, input shall be prompted for using a single +.BR ':' +character; otherwise, there shall be no prompt. +.P +The input characters in the following sections shall have the following +effects on the input line. +.SS "Scroll" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +eof +.fi \fR +.P +.RE +.RE +.P +See the description of the +.IR stty +.IR eof +character in +.IR "\fIstty\fR\^". +.P +If in +.IR ex +command mode: +.sp +.RS +If the +.IR eof +character is the first character entered on the line, the line shall be +evaluated as if it contained two characters: a +\(hyD +and a +. +.P +Otherwise, the +.IR eof +character shall have no special meaning. +.RE +.br +.P +If in +.IR ex +text input mode: +.sp +.RS +If the cursor follows an +.BR autoindent +character, the +.BR autoindent +characters in the line shall be modified so that a part of the next +text input character will be displayed on the first column in the line +after the previous +.BR shiftwidth +edit option column boundary, and the user shall be prompted again for +input for the same line. +.P +Otherwise, if the cursor follows a +.BR '0' , +which follows an +.BR autoindent +character, and the +.BR '0' +was the previous text input character, the +.BR '0' +and all +.BR autoindent +characters in the line shall be discarded, and the user shall be +prompted again for input for the same line. +.P +Otherwise, if the cursor follows a +.BR '^' , +which follows an +.BR autoindent +character, and the +.BR '^' +was the previous text input character, the +.BR '^' +and all +.BR autoindent +characters in the line shall be discarded, and the user shall be +prompted again for input for the same line. In addition, the +.BR autoindent +level for the next input line shall be derived from the same line from +which the +.BR autoindent +level for the current input line was derived. +.P +Otherwise, if there are no +.BR autoindent +or text input characters in the line, the +.IR eof +character shall be discarded. +.P +Otherwise, the +.IR eof +character shall have no special meaning. +.RE +.SS "" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB + +.br +-J +.fi \fR +.P +.RE +.RE +.P +If in +.IR ex +command mode: +.sp +.RS +Cause the command line to be parsed; +\(hyJ +shall be mapped to the + +for this purpose. +.RE +.br +.P +If in +.IR ex +text input mode: +.sp +.RS +Terminate the current line. If there are no characters other than +.BR autoindent +characters on the line, all characters on the line shall be discarded. +.P +Prompt for text input on a new line after the current line. If the +.BR autoindent +edit option is set, an appropriate number of +.BR autoindent +characters shall be added as a prefix to the line as described by the +.IR ex +.BR autoindent +edit option. +.RE +.SS "" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB + +.fi \fR +.P +.RE +.RE +.P +Allow the entry of a subsequent + +or +\(hyJ +as a literal character, removing any special meaning that it may have +to the editor during text input mode. The + +character shall be retained and evaluated when the command line is +parsed, or retained and included when the input text becomes part of +the edit buffer. +.SS "\(hyV" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +-V +.fi \fR +.P +.RE +.RE +.P +Allow the entry of any subsequent character as a literal character, +removing any special meaning that it may have to the editor during text +input mode. The +\(hyV +character shall be discarded before the command line is parsed or the +input text becomes part of the edit buffer. +.P +If the ``literal next'' functionality is performed by the underlying +system, it is implementation-defined whether a character other than +\(hyV +performs this function. +.SS "\(hyW" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +-W +.fi \fR +.P +.RE +.RE +.P +Discard the +\(hyW, +and the word previous to it in the input line, including any + +characters following the word and preceding the +\(hyW. +If the ``word erase'' functionality is performed by the underlying +system, it is implementation-defined whether a character other than +\(hyW +performs this function. +.SS "Command Descriptions in ex" +.P +The following symbols are used in this section to represent command +modifiers. Some of these modifiers can be omitted, in which case the +specified defaults shall be used. +.IP "\fI1addr\fR" 10 +A single line address, given in any of the forms described in +.IR "Addressing in ex"; +the default shall be the current line (\c +.BR '.' ), +unless otherwise specified. +.RS 10 +.P +If the line address is zero, it shall be an error, unless otherwise +specified in the following command descriptions. +.P +If the edit buffer is empty, and the address is specified with a +command other than +.BR = , +.BR append , +.BR insert , +.BR open , +.BR put , +.BR read , +or +.BR visual , +or the address is not zero, it shall be an error. +.RE +.IP "\fI2addr\fP" 10 +Two addresses specifying an inclusive range of lines. If no addresses +are specified, the default for +.IR 2addr +shall be the current line only (\c +.BR \(dq.,.\(dq ), +unless otherwise specified in the following command descriptions. If +one address is specified, +.IR 2addr +shall specify that line only, unless otherwise specified in the +following command descriptions. +.RS 10 +.P +It shall be an error if the first address is greater than the second +address. +.P +If the edit buffer is empty, and the two addresses are specified with a +command other than the +.BR ! , +.BR write , +.BR wq , +or +.BR xit +commands, or either address is not zero, it shall be an error. +.RE +.IP "\fIcount\fP" 10 +A positive decimal number. If +.IR count +is specified, it shall be equivalent to specifying an additional +address to the command, unless otherwise specified by the following +command descriptions. The additional address shall be equal to the last +address specified to the command (either explicitly or by default) plus +.IR count \(mi1. +.RS 10 +.P +If this would result in an address greater than the last line of the +edit buffer, it shall be corrected to equal the last line of the edit +buffer. +.RE +.IP "\fIflags\fP" 10 +One or more of the characters +.BR '\(pl' , +.BR '\(mi' , +.BR '#' , +.BR 'p' , +or +.BR 'l' +(ell). The flag characters can be +-separated, +and in any order or combination. The characters +.BR '#' , +.BR 'p' , +and +.BR 'l' +shall cause lines to be written in the format specified by the +.BR print +command with the specified +.IR flags . +.RS 10 +.P +The lines to be written are as follows: +.IP " 1." 4 +All edit buffer lines written during the execution of the +.IR ex +.BR & , +.BR ~ , +.BR list , +.BR number , +.BR open , +.BR print , +.BR s , +.BR visual , +and +.BR z +commands shall be written as specified by +.IR flags . +.IP " 2." 4 +After the completion of an +.IR ex +command with a flag as an argument, the current line shall be written +as specified by +.IR flags , +unless the current line was the last line written by the command. +.P +The characters +.BR '\(pl' +and +.BR '\(mi' +cause the value of the current line after the execution of the +.IR ex +command to be adjusted by the offset address as described in +.IR "Addressing in ex". +This adjustment shall occur before the current line is written as +described in 2. above. +.P +The default for +.IR flags +shall be none. +.RE +.IP "\fIbuffer\fP" 10 +One of a number of named areas for holding text. The named buffers are +specified by the alphanumeric characters of the POSIX locale. There +shall also be one ``unnamed'' buffer. When no buffer is specified for +editor commands that use a buffer, the unnamed buffer shall be used. +Commands that store text into buffers shall store the text as it was +before the command took effect, and shall store text occurring earlier +in the file before text occurring later in the file, regardless of how +the text region was specified. Commands that store text into buffers +shall store the text into the unnamed buffer as well as any specified +buffer. +.RS 10 +.P +In +.IR ex +commands, buffer names are specified as the name by itself. In open or +visual mode commands the name is preceded by a double-quote (\c +.BR '\&"' ) +character. +.P +If the specified buffer name is an uppercase character, and the buffer +contents are to be modified, the buffer shall be appended to rather +than being overwritten. If the buffer is not being modified, specifying +the buffer name in lowercase and uppercase shall have identical +results. +.P +There shall also be buffers named by the numbers 1 through 9. In open +and visual mode, if a region of text including characters from more +than a single line is being modified by the +.IR vi +.BR c +or +.BR d +commands, the motion character associated with the +.BR c +or +.BR d +commands specifies that the buffer text shall be in line mode, or the +commands +.BR % , +.BR ` , +.BR / , +.BR ? , +.BR ( , +.BR ) , +.BR N , +.BR n , +.BR { , +or +.BR } +are used to define a region of text for the +.BR c +or +.BR d +commands, the contents of buffers 1 through 8 shall be moved into the +buffer named by the next numerically greater value, the contents of +buffer 9 shall be discarded, and the region of text shall be copied +into buffer 1. This shall be in addition to copying the text into a +user-specified buffer or unnamed buffer, or both. Numeric buffers can +be specified as a source buffer for open and visual mode commands; +however, specifying a numeric buffer as the write target of an open or +visual mode command shall have unspecified results. +.P +The text of each buffer shall have the characteristic of being in +either line or character mode. Appending text to a non-empty buffer +shall set the mode to match the characteristic of the +text being appended. Appending text to a buffer shall cause the +creation of at least one additional line in the buffer. All text stored +into buffers by +.IR ex +commands shall be in line mode. The +.IR ex +commands that use buffers as the source of text specify individually +how buffers of different modes are handled. Each open or visual mode +command that uses buffers for any purpose specifies individually the +mode of the text stored into the buffer and how buffers of different +modes are handled. +.RE +.IP "\fIfile\fP" 10 +Command text used to derive a pathname. The default shall be the +current pathname, as defined previously, in which case, if no current +pathname has yet been established it shall be an error, except where +specifically noted in the individual command descriptions that follow. +If the command text contains any of the characters +.BR '~' , +.BR '{' , +.BR '[' , +.BR '*' , +.BR '?' , +.BR '$' , +.BR '\&"' , +backquote, single-quote, and +, +it shall be subjected to the process of ``shell expansions'', as +described below; if more than a single pathname results and the +command expects only one, it shall be an error. +.RS 10 +.P +The process of shell expansions in the editor shall be done as +follows. The +.IR ex +utility shall pass two arguments to the program named by the shell edit +option; the first shall be +.BR \(mic , +and the second shall be the string +.BR \(dqecho\(dq +and the command text as a single argument. The standard output and +standard error of that command shall replace the command text. +.RE +.IP "\fB!\fP" 10 +A character that can be appended to the command name to modify its +operation, as detailed in the individual command descriptions. With the +exception of the +.IR ex +.BR read , +.BR write , +and +.BR ! +commands, the +.BR '!' +character shall only act as a modifier if there are no + +characters between it and the command name. +.IP "\fIremembered\ search\ direction\fP" 10 +.br +The +.IR vi +commands +.BR N +and +.BR n +begin searching in a forwards or backwards direction in the edit buffer +based on a remembered search direction, which is initially unset, and +is set by the +.IR ex +.BR global , +.BR v , +.BR s , +and +.BR tag +commands, and the +.IR vi +.BR / +and +.BR ? +commands. +.SS "Abbreviate" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +ab\fB[\fIbreviate\fB][\fIlhs rhs\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If +.IR lhs +and +.IR rhs +are not specified, write the current list of abbreviations and do +nothing more. +.P +Implementations may restrict the set of characters accepted in +.IR lhs +or +.IR rhs , +except that printable characters and + +characters shall not be restricted. Additional restrictions shall be +implementation-defined. +.P +In both +.IR lhs +and +.IR rhs , +any character may be escaped with a +\(hyV, +in which case the character shall not be used to delimit +.IR lhs +from +.IR rhs , +and the escaping +\(hyV +shall be discarded. +.P +In open and visual text input mode, if a non-word or + +character that is not escaped by a +\(hyV +character is entered after a word character, a check shall be made for +a set of characters matching +.IR lhs , +in the text input entered during this command. If it is found, the +effect shall be as if +.IR rhs +was entered instead of +.IR lhs . +.P +The set of characters that are checked is defined as follows: +.IP " 1." 4 +If there are no characters inserted before the word and non-word or + +characters that triggered the check, the set of characters shall +consist of the word character. +.IP " 2." 4 +If the character inserted before the word and non-word or + +characters that triggered the check is a word character, the set of +characters shall consist of the characters inserted immediately before +the triggering characters that are word characters, plus the triggering +word character. +.IP " 3." 4 +If the character inserted before the word and non-word or + +characters that triggered the check is not a word character, the set of +characters shall consist of the characters that were inserted before +the triggering characters that are neither + +characters nor word characters, plus the triggering word character. +.P +It is unspecified whether the +.IR lhs +argument entered for the +.IR ex +.BR abbreviate +and +.BR unabbreviate +commands is replaced in this fashion. Regardless of whether or not the +replacement occurs, the effect of the command shall be as if the +replacement had not occurred. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Append" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI1addr\fB] \fRa\fB[\fRppend\fB][\fR!\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Enter +.IR ex +text input mode; the input text shall be placed after the specified +line. If line zero is specified, the text shall be placed at the +beginning of the edit buffer. +.P +This command shall be affected by the +.BR number +and +.BR autoindent +edit options; following the command name with +.BR '!' +shall cause the +.BR autoindent +edit option setting to be toggled for the duration of this command +only. +.P +.IR "Current line" : +Set to the last input line; if no lines were input, set to the +specified line, or to the first line of the edit buffer if a line of +zero was specified, or zero if the edit buffer is empty. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Arguments" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +ar\fB[\fIgs\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Write the current argument list, with the current argument-list entry, +if any, between +.BR '[' +and +.BR ']' +characters. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Change" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRc\fB[\fRhange\fB][\fR!\fB][\fIcount\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Enter +.IR ex +text input mode; the input text shall replace the specified lines. The +specified lines shall be copied into the unnamed buffer, which shall +become a line mode buffer. +.P +This command shall be affected by the +.BR number +and +.BR autoindent +edit options; following the command name with +.BR '!' +shall cause the +.BR autoindent +edit option setting to be toggled for the duration of this command +only. +.P +.IR "Current line" : +Set to the last input line; if no lines were input, set to the line +before the first address, or to the first line of the edit buffer if +there are no lines preceding the first address, or to zero if the edit +buffer is empty. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Change Directory" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +chd\fB[\fRir\fB][\fR!\fB][\fIdirectory\fB]\fR +cd\fB[\fR!\fB][\fIdirectory\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Change the current working directory to +.IR directory . +.P +If no +.IR directory +argument is specified, and the +.IR HOME +environment variable is set to a non-null and non-empty value, +.IR directory +shall default to the value named in the +.IR HOME +environment variable. If the +.IR HOME +environment variable is empty or is undefined, the default value of +.IR directory +is implementation-defined. +.P +If no +.BR '!' +is appended to the command name, and the edit buffer has been modified +since the last complete write, and the current pathname does not begin +with a +.BR '/' , +it shall be an error. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Copy" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRco\fB[\fRpy\fB] \fI1addr \fB[\fIflags\fB] +[\fI2addr\fB] \fRt \fI1addr \fB[\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Copy the specified lines after the specified destination line; line +zero specifies that the lines shall be placed at the beginning of the +edit buffer. +.P +.IR "Current line" : +Set to the last line copied. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Delete" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRd\fB[\fRelete\fB][\fIbuffer\fB][\fIcount\fB][\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Delete the specified lines into a buffer (defaulting to the unnamed +buffer), which shall become a line-mode buffer. +.P +Flags can immediately follow the command name; see +.IR "Command Line Parsing in ex". +.P +.IR "Current line" : +Set to the line following the deleted lines, or to the last line in the +edit buffer if that line is past the end of the edit buffer, or to zero +if the edit buffer is empty. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Edit" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +e\fB[\fRdit\fB][\fR!\fB][\fR+\fIcommand\fB][\fIfile\fB]\fR +ex\fB[\fR!\fB][\fR+\fIcommand\fB][\fIfile\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If no +.BR '!' +is appended to the command name, and the edit buffer has been modified +since the last complete write, it shall be an error. +.P +If +.IR file +is specified, replace the current contents of the edit buffer with the +current contents of +.IR file , +and set the current pathname to +.IR file . +If +.IR file +is not specified, replace the current contents of the edit buffer with +the current contents of the file named by the current pathname. If for +any reason the current contents of the file cannot be accessed, the +edit buffer shall be empty. +.P +The +.BR + \c +.IR command +option shall be +-delimited; + +characters within the +.BR + \c +.IR command +can be escaped by preceding them with a + +character. The +.BR + \c +.IR command +shall be interpreted as an +.IR ex +command immediately after the contents of the edit buffer have been +replaced and the current line and column have been set. +.P +If the edit buffer is empty: +.P +.IR "Current line" : +Set to 0. +.P +.IR "Current column" : +Set to 1. +.P +Otherwise, if executed while in +.IR ex +command mode or if the +.BR + \c +.IR command +argument is specified: +.P +.IR "Current line" : +Set to the last line of the edit buffer. +.P +.IR "Current column" : +Set to non-\c +. +.P +Otherwise, if +.IR file +is omitted or results in the current pathname: +.P +.IR "Current line" : +Set to the first line of the edit buffer. +.P +.IR "Current column" : +Set to non-\c +. +.P +Otherwise, if +.IR file +is the same as the last file edited, the line and column shall be set +as follows; if the file was previously edited, the line and column may +be set as follows: +.P +.IR "Current line" : +Set to the last value held when that file was last edited. If this +value is not a valid line in the new edit buffer, set to the first line +of the edit buffer. +.P +.IR "Current column" : +If the current line was set to the last value held when the file was +last edited, set to the last value held when the file was last edited. +Otherwise, or if the last value is not a valid column in the new edit +buffer, set to non-\c +. +.br +.P +Otherwise: +.P +.IR "Current line" : +Set to the first line of the edit buffer. +.P +.IR "Current column" : +Set to non-\c +. +.SS "File" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +f\fB[\fRile\fB][\fIfile\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If a +.IR file +argument is specified, the alternate pathname shall be set to the +current pathname, and the current pathname shall be set to +.IR file . +.P +Write an informational message. If the file has a current pathname, it +shall be included in this message; otherwise, the message shall +indicate that there is no current pathname. If the edit buffer +contains lines, the current line number and the number of lines in the +edit buffer shall be included in this message; otherwise, the message +shall indicate that the edit buffer is empty. If the edit buffer has +been modified since the last complete write, this fact shall be +included in this message. If the +.BR readonly +edit option is set, this fact shall be included in this message. The +message may contain other unspecified information. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Global" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRg\fB[\fRlobal\fB] \fR/\fIpattern\fR/ \fB[\fIcommands\fB] +[\fI2addr\fB] \fRv /\fIpattern\fR/ \fB[\fIcommands\fB]\fR +.fi \fR +.P +.RE +.RE +.P +The optional +.BR '!' +character after the +.BR global +command shall be the same as executing the +.BR v +command. +.P +If +.IR pattern +is empty (for example, +.BR \(dq//\(dq ) +or not specified, the last regular expression used in the editor +command shall be used as the +.IR pattern . +The +.IR pattern +can be delimited by + +characters (shown in the Synopsis), as well as any non-alphanumeric +or non-\c + +other than +, +, +, +or double-quote. +.P +If no lines are specified, the lines shall default to the entire file. +.P +The +.BR global +and +.BR v +commands are logically two-pass operations. First, mark the lines +within the specified lines for which the line excluding the terminating + +matches (\c +.BR global ) +or does not match (\c +.BR v +or +.BR global! ) +the specified pattern. Second, execute the +.IR ex +commands given by +.IR commands , +with the current line (\c +.BR '.' ) +set to each marked line. If an error occurs during this process, or the +contents of the edit buffer are replaced (for example, by the +.IR ex +.BR :edit +command) an error message shall be written and no more commands +resulting from the execution of this command shall be processed. +.P +Multiple +.IR ex +commands can be specified by entering multiple commands on a single +line using a + +to delimit them, or one per line, by escaping each + +with a +. +.P +If no commands are specified: +.IP " 1." 4 +If in +.IR ex +command mode, it shall be as if the +.BR print +command were specified. +.IP " 2." 4 +Otherwise, no command shall be executed. +.P +For the +.BR append , +.BR change , +and +.BR insert +commands, the input text shall be included as part of the command, and +the terminating + +can be omitted if the command ends the list of commands. The +.BR open +and +.BR visual +commands can be specified as one of the commands, in which case each +marked line shall cause the editor to enter open or visual mode. If +open or visual mode is exited using the +.IR vi +.BR Q +command, the current line shall be set to the next marked line, and +open or visual mode reentered, until the list of marked lines is +exhausted. +.P +The +.BR global , +.BR v , +and +.BR undo +commands cannot be used in +.IR commands . +Marked lines may be deleted by commands executed for lines occurring +earlier in the file than the marked lines. In this case, no commands +shall be executed for the deleted lines. +.P +If the remembered search direction is not set, the +.BR global +and +.BR v +commands shall set it to forward. +.P +The +.BR autoprint +and +.BR autoindent +edit options shall be inhibited for the duration of the +.BR g +or +.BR v +command. +.P +.IR "Current line" : +If no commands executed, set to the last marked line. Otherwise, as +specified for the executed +.IR ex +commands. +.P +.IR "Current column" : +If no commands are executed, set to non-\c +; +otherwise, as specified for the individual +.IR ex +commands. +.SS "Insert" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI1addr\fB] \fRi\fB[\fRnsert\fB][\fR!\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Enter +.IR ex +text input mode; the input text shall be placed before the specified +line. If the line is zero or 1, the text shall be placed at the +beginning of the edit buffer. +.P +This command shall be affected by the +.BR number +and +.BR autoindent +edit options; following the command name with +.BR '!' +shall cause the +.BR autoindent +edit option setting to be toggled for the duration of this command +only. +.P +.IR "Current line" : +Set to the last input line; if no lines were input, set to the line +before the specified line, or to the first line of the edit buffer if +there are no lines preceding the specified line, or zero if the edit +buffer is empty. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Join" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRj\fB[\fRoin\fB][\fR!\fB][\fIcount\fB][\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If +.IR count +is specified: +.sp +.RS +If no address was specified, the +.BR join +command shall behave as if +.IR 2addr +were the current line and the current line plus +.IR count +(.\|,\|. + +.IR count ). +.P +If one address was specified, the +.BR join +command shall behave as if +.IR 2addr +were the specified address and the specified address plus +.IR count +(\c +.IR addr ,\c +.IR addr ++ +.IR count ). +.P +If two addresses were specified, the +.BR join +command shall behave as if an additional address, equal to the last +address plus +.IR count +\(mi1 (\c +.IR addr1 ,\c +.IR addr2 ,\c +.IR addr2 ++ +.IR count +\(mi1), was specified. +.P +If this would result in a second address greater than the last line of +the edit buffer, it shall be corrected to be equal to the last line of +the edit buffer. +.RE +.P +If no +.IR count +is specified: +.sp +.RS +If no address was specified, the +.BR join +command shall behave as if +.IR 2addr +were the current line and the next line (.\|,\|. +1). +.P +If one address was specified, the +.BR join +command shall behave as if +.IR 2addr +were the specified address and the next line (\c +.IR addr ,\c +.IR addr ++1). +.RE +.P +Join the text from the specified lines together into a single line, +which shall replace the specified lines. +.P +If a +.BR '!' +character is appended to the command name, the +.BR join +shall be without modification of any line, independent of the current +locale. +.P +Otherwise, in the POSIX locale, set the current line to the first of +the specified lines, and then, for each subsequent line, proceed as +follows: +.IP " 1." 4 +Discard leading + +characters from the line to be joined. +.IP " 2." 4 +If the line to be joined is now empty, delete it, and skip steps 3 +through 5. +.IP " 3." 4 +If the current line ends in a +, +or the first character of the line to be joined is a +.BR ')' +character, join the lines without further modification. +.IP " 4." 4 +If the last character of the current line is a +.BR '.' , +join the lines with two + +characters between them. +.IP " 5." 4 +Otherwise, join the lines with a single + +between them. +.P +.IR "Current line" : +Set to the first line specified. +.P +.IR "Current column" : +Set to non-\c +. +.SS "List" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRl\fB[\fRist\fB][\fIcount\fB][\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the +.IR ex +command: +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRp\fB[\fRrint\fB][\fIcount\fB] \fRl\fB[\fIflags\fB]\fR +.fi \fR +.P +.RE +.P +See +.IR "Print". +.SS "Map" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +map\fB[\fR!\fB][\fIlhs rhs\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If +.IR lhs +and +.IR rhs +are not specified: +.IP " 1." 4 +If +.BR '!' +is specified, write the current list of text input mode maps. +.IP " 2." 4 +Otherwise, write the current list of command mode maps. +.IP " 3." 4 +Do nothing more. +.P +Implementations may restrict the set of characters accepted in +.IR lhs +or +.IR rhs , +except that printable characters and + +characters shall not be restricted. Additional restrictions shall be +implementation-defined. In both +.IR lhs +and +.IR rhs , +any character can be escaped with a +\(hyV, +in which case the character shall not be used to delimit +.IR lhs +from +.IR rhs , +and the escaping +\(hyV +shall be discarded. +.P +If the character +.BR '!' +is appended to the +.BR map +command name, the mapping shall be effective during open or visual text +input mode rather than +.BR open +or +.BR visual +command mode. This allows +.IR lhs +to have two different +.BR map +definitions at the same time: one for command mode and one for text +input mode. +.br +.P +For command mode mappings: +.sp +.RS +When the +.IR lhs +is entered as any part of a +.IR vi +command in open or visual mode (but not as part of the arguments to the +command), the action shall be as if the corresponding +.IR rhs +had been entered. +.P +If any character in the command, other than the first, is escaped using +a +\(hyV +character, that character shall not be part of a match to an +.IR lhs . +.P +It is unspecified whether implementations shall support +.BR map +commands where the +.IR lhs +is more than a single character in length, where the first character of +the +.IR lhs +is printable. +.RE +.P +.sp +.RS +If +.IR lhs +contains more than one character and the first character is +.BR '#' , +followed by a sequence of digits corresponding to a numbered function +key, then when this function key is typed it shall be mapped to +.IR rhs . +Characters other than digits following a +.BR '#' +character also represent the function key named by the characters in +the +.IR lhs +following the +.BR '#' +and may be mapped to +.IR rhs . +It is unspecified how function keys are named or what function keys are +supported. +.RE +.P +For text input mode mappings: +.sp +.RS +When the +.IR lhs +is entered as any part of text entered in open or visual text input +modes, the action shall be as if the corresponding +.IR rhs +had been entered. +.P +If any character in the input text is escaped using a +\(hyV +character, that character shall not be part of a match to an +.IR lhs . +.P +It is unspecified whether the +.IR lhs +text entered for subsequent +.BR map +or +.BR unmap +commands is replaced with the +.IR rhs +text for the purposes of the screen display; regardless of whether or +not the display appears as if the corresponding +.IR rhs +text was entered, the effect of the command shall be as if the +.IR lhs +text was entered. +.RE +.P +If only part of the +.IR lhs +is entered, it is unspecified how long the editor will wait for +additional, possibly matching characters before treating the already +entered characters as not matching the +.IR lhs . +.P +The +.IR rhs +characters shall themselves be subject to remapping, unless otherwise +specified by the +.BR remap +edit option, except that if the characters in +.IR lhs +occur as prefix characters in +.IR rhs , +those characters shall not be remapped. +.P +On block-mode terminals, the mapping need not occur immediately (for +example, it may occur after the terminal transmits a group of +characters to the system), but it shall achieve the same results as if +it occurred immediately. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Mark" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI1addr\fB] \fRma\fB[\fRrk\fB] \fIcharacter +\fB[\fI1addr\fB] \fRk \fIcharacter\fR +.fi \fR +.P +.RE +.RE +.P +Implementations shall support +.IR character +values of a single lowercase letter of the POSIX locale and the +backquote and single-quote characters; support of other characters is +implementation-defined. +.P +If executing the +.IR vi +.BR m +command, set the specified mark to the current line and 1-based +numbered character referenced by the current column, if any; otherwise, +column position 1. +.P +Otherwise, set the specified mark to the specified line and 1-based +numbered first non-\c + +non-\c + +in the line, if any; otherwise, the last non-\c + +in the line, if any; otherwise, column position 1. +.P +The mark shall remain associated with the line until the mark is reset +or the line is deleted. If a deleted line is restored by a subsequent +.BR undo +command, any marks previously associated with the line, which have not +been reset, shall be restored as well. Any use of a mark not associated +with a current line in the edit buffer shall be an error. +.P +The marks +.BR ` +and +.BR ' +shall be set as described previously, immediately before the following +events occur in the editor: +.IP " 1." 4 +The use of +.BR '$' +as an +.IR ex +address +.IP " 2." 4 +The use of a positive decimal number as an +.IR ex +address +.IP " 3." 4 +The use of a search command as an +.IR ex +address +.IP " 4." 4 +The use of a mark reference as an +.IR ex +address +.IP " 5." 4 +The use of the following open and visual mode commands: +\(hy], +.BR % , +.BR ( , +.BR ) , +.BR [ , +.BR ] , +.BR { , +.BR } +.IP " 6." 4 +The use of the following open and visual mode commands: +.BR ' , +.BR G , +.BR H , +.BR L , +.BR M , +.BR z +if the current line will change as a result of the command +.IP " 7." 4 +The use of the open and visual mode commands: +.BR / , +.BR ? , +.BR N , +.BR ` , +.BR n +if the current line or column will change as a result of the command +.IP " 8." 4 +The use of the +.IR ex +mode commands: +.BR z , +.BR undo , +.BR global , +.BR v +.P +For rules 1., 2., 3., and 4., the +.BR ` +and +.BR ' +marks shall not be set if the +.IR ex +command is parsed as specified by rule 6.a. in +.IR "Command Line Parsing in ex". +.P +For rules 5., 6., and 7., the +.BR ` +and +.BR ' +marks shall not be set if the commands are used as motion commands in +open and visual mode. +.P +For rules 1., 2., 3., 4., 5., 6., 7., and 8., the +.BR ` +and +.BR ' +marks shall not be set if the command fails. +.P +The +.BR ` +and +.BR ' +marks shall be set as described previously, each time the contents of +the edit buffer are replaced (including the editing of the initial +buffer), if in open or visual mode, or if in +.BR ex +mode and the edit buffer is not empty, before any commands or movements +(including commands or movements specified by the +.BR \(mic +or +.BR \(mit +options or the +.BR + \c +.IR command +argument) are executed on the edit buffer. If in open or visual mode, +the marks shall be set as if executing the +.IR vi +.BR m +command; otherwise, as if executing the +.IR ex +.BR mark +command. +.P +When changing from +.BR ex +mode to open or visual mode, if the +.BR ` +and +.BR ' +marks are not already set, the +.BR ` +and +.BR ' +marks shall be set as described previously. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Move" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRm\fB[\fRove\fB] \fI1addr\fR \fB[\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Move the specified lines after the specified destination line. A +destination of line zero specifies that the lines shall be placed at +the beginning of the edit buffer. It shall be an error if the +destination line is within the range of lines to be moved. +.P +.IR "Current line" : +Set to the last of the moved lines. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Next" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +n\fB[\fRext\fB][\fR!\fB][\fR+\fIcommand\fB][\fIfile \fR...\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If no +.BR '!' +is appended to the command name, and the edit buffer has been modified +since the last complete write, it shall be an error, unless the file is +successfully written as specified by the +.BR autowrite +option. +.br +.P +If one or more files is specified: +.IP " 1." 4 +Set the argument list to the specified filenames. +.IP " 2." 4 +Set the current argument list reference to be the first entry in the +argument list. +.IP " 3." 4 +Set the current pathname to the first filename specified. +.P +Otherwise: +.IP " 1." 4 +It shall be an error if there are no more filenames in the argument +list after the filename currently referenced. +.IP " 2." 4 +Set the current pathname and the current argument list reference to +the filename after the filename currently referenced in the argument +list. +.P +Replace the contents of the edit buffer with the contents of the file +named by the current pathname. If for any reason the contents of the +file cannot be accessed, the edit buffer shall be empty. +.P +This command shall be affected by the +.BR autowrite +and +.BR writeany +edit options. +.P +The +.BR + \c +.IR command +option shall be +-delimited; + +characters can be escaped by preceding them with a + +character. The +.BR + \c +.IR command +shall be interpreted as an +.IR ex +command immediately after the contents of the edit buffer have been +replaced and the current line and column have been set. +.P +.IR "Current line" : +Set as described for the +.BR edit +command. +.P +.IR "Current column" : +Set as described for the +.BR edit +command. +.SS "Number" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRnu\fB[\fRmber\fB][\fIcount\fB][\fIflags\fB] +[\fI2addr\fB] \fR#\fB[\fIcount\fB][\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +These commands shall be equivalent to the +.IR ex +command: +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRp\fB[\fRrint\fB][\fIcount\fB] \fR#\fB[\fIflags\fB]\fR +.fi \fR +.P +.RE +.P +See +.IR "Print". +.SS "Open" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI1addr\fB] \fRo\fB[\fRpen\fB]\fR /\fIpattern\fR/ \fB[\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +This command need not be supported on block-mode terminals or terminals +with insufficient capabilities. If standard input, standard output, or +standard error are not terminal devices, the results are unspecified. +.P +Enter open mode. +.P +The trailing delimiter can be omitted from +.IR pattern +at the end of the command line. If +.IR pattern +is empty (for example, +.BR \(dq//\(dq ) +or not specified, the last regular expression used in the editor shall +be used as the pattern. The pattern can be delimited by + +characters (shown in the Synopsis), as well as any alphanumeric, or non-\c + +other than +, +, +, +or +double-quote. +.P +.IR "Current line" : +Set to the specified line. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Preserve" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +pre\fB[\fRserve\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Save the edit buffer in a form that can later be recovered by using the +.BR \(mir +option or by using the +.IR ex +.BR recover +command. After the file has been preserved, a mail message shall be +sent to the user. This message shall be readable by invoking the +.IR mailx +utility. The message shall contain the name of the file, the time of +preservation, and an +.IR ex +command that could be used to recover the file. Additional information +may be included in the mail message. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Print" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRp\fB[\fRrint\fB][\fIcount\fB][\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Write the addressed lines. The behavior is unspecified if the number of +columns on the display is less than the number of columns required to +write any single character in the lines being written. +.P +Non-printable characters, except for the +, +shall be written as implementation-defined multi-character sequences. +.P +If the +.BR # +flag is specified or the +.BR number +edit option is set, each line shall be preceded by its line number in +the following format: +.sp +.RS 4 +.nf +\fB +"%6d ", <\fIline number\fR> +.fi \fR +.P +.RE +.P +If the +.BR l +flag is specified or the +.BR list +edit option is set: +.IP " 1." 4 +The characters listed in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Table 5-1" ", " "Escape Sequences and Associated Actions" +shall be written as the corresponding escape sequence. +.IP " 2." 4 +Non-printable characters not in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Table 5-1" ", " "Escape Sequences and Associated Actions" +shall be written as one three-digit octal number (with a preceding +) +for each byte in the character (most significant byte first). +.IP " 3." 4 +The end of each line shall be marked with a +.BR '$' , +and literal +.BR '$' +characters within the line shall be written with a preceding +. +.P +Long lines shall be folded; the length at which folding occurs is +unspecified, but should be appropriate for the output terminal, +considering the number of columns of the terminal. +.P +If a line is folded, and the +.BR l +flag is not specified and the +.BR list +edit option is not set, it is unspecified whether a multi-column +character at the folding position is separated; it shall not be +discarded. +.P +.IR "Current line" : +Set to the last written line. +.P +.IR "Current column" : +Unchanged if the current line is unchanged; otherwise, set to non-\c +. +.SS "Put" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI1addr\fB] \fRpu\fB[\fRt\fB][\fIbuffer\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Append text from the specified buffer (by default, the unnamed buffer) +to the specified line; line zero specifies that the text shall be +placed at the beginning of the edit buffer. Each portion of a line in +the buffer shall become a new line in the edit buffer, regardless of +the mode of the buffer. +.P +.IR "Current line" : +Set to the last line entered into the edit buffer. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Quit" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +q\fB[\fRuit\fB][\fR!\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If no +.BR '!' +is appended to the command name: +.IP " 1." 4 +If the edit buffer has been modified since the last complete write, it +shall be an error. +.IP " 2." 4 +If there are filenames in the argument list after the filename +currently referenced, and the last command was not a +.BR quit , +.BR wq , +.BR xit , +or +.BR ZZ +(see +.IR "Exit") +command, it shall be an error. +.P +Otherwise, terminate the editing session. +.SS "Read" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI1addr\fB] \fRr\fB[\fRead\fB][\fR!\fB][\fIfile\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If +.BR '!' +is not the first non-\c + +to follow the command name, a copy of the specified file shall be +appended into the edit buffer after the specified line; line zero +specifies that the copy shall be placed at the beginning of the edit +buffer. The number of lines and bytes read shall be written. If no +.IR file +is named, the current pathname shall be the default. If there is no +current pathname, then +.IR file +shall become the current pathname. If there is no current pathname or +.IR file +operand, it shall be an error. Specifying a +.IR file +that is not of type regular shall have unspecified results. +.P +Otherwise, if +.IR file +is preceded by +.BR '!' , +the rest of the line after the +.BR '!' +shall have +.BR '%' , +.BR '#' , +and +.BR '!' +characters expanded as described in +.IR "Command Line Parsing in ex". +.P +The +.IR ex +utility shall then pass two arguments to the program named by the +shell edit option; the first shall be +.BR \(mic +and the second shall be the expanded arguments to the +.BR read +command as a single argument. The standard input of the program shall +be set to the standard input of the +.IR ex +program when it was invoked. The standard error and standard output of +the program shall be appended into the edit buffer after the specified +line. +.P +Each line in the copied file or program output (as delimited by + +characters or the end of the file or output if it is not immediately +preceded by a +), +shall be a separate line in the edit buffer. Any occurrences of + +and + +pairs in the output shall be treated as single + +characters. +.P +The special meaning of the +.BR '!' +following the +.BR read +command can be overridden by escaping it with a + +character. +.P +.IR "Current line" : +If no lines are added to the edit buffer, unchanged. Otherwise, if in +open or visual mode, set to the first line entered into the edit +buffer. Otherwise, set to the last line entered into the edit buffer. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Recover" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +rec\fB[\fRover\fB][\fR!\fB] \fIfile\fR +.fi \fR +.P +.RE +.RE +.P +If no +.BR '!' +is appended to the command name, and the edit buffer has been modified +since the last complete write, it shall be an error. +.P +If no +.IR file +operand is specified, then the current pathname shall be used. If +there is no current pathname or +.IR file +operand, it shall be an error. +.P +If no recovery information has previously been saved about +.IR file , +the +.BR recover +command shall behave identically to the +.BR edit +command, and an informational message to this effect shall be written. +.P +Otherwise, set the current pathname to +.IR file , +and replace the current contents of the edit buffer with the recovered +contents of +.IR file . +If there are multiple instances of the file to be recovered, the one +most recently saved shall be recovered, and an informational message +that there are previous versions of the file that can be recovered +shall be written. The editor shall behave as if the contents of the +edit buffer have already been modified. +.P +.IR "Current file" : +Set as described for the +.BR edit +command. +.P +.IR "Current column" : +Set as described for the +.BR edit +command. +.SS "Rewind" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +rew\fB[\fRind\fB][\fR!\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If no +.BR '!' +is appended to the command name, and the edit buffer has been modified +since the last complete write, it shall be an error, unless the file is +successfully written as specified by the +.BR autowrite +option. +.P +If the argument list is empty, it shall be an error. +.P +The current argument list reference and the current pathname shall be +set to the first filename in the argument list. +.P +Replace the contents of the edit buffer with the contents of the file +named by the current pathname. If for any reason the contents of the +file cannot be accessed, the edit buffer shall be empty. +.P +This command shall be affected by the +.BR autowrite +and +.BR writeany +edit options. +.P +.IR "Current line" : +Set as described for the +.BR edit +command. +.P +.IR "Current column" : +Set as described for the +.BR edit +command. +.SS "Set" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +se\fB[\fRt\fB][\fIoption\fB[\fR=\fB[\fIvalue\fB]]\fR ...\fB][\fRno\fIoption\fR ...\fB][\fIoption\fR? ...\fB][\fRall\fB]\fR +.fi \fR +.P +.RE +.RE +.P +When no arguments are specified, write the value of the +.BR term +edit option and those options whose values have been changed from the +default settings; when the argument +.IR all +is specified, write all of the option values. +.P +Giving an option name followed by the character +.BR '?' +shall cause the current value of that option to be written. The +.BR '?' +can be separated from the option name by zero or more + +characters. The +.BR '?' +shall be necessary only for Boolean valued options. Boolean options can +be given values by the form +.BR set +.IR option +to turn them on or +.BR set +.BR no \c +.IR option +to turn them off; string and numeric options can be assigned by the +form +.BR set +.IR option =\c +.IR value . +Any + +characters in strings can be included as is by preceding each + +with an escaping +. +More than one option can be set or listed by a single set command by +specifying multiple arguments, each separated from the next by one or more + +characters. +.P +See +.IR "Edit Options in ex" +for details about specific options. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Shell" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +sh\fB[\fRell\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Invoke the program named in the +.BR shell +edit option with the single argument +.BR \(mii +(interactive mode). Editing shall be resumed when the program exits. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Source" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +so\fB[\fRurce\fB] \fIfile\fR +.fi \fR +.P +.RE +.RE +.P +Read and execute +.IR ex +commands from +.IR file . +Lines in the file that are blank lines shall be ignored. +.P +.IR "Current line" : +As specified for the individual +.IR ex +commands. +.P +.IR "Current column" : +As specified for the individual +.IR ex +commands. +.SS "Substitute" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRs\fB[\fRubstitute\fB][\fR/\fIpattern\fR/\fIrepl\fR/\fB[\fIoptions\fB][\fIcount\fB][\fIflags\fB]]\fR +.br +\fB[\fI2addr\fB] \fR&\fB[\fIoptions\fB][\fIcount\fB][\fIflags\fB]]\fR +.br +\fB[\fI2addr\fB] \fR~\fB[\fIoptions\fB][\fIcount\fB][\fIflags\fB]]\fR +.fi \fR +.P +.RE +.RE +.P +Replace the first instance of the pattern +.IR pattern +by the string +.IR repl +on each specified line. (See +.IR "Regular Expressions in ex" +and +.IR "Replacement Strings in ex".) +Any non-alphabetic, non-\c + +delimiter other than +, +.BR '|' , +, +or double-quote +can be used instead of +.BR '/' . + +characters can be used to escape delimiters, + +characters, and other special characters. +.P +The trailing delimiter can be omitted from +.IR pattern +or from +.IR repl +at the end of the command line. If both +.IR pattern +and +.IR repl +are not specified or are empty (for example, +.BR \(dq//\(dq ), +the last +.BR s +command shall be repeated. If only +.IR pattern +is not specified or is empty, the last regular expression used in the +editor shall be used as the pattern. If only +.IR repl +is not specified or is empty, the pattern shall be replaced by nothing. +If the entire replacement pattern is +.BR '%' , +the last replacement pattern to an +.BR s +command shall be used. +.P +Entering a + +in +.IR repl +(which requires an escaping + +in +.IR ex +mode and an escaping +\(hyV +in open or +.IR vi +mode) shall split the line at that point, creating a new line in the +edit buffer. The + +shall be discarded. +.P +If +.IR options +includes the letter +.BR 'g' +(\c +.BR global ), +all non-overlapping instances of the pattern in the line shall be +replaced. +.P +If +.IR options +includes the letter +.BR 'c' +(\c +.BR confirm ), +then before each substitution the line shall be written; the written +line shall reflect all previous substitutions. On the following line, + +characters shall be written beneath the characters from the line that +are before the +.IR pattern +to be replaced, and +.BR '^' +characters written beneath the characters included in the +.IR pattern +to be replaced. The +.IR ex +utility shall then wait for a response from the user. An affirmative +response shall cause the substitution to be done, while any other input +shall not make the substitution. An affirmative response shall consist +of a line with the affirmative response (as defined by the current +locale) at the beginning of the line. This line shall be subject to +editing in the same way as the +.IR ex +command line. +.P +If interrupted (see the ASYNCHRONOUS EVENTS section), any modifications +confirmed by the user shall be preserved in the edit buffer after the +interrupt. +.P +If the remembered search direction is not set, the +.BR s +command shall set it to forward. +.P +In the second Synopsis, the +.BR & +command shall repeat the previous substitution, as if the +.BR & +command were replaced by: +.sp +.RS 4 +.nf +\fB +s/\fIpattern\fR/\fIrepl\fR/ +.fi \fR +.P +.RE +.P +where +.IR pattern +and +.IR repl +are as specified in the previous +.BR s , +.BR & , +or +.BR ~ +command. +.P +In the third Synopsis, the +.BR ~ +command shall repeat the previous substitution, as if the +.BR '~' +were replaced by: +.sp +.RS 4 +.nf +\fB +s/\fIpattern\fR/\fIrepl\fR/ +.fi \fR +.P +.RE +.P +where +.IR pattern +shall be the last regular expression specified to the editor, and +.IR repl +shall be from the previous substitution (including +.BR & +and +.BR ~ ) +command. +.P +These commands shall be affected by the +.IR LC_MESSAGES +environment variable. +.P +.IR "Current line" : +Set to the last line in which a substitution occurred, or, unchanged if +no substitution occurred. +.P +.IR "Current column": +Set to non-\c +. +.SS "Suspend" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +su\fB[\fRspend\fB][\fR!\fB]\fR +st\fB[\fRop\fB][\fR!\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Allow control to return to the invoking process; +.IR ex +shall suspend itself as if it had received the SIGTSTP signal. The +suspension shall occur only if job control is enabled in the invoking +shell (see the description of +.IR set +.BR \(mim ). +.P +These commands shall be affected by the +.BR autowrite +and +.BR writeany +edit options. +.P +The current +.BR susp +character (see +.IR "\fIstty\fR\^") +shall be equivalent to the +.BR suspend +command. +.SS "Tag" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +ta\fB[\fRg\fB][\fR!\fB] \fItagstring\fR +.fi \fR +.P +.RE +.RE +.P +The results are unspecified if the format of a tags file is not as +specified by the +.IR ctags +utility (see +.IR "\fIctags\fR\^") +description. +.P +The +.BR tag +command shall search for +.IR tagstring +in the tag files referred to by the +.BR tag +edit option, in the order they are specified, until a reference to +.IR tagstring +is found. Files shall be searched from beginning to end. If no +reference is found, it shall be an error and an error message to this +effect shall be written. If the reference is not found, or if an error +occurs while processing a file referred to in the +.BR tag +edit option, it shall be an error, and an error message shall be +written at the first occurrence of such an error. +.P +Otherwise, if the tags file contained a pattern, the pattern shall be +treated as a regular expression used in the editor; for example, for +the purposes of the +.BR s +command. +.P +If the +.IR tagstring +is in a file with a different name than the current pathname, set the +current pathname to the name of that file, and replace the contents of +the edit buffer with the contents of that file. In this case, if no +.BR '!' +is appended to the command name, and the edit buffer has been modified +since the last complete write, it shall be an error, unless the file is +successfully written as specified by the +.BR autowrite +option. +.P +This command shall be affected by the +.BR autowrite , +.BR tag , +.BR taglength , +and +.BR writeany +edit options. +.P +.IR "Current line" : +If the tags file contained a line number, set to that line number. If +the line number is larger than the last line in the edit buffer, an +error message shall be written and the current line shall be set as +specified for the +.BR edit +command. +.P +If the tags file contained a pattern, set to the first occurrence of +the pattern in the file. If no matching pattern is found, an error +message shall be written and the current line shall be set as specified +for the +.BR edit +command. +.P +.IR "Current column" : +If the tags file contained a line-number reference and that line-number +was not larger than the last line in the edit buffer, or if the tags +file contained a pattern and that pattern was found, set to non-\c +. +Otherwise, set as specified for the +.BR edit +command. +.SS "Unabbreviate" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +una\fB[\fRbbrev\fB] \fIlhs\fR +.fi \fR +.P +.RE +.RE +.P +If +.IR lhs +is not an entry in the current list of abbreviations (see +.IR "Abbreviate"), +it shall be an error. Otherwise, delete +.IR lhs +from the list of abbreviations. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Undo" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +u\fB[\fRndo\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Reverse the changes made by the last command that modified the contents +of the edit buffer, including +.BR undo . +For this purpose, the +.BR global , +.BR v , +.BR open , +and +.BR visual +commands, and commands resulting from buffer executions and mapped +character expansions, are considered single commands. +.P +If no action that can be undone preceded the +.BR undo +command, it shall be an error. +.P +If the +.BR undo +command restores lines that were marked, the mark shall also be +restored unless it was reset subsequent to the deletion of the lines. +.P +.IR "Current line" : +.IP " 1." 4 +If lines are added or changed in the file, set to the first line added +or changed. +.IP " 2." 4 +Set to the line before the first line deleted, if it exists. +.IP " 3." 4 +Set to 1 if the edit buffer is not empty. +.IP " 4." 4 +Set to zero. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Unmap" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +unm\fB[\fRap\fB][\fR!\fB] \fIlhs\fR +.fi \fR +.P +.RE +.RE +.P +If +.BR '!' +is appended to the command name, and if +.IR lhs +is not an entry in the list of text input mode map definitions, it +shall be an error. Otherwise, delete +.IR lhs +from the list of text input mode map definitions. +.P +If no +.BR '!' +is appended to the command name, and if +.IR lhs +is not an entry in the list of command mode map definitions, it shall +be an error. Otherwise, delete +.IR lhs +from the list of command mode map definitions. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Version" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +ve\fB[\fRrsion\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Write a message containing version information for the editor. The +format of the message is unspecified. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Visual" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI1addr\fB] \fRvi\fB[\fRsual\fB][\fItype\fB][\fIcount\fB][\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If +.IR ex +is currently in open or visual mode, the Synopsis and behavior of the +visual command shall be the same as the +.BR edit +command, as specified by +.IR "Edit". +.P +Otherwise, this command need not be supported on block-mode terminals +or terminals with insufficient capabilities. If standard input, +standard output, or standard error are not terminal devices, the +results are unspecified. +.P +If +.IR count +is specified, the value of the +.BR window +edit option shall be set to +.IR count +(as described in +.IR "window"). +If the +.BR '^' +type character was also specified, the +.BR window +edit option shall be set before being used by the type character. +.P +Enter visual mode. If +.IR type +is not specified, it shall be as if a +.IR type +of +.BR '\(pl' +was specified. The +.IR type +shall cause the following effects: +.IP "\fR+\fP" 6 +Place the beginning of the specified line at the top of the display. +.IP "\fR-\fP" 6 +Place the end of the specified line at the bottom of the display. +.IP "\fR.\fP" 6 +Place the beginning of the specified line in the middle of the display. +.IP "\fR^\fP" 6 +If the specified line is less than or equal to the value of the +.BR window +edit option, set the line to 1; otherwise, decrement the line by the +value of the +.BR window +edit option minus 1. Place the beginning of this line as close to the +bottom of the displayed lines as possible, while still displaying the +value of the +.BR window +edit option number of lines. +.P +.IR "Current line" : +Set to the specified line. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Write" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRw\fB[\fRrite\fB][\fR!\fB][\fR>>\fB][\fIfile\fB] +[\fI2addr\fB] \fRw\fB[\fRrite\fB][\fR!\fB][\fIfile\fB] +[\fI2addr\fB] \fRwq\fB[\fR!\fB][\fR>>\fB][\fIfile\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If no lines are specified, the lines shall default to the entire file. +.P +The command +.BR wq +shall be equivalent to a +.BR write +command followed by a +.BR quit +command; +.BR wq! +shall be equivalent to +.BR write! +followed by +.BR quit . +In both cases, if the +.BR write +command fails, the +.BR quit +shall not be attempted. +.P +If the command name is not followed by one or more + +characters, or +.IR file +is not preceded by a +.BR '!' +character, the +.BR write +shall be to a file. +.IP " 1." 4 +If the +.BR >> +argument is specified, and the file already exists, the lines shall be +appended to the file instead of replacing its contents. If the +.BR >> +argument is specified, and the file does not already exist, it is +unspecified whether the write shall proceed as if the +.BR >> +argument had not been specified or if the write shall fail. +.IP " 2." 4 +If the +.BR readonly +edit option is set (see +.IR "readonly"), +the +.BR write +shall fail. +.IP " 3." 4 +If +.IR file +is specified, and is not the current pathname, and the file exists, +the +.BR write +shall fail. +.IP " 4." 4 +If +.IR file +is not specified, the current pathname shall be used. If there is no +current pathname, the +.BR write +command shall fail. +.IP " 5." 4 +If the current pathname is used, and the current pathname has been +changed by the +.BR file +or +.BR read +commands, and the file exists, the +.BR write +shall fail. If the +.BR write +is successful, subsequent +.BR write s +shall not fail for this reason (unless the current pathname is changed +again). +.IP " 6." 4 +If the whole edit buffer is not being written, and the file to be +written exists, the +.BR write +shall fail. +.P +For rules 1., 2., 3., and 5., the +.BR write +can be forced by appending the character +.BR '!' +to the command name. +.P +For rules 2., 3., and 5., the +.BR write +can be forced by setting the +.BR writeany +edit option. +.P +Additional, implementation-defined tests may cause the +.BR write +to fail. +.P +If the edit buffer is empty, a file without any contents shall be written. +.P +An informational message shall be written noting the number of lines +and bytes written. +.P +Otherwise, if the command is followed by one or more + +characters, and the file is preceded by +.BR '!' , +the rest of the line after the +.BR '!' +shall have +.BR '%' , +.BR '#' , +and +.BR '!' +characters expanded as described in +.IR "Command Line Parsing in ex". +.P +The +.IR ex +utility shall then pass two arguments to the program named by the +.BR shell +edit option; the first shall be +.BR \(mic +and the second shall be the expanded arguments to the +.BR write +command as a single argument. The specified lines shall be written to +the standard input of the command. The standard error and standard +output of the program, if any, shall be written as described for the +.BR print +command. If the last character in that output is not a +, +a + +shall be written at the end of the output. +.P +The special meaning of the +.BR '!' +following the +.BR write +command can be overridden by escaping it with a + +character. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Write and Exit" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRx\fB[\fRit\fB][\fR!\fB][\fIfile\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If the edit buffer has not been modified since the last complete +.BR write , +.BR xit +shall be equivalent to the +.BR quit +command, or if a +.BR '!' +is appended to the command name, to +.BR quit! . +.P +Otherwise, +.BR xit +shall be equivalent to the +.BR wq +command, or if a +.BR '!' +is appended to the command name, to +.BR wq! . +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Yank" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB] \fRya\fB[\fRnk\fB][\fIbuffer\fB][\fIcount\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Copy the specified lines to the specified buffer (by default, the +unnamed buffer), which shall become a line-mode buffer. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Adjust Window" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI1addr\fB] \fRz\fB[\fR!\fB][\fItype \fR...\fB][\fIcount\fB][\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If no line is specified, the current line shall be the default; if +.IR type +is omitted as well, the current line value shall first be incremented +by 1. If incrementing the current line would cause it to be greater +than the last line in the edit buffer, it shall be an error. +.P +If there are + +characters between the +.IR type +argument and the preceding +.BR z +command name or optional +.BR '!' +character, it shall be an error. +.P +If +.IR count +is specified, the value of the +.BR window +edit option shall be set to +.IR count +(as described in +.IR "window"). +If +.IR count +is omitted, it shall default to 2 times the value of the +.BR scroll +edit option, or if +.BR ! +was specified, the number of lines in the display minus 1. +.P +If +.IR type +is omitted, then +.IR count +lines starting with the specified line shall be written. Otherwise, +.IR count +lines starting with the line specified by the +.IR type +argument shall be written. +.P +The +.IR type +argument shall change the lines to be written. The possible values of +.IR type +are as follows: +.IP "\fR\(mi\fP" 6 +The specified line shall be decremented by the following value: +.RS 6 +.sp +.RS 4 +.nf +\fB +(((number of ``\(mi'' characters) x \fIcount\fR) \(mi1) +.fi \fR +.P +.RE +.P +If the calculation would result in a number less than 1, it shall be an +error. Write lines from the edit buffer, starting at the new value of +line, until +.IR count +lines or the last line in the edit buffer has been written. +.RE +.IP "\fR+\fP" 6 +The specified line shall be incremented by the following value: +.RS 6 +.sp +.RS 4 +.nf +\fB +(((number of ``+'' characters) \(mi1) x \fIcount\fR) +1 +.fi \fR +.P +.RE +.P +If the calculation would result in a number greater than the last line +in the edit buffer, it shall be an error. Write lines from the edit +buffer, starting at the new value of line, until +.IR count +lines or the last line in the edit buffer has been written. +.RE +.IP "\fR=\fR,\fR.\fR" 6 +If more than a single +.BR '.' +or +.BR '=' +is specified, it shall be an error. The following steps shall be +taken: +.RS 6 +.IP " 1." 4 +If +.IR count +is zero, nothing shall be written. +.IP " 2." 4 +Write as many of the +.IR N +lines before the current line in the edit buffer as exist. If +.IR count +or +.BR '!' +was specified, +.IR N +shall be: +.RS 4 +.sp +.RS 4 +.nf +\fB +(\fIcount\fR \(mi1) /2 +.fi \fR +.P +.RE +.P +Otherwise, +.IR N +shall be: +.sp +.RS 4 +.nf +\fB +(\fIcount\fP \(mi3) /2 +.fi \fR +.P +.RE +.P +If +.IR N +is a number less than 3, no lines shall be written. +.RE +.IP " 3." 4 +If +.BR '=' +was specified as the type character, write a line consisting of the +smaller of the number of columns in the display divided by two, or 40 +.BR '\(mi' +characters. +.IP " 4." 4 +Write the current line. +.IP " 5." 4 +Repeat step 3. +.IP " 6." 4 +Write as many of the +.IR N +lines after the current line in the edit buffer as exist. +.IR N +shall be defined as in step 2. If +.IR N +is a number less than 3, no lines shall be written. If +.IR count +is less than 3, no lines shall be written. +.RE +.IP "\fR^\fP" 6 +The specified line shall be decremented by the following value: +.RS 6 +.sp +.RS 4 +.nf +\fB +(((number of ``^'' characters) +1) x \fIcount\fR) \(mi1 +.fi \fR +.P +.RE +.P +If the calculation would result in a number less than 1, it shall be an +error. Write lines from the edit buffer, starting at the new value of +line, until +.IR count +lines or the last line in the edit buffer has been written. +.RE +.P +.IR "Current line" : +Set to the last line written, unless the type is +.BR = , +in which case, set to the specified line. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Escape" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +! \fIcommand +\fB[\fIaddr\fB]\fR! \fIcommand\fR +.fi \fR +.P +.RE +.RE +.P +The contents of the line after the +.BR '!' +shall have +.BR '%' , +.BR '#' , +and +.BR '!' +characters expanded as described in +.IR "Command Line Parsing in ex". +If the expansion causes the text of the line to change, it shall be +redisplayed, preceded by a single +.BR '!' +character. +.P +The +.IR ex +utility shall execute the program named by the +.BR shell +edit option. It shall pass two arguments to the program; the first +shall be +.BR \(mic , +and the second shall be the expanded arguments to the +.BR ! +command as a single argument. +.P +If no lines are specified, the standard input, standard output, and +standard error of the program shall be set to the standard input, +standard output, and standard error of the +.IR ex +program when it was invoked. In addition, a warning message shall be +written if the edit buffer has been modified since the last complete +write, and the +.BR warn +edit option is set. +.P +If lines are specified, they shall be passed to the program as standard +input, and the standard output and standard error of the program shall +replace those lines in the edit buffer. Each line in the program output +(as delimited by + +characters or the end of the output if it is not immediately preceded by a +), +shall be a separate line in the edit buffer. Any occurrences of + +and + +pairs in the output shall be treated as single + +characters. The specified lines shall be copied into the unnamed buffer +before they are replaced, and the unnamed buffer shall become a line-mode +buffer. +.P +If in +.IR ex +mode, a single +.BR '!' +character shall be written when the program completes. +.P +This command shall be affected by the +.BR shell +and +.BR warn +edit options. If no lines are specified, this command shall be affected +by the +.BR autowrite +and +.BR writeany +edit options. If lines are specified, this command shall be affected by +the +.BR autoprint +edit option. +.br +.P +.IR "Current line" : +.IP " 1." 4 +If no lines are specified, unchanged. +.IP " 2." 4 +Otherwise, set to the last line read in, if any lines are read in. +.IP " 3." 4 +Otherwise, set to the line before the first line of the lines +specified, if that line exists. +.IP " 4." 4 +Otherwise, set to the first line of the edit buffer if the edit buffer +is not empty. +.IP " 5." 4 +Otherwise, set to zero. +.P +.IR "Current column" : +If no lines are specified, unchanged. Otherwise, set to non-\c +. +.SS "Shift Left" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB]\fR <\fB[\fR< ...\fB][\fIcount\fB][\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Shift the specified lines to the start of the line; the number of +column positions to be shifted shall be the number of command +characters times the value of the +.BR shiftwidth +edit option. Only leading + +characters shall be deleted or changed into other + +characters in shifting; other characters shall not be affected. +.P +Lines to be shifted shall be copied into the unnamed buffer, which +shall become a line-mode buffer. +.P +This command shall be affected by the +.BR autoprint +edit option. +.P +.IR "Current line" : +Set to the last line in the lines specified. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Shift Right" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB]\fR >\fB[\fR> ...\fB][\fIcount\fB][\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Shift the specified lines away from the start of the line; the number +of column positions to be shifted shall be the number of command +characters times the value of the +.BR shiftwidth +edit option. The shift shall be accomplished by adding + +characters as a prefix to the line or changing leading + +characters into other + +characters. Empty lines shall not be changed. +.P +Lines to be shifted shall be copied into the unnamed buffer, which +shall become a line-mode buffer. +.P +This command shall be affected by the +.BR autoprint +edit option. +.P +.IR "Current line" : +Set to the last line in the lines specified. +.P +.IR "Current column" : +Set to non-\c +. +.SS "\(hyD" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +-D +.fi \fR +.P +.RE +.RE +.P +Write the next +.IR n +lines, where +.IR n +is the minimum of the values of the +.BR scroll +edit option and the number of lines after the current line in the edit +buffer. If the current line is the last line of the edit buffer it +shall be an error. +.P +.IR "Current line" : +Set to the last line written. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Write Line Number" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI1addr\fB] \fR= \fB[\fIflags\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If +.IR line +is not specified, it shall default to the last line in the edit buffer. +Write the line number of the specified line. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Execute" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fI2addr\fB]\fR @ \fIbuffer\fR +\fB[\fI2addr\fB]\fR * \fIbuffer\fR +.fi \fR +.P +.RE +.RE +.P +If no buffer is specified or is specified as +.BR '@' +or +.BR '*' , +the last buffer executed shall be used. If no previous buffer has been +executed, it shall be an error. +.P +For each line specified by the addresses, set the current line (\c +.BR '.' ) +to the specified line, and execute the contents of the named +.IR buffer +(as they were at the time the +.BR @ +command was executed) as +.IR ex +commands. For each line of a line-mode buffer, and all but the last +line of a character-mode buffer, the +.IR ex +command parser shall behave as if the line was terminated by a +. +.P +If an error occurs during this process, or a line specified by the +addresses does not exist when the current line would be set to it, or +more than a single line was specified by the addresses, and the +contents of the edit buffer are replaced (for example, by the +.IR ex +.BR :edit +command) an error message shall be written, and no more commands +resulting from the execution of this command shall be processed. +.P +.IR "Current line" : +As specified for the individual +.IR ex +commands. +.P +.IR "Current column" : +As specified for the individual +.IR ex +commands. +.SS "Regular Expressions in ex" +.P +The +.IR ex +utility shall support regular expressions that are a superset of the +basic regular expressions described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.3" ", " "Basic Regular Expressions". +A null regular expression (\c +.BR \(dq//\(dq ) +shall be equivalent to the last regular expression encountered. +.P +Regular expressions can be used in addresses to specify lines and, in +some commands (for example, the +.BR substitute +command), to specify portions of a line to be substituted. +.P +The following constructs can be used to enhance the basic regular +expressions: +.IP "\fR\e<\fR" 6 +Match the beginning of a +.IR word . +(See the definition of +.IR word +at the beginning of +.IR "Command Descriptions in ex".) +.IP "\fR\e>\fR" 6 +Match the end of a +.IR word . +.IP "\fR~\fR" 6 +Match the replacement part of the last +.BR substitute +command. The + +(\c +.BR '~' ) +character can be escaped in a regular expression to become a normal +character with no special meaning. The + +shall be discarded. +.P +When the editor option +.BR magic +is not set, the only characters with special meanings shall be +.BR '^' +at the beginning of a pattern, +.BR '$' +at the end of a pattern, and +. +The characters +.BR '.' , +.BR '*' , +.BR '[' , +and +.BR '~' +shall be treated as ordinary characters unless preceded by a +; +when preceded by a + +they shall regain their special meaning, or in the case of +, +be handled as a single +. + +characters used to escape other characters shall be discarded. +.SS "Replacement Strings in ex" +.P +The character +.BR '&' +(\c +.BR '\e&' +if the editor option +.BR magic +is not set) in the replacement string shall stand for the text matched +by the pattern to be replaced. The character +.BR '~' +(\c +.BR '\e~' +if +.BR magic +is not set) shall be replaced by the replacement part of the previous +.BR substitute +command. The sequence +.BR '\en' , +where +.IR n +is an integer, shall be replaced by the text matched by the +corresponding back-reference expression. If the corresponding +back-reference expression does not match, then the characters +.BR '\en' +shall be replaced by the empty string. +.P +The strings +.BR '\el' , +.BR '\eu' , +.BR '\eL' , +and +.BR '\eU' +can be used to modify the case of elements in the replacement string +(using the +.BR '\e&' +or +.BR \(dq\e\(dq digit) +notation. The string +.BR '\el' +(\c +.BR '\eu' ) +shall cause the character that follows to be converted to lowercase +(uppercase). The string +.BR '\eL' +(\c +.BR '\eU' ) +shall cause all characters subsequent to it to be converted to +lowercase (uppercase) as they are inserted by the substitution until +the string +.BR '\ee' +or +.BR '\eE' , +or the end of the replacement string, is encountered. +.P +Otherwise, any character following a + +shall be treated as that literal character, and the escaping + +shall be discarded. +.P +An example of case conversion with the +.BR s +command is as follows: +.sp +.RS 4 +.nf +\fB +\fB:\fRp +\fBThe cat sat on the mat. +\fB:\fRs/\e<.at\e>/\eu&/gp +\fBThe Cat Sat on the Mat. +\fB:\fRs/S\e(.*\e)M/S\eU\e1\eeM/p +\fBThe Cat SAT ON THE Mat.\fR +.fi \fR +.P +.RE +.SS "Edit Options in ex" +.P +The +.IR ex +utility has a number of options that modify its behavior. These options +have default settings, which can be changed using the +.BR set +command. +.P +Options are Boolean unless otherwise specified. +.SS "autoindent, ai" +.P +[Default \fIunset\fR] +.P +If +.BR autoindent +is set, each line in input mode shall be indented (using first as many + +characters as possible, as determined by the editor option +.BR tabstop , +and then using + +characters) to align with another line, as follows: +.IP " 1." 4 +If in open or visual mode and the text input is part of a line-oriented +command (see the EXTENDED DESCRIPTION in +.IR "\fIvi\fR\^"), +align to the first column. +.IP " 2." 4 +Otherwise, if in open or visual mode, indentation for each line shall +be set as follows: +.RS 4 +.IP " a." 4 +If a line was previously inserted as part of this command, it shall be +set to the indentation of the last inserted line by default, or as +otherwise specified for the +\(hyD +character in +.IR "Input Mode Commands in vi". +.IP " b." 4 +Otherwise, it shall be set to the indentation of the previous current +line, if any; otherwise, to the first column. +.RE +.IP " 3." 4 +For the +.IR ex +.BR a , +.BR i , +and +.BR c +commands, indentation for each line shall be set as follows: +.RS 4 +.IP " a." 4 +If a line was previously inserted as part of this command, it shall be +set to the indentation of the last inserted line by default, or as +otherwise specified for the +.IR eof +character in +.IR "Scroll". +.IP " b." 4 +Otherwise, if the command is the +.IR ex +.BR a +command, it shall be set to the line appended after, if any; otherwise +to the first column. +.IP " c." 4 +Otherwise, if the command is the +.IR ex +.BR i +command, it shall be set to the line inserted before, if any; otherwise +to the first column. +.IP " d." 4 +Otherwise, if the command is the +.IR ex +.BR c +command, it shall be set to the indentation of the line replaced. +.RE +.SS "autoprint, ap" +.P +[Default \fIset\fR] +.P +If +.BR autoprint +is set, the current line shall be written after each +.IR ex +command that modifies the contents of the current edit buffer, and +after each +.BR tag +command for which the tag search pattern was found or tag line number +was valid, unless: +.IP " 1." 4 +The command was executed while in open or visual mode. +.IP " 2." 4 +The command was executed as part of a +.BR global +or +.BR v +command or +.BR @ +buffer execution. +.IP " 3." 4 +The command was the form of the +.BR read +command that reads a file into the edit buffer. +.IP " 4." 4 +The command was the +.BR append , +.BR change , +or +.BR insert +command. +.IP " 5." 4 +The command was not terminated by a +. +.IP " 6." 4 +The current line shall be written by a flag specified to the command; +for example, +.BR "delete #" +shall write the current line as specified for the flag modifier to the +.BR delete +command, and not as specified by the +.BR autoprint +edit option. +.SS "autowrite, aw" +.P +[Default \fIunset\fR] +.P +If +.BR autowrite +is set, and the edit buffer has been modified since it was last +completely written to any file, the contents of the edit buffer shall +be written as if the +.IR ex +.BR write +command had been specified without arguments, before each command +affected by the +.BR autowrite +edit option is executed. Appending the character +.BR '!' +to the command name of any of the +.IR ex +commands except +.BR '!' +shall prevent the write. If the write fails, it shall be an error and +the command shall not be executed. +.SS "beautify, bf" +.P +[Default \fIunset\fR] +.P +If +.BR beautify +is set, all non-printable characters, other than +, +, +and + +characters, shall be discarded from text read in from files. +.SS "directory, dir" +.P +[Default \fIimplementation-defined\fR] +.P +The value of this option specifies the directory in which the editor +buffer is to be placed. If this directory is not writable by the user, +the editor shall quit. +.SS "edcompatible, ed" +.P +[Default \fIunset\fR] +.P +Causes the presence of +.BR g +and +.BR c +suffixes on substitute commands to be remembered, and toggled by +repeating the suffixes. +.SS "errorbells, eb" +.P +[Default \fIunset\fR] +.P +If the editor is in +.IR ex +mode, and the terminal does not support a standout mode (such as +inverse video), and +.BR errorbells +is set, error messages shall be preceded by alerting the terminal. +.SS "exrc" +.P +[Default \fIunset\fR] +.P +If +.BR exrc +is set, +.IR ex +shall access any +.BR .exrc +file in the current directory, as described in +.IR "Initialization in ex and vi". +If +.BR exrc +is not set, +.IR ex +shall ignore any +.BR .exrc +file in the current directory during initialization, unless the current +directory is that named by the +.IR HOME +environment variable. +.SS "ignorecase, ic" +.P +[Default \fIunset\fR] +.P +If +.BR ignorecase +is set, characters that have uppercase and lowercase representations +shall have those representations considered as equivalent for purposes +of regular expression comparison. +.P +The +.BR ignorecase +edit option shall affect all remembered regular expressions; for +example, unsetting the +.BR ignorecase +edit option shall cause a subsequent +.IR vi +.BR n +command to search for the last basic regular expression in a +case-sensitive fashion. +.SS "list" +.P +[Default \fIunset\fR] +.P +If +.BR list +is set, edit buffer lines written while in +.IR ex +command mode shall be written as specified for the +.BR print +command with the +.BR l +flag specified. In open or visual mode, each edit buffer line shall be +displayed as specified for the +.IR ex +.BR print +command with the +.BR l +flag specified. In open or visual text input mode, when the cursor +does not rest on any character in the line, it shall rest on the +.BR '$' +marking the end of the line. +.SS "magic" +.P +[Default \fIset\fR] +.P +If +.BR magic +is set, modify the interpretation of characters in regular expressions +and substitution replacement strings (see +.IR "Regular Expressions in ex" +and +.IR "Replacement Strings in ex"). +.SS "mesg" +.P +[Default \fIset\fR] +.P +If +.BR mesg +is set, the permission for others to use the +.BR write +or +.BR talk +commands to write to the terminal shall be turned on while in open or +visual mode. The shell-level command +.IR mesg +.BR n +shall take precedence over any setting of the +.IR ex +.BR mesg +option; that is, if +.BR "mesg y" +was issued before the editor started (or in a shell escape), such as: +.sp +.RS 4 +.nf +\fB +:!mesg y +.fi \fR +.P +.RE +.P +the +.BR mesg +option in +.IR ex +shall suppress incoming messages, but the +.BR mesg +option shall not enable incoming messages if +.BR "mesg n" +was issued. +.SS "number, nu" +.P +[Default \fIunset\fR] +.P +If +.BR number +is set, edit buffer lines written while in +.IR ex +command mode shall be written with line numbers, in the format +specified by the +.BR print +command with the +.BR # +flag specified. In +.IR ex +text input mode, each line shall be preceded by the line number it will +have in the file. +.P +In open or visual mode, each edit buffer line shall be displayed with a +preceding line number, in the format specified by the +.IR ex +.BR print +command with the +.BR # +flag specified. This line number shall not be considered part of the +line for the purposes of evaluating the current column; that is, column +position 1 shall be the first column position after the format +specified by the +.BR print +command. +.SS "paragraphs, para" +.P +[Default in the POSIX locale \fRIPLPPPQPP LIpplpipbp\fR] +.P +The +.BR paragraphs +edit option shall define additional paragraph boundaries for the open +and visual mode commands. The +.BR paragraphs +edit option can be set to a character string consisting of zero or more +character pairs. It shall be an error to set it to an odd number of +characters. +.SS "prompt" +.P +[Default \fIset\fR] +.P +If +.BR prompt +is set, +.IR ex +command mode input shall be prompted for with a + +(\c +.BR ':' ); +when unset, no prompt shall be written. +.SS "readonly" +.P +[Default \fIsee text\fR] +.P +If the +.BR readonly +edit option is set, read-only mode shall be enabled (see +.IR "Write"). +The +.BR readonly +edit option shall be initialized to set if either of the following +conditions are true: +.IP " *" 4 +The command-line option +\(miR +was specified. +.IP " *" 4 +Performing actions equivalent to the +\fIaccess\fR() +function called with the following arguments indicates that the file +lacks write permission: +.RS 4 +.IP " 1." 4 +The current pathname is used as the +.IR path +argument. +.IP " 2." 4 +The constant +.BR W_OK +is used as the +.IR amode +argument. +.RE +.P +The +.BR readonly +edit option may be initialized to set for other, +implementation-defined reasons. The +.BR readonly +edit option shall not be initialized to unset based on any special +privileges of the user or process. The +.BR readonly +edit option shall be reinitialized each time that the contents of the +edit buffer are replaced (for example, by an +.BR edit +or +.BR next +command) unless the user has explicitly set it, in which case it shall +remain set until the user explicitly unsets it. Once unset, it shall +again be reinitialized each time that the contents of the edit buffer +are replaced. +.SS "redraw" +.P +[Default \fIunset\fR] +.P +The editor simulates an intelligent terminal on a dumb terminal. +(Since this is likely to require a large amount of output to the +terminal, it is useful only at high transmission speeds.) +.SS "remap" +.P +[Default \fIset\fR] +.P +If +.BR remap +is set, map translation shall allow for maps defined in terms of other +maps; translation shall continue until a final product is obtained. If +unset, only a one-step translation shall be done. +.SS "report" +.P +[Default 5] +.P +The value of this +.BR report +edit option specifies what number of lines being added, copied, +deleted, or modified in the edit buffer will cause an informational +message to be written to the user. The following conditions shall cause +an informational message. The message shall contain the number of lines +added, copied, deleted, or modified, but is otherwise unspecified. +.IP " *" 4 +An +.IR ex +or +.IR vi +editor command, other than +.BR open , +.BR undo , +or +.BR visual , +that modifies at least the value of the +.BR report +edit option number of lines, and which is not part of an +.IR ex +.BR global +or +.BR v +command, or +.IR ex +or +.IR vi +buffer execution, shall cause an informational message to be written. +.IP " *" 4 +An +.IR ex +.BR yank +or +.IR vi +.BR y +or +.BR Y +command, that copies at least the value of the +.BR report +edit option plus 1 number of lines, and which is not part of an +.IR ex +.BR global +or +.BR v +command, or +.IR ex +or +.IR vi +buffer execution, shall cause an informational message to be written. +.IP " *" 4 +An +.IR ex +.BR global , +.BR v , +.BR open , +.BR undo , +or +.BR visual +command or +.IR ex +or +.IR vi +buffer execution, that adds or deletes a total of at least the value of +the +.BR report +edit option number of lines, and which is not part of an +.IR ex +.BR global +or +.BR v +command, or +.IR ex +or +.IR vi +buffer execution, shall cause an informational message to be written. +(For example, if 3 lines were added and 8 lines deleted during an +.IR ex +.BR visual +command, 5 would be the number compared against the +.BR report +edit option after the command completed.) +.SS "scroll, scr" +.P +[Default (number of lines in the display \(mi1)/2] +.P +The value of the +.BR scroll +edit option shall determine the number of lines scrolled by the +.IR ex +\(hyD +and +.BR z +commands. For the +.IR vi +\(hyD +and +\(hyU +commands, it shall be the initial number of lines to scroll when no +previous +\(hyD +or +\(hyU +command has been executed. +.SS "sections" +.P +[Default in the POSIX locale \fRNHSHH HUnhsh\fR] +.P +The +.BR sections +edit option shall define additional section boundaries for the open and +visual mode commands. The +.BR sections +edit option can be set to a character string consisting of zero or more +character pairs; it shall be an error to set it to an odd number of +characters. +.SS "shell, sh" +.P +[Default from the environment variable +.IR SHELL ] +.P +The value of this option shall be a string. The default shall be taken +from the +.IR SHELL +environment variable. If the +.IR SHELL +environment variable is null or empty, the +.IR sh +(see +.IR "\fIsh\fR\^") +utility shall be the default. +.SS "shiftwidth, sw" +.P +[Default 8] +.P +The value of this option shall give the width in columns of an +indentation level used during autoindentation and by the shift commands +(\c +.BR < +and +.BR > ). +.SS "showmatch, sm" +.P +[Default \fIunset\fR] +.P +The functionality described for the +.BR showmatch +edit option need not be supported on block-mode terminals or terminals +with insufficient capabilities. +.P +If +.BR showmatch +is set, in open or visual mode, when a +.BR ')' +or +.BR '}' +is typed, if the matching +.BR '(' +or +.BR '{' +is currently visible on the display, the matching +.BR '(' +or +.BR '{' +shall be flagged moving the cursor to its location for an unspecified +amount of time. +.SS "showmode" +.P +[Default \fIunset\fP] +.P +If +.BR showmode +is set, in open or visual mode, the current mode that the editor is in +shall be displayed on the last line of the display. Command mode and +text input mode shall be differentiated; other unspecified modes and +implementation-defined information may be displayed. +.SS "slowopen" +.P +[Default \fIunset\fR] +.P +If +.BR slowopen +is set during open and visual text input modes, the editor shall not +update portions of the display other than those display line columns +that display the characters entered by the user (see +.IR "Input Mode Commands in vi"). +.SS "tabstop, ts" +.P +[Default 8] +.P +The value of this edit option shall specify the column boundary used by +a + +in the display (see +.IR "autoprint" ", " "ap" +and +.IR "Input Mode Commands in vi"). +.SS "taglength, tl" +.P +[Default zero] +.P +The value of this edit option shall specify the maximum number of +characters that are considered significant in the user-specified tag +name and in the tag name from the tags file. If the value is zero, all +characters in both tag names shall be significant. +.SS "tags" +.P +[Default \fIsee text\fP] +.P +The value of this edit option shall be a string of +-delimited +pathnames of files used by the +.BR tag +command. The default value is unspecified. +.SS "term" +.P +[Default from the environment variable +.IR TERM ] +.P +The value of this edit option shall be a string. The default shall be +taken from the +.IR TERM +variable in the environment. If the +.IR TERM +environment variable is empty or null, the default is unspecified. The +editor shall use the value of this edit option to determine the type of +the display device. +.P +The results are unspecified if the user changes the value of the term +edit option after editor initialization. +.SS "terse" +.P +[Default \fIunset\fR] +.P +If +.BR terse +is set, error messages may be less verbose. However, except for this +caveat, error messages are unspecified. Furthermore, not all error +messages need change for different settings of this option. +.SS "warn" +.P +[Default \fIset\fR] +.P +If +.BR warn +is set, and the contents of the edit buffer have been modified since +they were last completely written, the editor shall write a warning +message before certain +.BR ! +commands (see +.IR "Escape"). +.SS "window" +.P +[Default \fIsee text\fR] +.P +A value used in open and visual mode, by the +\(hyB +and +\(hyF +commands, and, in visual mode, to specify the number of lines displayed +when the screen is repainted. +.P +If the +.BR \(miw +command-line option is not specified, the default value shall be set to +the value of the +.IR LINES +environment variable. If the +.IR LINES +environment variable is empty or null, the default shall be the number +of lines in the display minus 1. +.P +Setting the +.BR window +edit option to zero or to a value greater than the number of lines in +the display minus 1 (either explicitly or based on the +.BR \(miw +option or the +.IR LINES +environment variable) shall cause the +.BR window +edit option to be set to the number of lines in the display minus 1. +.P +The baud rate of the terminal line may change the default in an +implementation-defined manner. +.SS "wrapmargin, wm" +.P +[Default 0] +.P +If the value of this edit option is zero, it shall have no effect. +.P +If not in the POSIX locale, the effect of this edit option is +implementation-defined. +.P +Otherwise, it shall specify a number of columns from the ending margin +of the terminal. +.P +During open and visual text input modes, for each character for which +any part of the character is displayed in a column that is less than +.BR wrapmargin +columns from the ending margin of the display line, the editor shall +behave as follows: +.IP " 1." 4 +If the character triggering this event is a +, +it, and all immediately preceding + +characters on the current line entered during the execution of the +current text input command, shall be discarded, and the editor shall +behave as if the user had entered a single + +instead. In addition, if the next user-entered character is a +, +it shall be discarded as well. +.IP " 2." 4 +Otherwise, if there are one or more + +characters on the current line immediately preceding the last group of +inserted non-\c + +characters which was entered during the execution of the current text +input command, the + +characters shall be replaced as if the user had entered a single + +instead. +.P +If the +.BR autoindent +edit option is set, and the events described in 1. or 2. are performed, +any + +characters at or after the cursor in the current line shall be discarded. +.P +The ending margin shall be determined by the system or overridden by +the user, as described for +.IR COLUMNS +in the ENVIRONMENT VARIABLES section and the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +.SS "wrapscan, ws" +.P +[Default \fIset\fR] +.P +If +.BR wrapscan +is set, searches (the +.IR ex +.BR / +or +.BR ? +addresses, or open and visual mode +.BR / , +.BR ? , +.BR N , +and +.BR n +commands) shall wrap around the beginning or end of the edit buffer; +when unset, searches shall stop at the beginning or end of the edit +buffer. +.SS "writeany, wa" +.P +[Default \fIunset\fR] +.P +If +.BR writeany +is set, some of the checks performed when executing the +.IR ex +.BR write +commands shall be inhibited, as described in editor option +.BR autowrite . +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +When any error is encountered and the standard input is not a terminal +device file, +.IR ex +shall not write the file or return to command or text input mode, and +shall terminate with a non-zero exit status. +.P +Otherwise, when an unrecoverable error is encountered, it shall be +equivalent to a SIGHUP asynchronous event. +.P +Otherwise, when an error is encountered, the editor shall behave as +specified in +.IR "Command Line Parsing in ex". +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +If a SIGSEGV signal is received while +.IR ex +is saving a file, the file might not be successfully saved. +.P +The +.BR next +command can accept more than one file, so usage such as: +.sp +.RS 4 +.nf +\fB +next `ls [abc]*` +.fi \fR +.P +.RE +.P +is valid; it would not be valid for the +.BR edit +or +.BR read +commands, for example, because they expect only one file and +unspecified results occur. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR ex /\c +.IR vi +specification is based on the historical practice found in the 4 BSD and +System V implementations of +.IR ex +and +.IR vi . +.P +A +.IR "restricted editor" +(both the historical +.IR red +utility and modifications to +.IR ex ) +were considered and rejected for inclusion. Neither option provided the +level of security that users might expect. +.P +It is recognized that +.IR ex +visual mode and related features would be difficult, if not impossible, +to implement satisfactorily on a block-mode terminal, or a terminal +without any form of cursor addressing; thus, it is not a mandatory +requirement that such features should work on all terminals. It is the +intention, however, that an +.IR ex +implementation should provide the full set of capabilities on all +terminals capable of supporting them. +.SS "Options" +.P +The +.BR \(mic +replacement for +.BR + \c +.IR command +was inspired by the +.BR \(mie +option of +.IR sed . +Historically, all such commands (see +.BR edit +and +.BR next +as well) were executed from the last line of the edit buffer. This +meant, for example, that +.BR \(dq+/pattern\(dq +would fail unless the +.BR wrapscan +option was set. POSIX.1\(hy2008 requires conformance to historical practice. The +.BR \(pl \c +.IR command +option is no longer specified by POSIX.1\(hy2008 but may be present in +some implementations. Historically, some implementations restricted the +.IR ex +commands that could be listed as part of the command line arguments. +For consistency, POSIX.1\(hy2008 does not permit these restrictions. +.P +In historical implementations of the editor, the +.BR \(miR +option (and the +.BR readonly +edit option) only prevented overwriting of files; appending to files +was still permitted, mapping loosely into the +.IR csh +.BR noclobber +variable. Some implementations, however, have not followed this +semantic, and +.BR readonly +does not permit appending either. POSIX.1\(hy2008 follows the latter practice, +believing that it is a more obvious and intuitive meaning of +.BR readonly . +.P +The +.BR \(mis +option suppresses all interactive user feedback and is useful for +editing scripts in batch jobs. The list of specific effects is +historical practice. The terminal type ``incapable of supporting open +and visual modes'' has historically been named ``dumb''. +.P +The +.BR \(mit +option was required because the +.IR ctags +utility appears in POSIX.1\(hy2008 and the option is available in all historical +implementations of +.IR ex . +.P +Historically, the +.IR ex +and +.IR vi +utilities accepted a +.BR \(mix +option, which did encryption based on the algorithm found in the +historical +.IR crypt +utility. The +.BR \(mix +option for encryption, and the associated +.IR crypt +utility, were omitted because the algorithm used was not specifiable +and the export control laws of some nations make it difficult to export +cryptographic technology. In addition, it did not historically provide +the level of security that users might expect. +.SS "Standard Input" +.P +An end-of-file condition is not equivalent to an end-of-file character. +A common end-of-file character, +\(hyD, +is historically an +.IR ex +command. +.P +There was no maximum line length in historical implementations of +.IR ex . +Specifically, as it was parsed in chunks, the addresses had a different +maximum length than the filenames. Further, the maximum line buffer +size was declared as BUFSIZ, which was different lengths on different +systems. This version selected the value of +{LINE_MAX} +to impose a reasonable restriction on portable usage of +.IR ex +and to aid test suite writers in their development of realistic tests +that exercise this limit. +.SS "Input Files" +.P +It was an explicit decision by the standard developers that a + +be added to any file lacking one. It was believed that this feature of +.IR ex +and +.IR vi +was relied on by users in order to make text files lacking a trailing + +more portable. It is recognized that this will require a user-specified +option or extension for implementations that permit +.IR ex +and +.IR vi +to edit files of type other than text if such files are not otherwise +identified by the system. It was agreed that the ability to edit files +of arbitrary type can be useful, but it was not considered necessary to +mandate that an +.IR ex +or +.IR vi +implementation be required to handle files other than text files. +.P +The paragraph in the INPUT FILES section, ``By default, .\|.\|.'', is +intended to close a long-standing security problem in +.IR ex +and +.IR vi ; +that of the ``modeline'' or ``modelines'' edit option. This feature +allows any line in the first or last five lines of the file containing +the strings +.BR \(dqex:\(dq +or +.BR \(dqvi:\(dq +(and, apparently, +.BR \(dqei:\(dq +or +.BR \(dqvx:\(dq ) +to be a line containing editor commands, and +.IR ex +interprets all the text up to the next +.BR ':' +or + +as a command. Consider the consequences, for example, of an +unsuspecting user using +.IR ex +or +.IR vi +as the editor when replying to a mail message in which a line such as: +.sp +.RS 4 +.nf +\fB +ex:! rm \(mirf : +.fi \fR +.P +.RE +.P +appeared in the signature lines. The standard developers believed +strongly that an editor should not by default interpret any lines of a +file. Vendors are strongly urged to delete this feature from their +implementations of +.IR ex +and +.IR vi . +.SS "Asynchronous Events" +.P +The intention of the phrase ``complete write'' is that the entire edit +buffer be written to stable storage. The note regarding temporary files +is intended for implementations that use temporary files to back edit +buffers unnamed by the user. +.P +Historically, SIGQUIT was ignored by +.IR ex , +but was the equivalent of the +.BR Q +command in visual mode; that is, it exited visual mode and entered +.IR ex +mode. POSIX.1\(hy2008 permits, but does not require, this behavior. Historically, +SIGINT was often used by +.IR vi +users to terminate text input mode (\c +\(hyC +is often easier to enter than +). +Some implementations of +.IR vi +alerted the terminal on this event, and some did not. POSIX.1\(hy2008 requires +that SIGINT behave identically to +, +and that the terminal not be alerted. +.P +Historically, suspending the +.IR ex +editor during text input mode was similar to SIGINT, as completed lines +were retained, but any partial line discarded, and the editor returned +to command mode. POSIX.1\(hy2008 is silent on this issue; implementations are +encouraged to follow historical practice, where possible. +.P +Historically, the +.IR vi +editor did not treat SIGTSTP as an asynchronous event, and it was +therefore impossible to suspend the editor in visual text input mode. +There are two major reasons for this. The first is that SIGTSTP is a +broadcast signal on UNIX systems, and the chain of events where the +shell +.IR exec s +an application that then +.IR exec s +.IR vi +usually caused confusion for the terminal state if SIGTSTP was delivered +to the process group in the default manner. The second was that most +implementations of the UNIX +.IR curses +package did not handle SIGTSTP safely, and the receipt of SIGTSTP at +the wrong time would cause them to crash. POSIX.1\(hy2008 is silent on this issue; +implementations are encouraged to treat suspension as an asynchronous +event if possible. +.P +Historically, modifications to the edit buffer made before SIGINT +interrupted an operation were retained; that is, anywhere from zero to +all of the lines to be modified might have been modified by the time +the SIGINT arrived. These changes were not discarded by the arrival of +SIGINT. POSIX.1\(hy2008 permits this behavior, noting that the +.BR undo +command is required to be able to undo these partially completed +commands. +.P +The action taken for signals other than SIGINT, SIGCONT, SIGHUP, and +SIGTERM is unspecified because some implementations attempt to save the +edit buffer in a useful state when other signals are received. +.SS "Standard Error" +.P +For +.IR ex /\c +.IR vi , +diagnostic messages are those messages reported as a result of a failed +attempt to invoke +.IR ex +or +.IR vi , +such as invalid options or insufficient resources, or an abnormal +termination condition. Diagnostic messages should not be confused with +the error messages generated by inappropriate or illegal user +commands. +.SS "Initialization in ex and vi" +.P +If an +.IR ex +command (other than +.BR cd , +.BR chdir , +or +.BR source ) +has a filename argument, one or both of the alternate and current +pathnames will be set. Informally, they are set as follows: +.IP " 1." 4 +If the +.IR ex +command is one that replaces the contents of the edit buffer, and it +succeeds, the current pathname will be set to the filename argument +(the first filename argument in the case of the +.BR next +command) and the alternate pathname will be set to the previous +current pathname, if there was one. +.IP " 2." 4 +In the case of the file read/write forms of the +.BR read +and +.BR write +commands, if there is no current pathname, the current pathname will +be set to the filename argument. +.IP " 3." 4 +Otherwise, the alternate pathname will be set to the filename +argument. +.P +For example, +.BR ":edit foo" +and +.BR ":recover foo" , +when successful, set the current pathname, and, if there was a +previous current pathname, the alternate pathname. The commands +.BR :write , +.BR !command , +and +.BR :edit +set neither the current or alternate pathnames. If the +.BR ":edit foo" +command were to fail for some reason, the alternate pathname would be +set. The +.BR read +and +.BR write +commands set the alternate pathname to their +.IR file +argument, unless the current pathname is not set, in which case they +set the current pathname to their +.IR file +arguments. The alternate pathname was not historically set by the +.BR :source +command. POSIX.1\(hy2008 requires conformance to historical practice. +Implementations adding commands that take filenames as arguments are +encouraged to set the alternate pathname as described here. +.P +Historically, +.IR ex +and +.IR vi +read the +.BR .exrc +file in the +.IR $HOME +directory twice, if the editor was executed in the +.IR $HOME +directory. POSIX.1\(hy2008 prohibits this behavior. +.P +Historically, the 4 BSD +.IR ex +and +.IR vi +read the +.IR $HOME +and local +.BR .exrc +files if they were owned by the real ID of the user, or the +.BR sourceany +option was set, regardless of other considerations. This was a security +problem because it is possible to put normal UNIX system commands +inside a +.BR .exrc +file. POSIX.1\(hy2008 does not specify the +.BR sourceany +option, and historical implementations are encouraged to delete it. +.P +The +.BR .exrc +files must be owned by the real ID of the user, and not writable by +anyone other than the owner. The appropriate privileges exception is +intended to permit users to acquire special privileges, but continue to +use the +.BR .exrc +files in their home directories. +.P +System V Release 3.2 and later +.IR vi +implementations added the option +.BR [no]exrc . +The behavior is that local +.BR .exrc +files are read-only if the +.BR exrc +option is set. The default for the +.BR exrc +option was off, so by default, local +.BR .exrc +files were not read. The problem this was intended to solve was that +System V permitted users to give away files, so there is no possible +ownership or writeability test to ensure that the file is safe. This is +still a security problem on systems where users can give away files, +but there is nothing additional that POSIX.1\(hy2008 can do. The +implementation-defined exception is intended to permit groups to have +local +.BR .exrc +files that are shared by users, by creating pseudo-users to own the +shared files. +.P +POSIX.1\(hy2008 does not mention system-wide +.IR ex +and +.IR vi +start-up files. While they exist in several implementations of +.IR ex +and +.IR vi , +they are not present in any implementations considered historical +practice by POSIX.1\(hy2008. Implementations that have such files should use them +only if they are owned by the real user ID or an appropriate user (for +example, root on UNIX systems) and if they are not writable by any +user other than their owner. System-wide start-up files should be read +before the +.IR EXINIT +variable, +.BR $HOME/.exrc , +or local +.BR .exrc +files are evaluated. +.P +Historically, any +.IR ex +command could be entered in the +.IR EXINIT +variable or the +.BR .exrc +file, although ones requiring that the edit buffer already contain +lines of text generally caused historical implementations of the editor +to drop +.BR core . +POSIX.1\(hy2008 requires that any +.IR ex +command be permitted in the +.IR EXINIT +variable and +.BR .exrc +files, for simplicity of specification and consistency, although many +of them will obviously fail under many circumstances. +.P +The initialization of the contents of the edit buffer uses the phrase +``the effect shall be'' with regard to various +.IR ex +commands. The intent of this phrase is that edit buffer contents loaded +during the initialization phase not be lost; that is, loading the edit +buffer should fail if the +.BR .exrc +file read in the contents of a file and did not subsequently write the +edit buffer. An additional intent of this phrase is to specify that the +initial current line and column is set as specified for the individual +.IR ex +commands. +.P +Historically, the +.BR \(mit +option behaved as if the tag search were a +.BR + \c +.IR command ; +that is, it was executed from the last line of the file specified by +the tag. This resulted in the search failing if the pattern was a +forward search pattern and the +.BR wrapscan +edit option was not set. POSIX.1\(hy2008 does not permit this behavior, requiring +that the search for the tag pattern be performed on the entire file, +and, if not found, that the current line be set to a more reasonable +location in the file. +.P +Historically, the empty edit buffer presented for editing when a file +was not specified by the user was unnamed. This is permitted by POSIX.1\(hy2008; +however, implementations are encouraged to provide users a temporary +filename for this buffer because it permits them the use of +.IR ex +commands that use the current pathname during temporary edit +sessions. +.P +Historically, the file specified using the +.BR \(mit +option was not part of the current argument list. This practice is +permitted by POSIX.1\(hy2008; however, implementations are encouraged to include +its name in the current argument list for consistency. +.P +Historically, the +.BR \(mic +command was generally not executed until a file that already exists was +edited. POSIX.1\(hy2008 requires conformance to this historical practice. +Commands that could cause the +.BR \(mic +command to be executed include the +.IR ex +commands +.BR edit , +.BR next , +.BR recover , +.BR rewind , +and +.BR tag , +and the +.IR vi +commands +\(hy^ +and +\(hy]. +Historically, reading a file into an edit buffer did not cause the +.BR \(mic +command to be executed (even though it might set the current pathname) +with the exception that it did cause the +.BR \(mic +command to be executed if: the editor was in +.IR ex +mode, the edit buffer had no current pathname, the edit buffer was +empty, and no read commands had yet been attempted. For consistency and +simplicity of specification, POSIX.1\(hy2008 does not permit this behavior. +.P +Historically, the +.BR \(mir +option was the same as a normal edit session if there was no recovery +information available for the file. This allowed users to enter: +.sp +.RS 4 +.nf +\fB +vi \(mir *.c +.fi \fR +.P +.RE +.P +and recover whatever files were recoverable. In some implementations, +recovery was attempted only on the first file named, and the file was +not entered into the argument list; in others, recovery was attempted +for each file named. In addition, some historical implementations +ignored +.BR \(mir +if +.BR \(mit +was specified or did not support command line +.IR file +arguments with the +.BR \(mit +option. For consistency and simplicity of specification, POSIX.1\(hy2008 +disallows these special cases, and requires that recovery be attempted +the first time each file is edited. +.P +Historically, +.IR vi +initialized the +.BR ` +and +.BR ' +marks, but +.IR ex +did not. This meant that if the first command in +.IR ex +mode was +.BR visual +or if an +.IR ex +command was executed first (for example, +.IR vi ++10 +.IR file ), +.IR vi +was entered without the marks being initialized. Because the standard +developers believed the marks to be generally useful, and for +consistency and simplicity of specification, POSIX.1\(hy2008 requires that they +always be initialized if in open or visual mode, or if in +.IR ex +mode and the edit buffer is not empty. Not initializing it in +.IR ex +mode if the edit buffer is empty is historical practice; however, it +has always been possible to set (and use) marks in empty edit buffers +in open and visual mode edit sessions. +.SS "Addressing" +.P +Historically, +.IR ex +and +.IR vi +accepted the additional addressing forms +.BR '\e/' +and +.BR '\e?' . +They were equivalent to +.BR \(dq//\(dq +and +.BR \(dq??\(dq , +respectively. They are not required by POSIX.1\(hy2008, mostly because nobody can +remember whether they ever did anything different historically. +.P +Historically, +.IR ex +and +.IR vi +permitted an address of zero for several commands, and permitted the +.BR % +address in empty files for others. For consistency, POSIX.1\(hy2008 requires +support for the former in the few commands where it makes sense, and +disallows it otherwise. In addition, because POSIX.1\(hy2008 requires that +.BR % +be logically equivalent to +.BR \(dq1,$\(dq , +it is also supported where it makes sense and disallowed otherwise. +.P +Historically, the +.BR % +address could not be followed by further addresses. For consistency and +simplicity of specification, POSIX.1\(hy2008 requires that additional addresses +be supported. +.P +All of the following are valid +.IR addresses : +.IP "\fR+++\fP" 10 +Three lines after the current line. +.IP "\fR/\fIre\fR/\(mi\fR" 10 +One line before the next occurrence of +.IR re . +.IP "\fR\(mi2\fR" 10 +Two lines before the current line. +.IP "\fR3\0\(mi\|\(mi\|\(mi\|\(mi\02\fR" 10 +Line one (note intermediate negative address). +.IP "\fR1\02\03\fR" 10 +Line six. +.P +Any number of addresses can be provided to commands taking addresses; +for example, +.BR \(dq1,2,3,4,5p\(dq +prints lines 4 and 5, because two is the greatest valid number of +addresses accepted by the +.BR print +command. This, in combination with the + +delimiter, permits users to create commands based on ordered patterns +in the file. For example, the command +.BR "3;/foo/;+2print" +will display the first line after line 3 that contains the pattern +.IR foo , +plus the next two lines. Note that the address +.BR "3;" +must be evaluated before being discarded because the search origin for +the +.BR /foo/ +command depends on this. +.P +Historically, values could be added to addresses by including them +after one or more + +characters; for example, +.BR "3\0\(mi\05p" +wrote the seventh line of the file, and +.BR "/foo/\05" +was the same as +.BR "/foo/+5" . +However, only absolute values could be added; for example, +.BR "5\0/foo/" +was an error. POSIX.1\(hy2008 requires conformance to historical practice. +Address offsets are separately specified from addresses because they +could historically be provided to visual mode search commands. +.P +Historically, any missing addresses defaulted to the current line. This +was true for leading and trailing +-delimited +addresses, and for trailing +-delimited +addresses. For consistency, POSIX.1\(hy2008 requires it for leading + +addresses as well. +.P +Historically, +.IR ex +and +.IR vi +accepted the +.BR '^' +character as both an address and as a flag offset for commands. In both +cases it was identical to the +.BR '\(mi' +character. POSIX.1\(hy2008 does not require or prohibit this behavior. +.P +Historically, the enhancements to basic regular expressions could be +used in addressing; for example, +.BR '~' , +.BR '\e<' , +and +.BR '\e>' . +POSIX.1\(hy2008 requires conformance to historical practice; that is, that +regular expression usage be consistent, and that regular expression +enhancements be supported wherever regular expressions are used. +.SS "Command Line Parsing in ex" +.P +Historical +.IR ex +command parsing was even more complex than that described here. POSIX.1\(hy2008 +requires the subset of the command parsing that the standard developers +believed was documented and that users could reasonably be expected to +use in a portable fashion, and that was historically consistent between +implementations. (The discarded functionality is obscure, at best.) +Historical implementations will require changes in order to comply with +POSIX.1\(hy2008; however, users are not expected to notice any of these changes. +Most of the complexity in +.IR ex +parsing is to handle three special termination cases: +.IP " 1." 4 +The +.BR ! , +.BR global , +.BR v , +and the filter versions of the +.BR read +and +.BR write +commands are delimited by + +characters (they can contain + +characters that are usually shell pipes). +.IP " 2." 4 +The +.BR ex , +.BR edit , +.BR next , +and +.BR visual +in open and visual mode commands all take +.IR ex +commands, optionally containing + +characters, as their first arguments. +.IP " 3." 4 +The +.BR s +command takes a regular expression as its first argument, and uses the +delimiting characters to delimit the command. +.P +Historically, + +characters in the +.BR + \c +.IR command +argument of the +.BR ex , +.BR edit , +.BR next , +.BR vi , +and +.BR visual +commands, and in the +.IR pattern +and +.IR replacement +parts of the +.BR s +command, did not delimit the command, and in the filter cases for +.BR read +and +.BR write , +and the +.BR ! , +.BR global , +and +.BR v +commands, they did not delimit the command at all. For example, the +following commands are all valid: +.sp +.RS 4 +.nf +\fB +\fB:\fRedit +25 | s/abc/ABC/ file.c +\fB:\fRs/ | /PIPE/ +\fB:\fRread !spell % | columnate +\fB:\fRglobal/pattern/p | l +\fB:\fRs/a/b/ | s/c/d | set +.fi \fR +.P +.RE +.P +Historically, empty or + +filled lines in +.BR .exrc +files and +.BR source d +files (as well as +.IR EXINIT +variables and +.IR ex +command scripts) were treated as default commands; that is, +.BR print +commands. POSIX.1\(hy2008 specifically requires that they be ignored when +encountered in +.BR .exrc +and +.BR source d +files to eliminate a common source of new user error. +.P +Historically, +.IR ex +commands with multiple adjacent (or +-separated) +vertical lines were handled oddly when executed from +.IR ex +mode. For example, the command +.BR "|||" +, +when the cursor was on line 1, displayed lines 2, 3, and 5 of the file. +In addition, the command +.BR | +would only display the line after the next line, instead of the next +two lines. The former worked more logically when executed from +.IR vi +mode, and displayed lines 2, 3, and 4. POSIX.1\(hy2008 requires the +.IR vi +behavior; that is, a single default command and line number increment +for each command separator, and trailing + +characters after + +separators are discarded. +.P +Historically, +.IR ex +permitted a single extra + +as a leading command character; for example, +.BR ":g/pattern/:p" +was a valid command. POSIX.1\(hy2008 generalizes this to require that any number +of leading + +characters be stripped. +.P +Historically, any prefix of the +.BR delete +command could be followed without intervening + +characters by a flag character because in the command +.BR "d\0p" , +.IR p +is interpreted as the buffer +.IR p . +POSIX.1\(hy2008 requires conformance to historical practice. +.P +Historically, the +.BR k +command could be followed by the mark name without intervening + +characters. POSIX.1\(hy2008 requires conformance to historical practice. +.P +Historically, the +.BR s +command could be immediately followed by flag and option characters; +for example, +.BR "s/e/E/|s|sgc3p" +was a valid command. However, flag characters could not stand alone; +for example, the commands +.BR sp +and +.BR s\0l +would fail, while the command +.BR sgp +and +.BR "s\0gl" +would succeed. (Obviously, the +.BR '#' +flag character was used as a delimiter character if it followed the +command.) Another issue was that option characters had to precede flag +characters even when the command was fully specified; for example, the +command +.BR s/e/E/pg +would fail, while the command +.BR s/e/E/gp +would succeed. POSIX.1\(hy2008 requires conformance to historical practice. +.P +Historically, the first command name that had a prefix matching the +input from the user was the executed command; for example, +.BR ve , +.BR ver , +and +.BR vers +all executed the +.BR version +command. Commands were in a specific order, however, so that +.BR a +matched +.BR append , +not +.BR abbreviate . +POSIX.1\(hy2008 requires conformance to historical practice. The restriction on +command search order for implementations with extensions is to avoid +the addition of commands such that the historical prefixes would fail +to work portably. +.P +Historical implementations of +.IR ex +and +.IR vi +did not correctly handle multiple +.IR ex +commands, separated by + +characters, that entered or exited visual mode or the editor. Because +implementations of +.IR vi +exist that do not exhibit this failure mode, POSIX.1\(hy2008 does not permit it. +.P +The requirement that alphabetic command names consist of all following +alphabetic characters up to the next non-alphabetic character means +that alphabetic command names must be separated from their arguments by +one or more non-alphabetic characters, normally a + +or +.BR '!' +character, except as specified for the exceptions, the +.BR delete , +.BR k , +and +.BR s +commands. +.P +Historically, the repeated execution of the +.IR ex +default +.BR print +commands (\c +\(hyD, +.IR eof , +, +) +erased any prompting character and displayed the next lines without +scrolling the terminal; that is, immediately below any previously +displayed lines. This provided a cleaner presentation of the lines in +the file for the user. POSIX.1\(hy2008 does not require this behavior because it +may be impossible in some situations; however, implementations are +strongly encouraged to provide this semantic if possible. +.P +Historically, it was possible to change files in the middle of a command, +and have the rest of the command executed in the new file; for example: +.sp +.RS 4 +.nf +\fB +:edit +25 file.c | s/abc/ABC/ | 1 +.fi \fR +.P +.RE +.P +was a valid command, and the substitution was attempted in the newly +edited file. POSIX.1\(hy2008 requires conformance to historical practice. The +following commands are examples that exercise the +.IR ex +parser: +.sp +.RS 4 +.nf +\fB +echo 'foo | bar' > file1; echo 'foo/bar' > file2; +vi +:edit +1 | s/|/PIPE/ | w file1 | e file2 | 1 | s/\e//SLASH/ | wq +.fi \fR +.P +.RE +.P +Historically, there was no protection in editor implementations to +avoid +.IR ex +.BR global , +.BR v , +.BR @ , +or +.BR * +commands changing edit buffers during execution of their associated +commands. Because this would almost invariably result in catastrophic +failure of the editor, and implementations exist that do exhibit these +problems, POSIX.1\(hy2008 requires that changing the edit buffer during a +.BR global +or +.BR v +command, or during a +.BR @ +or +.BR * +command for which there will be more than a single execution, be an +error. Implementations supporting multiple edit buffers simultaneously +are strongly encouraged to apply the same semantics to switching +between buffers as well. +.P +The +.IR ex +command quoting required by POSIX.1\(hy2008 is a superset of the quoting in +historical implementations of the editor. For example, it was not +historically possible to escape a + +in a filename; for example, +.BR ":edit\0foo\e\e\e\0bar" +would report that too many filenames had been entered for the edit +command, and there was no method of escaping a + +in the first argument of an +.BR edit , +.BR ex , +.BR next , +or +.BR visual +command at all. POSIX.1\(hy2008 extends historical practice, requiring that +quoting behavior be made consistent across all +.IR ex +commands, except for the +.BR map , +.BR unmap , +.BR abbreviate , +and +.BR unabbreviate +commands, which historically used +\(hyV +instead of + +characters for quoting. For those four commands, POSIX.1\(hy2008 requires +conformance to historical practice. +.P +Backslash quoting in +.IR ex +is non-intuitive. +-escapes +are ignored unless they escape a special character; for example, when +performing +.IR file +argument expansion, the string +.BR \(dq\e\e%\(dq +is equivalent to +.BR '\e%' , +not \fR"\e<\fIcurrent\ pathname\fR>"\fR. +This can be confusing for users because + +is usually one of the characters that causes shell expansion to +be performed, and therefore shell quoting rules must be taken into +consideration. Generally, quoting characters are only considered if they +escape a special character, and a quoting character must be provided +for each layer of parsing for which the character is special. As another +example, only a single + +is necessary for the +.BR '\el' +sequence in substitute replacement patterns, because the character +.BR 'l' +is not special to any parsing layer above it. +.P +\(hyV +quoting in +.IR ex +is slightly different from backslash quoting. In the four commands +where +\(hyV +quoting applies (\c +.BR abbreviate , +.BR unabbreviate , +.BR map , +and +.BR unmap ), +any character may be escaped by a +\(hyV +whether it would have a special meaning or not. POSIX.1\(hy2008 requires +conformance to historical practice. +.P +Historical implementations of the editor did not require delimiters +within character classes to be escaped; for example, the command +.BR ":s/[/]//" +on the string +.BR \(dqxxx/yyy\(dq +would delete the +.BR '/' +from the string. POSIX.1\(hy2008 disallows this historical practice for +consistency and because it places a large burden on implementations by +requiring that knowledge of regular expressions be built into the +editor parser. +.P +Historically, quoting + +characters in +.IR ex +commands was handled inconsistently. In most cases, the + +character always terminated the command, regardless of any preceding +escape character, because + +characters did not escape + +characters for most +.IR ex +commands. However, some +.IR ex +commands (for example, +.BR s , +.BR map , +and +.BR abbreviation ) +permitted + +characters to be escaped (although in the case of +.BR map +and +.BR abbreviation , +\(hyV +characters escaped them instead of + +characters). This was true in not only the command line, but also +.BR .exrc +and +.BR source d +files. For example, the command: +.sp +.RS 4 +.nf +\fB +map = foobar +.fi \fR +.P +.RE +.P +would succeed, although it was sometimes difficult to get the +\(hyV +and the inserted + +passed to the +.IR ex +parser. For consistency and simplicity of specification, POSIX.1\(hy2008 requires +that it be possible to escape + +characters in +.IR ex +commands at all times, using + +characters for most +.IR ex +commands, and using +\(hyV +characters for the +.BR map +and +.BR abbreviation +commands. For example, the command +.BR print \c +\c +.BR list +is required to be parsed as the single command +.BR print \c +\c +.BR list . +While this differs from historical practice, POSIX.1\(hy2008 developers believed +it unlikely that any script or user depended on the historical +behavior. +.P +Historically, an error in a command specified using the +.BR \(mic +option did not cause the rest of the +.BR \(mic +commands to be discarded. POSIX.1\(hy2008 disallows this for consistency with +mapped keys, the +.BR @ , +.BR global , +.BR source , +and +.BR v +commands, the +.IR EXINIT +environment variable, and the +.BR .exrc +files. +.SS "Input Editing in ex" +.P +One of the common uses of the historical +.IR ex +editor is over slow network connections. Editors that run in canonical +mode can require far less traffic to and from, and far less processing +on, the host machine, as well as more easily supporting block-mode +terminals. For these reasons, POSIX.1\(hy2008 requires that +.IR ex +be implemented using canonical mode input processing, as was done +historically. +.P +POSIX.1\(hy2008 does not require the historical 4 BSD input editing characters +``word erase'' or ``literal next''. For this reason, it is unspecified +how they are handled by +.IR ex , +although they must have the required effect. Implementations that +resolve them after the line has been ended using a + +or +\(hyM +character, and implementations that rely on the underlying system +terminal support for this processing, are both conforming. +Implementations are strongly urged to use the underlying system +functionality, if at all possible, for compatibility with other system +text input interfaces. +.P +Historically, when the +.IR eof +character was used to decrement the +.BR autoindent +level, the cursor moved to display the new end of the +.BR autoindent +characters, but did not move the cursor to a new line, nor did it erase +the +\(hyD +character from the line. POSIX.1\(hy2008 does not specify that the cursor remain +on the same line or that the rest of the line is erased; however, +implementations are strongly encouraged to provide the best possible +user interface; that is, the cursor should remain on the same line, and +any +\(hyD +character on the line should be erased. +.P +POSIX.1\(hy2008 does not require the historical 4 BSD input editing character +``reprint'', traditionally +\(hyR, +which redisplayed the current input from the user. For this reason, and +because the functionality cannot be implemented after the line has been +terminated by the user, POSIX.1\(hy2008 makes no requirements about this +functionality. Implementations are strongly urged to make this +historical functionality available, if possible. +.P +Historically, +\(hyQ +did not perform a literal next function in +.IR ex , +as it did in +.IR vi . +POSIX.1\(hy2008 requires conformance to historical practice to avoid breaking +historical +.IR ex +scripts and +.BR .exrc +files. +.SS "eof" +.P +Whether the +.IR eof +character immediately modifies the +.BR autoindent +characters in the prompt is left unspecified so that implementations +can conform in the presence of systems that do not support this +functionality. Implementations are encouraged to modify the line and +redisplay it immediately, if possible. +.P +The specification of the handling of the +.IR eof +character differs from historical practice only in that +.IR eof +characters are not discarded if they follow normal characters in the +text input. Historically, they were always discarded. +.SS "Command Descriptions in ex" +.P +Historically, several commands (for example, +.BR global , +.BR v , +.BR visual , +.BR s , +.BR write , +.BR wq , +.BR yank , +.BR ! , +.BR < , +.BR > , +.BR & , +and +.BR ~ ) +were executable in empty files (that is, the default address(es) were +0), or permitted explicit addresses of 0 (for example, 0 was a valid +address, or 0,0 was a valid range). Addresses of 0, or command +execution in an empty file, make sense only for commands that add new +text to the edit buffer or write commands (because users may wish to +write empty files). POSIX.1\(hy2008 requires this behavior for such commands and +disallows it otherwise, for consistency and simplicity of +specification. +.P +A count to an +.IR ex +command has been historically corrected to be no greater than the last +line in a file; for example, in a five-line file, the command +.BR "1,6print" +would fail, but the command +.BR "1print300" +would succeed. POSIX.1\(hy2008 requires conformance to historical practice. +.P +Historically, the use of flags in +.IR ex +commands could be obscure. General historical practice was as described +by POSIX.1\(hy2008, but there were some special cases. For instance, the +.BR list , +.BR number , +and +.BR print +commands ignored trailing address offsets; for example, +.BR "3p\0+++#" +would display line 3, and 3 would be the current line after the +execution of the command. The +.BR open +and +.BR visual +commands ignored both the trailing offsets and the trailing flags. +Also, flags specified to the +.BR open +and +.BR visual +commands interacted badly with the +.BR list +edit option, and setting and then unsetting it during the open/visual +session would cause +.IR vi +to stop displaying lines in the specified format. For consistency and +simplicity of specification, POSIX.1\(hy2008 does not permit any of these +exceptions to the general rule. +.P +POSIX.1\(hy2008 uses the word +.IR copy +in several places when discussing buffers. This is not intended to +imply implementation. +.P +Historically, +.IR ex +users could not specify numeric buffers because of the ambiguity this +would cause; for example, in the command +.BR "3\0delete\02" , +it is unclear whether 2 is a buffer name or a +.IR count . +POSIX.1\(hy2008 requires conformance to historical practice by default, but does +not preclude extensions. +.P +Historically, the contents of the unnamed buffer were frequently +discarded after commands that did not explicitly affect it; for +example, when using the +.BR edit +command to switch files. For consistency and simplicity of +specification, POSIX.1\(hy2008 does not permit this behavior. +.P +The +.IR ex +utility did not historically have access to the numeric buffers, and, +furthermore, deleting lines in +.IR ex +did not modify their contents. For example, if, after doing a delete in +.IR vi , +the user switched to +.IR ex , +did another delete, and then switched back to +.IR vi , +the contents of the numeric buffers would not have changed. POSIX.1\(hy2008 +requires conformance to historical practice. Numeric buffers are +described in the +.IR ex +utility in order to confine the description of buffers to a single +location in POSIX.1\(hy2008. +.P +The metacharacters that trigger shell expansion in +.IR file +arguments match historical practice, as does the method for doing shell +expansion. Implementations wishing to provide users with the +flexibility to alter the set of metacharacters are encouraged to +provide a +.BR shellmeta +string edit option. +.P +Historically, +.IR ex +commands executed from +.IR vi +refreshed the screen when it did not strictly need to do so; for +example, +.BR ":!date\0>\0/dev/null" +does not require a screen refresh because the output of the UNIX +.IR date +command requires only a single line of the screen. POSIX.1\(hy2008 requires that +the screen be refreshed if it has been overwritten, but makes no +requirements as to how an implementation should make that +determination. Implementations may prompt and refresh the screen +regardless. +.SS "Abbreviate" +.P +Historical practice was that characters that were entered as part of an +abbreviation replacement were subject to +.BR map +expansions, the +.BR showmatch +edit option, further abbreviation expansions, and so on; that is, they +were logically pushed onto the terminal input queue, and were not a +simple replacement. POSIX.1\(hy2008 requires conformance to historical practice. +Historical practice was that whenever a non-word character (that had +not been escaped by a +\(hyV) +was entered after a word character, +.IR vi +would check for abbreviations. The check was based on the type of the +character entered before the word character of the word/non-word pair +that triggered the check. The word character of the word/non-word pair +that triggered the check and all characters entered before the trigger +pair that were of that type were included in the check, with the +exception of + +characters, which always delimited the abbreviation. +.P +This means that, for the abbreviation to work, the +.IR lhs +must end with a word character, there can be no transitions from word +to non-word characters (or \fIvice versa\fP) other than between the +last and next-to-last characters in the +.IR lhs , +and there can be no + +characters in the +.IR lhs . +In addition, because of the historical quoting rules, it was impossible +to enter a literal +\(hyV +in the +.IR lhs . +POSIX.1\(hy2008 requires conformance to historical practice. Historical +implementations did not inform users when abbreviations that could +never be used were entered; implementations are strongly encouraged to +do so. +.br +.P +For example, the following abbreviations will work: +.sp +.RS 4 +.nf +\fB +:ab (p REPLACE +:ab p REPLACE +:ab ((p REPLACE +.fi \fR +.P +.RE +.P +The following abbreviations will not work: +.sp +.RS 4 +.nf +\fB +:ab ( REPLACE +:ab (pp REPLACE +.fi \fR +.P +.RE +.P +Historical practice is that words on the +.IR vi +colon command line were subject to abbreviation expansion, including +the arguments to the +.BR abbrev +(and more interestingly) the +.BR unabbrev +command. Because there are implementations that do not do abbreviation +expansion for the first argument to those commands, this is permitted, +but not required, by POSIX.1\(hy2008. However, the following sequence: +.sp +.RS 4 +.nf +\fB +:ab foo bar +:ab foo baz +.fi \fR +.P +.RE +.P +resulted in the addition of an abbreviation of +.BR \(dqbaz\(dq +for the string +.BR \(dqbar\(dq +in historical +.IR ex /\c +.IR vi , +and the sequence: +.sp +.RS 4 +.nf +\fB +:ab foo1 bar +:ab foo2 bar +:unabbreviate foo2 +.fi \fR +.P +.RE +.P +deleted the abbreviation +.BR \(dqfoo1\(dq , +not +.BR \(dqfoo2\(dq . +These behaviors are not permitted by POSIX.1\(hy2008 because they clearly violate +the expectations of the user. +.P +It was historical practice that +\(hyV, +not +, +characters be interpreted as escaping subsequent characters in the +.BR abbreviate +command. POSIX.1\(hy2008 requires conformance to historical practice; however, it +should be noted that an abbreviation containing a + +will never work. +.SS "Append" +.P +Historically, any text following a + +command separator after an +.BR append , +.BR change , +or +.BR insert +command became part of the insert text. For example, in the command: +.sp +.RS 4 +.nf +\fB +:g/pattern/append|stuff1 +.fi \fR +.P +.RE +.P +a line containing the text +.BR \(dqstuff1\(dq +would be appended to each line matching pattern. It was also +historically valid to enter: +.sp +.RS 4 +.nf +\fB +:append|stuff1 +stuff2 +\&. +.fi \fR +.P +.RE +.P +and the text on the +.IR ex +command line would be appended along with the text inserted after it. +There was an historical bug, however, that the user had to enter two +terminating lines (the +.BR '.' +lines) to terminate text input mode in this case. POSIX.1\(hy2008 requires +conformance to historical practice, but disallows the historical need +for multiple terminating lines. +.SS "Change" +.P +See the RATIONALE for the +.BR append +command. Historical practice for cursor positioning after the change +command when no text is input, is as described in POSIX.1\(hy2008. However, one +System V implementation is known to have been modified such that the +cursor is positioned on the first address specified, and not on the +line before the first address. POSIX.1\(hy2008 disallows this modification for +consistency. +.P +Historically, the +.BR change +command did not support buffer arguments, although some implementations +allow the specification of an optional buffer. This behavior is neither +required nor disallowed by POSIX.1\(hy2008. +.SS "Change Directory" +.P +A common extension in +.IR ex +implementations is to use the elements of a +.BR cdpath +edit option as prefix directories for +.IR path +arguments to +.BR chdir +that are relative pathnames and that do not have +.BR '.' +or +.BR \(dq..\(dq +as their first component. Elements in the +.BR cdpath +edit option are +-separated. +The initial value of the +.BR cdpath +edit option is the value of the shell +.IR CDPATH +environment variable. This feature was not included in POSIX.1\(hy2008 because it +does not exist in any of the implementations considered historical +practice. +.SS "Copy" +.P +Historical implementations of +.IR ex +permitted copies to lines inside of the specified range; for example, +.BR ":2,5copy3" +was a valid command. POSIX.1\(hy2008 requires conformance to historical +practice. +.SS "Delete" +.P +POSIX.1\(hy2008 requires support for the historical parsing of a +.BR delete +command followed by flags, without any intervening + +characters. For example: +.IP "\fB1dp\fP" 8 +Deletes the first line and prints the line that was second. +.IP "\fB1delep\fP" 8 +As for +.BR 1dp . +.IP "\fB1d\fP" 8 +Deletes the first line, saving it in buffer +.IR p . +.IP "\fB1d\0p1l\fP" 8 +(Pee-one-ell.) Deletes the first line, saving it in buffer +.IR p , +and listing the line that was second. +.SS "Edit" +.P +Historically, any +.IR ex +command could be entered as a +.BR + \c +.IR command +argument to the +.BR edit +command, although some (for example, +.BR insert +and +.BR append ) +were known to confuse historical implementations. For consistency and +simplicity of specification, POSIX.1\(hy2008 requires that any command be +supported as an argument to the +.BR edit +command. +.P +Historically, the command argument was executed with the current line +set to the last line of the file, regardless of whether the +.BR edit +command was executed from visual mode or not. POSIX.1\(hy2008 requires +conformance to historical practice. +.P +Historically, the +.BR + \c +.IR command +specified to the +.BR edit +and +.BR next +commands was delimited by the first +, +and there was no way to quote them. For consistency, POSIX.1\(hy2008 requires +that the usual +.IR ex +backslash quoting be provided. +.P +Historically, specifying the +.BR + \c +.IR command +argument to the edit command required a filename to be specified as +well; for example, +.BR ":edit\0+100" +would always fail. For consistency and simplicity of specification, +POSIX.1\(hy2008 does not permit this usage to fail for that reason. +.P +Historically, only the cursor position of the last file edited was +remembered by the editor. POSIX.1\(hy2008 requires that this be supported; +however, implementations are permitted to remember and restore the +cursor position for any file previously edited. +.SS "File" +.P +Historical versions of the +.IR ex +editor +.BR file +command displayed a current line and number of lines in the edit buffer +of 0 when the file was empty, while the +.IR vi +\(hyG +command displayed a current line and number of lines in the edit buffer +of 1 in the same situation. POSIX.1\(hy2008 does not permit this discrepancy, +instead requiring that a message be displayed indicating that the file +is empty. +.SS "Global" +.P +The two-pass operation of the +.BR global +and +.BR v +commands is not intended to imply implementation, only the required +result of the operation. +.P +The current line and column are set as specified for the individual +.IR ex +commands. This requirement is cumulative; that is, the current line and +column must track across all the commands executed by the +.BR global +or +.BR v +commands. +.SS "Insert" +.P +See the RATIONALE for the +.BR append +command. +.P +Historically, +.BR insert +could not be used with an address of zero; that is, not when the edit +buffer was empty. POSIX.1\(hy2008 requires that this command behave consistently +with the +.BR append +command. +.SS "Join" +.P +The action of the +.BR join +command in relation to the special characters is only defined for the +POSIX locale because the correct amount of white space after a period +varies; in Japanese none is required, in French only a single space, +and so on. +.SS "List" +.P +The historical output of the +.BR list +command was potentially ambiguous. The standard developers believed +correcting this to be more important than adhering to historical +practice, and POSIX.1\(hy2008 requires unambiguous output. +.SS "Map" +.P +Historically, command mode maps only applied to command names; for +example, if the character +.BR 'x' +was mapped to +.BR 'y' , +the command +.BR fx +searched for the +.BR 'x' +character, not the +.BR 'y' +character. POSIX.1\(hy2008 requires this behavior. Historically, entering +\(hyV +as the first character of a +.IR vi +command was an error. Several implementations have extended the +semantics of +.IR vi +such that +\(hyV +means that the subsequent command character is not mapped. This is +permitted, but not required, by POSIX.1\(hy2008. Regardless, using +\(hyV +to escape the second or later character in a sequence of characters +that might match a +.BR map +command, or any character in text input mode, is historical practice, +and stops the entered keys from matching a map. POSIX.1\(hy2008 requires +conformance to historical practice. +.P +Historical implementations permitted digits to be used as a +.BR map +command +.IR lhs , +but then ignored the map. POSIX.1\(hy2008 requires that the mapped digits not be +ignored. +.P +The historical implementation of the +.BR map +command did not permit +.BR map +commands that were more than a single character in length if the first +character was printable. This behavior is permitted, but not required, +by POSIX.1\(hy2008. +.P +Historically, mapped characters were remapped unless the +.BR remap +edit option was not set, or the prefix of the mapped characters matched +the mapping characters; for example, in the +.BR map : +.sp +.RS 4 +.nf +\fB +:map ab abcd +.fi \fR +.P +.RE +.P +the characters +.BR \(dqab\(dq +were used as is and were not remapped, but the characters +.BR \(dqcd\(dq +were mapped if appropriate. This can cause infinite loops in the +.IR vi +mapping mechanisms. POSIX.1\(hy2008 requires conformance to historical practice, +and that such loops be interruptible. +.P +Text input maps had the same problems with expanding the +.IR lhs +for the +.IR ex +.BR map! +and +.BR unmap! +command as did the +.IR ex +.BR abbreviate +and +.BR unabbreviate +commands. See the RATIONALE for the +.IR ex +.BR abbreviate +command. POSIX.1\(hy2008 requires similar modification of some historical +practice for the +.BR map +and +.BR unmap +commands, as described for the +.BR abbreviate +and +.BR unabbreviate +commands. +.P +Historically, +.BR map s +that were subsets of other +.BR map s +behaved differently depending on the order in which they were defined. +For example: +.sp +.RS 4 +.nf +\fB +:map! ab short +:map! abc long +.fi \fR +.P +.RE +.P +would always translate the characters +.BR \(dqab\(dq +to +.BR \(dqshort\(dq , +regardless of how fast the characters +.BR \(dqabc\(dq +were entered. If the entry order was reversed: +.sp +.RS 4 +.nf +\fB +:map! abc long +:map! ab short +.fi \fR +.P +.RE +.P +the characters +.BR \(dqab\(dq +would cause the editor to pause, waiting for the completing +.BR 'c' +character, and the characters might never be mapped to +.BR \(dqshort\(dq . +For consistency and simplicity of specification, POSIX.1\(hy2008 requires that +the shortest match be used at all times. +.P +The length of time the editor spends waiting for the characters to +complete the +.IR lhs +is unspecified because the timing capabilities of systems are often +inexact and variable, and it may depend on other factors such as the +speed of the connection. The time should be long enough for the user to +be able to complete the sequence, but not long enough for the user to +have to wait. Some implementations of +.IR vi +have added a +.BR keytime +option, which permits users to set the number of 0,1 seconds the editor +waits for the completing characters. Because mapped terminal function +and cursor keys tend to start with an + +character, and + +is the key ending +.IR vi +text input mode, +.BR map s +starting with + +characters are generally exempted from this timeout period, or, at +least timed out differently. +.SS "Mark" +.P +Historically, users were able to set the ``previous context'' marks +explicitly. In addition, the +.IR ex +commands +.BR '' +and +.BR '` +and the +.IR vi +commands +.BR '' , +.BR `` , +.BR `' , +and +.BR '` +all referred to the same mark. In addition, the previous context marks +were not set if the command, with which the address setting the mark +was associated, failed. POSIX.1\(hy2008 requires conformance to historical +practice. Historically, if marked lines were deleted, the mark was also +deleted, but would reappear if the change was undone. POSIX.1\(hy2008 requires +conformance to historical practice. +.P +The description of the special events that set the +.BR ` +and +.BR ' +marks matches historical practice. For example, historically the +command +.BR "/a/,/b/" +did not set the +.BR ` +and +.BR ' +marks, but the command +.BR "/a/,/b/delete" +did. +.SS "Next" +.P +Historically, any +.IR ex +command could be entered as a +.BR + \c +.IR command +argument to the +.BR next +command, although some (for example, +.BR insert +and +.BR append ) +were known to confuse historical implementations. POSIX.1\(hy2008 requires that +any command be permitted and that it behave as specified. The +.BR next +command can accept more than one file, so usage such as: +.sp +.RS 4 +.nf +\fB +next `ls [abc] ` +.fi \fR +.P +.RE +.P +is valid; it need not be valid for the +.BR edit +or +.BR read +commands, for example, because they expect only one filename. +.P +Historically, the +.BR next +command behaved differently from the +.BR :rewind +command in that it ignored the force flag if the +.BR autowrite +flag was set. For consistency, POSIX.1\(hy2008 does not permit this behavior. +.P +Historically, the +.BR next +command positioned the cursor as if the file had never been edited +before, regardless. POSIX.1\(hy2008 does not permit this behavior, for +consistency with the +.BR edit +command. +.P +Implementations wanting to provide a counterpart to the +.BR next +command that edited the previous file have used the command +.BR prev[ious], +which takes no +.IR file +argument. POSIX.1\(hy2008 does not require this command. +.SS "Open" +.P +Historically, the +.BR open +command would fail if the +.BR open +edit option was not set. POSIX.1\(hy2008 does not mention the +.BR open +edit option and does not require this behavior. Some historical +implementations do not permit entering open mode from open or visual +mode, only from +.IR ex +mode. For consistency, POSIX.1\(hy2008 does not permit this behavior. +.P +Historically, entering open mode from the command line (that is, +.IR vi +.BR +open ) +resulted in anomalous behaviors; for example, the +.IR ex +file and +.IR set +commands, and the +.IR vi +command +\(hyG +did not work. For consistency, POSIX.1\(hy2008 does not permit this behavior. +.P +Historically, the +.BR open +command only permitted +.BR '/' +characters to be used as the search pattern delimiter. For consistency, +POSIX.1\(hy2008 requires that the search delimiters used by the +.BR s , +.BR global , +and +.BR v +commands be accepted as well. +.SS "Preserve" +.P +The +.BR preserve +command does not historically cause the file to be considered +unmodified for the purposes of future commands that may exit the +editor. POSIX.1\(hy2008 requires conformance to historical practice. +.P +Historical documentation stated that mail was not sent to the user when +preserve was executed; however, historical implementations did send +mail in this case. POSIX.1\(hy2008 requires conformance to the historical +implementations. +.SS "Print" +.P +The writing of NUL by the +.BR print +command is not specified as a special case because the standard +developers did not want to require +.IR ex +to support NUL characters. Historically, characters were displayed +using the ARPA standard mappings, which are as follows: +.IP " 1." 4 +Printable characters are left alone. +.IP " 2." 4 +Control characters less than \e177 are represented as +.BR '^' +followed by the character offset from the +.BR '@' +character in the ASCII map; for example, \e007 is represented as +.BR '^G' . +.IP " 3." 4 +\e177 is represented as +.BR '^' +followed by +.BR '?' . +.P +The display of characters having their eighth bit set was less +standard. Existing implementations use hex (0x00), octal (\e000), and a +meta-bit display. (The latter displayed bytes that had their eighth bit +set as the two characters +.BR \(dqM\(mi\(dq +followed by the seven-bit display as described above.) The latter +probably has the best claim to historical practice because it was used +for the +.BR \(miv +option of 4 BSD and 4 BSD-derived versions of the +.IR cat +utility since 1980. +.P +No specific display format is required by POSIX.1\(hy2008. +.P +Explicit dependence on the ASCII character set has been avoided where +possible, hence the use of the phrase an ``implementation-defined +multi-character sequence'' for the display of non-printable characters +in preference to the historical usage of, for instance, +.BR \(dq^I\(dq +for the +. +Implementations are encouraged to conform to historical practice in the +absence of any strong reason to diverge. +.P +Historically, all +.IR ex +commands beginning with the letter +.BR 'p' +could be entered using capitalized versions of the commands; for +example, +.BR P[rint] , +.BR Pre[serve] , +and +.BR Pu[t] +were all valid command names. POSIX.1\(hy2008 permits, but does not require, this +historical practice because capital forms of the commands are used by +some implementations for other purposes. +.SS "Put" +.P +Historically, an +.IR ex +.BR put +command, executed from open or visual mode, was the same as the open or +visual mode +.BR P +command, if the buffer was named and was cut in character mode, and the +same as the +.BR p +command if the buffer was named and cut in line mode. If the unnamed +buffer was the source of the text, the entire line from which the text +was taken was usually +.BR put , +and the buffer was handled as if in line mode, but it was possible to +get extremely anomalous behavior. In addition, using the +.BR Q +command to switch into +.IR ex +mode, and then doing a +.BR put +often resulted in errors as well, such as appending text that was +unrelated to the (supposed) contents of the buffer. For consistency and +simplicity of specification, POSIX.1\(hy2008 does not permit these behaviors. All +.IR ex +.BR put +commands are required to operate in line mode, and the contents of the +buffers are not altered by changing the mode of the editor. +.SS "Read" +.P +Historically, an +.IR ex +.BR read +command executed from open or visual mode, executed in an empty file, +left an empty line as the first line of the file. For consistency and +simplicity of specification, POSIX.1\(hy2008 does not permit this behavior. +Historically, a +.BR read +in open or visual mode from a program left the cursor at the last line +read in, not the first. For consistency, POSIX.1\(hy2008 does not permit this +behavior. +.P +Historical implementations of +.IR ex +were unable to undo +.BR read +commands that read from the output of a program. For consistency, POSIX.1\(hy2008 +does not permit this behavior. +.P +Historically, the +.IR ex +and +.IR vi +message after a successful +.BR read +or +.BR write +command specified ``characters'', not ``bytes''. POSIX.1\(hy2008 requires that +the number of bytes be displayed, not the number of characters, because +it may be difficult in multi-byte implementations to determine the +number of characters read. Implementations are encouraged to clarify +the message displayed to the user. +.P +Historically, reads were not permitted on files other than type +regular, except that FIFO files could be read (probably only because +they did not exist when +.IR ex +and +.IR vi +were originally written). Because the historical +.IR ex +evaluated +.BR read! +and +.BR read\0! +equivalently, there can be no optional way to force the read. POSIX.1\(hy2008 +permits, but does not require, this behavior. +.SS "Recover" +.P +Some historical implementations of the editor permitted users to +recover the edit buffer contents from a previous edit session, and then +exit without saving those contents (or explicitly discarding them). The +intent of POSIX.1\(hy2008 in requiring that the edit buffer be treated as already +modified is to prevent this user error. +.SS "Rewind" +.P +Historical implementations supported the +.BR rewind +command when the user was editing the first file in the list; that is, +the file that the +.BR rewind +command would edit. POSIX.1\(hy2008 requires conformance to historical practice. +.SS "Substitute" +.P +Historically, +.IR ex +accepted an +.BR r +option to the +.BR s +command. The effect of the +.BR r +option was to use the last regular expression used in any command as +the pattern, the same as the +.BR ~ +command. The +.BR r +option is not required by POSIX.1\(hy2008. Historically, the +.BR c +and +.BR g +options were toggled; for example, the command +.BR ":s/abc/def/" +was the same as +.BR "s/abc/def/ccccgggg" . +For simplicity of specification, POSIX.1\(hy2008 does not permit this behavior. +.P +The tilde command is often used to replace the last search RE. For +example, in the sequence: +.sp +.RS 4 +.nf +\fB +s/red/blue/ +/green +~ +.fi \fR +.P +.RE +.P +the +.BR ~ +command is equivalent to: +.sp +.RS 4 +.nf +\fB +s/green/blue/ +.fi \fR +.P +.RE +.P +Historically, +.IR ex +accepted all of the following forms: +.sp +.RS 4 +.nf +\fB +s/abc/def/ +s/abc/def +s/abc/ +s/abc +.fi \fR +.P +.RE +.P +POSIX.1\(hy2008 requires conformance to this historical practice. +.P +The +.BR s +command presumes that the +.BR '^' +character only occupies a single column in the display. Much of the +.IR ex +and +.IR vi +specification presumes that the + +only occupies a single column in the display. There are no known +character sets for which this is not true. +.P +Historically, the final column position for the substitute commands was +based on previous column movements; a search for a pattern followed by +a substitution would leave the column position unchanged, while a 0 +command followed by a substitution would change the column position to +the first non-\c +. +For consistency and simplicity of specification, POSIX.1\(hy2008 requires that +the final column position always be set to the first non-\c +. +.SS "Set" +.P +Historical implementations redisplayed all of the options for each +occurrence of the +.BR all +keyword. POSIX.1\(hy2008 permits, but does not require, this behavior. +.SS "Tag" +.P +No requirement is made as to where +.IR ex +and +.IR vi +shall look for the file referenced by the tag entry. Historical +practice has been to look for the path found in the +.BR tags +file, based on the current directory. A useful extension found in some +implementations is to look based on the directory containing the tags +file that held the entry, as well. No requirement is made as to which +reference for the tag in the tags file is used. This is deliberate, in +order to permit extensions such as multiple entries in a tags file for +a tag. +.P +Because users often specify many different tags files, some of which +need not be relevant or exist at any particular time, POSIX.1\(hy2008 requires +that error messages about problem tags files be displayed only if the +requested tag is not found, and then, only once for each time that the +.BR tag +edit option is changed. +.P +The requirement that the current edit buffer be unmodified is only +necessary if the file indicated by the tag entry is not the same as the +current file (as defined by the current pathname). Historically, the +file would be reloaded if the filename had changed, as well as if the +filename was different from the current pathname. For consistency and +simplicity of specification, POSIX.1\(hy2008 does not permit this behavior, +requiring that the name be the only factor in the decision. +.P +Historically, +.IR vi +only searched for tags in the current file from the current cursor to +the end of the file, and therefore, if the +.BR wrapscan +option was not set, tags occurring before the current cursor were not +found. POSIX.1\(hy2008 considers this a bug, and implementations are required to +search for the first occurrence in the file, regardless. +.SS "Undo" +.P +The +.BR undo +description deliberately uses the word ``modified''. The +.BR undo +command is not intended to undo commands that replace the contents of +the edit buffer, such as +.BR edit , +.BR next , +.BR tag , +or +.BR recover . +.P +Cursor positioning after the +.BR undo +command was inconsistent in the historical +.IR vi , +sometimes attempting to restore the original cursor position (\c +.BR global , +.BR undo , +and +.BR v +commands), and sometimes, in the presence of maps, placing the cursor +on the last line added or changed instead of the first. POSIX.1\(hy2008 requires +a simplified behavior for consistency and simplicity of specification. +.SS "Version" +.P +The +.BR version +command cannot be exactly specified since there is no widely-accepted +definition of what the version information should contain. +Implementations are encouraged to do something reasonably intelligent. +.SS "Write" +.P +Historically, the +.IR ex +and +.IR vi +message after a successful +.BR read +or +.BR write +command specified ``characters'', not ``bytes''. POSIX.1\(hy2008 requires that +the number of bytes be displayed, not the number of characters because +it may be difficult in multi-byte implementations to determine the +number of characters written. Implementations are encouraged to clarify +the message displayed to the user. +.P +Implementation-defined tests are permitted so that implementations +can make additional checks; for example, for locks or file modification +times. +.P +Historically, attempting to append to a nonexistent file caused an +error. It has been left unspecified in POSIX.1\(hy2008 to permit implementations +to let the +.BR write +succeed, so that the append semantics are similar to those of the +historical +.IR csh . +.P +Historical +.IR vi +permitted empty edit buffers to be written. However, since the way +.IR vi +got around dealing with ``empty'' files was to always have a line in +the edit buffer, no matter what, it wrote them as files of a single, +empty line. POSIX.1\(hy2008 does not permit this behavior. +.P +Historically, +.IR ex +restored standard output and standard error to their values as of when +.IR ex +was invoked, before writes to programs were performed. This could +disturb the terminal configuration as well as be a security issue for +some terminals. POSIX.1\(hy2008 does not permit this, requiring that the program +output be captured and displayed as if by the +.IR ex +.BR print +command. +.SS "Adjust Window" +.P +Historically, the line count was set to the value of the +.BR scroll +option if the type character was end-of-file. This feature was broken +on most historical implementations long ago, however, and is not +documented anywhere. For this reason, POSIX.1\(hy2008 is resolutely silent. +.P +Historically, the +.BR z +command was +-sensitive +and +.BR z\0+ +and +.BR z\0\(mi +did different things than +.BR z+ +and +.BR z\(mi +because the type could not be distinguished from a flag. (The commands +.BR z\0. +and +.BR z\0= +were historically invalid.) POSIX.1\(hy2008 requires conformance to this +historical practice. +.P +Historically, the +.BR z +command was further +-sensitive +in that the +.IR count +could not be +-delimited; +for example, the commands +.BR z=\05 +and +.BR z\(mi\05 +were also invalid. Because the +.IR count +is not ambiguous with respect to either the type character or the +flags, this is not permitted by POSIX.1\(hy2008. +.SS "Escape" +.P +Historically, +.IR ex +filter commands only read the standard output of the commands, letting +standard error appear on the terminal as usual. The +.IR vi +utility, however, read both standard output and standard error. POSIX.1\(hy2008 +requires the latter behavior for both +.IR ex +and +.IR vi , +for consistency. +.SS "Shift Left and Shift Right" +.P +Historically, it was possible to add shift characters to increase the +effect of the command; for example, +.BR <<< +outdented (or +.BR >>> +indented) the lines 3 levels of indentation instead of the default 1. +POSIX.1\(hy2008 requires conformance to historical practice. +.SS "\(hyD" +.P +Historically, the +\(hyD +command erased the prompt, providing the user with an unbroken +presentation of lines from the edit buffer. This is not required by +POSIX.1\(hy2008; implementations are encouraged to provide it if possible. +Historically, the +\(hyD +command took, and then ignored, a +.IR count . +POSIX.1\(hy2008 does not permit this behavior. +.SS "Write Line Number" +.P +Historically, the +.IR ex +.BR = +command, when executed in +.IR ex +mode in an empty edit buffer, reported 0, and from open or visual mode, +reported 1. For consistency and simplicity of specification, POSIX.1\(hy2008 does +not permit this behavior. +.SS "Execute" +.P +Historically, +.IR ex +did not correctly handle the inclusion of text input commands (that is, +.BR append , +.BR insert , +and +.BR change ) +in executed buffers. POSIX.1\(hy2008 does not permit this exclusion for +consistency. +.P +Historically, the logical contents of the buffer being executed did not +change if the buffer itself were modified by the commands being +executed; that is, buffer execution did not support self-modifying +code. POSIX.1\(hy2008 requires conformance to historical practice. +.P +Historically, the +.BR @ +command took a range of lines, and the +.BR @ +buffer was executed once per line, with the current line (\c +.BR '.' ) +set to each specified line. POSIX.1\(hy2008 requires conformance to historical +practice. +.P +Some historical implementations did not notice if errors occurred +during buffer execution. This, coupled with the ability to specify a +range of lines for the +.IR ex +.BR @ +command, makes it trivial to cause them to drop +.BR core . +POSIX.1\(hy2008 requires that implementations stop buffer execution if any error +occurs, if the specified line doesn't exist, or if the contents of the +edit buffer itself are replaced (for example, the buffer executes the +.IR ex +.BR :edit +command). +.SS "Regular Expressions in ex" +.P +Historical practice is that the characters in the replacement part of +the last +.BR s +command\(emthat is, those matched by entering a +.BR '~' +in the regular expression\(emwere not further expanded by the regular +expression engine. So, if the characters contained the string +.BR \(dqa.,\(dq +they would match +.BR 'a' +followed by +.BR \(dq.,\(dq +and not +.BR 'a' +followed by any character. POSIX.1\(hy2008 requires conformance to historical +practice. +.SS "Edit Options in ex" +.P +The following paragraphs describe the historical behavior of some edit +options that were not, for whatever reason, included in POSIX.1\(hy2008. +Implementations are strongly encouraged to only use these names if the +functionality described here is fully supported. +.IP "\fBextended\fP" 10 +The +.BR extended +edit option has been used in some implementations of +.IR vi +to provide extended regular expressions instead of basic regular +expressions This option was omitted from POSIX.1\(hy2008 because it is not +widespread historical practice. +.IP "\fBflash\fP" 10 +The +.BR flash +edit option historically caused the screen to flash instead of beeping +on error. This option was omitted from POSIX.1\(hy2008 because it is not found in +some historical implementations. +.IP "\fBhardtabs\fP" 10 +The +.BR hardtabs +edit option historically defined the number of columns between hardware +tab settings. This option was omitted from POSIX.1\(hy2008 because it was +believed to no longer be generally useful. +.IP "\fBmodeline\fP" 10 +The +.BR modeline +(sometimes named +.BR modelines ) +edit option historically caused +.IR ex +or +.IR vi +to read the five first and last lines of the file for editor commands. +This option is a security problem, and vendors are strongly encouraged +to delete it from historical implementations. +.IP "\fBopen\fP" 10 +The +.BR open +edit option historically disallowed the +.IR ex +.BR open +and +.BR visual +commands. This edit option was omitted because these commands are +required by POSIX.1\(hy2008. +.IP "\fBoptimize\fP" 10 +The +.BR optimize +edit option historically expedited text throughput by setting the +terminal to not do automatic + +characters when printing more than one logical line of output. This +option was omitted from POSIX.1\(hy2008 because it was intended for terminals +without addressable cursors, which are rarely, if ever, still used. +.IP "\fBruler\fP" 10 +The +.BR ruler +edit option has been used in some implementations of +.IR vi +to present a current row/column ruler for the user. This option was +omitted from POSIX.1\(hy2008 because it is not widespread historical practice. +.IP "\fBsourceany\fP" 10 +The +.BR sourceany +edit option historically caused +.IR ex +or +.IR vi +to source start-up files that were owned by users other than the user +running the editor. This option is a security problem, and vendors are +strongly encouraged to remove it from their implementations. +.IP "\fBtimeout\fP" 10 +The +.BR timeout +edit option historically enabled the (now standard) feature of only +waiting for a short period before returning keys that could be part of +a macro. This feature was omitted from POSIX.1\(hy2008 because its behavior is +now standard, it is not widely useful, and it was rarely documented. +.IP "\fBverbose\fP" 10 +The +.BR verbose +edit option has been used in some implementations of +.IR vi +to cause +.IR vi +to output error messages for common errors; for example, attempting to +move the cursor past the beginning or end of the line instead of only +alerting the screen. (The historical +.IR vi +only alerted the terminal and presented no message for such errors. The +historical editor option +.BR terse +did not select when to present error messages, it only made existing +error messages more or less verbose.) This option was omitted from +POSIX.1\(hy2008 because it is not widespread historical practice; however, +implementors are encouraged to use it if they wish to provide error +messages for naive users. +.IP "\fBwraplen\fP" 10 +The +.BR wraplen +edit option has been used in some implementations of +.IR vi +to specify an automatic margin measured from the left margin instead of +from the right margin. This is useful when multiple screen sizes are +being used to edit a single file. This option was omitted from POSIX.1\(hy2008 +because it is not widespread historical practice; however, implementors +are encouraged to use it if they add this functionality. +.SS "autoindent, ai" +.P +Historically, the command +.BR 0a +did not do any autoindentation, regardless of the current indentation +of line 1. POSIX.1\(hy2008 requires that any indentation present in line 1 be +used. +.SS "autoprint, ap" +.P +Historically, the +.BR autoprint +edit option was not completely consistent or based solely on +modifications to the edit buffer. Exceptions were the +.BR read +command (when reading from a file, but not from a filter), the +.BR append , +.BR change , +.BR insert , +.BR global , +and +.BR v +commands, all of which were not affected by +.BR autoprint , +and the +.BR tag +command, which was affected by +.BR autoprint . +POSIX.1\(hy2008 requires conformance to historical practice. +.P +Historically, the +.BR autoprint +option only applied to the last of multiple commands entered using + +delimiters; for example, +.BR delete + +was affected by +.BR autoprint , +but +.BR delete|version + +was not. POSIX.1\(hy2008 requires conformance to historical practice. +.SS "autowrite, aw" +.P +Appending the +.BR '!' +character to the +.IR ex +.BR next +command to avoid performing an automatic write was not supported in +historical implementations. POSIX.1\(hy2008 requires that the behavior match the +other +.IR ex +commands for consistency. +.SS "ignorecase, ic" +.P +Historical implementations of case-insensitive matching (the +.BR ignorecase +edit option) lead to counter-intuitive situations when uppercase +characters were used in range expressions. Historically, the process +was as follows: +.IP " 1." 4 +Take a line of text from the edit buffer. +.IP " 2." 4 +Convert uppercase to lowercase in text line. +.IP " 3." 4 +Convert uppercase to lowercase in regular expressions, except in +character class specifications. +.IP " 4." 4 +Match regular expressions against text. +.P +This would mean that, with +.BR ignorecase +in effect, the text: +.sp +.RS 4 +.nf +\fB +The cat sat on the mat +.fi \fR +.P +.RE +.P +would be matched by +.sp +.RS 4 +.nf +\fB +/^the/ +.fi \fR +.P +.RE +.P +but not by: +.sp +.RS 4 +.nf +\fB +/^[A\(miZ]he/ +.fi \fR +.P +.RE +.P +For consistency with other commands implementing regular expressions, +POSIX.1\(hy2008 does not permit this behavior. +.SS "paragraphs, para" +.P +The ISO\ POSIX\(hy2:\|1993 standard made the default +.BR paragraphs +and +.BR sections +edit options implementation-defined, arguing they were historically +oriented to the UNIX system +.IR troff +text formatter, and a ``portable user'' could use the +.BR { , +.BR } , +.BR [[ , +.BR ]] , +.BR ( , +and +.BR ) +commands in open or visual mode and have the cursor stop in unexpected +places. POSIX.1\(hy2008 specifies their values in the POSIX locale because the +unusual grouping (they only work when grouped into two characters at a +time) means that they cannot be used for general-purpose movement, +regardless. +.SS "readonly" +.P +Implementations are encouraged to provide the best possible information +to the user as to the read-only status of the file, with the exception +that they should not consider the current special privileges of the +process. This provides users with a safety net because they must force +the overwrite of read-only files, even when running with additional +privileges. +.P +The +.BR readonly +edit option specification largely conforms to historical practice. The +only difference is that historical implementations did not notice that +the user had set the +.BR readonly +edit option in cases where the file was already marked read-only for +some reason, and would therefore reinitialize the +.BR readonly +edit option the next time the contents of the edit buffer were +replaced. This behavior is disallowed by POSIX.1\(hy2008. +.SS "report" +.P +The requirement that lines copied to a buffer interact differently than +deleted lines is historical practice. For example, if the +.BR report +edit option is set to 3, deleting 3 lines will cause a report to be +written, but 4 lines must be copied before a report is written. +.P +The requirement that the +.IR ex +.BR global , +.BR v , +.BR open , +.BR undo , +and +.BR visual +commands present reports based on the total number of lines added or +deleted during the command execution, and that commands executed by the +.BR global +and +.BR v +commands not present reports, is historical practice. POSIX.1\(hy2008 extends +historical practice by requiring that buffer execution be treated +similarly. The reasons for this are two-fold. Historically, only the +report by the last command executed from the buffer would be seen by +the user, as each new report would overwrite the last. In addition, the +standard developers believed that buffer execution had more in common +with +.BR global +and +.BR v +commands than it did with other +.IR ex +commands, and should behave similarly, for consistency and simplicity +of specification. +.SS "showmatch, sm" +.P +The length of time the cursor spends on the matching character is +unspecified because the timing capabilities of systems are often +inexact and variable. The time should be long enough for the user to +notice, but not long enough for the user to become annoyed. Some +implementations of +.IR vi +have added a +.BR matchtime +option that permits users to set the number of 0,1 second intervals the +cursor pauses on the matching character. +.SS "showmode" +.P +The +.BR showmode +option has been used in some historical implementations of +.IR ex +and +.IR vi +to display the current editing mode when in open or visual mode. The +editing modes have generally included ``command'' and ``input'', and +sometimes other modes such as ``replace'' and ``change''. The string +was usually displayed on the bottom line of the screen at the far +right-hand corner. In addition, a preceding +.BR '*' +character often denoted whether the contents of the edit buffer had +been modified. The latter display has sometimes been part of the +.BR showmode +option, and sometimes based on another option. This option was not +available in the 4 BSD historical implementation of +.IR vi , +but was viewed as generally useful, particularly to novice users, and +is required by POSIX.1\(hy2008. +.P +The +.BR smd +shorthand for the +.BR showmode +option was not present in all historical implementations of the editor. +POSIX.1\(hy2008 requires it, for consistency. +.P +Not all historical implementations of the editor displayed a mode +string for command mode, differentiating command mode from text input +mode by the absence of a mode string. POSIX.1\(hy2008 permits this behavior for +consistency with historical practice, but implementations are +encouraged to provide a display string for both modes. +.SS "slowopen" +.P +Historically, the +.BR slowopen +option was automatically set if the terminal baud rate was less than +1\|200 baud, or if the baud rate was 1\|200 baud and the +.BR redraw +option was not set. The +.BR slowopen +option had two effects. First, when inserting characters in the middle +of a line, characters after the cursor would not be pushed ahead, but +would appear to be overwritten. Second, when creating a new line of +text, lines after the current line would not be scrolled down, but +would appear to be overwritten. In both cases, ending text input mode +would cause the screen to be refreshed to match the actual contents of +the edit buffer. Finally, terminals that were sufficiently intelligent +caused the editor to ignore the +.BR slowopen +option. POSIX.1\(hy2008 permits most historical behavior, extending historical +practice to require +.BR slowopen +behaviors if the edit option is set by the user. +.SS "tags" +.P +The default path for tags files is left unspecified as implementations +may have their own +.BR tags +implementations that do not correspond to the historical ones. The +default +.BR tags +option value should probably at least include the file +.BR ./tags . +.SS "term" +.P +Historical implementations of +.IR ex +and +.IR vi +ignored changes to the +.BR term +edit option after the initial terminal information was loaded. This is +permitted by POSIX.1\(hy2008; however, implementations are encouraged to permit +the user to modify their terminal type at any time. +.SS "terse" +.P +Historically, the +.BR terse +edit option optionally provided a shorter, less descriptive error +message, for some error messages. This is permitted, but not required, +by POSIX.1\(hy2008. Historically, most common visual mode errors (for example, +trying to move the cursor past the end of a line) did not result in an +error message, but simply alerted the terminal. Implementations wishing +to provide messages for novice users are urged to do so based on the +.BR edit +option +.BR verbose , +and not +.BR terse . +.SS "window" +.P +In historical implementations, the default for the +.BR window +edit option was based on the baud rate as follows: +.IP " 1." 4 +If the baud rate was less than 1\|200, the +.BR edit +option +.BR w300 +set the window value; for example, the line: +.RS 4 +.sp +.RS 4 +.nf +\fB +set w300=12 +.fi \fR +.P +.RE +.P +would set the window option to 12 if the baud rate was less than +1\|200. +.RE +.IP " 2." 4 +If the baud rate was equal to 1\|200, the +.BR edit +option +.BR w1200 +set the window value. +.IP " 3." 4 +If the baud rate was greater than 1\|200, the +.BR edit +option +.BR w9600 +set the window value. +.P +The +.BR w300 , +.BR w1200 , +and +.BR w9600 +options do not appear in POSIX.1\(hy2008 because of their dependence on specific +baud rates. +.P +In historical implementations, the size of the window displayed by +various commands was related to, but not necessarily the same as, the +.BR window +edit option. For example, the size of the window was set by the +.IR ex +command +.BR "visual 10" , +but it did not change the value of the +.BR window +edit option. However, changing the value of the +.BR window +edit option did change the number of lines that were displayed when the +screen was repainted. POSIX.1\(hy2008 does not permit this behavior in the +interests of consistency and simplicity of specification, and requires +that all commands that change the number of lines that are displayed do +it by setting the value of the +.BR window +edit option. +.SS "wrapmargin, wm" +.P +Historically, the +.BR wrapmargin +option did not affect maps inserting characters that also had +associated +.IR count s; +for example +.BR ":map\0K\05aABC\0DEF" . +Unfortunately, there are widely used maps that depend on this behavior. +For consistency and simplicity of specification, POSIX.1\(hy2008 does not permit +this behavior. +.P +Historically, +.BR wrapmargin +was calculated using the column display width of all characters on the +screen. For example, an implementation using +.BR \(dq^I\(dq +to represent + +characters when the +.BR list +edit option was set, where +.BR '^' +and +.BR 'I' +each took up a single column on the screen, would calculate the +.BR wrapmargin +based on a value of 2 for each +. +The +.BR number +edit option similarly changed the effective length of the line as well. +POSIX.1\(hy2008 requires conformance to historical practice. +.P +Earlier versions of this standard allowed for implementations +with bytes other than eight bits, but this has been modified in this +version. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.9.1.1" ", " "Command Search and Execution", +.IR "\fIctags\fR\^", +.IR "\fIed\fR\^", +.IR "\fIsed\fR\^", +.IR "\fIsh\fR\^", +.IR "\fIstty\fR\^", +.IR "\fIvi\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Table 5-1" ", " "Escape Sequences and Associated Actions", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 9.3" ", " "Basic Regular Expressions", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIaccess\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/exec.1p b/man-pages-posix-2013/man1p/exec.1p new file mode 100644 index 0000000..9b6c976 --- /dev/null +++ b/man-pages-posix-2013/man1p/exec.1p @@ -0,0 +1,184 @@ +'\" et +.TH EXEC "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +exec +\(em execute commands and open, close, or copy file descriptors +.SH SYNOPSIS +.LP +.nf +exec \fB[\fIcommand \fB[\fIargument\fR...\fB]]\fR +.fi +.SH DESCRIPTION +The +.IR exec +utility shall open, close, and/or copy file descriptors as specified by +any redirections as part of the command. +.P +If +.IR exec +is specified without +.IR command +or +.IR argument s, +and any file descriptors with numbers greater than 2 are opened with +associated redirection statements, it is unspecified whether those file +descriptors remain open when the shell invokes another utility. +Scripts concerned that child shells could misuse open file descriptors +can always close them explicitly, as shown in one of the following +examples. +.P +If +.IR exec +is specified with +.IR command , +it shall replace the shell with +.IR command +without creating a new process. If +.IR argument s +are specified, they shall be arguments to +.IR command . +Redirection affects the current shell execution environment. +.SH OPTIONS +None. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +If +.IR command +is specified, +.IR exec +shall not return to the shell; rather, the exit status of the process +shall be the exit status of the program implementing +.IR command , +which overlaid the shell. If +.IR command +is not found, the exit status shall be 127. If +.IR command +is found, but it is not an executable utility, the exit status shall be +126. If a redirection error occurs (see +.IR "Section 2.8.1" ", " "Consequences of Shell Errors"), +the shell shall exit with a value in the range 1\(mi125. Otherwise, +.IR exec +shall return a zero exit status. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +Open +.IR readfile +as file descriptor 3 for reading: +.sp +.RS 4 +.nf +\fB +exec 3< readfile +.fi \fR +.P +.RE +.P +Open +.IR writefile +as file descriptor 4 for writing: +.sp +.RS 4 +.nf +\fB +exec 4> writefile +.fi \fR +.P +.RE +.P +Make file descriptor 5 a copy of file descriptor 0: +.sp +.RS 4 +.nf +\fB +exec 5<&0 +.fi \fR +.P +.RE +.P +Close file descriptor 3: +.sp +.RS 4 +.nf +\fB +exec 3<&\(mi +.fi \fR +.P +.RE +.P +Cat the file +.BR maggie +by replacing the current shell with the +.IR cat +utility: +.sp +.RS 4 +.nf +\fB +exec cat maggie +.fi \fR +.P +.RE +.SH "RATIONALE" +Most historical implementations were not conformant in that: +.sp +.RS 4 +.nf +\fB +foo=bar exec cmd +.fi \fR +.P +.RE +.P +did not pass +.BR foo +to +.BR cmd . +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/exit.1p b/man-pages-posix-2013/man1p/exit.1p new file mode 100644 index 0000000..28ebb68 --- /dev/null +++ b/man-pages-posix-2013/man1p/exit.1p @@ -0,0 +1,129 @@ +'\" et +.TH EXIT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 cause the shell to exit +.SH SYNOPSIS +.LP +.nf +exit \fB[\fIn\fB]\fR +.fi +.SH DESCRIPTION +The +.IR exit +utility shall cause the shell to exit with the exit status specified +by the unsigned decimal integer +.IR n . +If +.IR n +is specified, but its value is not between 0 and 255 inclusively, the +exit status is undefined. +.P +A +.IR trap +on +.BR EXIT +shall be executed before the shell terminates, except when the +.IR exit +utility is invoked in that +.IR trap +itself, in which case the shell shall exit immediately. +.SH OPTIONS +None. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The exit status shall be +.IR n , +if specified. Otherwise, the value shall be the exit value of the last +command executed, or zero if no command was executed. When +.IR exit +is executed in a +.IR trap +action, the last command is considered to be the command that executed +immediately preceding the +.IR trap +action. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +Exit with a +.IR true +value: +.sp +.RS 4 +.nf +\fB +exit 0 +.fi \fR +.P +.RE +.P +Exit with a +.IR false +value: +.sp +.RS 4 +.nf +\fB +exit 1 +.fi \fR +.P +.RE +.SH "RATIONALE" +As explained in other sections, certain exit status values have been +reserved for special uses and should be used by applications only for +those purposes: +.IP "\0126" 8 +A file to be executed was found, but it was not an executable utility. +.IP "\0127" 8 +A utility to be executed was not found. +.IP >128 8 +A command was interrupted by a signal. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/expand.1p b/man-pages-posix-2013/man1p/expand.1p new file mode 100644 index 0000000..6b4e2aa --- /dev/null +++ b/man-pages-posix-2013/man1p/expand.1p @@ -0,0 +1,205 @@ +'\" et +.TH EXPAND "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +expand +\(em convert tabs to spaces +.SH SYNOPSIS +.LP +.nf +expand \fB[\fR\(mit \fItablist\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR expand +utility shall write files or the standard input to the standard output +with + +characters replaced with one or more + +characters needed to pad to the next tab stop. Any + +characters shall be copied to the output and cause the column position +count for tab stop calculations to be decremented; the column position +count shall not be decremented below zero. +.SH OPTIONS +The +.IR expand +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(mit\ \fItablist\fR" 10 +Specify the tab stops. The application shall ensure that the argument +.IR tablist +consists of either a single positive decimal integer or a list of +tabstops. If a single number is given, tabs shall be set that number of +column positions apart instead of the default 8. +.RS 10 +.P +If a list of tabstops is given, the application shall ensure that it +consists of a list of two or more positive decimal integers, separated +by + +or + +characters, in ascending order. The + +characters shall be set at those specific column positions. Each tab stop +.IR N +shall be an integer value greater than zero, and the list is in +strictly ascending order. This is taken to mean that, from the start of +a line of output, tabbing to position +.IR N +shall cause the next character output to be in the (\c +.IR N +1)th +column position on that line. +.P +In the event of +.IR expand +having to process a + +at a position beyond the last of those specified in a multiple tab-stop +list, the + +shall be replaced by a single + +in the output. +.RE +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +The pathname of a text file to be used as input. +.SH STDIN +See the INPUT FILES section. +.SH "INPUT FILES" +Input files shall be text files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR expand : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files), the processing of + +and + +characters, and for the determination of the width in column positions +each character would occupy on an output device. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall be equivalent to the input files with + +characters converted into the appropriate number of + +characters. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +The +.IR expand +utility shall terminate with an error message and non-zero exit status +upon encountering difficulties accessing one of the +.IR file +operands. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR expand +utility is useful for preprocessing text files (before sorting, looking +at specific columns, and so on) that contain + +characters. +.P +See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.103" ", " "Column Position". +.P +The +.IR tablist +option-argument consists of integers in ascending order. Utility Syntax +Guideline 8 mandates that +.IR expand +shall accept the integers (within the single argument) separated using +either + +or + +characters. +.P +Earlier versions of this standard allowed the following form in +the SYNOPSIS: +.sp +.RS 4 +.nf +\fB +expand \fB[\fR\(mitabstop\fB][\fR\(mitab1,tab2,...,tabn\fB][\fIfile\fR ...\fB]\fR +.fi \fR +.P +.RE +.P +This form is no longer specified by POSIX.1\(hy2008 but may be present +in some implementations. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fItabs\fR\^", +.IR "\fIunexpand\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.103" ", " "Column Position", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/export.1p b/man-pages-posix-2013/man1p/export.1p new file mode 100644 index 0000000..d9b6094 --- /dev/null +++ b/man-pages-posix-2013/man1p/export.1p @@ -0,0 +1,191 @@ +'\" et +.TH EXPORT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +export +\(em set the export attribute for variables +.SH SYNOPSIS +.LP +.nf +export name\fB[\fR=\fIword\fB]\fR... +.P +export\fR \(mip +.fi +.SH DESCRIPTION +The shell shall give the +.IR export +attribute to the variables corresponding to the specified +.IR name s, +which shall cause them to be in the environment of subsequently +executed commands. If the name of a variable is followed by =\c +.IR word , +then the value of that variable shall be set to +.IR word . +.P +The +.IR export +special built-in shall support the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +When +.BR \(mip +is specified, +.IR export +shall write to the standard output the names and values of all exported +variables, in the following format: +.sp +.RS 4 +.nf +\fB +"export %s=%s\en", <\fIname\fR>, <\fIvalue\fR> +.fi \fR +.P +.RE +.P +if +.IR name +is set, and: +.sp +.RS 4 +.nf +\fB +"export %s\en", <\fIname\fR> +.fi \fR +.P +.RE +.P +if +.IR name +is unset. +.P +The shell shall format the output, including the proper use of quoting, +so that it is suitable for reinput to the shell as commands that +achieve the same exporting results, except: +.IP " 1." 4 +Read-only variables with values cannot be reset. +.IP " 2." 4 +Variables that were unset at the time they were output need not be +reset to the unset state if a value is assigned to the variable between +the time the state was saved and the time at which the saved output is +reinput to the shell. +.P +When no arguments are given, the results are unspecified. If a variable +assignment precedes the command name of +.IR export +but that variable is not also listed as an operand of +.IR export , +then that variable shall be set in the current shell execution environment +after the completion of the +.IR export +command, but it is unspecified whether that variable is marked for export. +.SH OPTIONS +See the DESCRIPTION. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +See the DESCRIPTION. +.SH STDERR S +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +Zero. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +Export +.IR PWD +and +.IR HOME +variables: +.sp +.RS 4 +.nf +\fB +export PWD HOME +.fi \fR +.P +.RE +.P +Set and export the +.IR PATH +variable: +.sp +.RS 4 +.nf +\fB +export PATH=/local/bin:$PATH +.fi \fR +.P +.RE +.P +Save and restore all exported variables: +.sp +.RS 4 +.nf +\fB +export \(mip > \fItemp-file\fR +unset \fIa lot of variables\fR +\&... \fIprocessing\fR +\&. \fItemp-file\fR +.fi \fR +.P +.RE +.SH "RATIONALE" +Some historical shells use the no-argument case as the functional +equivalent of what is required here with +.BR \(mip . +This feature was left unspecified because it is not historical practice +in all shells, and some scripts may rely on the now-unspecified results +on their implementations. Attempts to specify the +.BR \(mip +output as the default case were unsuccessful in achieving consensus. +The +.BR \(mip +option was added to allow portable access to the values that can be +saved and then later restored using; for example, a +.IR dot +script. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/expr.1p b/man-pages-posix-2013/man1p/expr.1p new file mode 100644 index 0000000..a0be688 --- /dev/null +++ b/man-pages-posix-2013/man1p/expr.1p @@ -0,0 +1,440 @@ +'\" et +.TH EXPR "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +expr +\(em evaluate arguments as an expression +.SH SYNOPSIS +.LP +.nf +expr \fIoperand\fR... +.fi +.SH DESCRIPTION +The +.IR expr +utility shall evaluate an expression and write the result to standard +output. +.SH OPTIONS +None. +.SH OPERANDS +The single expression evaluated by +.IR expr +shall be formed from the +.IR operand +operands, as described in the EXTENDED DESCRIPTION section. The +application shall ensure that each of the expression operator symbols: +.sp +.RS 4 +.nf +\fB +( ) | & = > >= < <= != + \(mi * / % : +.fi \fR +.P +.RE +.P +and the symbols +.IR integer +and +.IR string +in the table are provided as separate arguments to +.IR expr . +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR expr : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular expressions and +by the string comparison operators. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments) and the behavior of character +classes within regular expressions. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR expr +utility shall evaluate the expression and write the result, followed by +a +, +to standard output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +The formation of the expression to be evaluated is shown in the +following table. The symbols +.IR expr , +.IR expr1 , +and +.IR expr2 +represent expressions formed from +.IR integer +and +.IR string +symbols and the expression operator symbols (all separate arguments) by +recursive application of the constructs described in the table. The +expressions are listed in order of increasing precedence, with +equal-precedence operators grouped between horizontal lines. All of +the operators shall be left-associative. +.TS +center tab(@) box; +cB | cB +l | lw(4i). +Expression@Description +_ +\fIexpr1\fP\ |\ \fIexpr2\fP@T{ +Returns the evaluation of +.IR expr1 +if it is neither null nor zero; otherwise, returns the evaluation of +.IR expr2 +if it is not null; otherwise, zero. +T} +_ +\fIexpr1\fP\ &\ \fIexpr2\fP@T{ +Returns the evaluation of +.IR expr1 +if neither expression evaluates to null or zero; otherwise, returns zero. +T} +_ +@T{ +Returns the result of a decimal integer comparison if both arguments +are integers; otherwise, returns the result of a string comparison +using the locale-specific collation sequence. The result of each +comparison is 1 if the specified relationship is true, or 0 if the +relationship is false. +T} +\fIexpr1\fP\ =\ \fIexpr2\fR@Equal. +\fIexpr1\fP\ >\ \fIexpr2\fR@Greater than. +\fIexpr1\fP\ >=\ \fIexpr2\fR@Greater than or equal. +\fIexpr1\fP\ <\ \fIexpr2\fR@Less than. +\fIexpr1\fP\ <=\ \fIexpr2\fR@Less than or equal. +\fIexpr1\fP\ !=\ \fIexpr2\fR@Not equal. +_ +\fIexpr1\fP\ +\ \fIexpr2\fP@T{ +Addition of decimal integer-valued arguments. +T} +\fIexpr1\fP\ \(mi\ \fIexpr2\fP@T{ +Subtraction of decimal integer-valued arguments. +T} +_ +\fIexpr1\fP\ *\ \fIexpr2\fP@T{ +Multiplication of decimal integer-valued arguments. +T} +\fIexpr1\fP\ /\ \fIexpr2\fP@T{ +Integer division of decimal integer-valued arguments, producing +an integer result. +T} +\fIexpr1\fP\ %\ \fIexpr2\fP@T{ +Remainder of integer division of decimal integer-valued arguments. +T} +_ +\fIexpr1\fP\ :\ \fIexpr2\fP@T{ +Matching expression; see below. +T} +_ +(\ \fIexpr\fR\ )@T{ +Grouping symbols. Any expression can be placed within parentheses. +Parentheses can be nested to a depth of +{EXPR_NEST_MAX}. +T} +_ +\fIinteger\fP@T{ +An argument consisting only of an (optional) unary minus followed +by digits. +T} +\fIstring\fP@T{ +A string argument; see below. +T} +.TE +.SS "Matching Expression" +.P +The +.BR ':' +matching operator shall compare the string resulting from the +evaluation of +.IR expr1 +with the regular expression pattern resulting from the evaluation of +.IR expr2 . +Regular expression syntax shall be that defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.3" ", " "Basic Regular Expressions", +except that all patterns are anchored to the beginning of the string (that +is, only sequences starting at the first character of a string are matched +by the regular expression) and, therefore, it is unspecified whether +.BR '^' +is a special character in that context. Usually, the matching operator +shall return a string representing the number of characters matched (\c +.BR '0' +on failure). Alternatively, if the pattern contains at least one +regular expression subexpression +.BR \(dq[\e(...\e)]\(dq , +the string matched by the back-reference expression +.BR \(dq\e1\(dq +shall be returned. If the back-reference expression +.BR \(dq\e1\(dq +does not match, then the null string shall be returned. +.SS "String Operand" +.P +A string argument is an argument that cannot be identified as an +.IR integer +argument or as one of the expression operator symbols shown in the +OPERANDS section. +.P +The use of string arguments +.BR length , +.BR substr , +.BR index , +or +.BR match +produces unspecified results. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The +.IR expression +evaluates to neither null nor zero. +.IP "\01" 6 +The +.IR expression +evaluates to null or zero. +.IP "\02" 6 +Invalid +.IR expression . +.IP >2 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +After argument processing by the shell, +.IR expr +is not required to be able to tell the difference between an operator +and an operand except by the value. If +.BR \(dq$a\(dq +is +.BR '=' , +the command: +.sp +.RS 4 +.nf +\fB +expr $a = '=' +.fi \fR +.P +.RE +.P +looks like: +.sp +.RS 4 +.nf +\fB +expr = = = +.fi \fR +.P +.RE +.P +as the arguments are passed to +.IR expr +(and they all may be taken as the +.BR '=' +operator). The following works reliably: +.sp +.RS 4 +.nf +\fB +expr X$a = X= +.fi \fR +.P +.RE +.P +Also note that this volume of POSIX.1\(hy2008 permits implementations to extend utilities. The +.IR expr +utility permits the integer arguments to be preceded with a unary +minus. This means that an integer argument could look like an option. +Therefore, the conforming application must employ the +.BR \(dq\(mi\|\(mi\(dq +construct of Guideline 10 of the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +to protect its operands if there is any chance the first operand might +be a negative integer (or any string with a leading minus). +.br +.SH EXAMPLES +The +.IR expr +utility has a rather difficult syntax: +.IP " *" 4 +Many of the operators are also shell control operators or reserved +words, so they have to be escaped on the command line. +.IP " *" 4 +Each part of the expression is composed of separate arguments, so +liberal usage of + +characters is required. For example: +.TS +center tab(@) box; +cB | cB +lf5 | lf5. +Invalid@Valid +_ +\fIexpr\fP 1+2@\fIexpr\fP 1 + 2 +\fIexpr\fP "1 + 2"@\fIexpr\fP 1 + 2 +\fIexpr\fP 1 + (2 * 3)@\fIexpr\fP 1 + \e( 2 \e* 3 \e) +.TE +.P +In many cases, the arithmetic and string features provided as part of +the shell command language are easier to use than their equivalents in +.IR expr . +Newly written scripts should avoid +.IR expr +in favor of the new features within the shell; see +.IR "Section 2.5" ", " "Parameters and Variables" +and +.IR "Section 2.6.4" ", " "Arithmetic Expansion". +.P +The following command: +.sp +.RS 4 +.nf +\fB +a=$(expr $a + 1) +.fi \fR +.P +.RE +.P +adds 1 to the variable +.IR a . +.P +The following command, for +.BR \(dq$a\(dq +equal to either +.BR /usr/abc/file +or just +.BR file : +.sp +.RS 4 +.nf +\fB +expr $a : '.*/\e(.*\e)' \e| $a +.fi \fR +.P +.RE +.P +returns the last segment of a pathname (that is, +.BR file ). +Applications should avoid the character +.BR '/' +used alone as an argument; +.IR expr +may interpret it as the division operator. +.P +The following command: +.sp +.RS 4 +.nf +\fB +expr "//$a" : '.*/\e(.*\e)' +.fi \fR +.P +.RE +.P +is a better representation of the previous example. The addition of +the +.BR \(dq//\(dq +characters eliminates any ambiguity about the division operator and +simplifies the whole expression. Also note that pathnames may contain +characters contained in the +.IR IFS +variable and should be quoted to avoid having +.BR \(dq$a\(dq +expand into multiple arguments. +.P +The following command: +.sp +.RS 4 +.nf +\fB +expr "$VAR" : '.*' +.fi \fR +.P +.RE +.P +returns the number of characters in +.IR VAR . +.SH RATIONALE +In an early proposal, EREs were used in the matching expression syntax. +This was changed to BREs to avoid breaking historical applications. +.P +The use of a leading + +in the BRE is unspecified because many historical implementations have +treated it as a special character, despite their system documentation. For +example: +.sp +.RS 4 +.nf +\fB +expr foo : ^foo expr ^foo : ^foo +.fi \fR +.P +.RE +.P +return 3 and 0, respectively, on those systems; their documentation +would imply the reverse. Thus, the anchoring condition is left +unspecified to avoid breaking historical scripts relying on this +undocumented feature. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Parameters and Variables", +.IR "Section 2.6.4" ", " "Arithmetic Expansion" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 9.3" ", " "Basic Regular Expressions", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/false.1p b/man-pages-posix-2013/man1p/false.1p new file mode 100644 index 0000000..7fa2366 --- /dev/null +++ b/man-pages-posix-2013/man1p/false.1p @@ -0,0 +1,75 @@ +'\" et +.TH FALSE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +false +\(em return false value +.SH SYNOPSIS +.LP +.nf +false +.fi +.SH DESCRIPTION +The +.IR false +utility shall return with a non-zero exit code. +.SH OPTIONS +None. +.SH OPERANDS +None. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +Not used. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The +.IR false +utility shall always exit with a value other than zero. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fItrue\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/fc.1p b/man-pages-posix-2013/man1p/fc.1p new file mode 100644 index 0000000..f6e7463 --- /dev/null +++ b/man-pages-posix-2013/man1p/fc.1p @@ -0,0 +1,593 @@ +'\" et +.TH FC "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fc +\(em process the command history list +.SH SYNOPSIS +.LP +.nf +fc \fB[\fR\(mir\fB] [\fR\(mie \fIeditor\fB] [\fIfirst \fB[\fIlast\fB]]\fR +.P +fc \(mil\fB [\fR\(minr\fB] [\fIfirst \fB[\fIlast\fB]]\fR +.P +fc \(mis\fB [\fIold\fR=\fInew\fB] [\fIfirst\fB]\fR +.fi +.SH DESCRIPTION +The +.IR fc +utility shall list, or shall edit and re-execute, commands previously +entered to an interactive +.IR sh . +.P +The command history list shall reference commands by number. The first +number in the list is selected arbitrarily. The relationship of a +number to its command shall not change except when the user logs in and +no other process is accessing the list, at which time the system may +reset the numbering to start the oldest retained command at another +number (usually 1). When the number reaches an +implementation-defined upper limit, which shall be no smaller than +the value in +.IR HISTSIZE +or 32\|767 (whichever is greater), the shell may wrap the numbers, +starting the next command with a lower number (usually 1). However, +despite this optional wrapping of numbers, +.IR fc +shall maintain the time-ordering sequence of the commands. For +example, if four commands in sequence are given the numbers 32\|766, +32\|767, 1 (wrapped), and 2 as they are executed, command 32\|767 is +considered the command previous to 1, even though its number is +higher. +.P +When commands are edited (when the +.BR \(mil +option is not specified), the resulting lines shall be entered at the +end of the history list and then re-executed by +.IR sh . +The +.IR fc +command that caused the editing shall not be entered into the history +list. If the editor returns a non-zero exit status, this shall +suppress the entry into the history list and the command re-execution. +Any command line variable assignments or redirection operators used +with +.IR fc +shall affect both the +.IR fc +command itself as well as the command that results; for example: +.sp +.RS 4 +.nf +\fB +fc \(mis \(mi\|\(mi \(mi1 2>/dev/null +.fi \fR +.P +.RE +.P +reinvokes the previous command, suppressing standard error for both +.IR fc +and the previous command. +.SH OPTIONS +The +.IR fc +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mie\ \fIeditor\fR" 10 +Use the editor named by +.IR editor +to edit the commands. The +.IR editor +string is a utility name, subject to search via the +.IR PATH +variable (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables"). +The value in the +.IR FCEDIT +variable shall be used as a default when +.BR \(mie +is not specified. If +.IR FCEDIT +is null or unset, +.IR ed +shall be used as the editor. +.IP "\fB\(mil\fP" 10 +(The letter ell.) List the commands rather than invoking an editor on +them. The commands shall be written in the sequence indicated by the +.IR first +and +.IR last +operands, as affected by +.BR \(mir , +with each command preceded by the command number. +.IP "\fB\(min\fP" 10 +Suppress command numbers when listing with +.BR \(mil . +.IP "\fB\(mir\fP" 10 +Reverse the order of the commands listed (with +.BR \(mil ) +or edited (with neither +.BR \(mil +nor +.BR \(mis ). +.IP "\fB\(mis\fP" 10 +Re-execute the command without invoking an editor. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfirst\fR,\ \fIlast\fR" 10 +Select the commands to list or edit. The number of previous commands +that can be accessed shall be determined by the value of the +.IR HISTSIZE +variable. The value of +.IR first +or +.IR last +or both shall be one of the following: +.RS 10 +.IP "\fB[+]\fInumber\fR" 10 +A positive number representing a command number; command numbers can be +displayed with the +.BR \(mil +option. +.IP "\fB\(mi\fInumber\fR" 10 +A negative decimal number representing the command that was executed +.IR number +of commands previously. For example, \(mi1 is the immediately previous +command. +.IP "\fIstring\fR" 10 +A string indicating the most recently entered command that begins with +that string. If the +.IR old =\c +.IR new +operand is not also specified with +.BR \(mis , +the string form of the +.IR first +operand cannot contain an embedded +. +.P +When the synopsis form with +.BR \(mis +is used: +.IP " *" 4 +If +.IR first +is omitted, the previous command shall be used. +.P +For the synopsis forms without +.BR \(mis : +.IP " *" 4 +If +.IR last +is omitted, +.IR last +shall default to the previous command when +.BR \(mil +is specified; otherwise, it shall default to +.IR first . +.IP " *" 4 +If +.IR first +and +.IR last +are both omitted, the previous 16 commands shall be listed or the +previous single command shall be edited (based on the +.BR \(mil +option). +.IP " *" 4 +If +.IR first +and +.IR last +are both present, all of the commands from +.IR first +to +.IR last +shall be edited (without +.BR \(mil ) +or listed (with +.BR \(mil ). +Editing multiple commands shall be accomplished by presenting to the +editor all of the commands at one time, each command starting on a new +line. If +.IR first +represents a newer command than +.IR last , +the commands shall be listed or edited in reverse sequence, equivalent +to using +.BR \(mir . +For example, the following commands on the first line are equivalent to +the corresponding commands on the second: +.RS 4 +.sp +.RS 4 +.nf +\fB +fc \(mir 10 20 fc 30 40 +fc 20 10 fc \(mir 40 30 +.fi \fR +.P +.RE +.RE +.IP " *" 4 +When a range of commands is used, it shall not be an error to specify +.IR first +or +.IR last +values that are not in the history list; +.IR fc +shall substitute the value representing the oldest or newest command in +the list, as appropriate. For example, if there are only ten commands +in the history list, numbered 1 to 10: +.RS 4 +.sp +.RS 4 +.nf +\fB +fc \(mil +fc 1 99 +.fi \fR +.P +.RE +.P +shall list and edit, respectively, all ten commands. +.RE +.RE +.IP "\fIold\fP=\fInew\fR" 10 +Replace the first occurrence of string +.IR old +in the commands to be re-executed by the string +.IR new . +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR fc : +.IP "\fIFCEDIT\fP" 10 +This variable, when expanded by the shell, shall determine the default +value for the +.BR \(mie +.IR editor +option's +.IR editor +option-argument. If +.IR FCEDIT +is null or unset, +.IR ed +shall be used as the editor. +.IP "\fIHISTFILE\fP" 10 +Determine a pathname naming a command history file. If the +.IR HISTFILE +variable is not set, the shell may attempt to access or create a file +.BR .sh_history +in the directory referred to by the +.IR HOME +environment variable. If the shell cannot obtain both read and write +access to, or create, the history file, it shall use an unspecified +mechanism that allows the history to operate properly. (References to +history ``file'' in this section shall be understood to mean this +unspecified mechanism in such cases.) An implementation may choose to +access this variable only when initializing the history file; this +initialization shall occur when +.IR fc +or +.IR sh +first attempt to retrieve entries from, or add entries to, the file, as +the result of commands issued by the user, the file named by the +.IR ENV +variable, or implementation-defined system start-up files. In some +historical shells, the history file is initialized just after the +.IR ENV +file has been processed. Therefore, it is implementation-defined +whether changes made to +.IR HISTFILE +after the history file has been initialized are effective. +Implementations may choose to disable the history list mechanism for +users with appropriate privileges who do not set +.IR HISTFILE ; +the specific circumstances under which this occurs are +implementation-defined. If more than one instance of the shell is +using the same history file, it is unspecified how updates to the +history file from those shells interact. As entries are deleted from +the history file, they shall be deleted oldest first. It is +unspecified when history file entries are physically removed from the +history file. +.IP "\fIHISTSIZE\fP" 10 +Determine a decimal number representing the limit to the number of +previous commands that are accessible. If this variable is unset, an +unspecified default greater than or equal to 128 shall be used. The +maximum number of commands in the history list is unspecified, but +shall be at least 128. An implementation may choose to access this +variable only when initializing the history file, as described under +.IR HISTFILE . +Therefore, it is unspecified whether changes made to +.IR HISTSIZE +after the history file has been initialized are effective. +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +When the +.BR \(mil +option is used to list commands, the format of each command in the list +shall be as follows: +.sp +.RS 4 +.nf +\fB +"%d\et%s\en", <\fIline number\fR>, <\fIcommand\fR> +.fi \fR +.P +.RE +.P +If both the +.BR \(mil +and +.BR \(min +options are specified, the format of each command shall be: +.sp +.RS 4 +.nf +\fB +"\et%s\en", <\fIcommand\fR> +.fi \fR +.P +.RE +.P +If the <\fIcommand\fP> consists of more than one line, the lines after +the first shall be displayed as: +.sp +.RS 4 +.nf +\fB +"\et%s\en", <\fIcontinued-command\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion of the listing. +.IP >0 6 +An error occurred. +.P +Otherwise, the exit status shall be that of the commands executed by +.IR fc . +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Since editors sometimes use file descriptors as integral parts of their +editing, redirecting their file descriptors as part of the +.IR fc +command can produce unexpected results. For example, if +.IR vi +is the +.IR FCEDIT +editor, the command: +.sp +.RS 4 +.nf +\fB +fc \(mis | more +.fi \fR +.P +.RE +.P +does not work correctly on many systems. +.P +Users on windowing systems may want to have separate history files for +each window by setting +.IR HISTFILE +as follows: +.sp +.RS 4 +.nf +\fB +HISTFILE=$HOME/.sh_hist$$ +.fi \fR +.P +.RE +.SH "EXAMPLES" +None. +.SH RATIONALE +This utility is based on the +.IR fc +built-in of the KornShell. +.P +An early proposal specified the +.BR \(mie +option as +.BR [\(mie +.IR editor +.BR [ \c +.IR old \c += +.IR new +.BR ]\|] , +which is not historical practice. Historical practice in +.IR fc +of either +.BR [\(mie +.IR editor \c +.BR ] +or +.BR "[\(mie \(mi [" +.IR old \c += +.IR new +.BR ]\|] +is acceptable, but not both together. To clarify this, a new option +.BR \(mis +was introduced replacing the +.BR "[\(mie \(mi]" . +This resolves the conflict and makes +.IR fc +conform to the Utility Syntax Guidelines. +.IP "\fIHISTFILE\fP" 10 +Some implementations of the KornShell check for the superuser +and do not create a history file unless +.IR HISTFILE +is set. This is done primarily to avoid creating unlinked files in the +root file system when logging in during single-user mode. +.IR HISTFILE +must be set for the superuser to have history. +.IP "\fIHISTSIZE\fP" 10 +Needed to limit the size of history files. It is the intent of the +standard developers that when two shells share the same history file, +commands that are entered in one shell shall be accessible by the other +shell. Because of the difficulties of synchronization over a network, +the exact nature of the interaction is unspecified. +.P +The initialization process for the history file can be dependent on the +system start-up files, in that they may contain commands that +effectively preempt the settings the user has for +.IR HISTFILE +and +.IR HISTSIZE . +For example, function definition commands are recorded in the history +file. If the system administrator includes function definitions in some +system start-up file called before the +.IR ENV +file, the history file is initialized before the user can influence its +characteristics. In some historical shells, the history file is +initialized just after the +.IR ENV +file has been processed. Because of these situations, the text requires +the initialization process to be implementation-defined. +.P +Consideration was given to omitting the +.IR fc +utility in favor of the command line editing feature in +.IR sh . +For example, in +.IR vi +editing mode, typing +.BR \(dq v\(dq +is equivalent to: +.sp +.RS 4 +.nf +\fB +EDITOR=vi fc +.fi \fR +.P +.RE +.P +However, the +.IR fc +utility allows the user the flexibility to edit multiple commands +simultaneously (such as +.IR fc +10 20) and to use editors other than those supported by +.IR sh +for command line editing. +.P +In the KornShell, the alias +.BR r +(``re-do'') is preset to +.IR fc +.BR "\(mie \(mi" +(equivalent to the POSIX +.IR fc +.BR \(mis ). +This is probably an easier command name to remember than +.IR fc +(``fix command''), but it does not meet the Utility Syntax Guidelines. +Renaming +.IR fc +to +.IR hist +or +.IR redo +was considered, but since this description closely matches historical +KornShell practice already, such a renaming was seen as gratuitous. +Users are free to create aliases whenever odd historical names such as +.IR fc , +.IR awk , +.IR cat , +.IR grep , +or +.IR yacc +are standardized by POSIX. +.P +Command numbers have no ordering effects; they are like serial numbers. +The +.BR \(mir +option and \(mi\fInumber\fP operand address the sequence of command +execution, regardless of serial numbers. So, for example, if the +command number wrapped back to 1 at some arbitrary point, there would +be no ambiguity associated with traversing the wrap point. For example, +if the command history were: +.sp +.RS 4 +.nf +\fB +32766: echo 1 +32767: echo 2 +1: echo 3 +.fi \fR +.P +.RE +.P +the number \(mi2 refers to command 32\|767 because it is the second +previous command, regardless of serial number. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsh\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/fg.1p b/man-pages-posix-2013/man1p/fg.1p new file mode 100644 index 0000000..ba1802c --- /dev/null +++ b/man-pages-posix-2013/man1p/fg.1p @@ -0,0 +1,162 @@ +'\" et +.TH FG "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fg +\(em run jobs in the foreground +.SH SYNOPSIS +.LP +.nf +fg \fB[\fIjob_id\fB]\fR +.fi +.SH DESCRIPTION +If job control is enabled (see the description of +.IR set +.BR \(mim ), +the +.IR fg +utility shall move a background job from the current environment (see +.IR "Section 2.12" ", " "Shell Execution Environment") +into the foreground. +.P +Using +.IR fg +to place a job into the foreground shall remove its process ID from the +list of those ``known in the current shell execution environment''; see +.IR "Section 2.9.3.1" ", " "Examples". +.SH OPTIONS +None. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIjob_id\fR" 10 +Specify the job to be run as a foreground job. If no +.IR job_id +operand is given, the +.IR job_id +for the job that was most recently suspended, placed in the background, +or run as a background job shall be used. The format of +.IR job_id +is described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.204" ", " "Job Control Job ID". +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR fg : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR fg +utility shall write the command line of the job to standard output +in the following format: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIcommand\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If job control is disabled, the +.IR fg +utility shall exit with an error and no job shall be placed in the +foreground. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR fg +utility does not work as expected when it is operating in its own +utility execution environment because that environment has no +applicable jobs to manipulate. See the APPLICATION USAGE section for +.IR "\fIbg\fR\^". +For this reason, +.IR fg +is generally implemented as a shell regular built-in. +.SH EXAMPLES +None. +.SH RATIONALE +The extensions to the shell specified in this volume of POSIX.1\(hy2008 have mostly been based +on features provided by the KornShell. The job control features +provided by +.IR bg , +.IR fg , +and +.IR jobs +are also based on the KornShell. The standard developers examined the +characteristics of the C shell versions of these utilities and found +that differences exist. Despite widespread use of the C shell, the +KornShell versions were selected for this volume of POSIX.1\(hy2008 to maintain a degree of +uniformity with the rest of the KornShell features selected (such as +the very popular command line editing features). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.9.3.1" ", " "Examples", +.IR "Section 2.12" ", " "Shell Execution Environment", +.IR "\fIbg\fR\^", +.IR "\fIkill\fR\^", +.IR "\fIjobs\fR\^", +.IR "\fIwait\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.204" ", " "Job Control Job ID", +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/file.1p b/man-pages-posix-2013/man1p/file.1p new file mode 100644 index 0000000..3353707 --- /dev/null +++ b/man-pages-posix-2013/man1p/file.1p @@ -0,0 +1,829 @@ +'\" et +.TH FILE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +file +\(em determine file type +.SH SYNOPSIS +.LP +.nf +file \fB[\fR\(midh\fB] [\fR\(miM \fIfile\fB] [\fR\(mim \fIfile\fB] \fIfile\fR... +.P +file \(mii \fB[\fR\(mih\fB] \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR file +utility shall perform a series of tests in sequence on each specified +.IR file +in an attempt to classify it: +.IP " 1." 4 +If +.IR file +does not exist, cannot be read, or its file status could not be +determined, the output shall indicate that the file was processed, but +that its type could not be determined. +.IP " 2." 4 +If the file is not a regular file, its file type shall be identified. +The file types directory, FIFO, socket, block special, and character +special shall be identified as such. Other implementation-defined file +types may also be identified. If +.IR file +is a symbolic link, by default the link shall be resolved and +.IR file +shall test the type of file referenced by the symbolic link. (See the +.BR \(mih +and +.BR \(mii +options below.) +.IP " 3." 4 +If the length of +.IR file +is zero, it shall be identified as an empty file. +.IP " 4." 4 +The +.IR file +utility shall examine an initial segment of +.IR file +and shall make a guess at identifying its contents based on +position-sensitive tests. (The answer is not guaranteed to be correct; +see the +.BR \(mid , +.BR \(miM , +and +.BR \(mim +options below.) +.IP " 5." 4 +The +.IR file +utility shall examine +.IR file +and make a guess at identifying its contents based on context-sensitive +default system tests. (The answer is not guaranteed to be correct.) +.IP " 6." 4 +The file shall be identified as a data file. +.P +If +.IR file +does not exist, cannot be read, or its file status could not be +determined, the output shall indicate that the file was processed, but +that its type could not be determined. +.P +If +.IR file +is a symbolic link, by default the link shall be resolved and +.IR file +shall test the type of file referenced by the symbolic link. +.SH OPTIONS +The +.IR file +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that the order of the +.BR \(mim , +.BR \(mid , +and +.BR \(miM +options shall be significant. +.P +The following options shall be supported by the implementation: +.IP "\fB\(mid\fP" 10 +Apply any position-sensitive default system tests and +context-sensitive default system tests to the file. This is the +default if no +.BR \(miM +or +.BR \(mim +option is specified. +.IP "\fB\(mih\fP" 10 +When a symbolic link is encountered, identify the file as a symbolic +link. If +.BR \(mih +is not specified and +.IR file +is a symbolic link that refers to a nonexistent file, +.IR file +shall identify the file as a symbolic link, as if +.BR \(mih +had been specified. +.IP "\fB\(mii\fP" 10 +If a file is a regular file, do not attempt to classify the type of the +file further, but identify the file as specified in the STDOUT section. +.IP "\fB\(miM\ \fIfile\fR" 10 +Specify the name of a file containing position-sensitive tests that +shall be applied to a file in order to classify it (see the EXTENDED +DESCRIPTION). No position-sensitive default system tests nor +context-sensitive default system tests shall be applied unless the +.BR \(mid +option is also specified. +.IP "\fB\(mim\ \fIfile\fR" 10 +Specify the name of a file containing position-sensitive tests that +shall be applied to a file in order to classify it (see the EXTENDED +DESCRIPTION). +.P +If the +.BR \(mim +option is specified without specifying the +.BR \(mid +option or the +.BR \(miM +option, position-sensitive default system tests shall be applied after +the position-sensitive tests specified by the +.BR \(mim +option. If the +.BR \(miM +option is specified with the +.BR \(mid +option, the +.BR \(mim +option, or both, or the +.BR \(mim +option is specified with the +.BR \(mid +option, the concatenation of the position-sensitive tests specified by +these options shall be applied in the order specified by the appearance +of these options. If a +.BR \(miM +or +.BR \(mim +.IR file +option-argument is +.BR \(mi , +the results are unspecified. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file to be tested. +.SH STDIN +The standard input shall be used if a +.IR file +operand is +.BR '\(mi' +and the implementation treats the +.BR '\(mi' +as meaning standard input. +Otherwise, the standard input shall not be used. +.SH "INPUT FILES" +The +.IR file +can be any file type. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR file : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +In the POSIX locale, the following format shall be used to identify +each operand, +.IR file +specified: +.sp +.RS 4 +.nf +\fB +"%s: %s\en", <\fIfile\fR>, <\fItype\fR> +.fi \fR +.P +.RE +.P +The values for <\fItype\fP> are unspecified, except that in the POSIX +locale, if +.IR file +is identified as one of the types listed in the following table, +<\fItype\fP> shall contain (but is not limited to) the corresponding +string, unless the file is identified by a position-sensitive test +specified by a +.BR \(miM +or +.BR \(mim +option. Each + +shown in the strings shall be exactly one +. +.br +.sp +.ce 1 +\fBTable 4-9: File Utility Output Strings\fR +.TS +center tab(@) box; +cB | cB | cB +l | l | l. +If \fIfile\fP is:@<\fItype\fP> shall contain the string:@Notes +_ +Nonexistent@cannot open +.P +Block special@block special@1 +Character special@character special@1 +Directory@directory@1 +FIFO@fifo@1 +Socket@socket@1 +Symbolic link@symbolic link to@1 +Regular file@regular file@1,2 +Empty regular file@empty@3 +Regular file that cannot be read@cannot open@3 +.P +Executable binary@executable@3,4,6 +\fIar\fR archive library (see \fIar\fP)@archive@3,4,6 +Extended \fIcpio\fP format (see \fIpax\fP)@cpio archive@3,4,6 +Extended \fItar\fP format (see \fBustar\fP in \fIpax\fP)@tar archive@3,4,6 +.P +Shell script@commands text@3,5,6 +C-language source@c program text@3,5,6 +FORTRAN source@fortran program text@3,5,6 +.P +Regular file whose type cannot be determined@data@3 +.TE +.TP 10 +.BR Notes: +.RS 10 +.IP " 1." 4 +This is a file type test. +.IP " 2." 4 +This test is applied only if the +.BR \(mii +option is specified. +.IP " 3." 4 +This test is applied only if the +.BR \(mii +option is not specified. +.IP " 4." 4 +This is a position-sensitive default system test. +.IP " 5." 4 +This is a context-sensitive default system test. +.IP " 6." 4 +Position-sensitive default system tests and context-sensitive +default system tests are not applied if the +.BR \(miM +option is specified unless the +.BR \(mid +option is also specified. +.RE +.P +.P +In the POSIX locale, if +.IR file +is identified as a symbolic link (see the +.BR \(mih +option), the following alternative output format shall be used: +.sp +.RS 4 +.nf +\fB +"%s: %s %s\en", <\fIfile\fR>, <\fItype\fR>, <\fIcontents of link\fR>" +.fi \fR +.P +.RE +.P +If the file named by the +.IR file +operand does not exist, cannot be read, or the type of the file named +by the +.IR file +operand cannot be determined, this shall not be considered an error +that affects the exit status. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +A file specified as an option-argument to the +.BR \(mim +or +.BR \(miM +options shall contain one position-sensitive test per line, which shall +be applied to the file. If the test succeeds, the message field of the +line shall be printed and no further tests shall be applied, with the +exception that tests on immediately following lines beginning with a +single +.BR '>' +character shall be applied. +.P +Each line shall be composed of the following four +-separated +fields. (Implementations may allow any combination of one or more +white-space characters other than + +to act as field separators.) +.IP "\fIoffset\fP" 10 +An unsigned number (optionally preceded by a single +.BR '>' +character) specifying the +.IR offset , +in bytes, of the value in the file that is to be compared against the +.IR value +field of the line. If the file is shorter than the specified offset, +the test shall fail. +.RS 10 +.P +If the +.IR offset +begins with the character +.BR '>' , +the test contained in the line shall not be applied to the file unless +the test on the last line for which the +.IR offset +did not begin with a +.BR '>' +was successful. By default, the +.IR offset +shall be interpreted as an unsigned decimal number. With a leading 0x +or 0X, the +.IR offset +shall be interpreted as a hexadecimal number; otherwise, with a leading +0, the +.IR offset +shall be interpreted as an octal number. +.RE +.IP "\fItype\fP" 10 +The type of the value in the file to be tested. The type shall consist +of the type specification characters +.BR d , +.BR s , +and +.BR u , +specifying signed decimal, string, and unsigned decimal, respectively. +.RS 10 +.P +The +.IR type +string shall be interpreted as the bytes from the file starting at the +specified +.IR offset +and including the same number of bytes specified by the +.IR value +field. If insufficient bytes remain in the file past the +.IR offset +to match the +.IR value +field, the test shall fail. +.P +The type specification characters +.BR d +and +.BR u +can be followed by an optional unsigned decimal integer that specifies +the number of bytes represented by the type. The type specification +characters +.BR d +and +.BR u +can be followed by an optional +.BR C , +.BR S , +.BR I , +or +.BR L , +indicating that the value is of type +.BR char , +.BR short , +.BR int , +or +.BR long , +respectively. +.P +The default number of bytes represented by the type specifiers +.BR d , +.BR f , +and +.BR u +shall correspond to their respective C-language types as follows. If +the system claims conformance to the C-Language Development Utilities +option, those specifiers shall correspond to the default sizes used in +the +.IR c99 +utility. Otherwise, the default sizes shall be implementation-defined. +.P +For the type specifier characters +.BR d +and +.BR u , +the default number of bytes shall correspond to the size of a basic +integer type of the implementation. For these specifier +characters, the implementation shall support values of the optional +number of bytes to be converted corresponding to the number of bytes in +the C-language types +.BR char , +.BR short , +.BR int , +or +.BR long . +These numbers can also be specified by an application as the characters +.BR C , +.BR S , +.BR I , +and +.BR L , +respectively. The byte order used when interpreting numeric values is +implementation-defined, but shall correspond to the order in which a +constant of the corresponding type is stored in memory on the system. +.P +All type specifiers, except for +.BR s , +can be followed by a mask specifier of the form &\fInumber\fP. The mask +value shall be AND'ed with the value of the input file before the +comparison with the +.IR value +field of the line is made. By default, the mask shall be interpreted as +an unsigned decimal number. With a leading 0x or 0X, the mask shall be +interpreted as an unsigned hexadecimal number; otherwise, with a +leading 0, the mask shall be interpreted as an unsigned octal number. +.P +The strings +.BR byte , +.BR short , +.BR long , +and +.BR string +shall also be supported as type fields, being interpreted as +.BR dC , +.BR dS , +.BR dL , +and +.BR s , +respectively. +.RE +.IP "\fIvalue\fP" 10 +The +.IR value +to be compared with the value from the file. +.RS 10 +.P +If the specifier from the type field is +.BR s +or +.BR string , +then interpret the value as a string. Otherwise, interpret it as a +number. If the value is a string, then the test shall succeed only when +a string value exactly matches the bytes from the file. +.P +If the +.IR value +is a string, it can contain the following sequences: +.IP "\e\fIcharacter\fR" 12 +The +-escape +sequences as specified in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Table 5-1" ", " "Escape Sequences and Associated Actions" +(\c +.BR '\e\e' , +.BR '\ea' , +.BR '\eb' , +.BR '\ef' , +.BR '\en' , +.BR '\er' , +.BR '\et' , +.BR '\ev' ). +In addition, the escape sequence +.BR '\e\ ' +(the + +character followed by a + +character) shall be recognized to represent a + +character. The results of using any other character, other than an +octal digit, following the + +are unspecified. +.IP "\e\fIoctal\fR" 12 +Octal sequences that can be used to represent characters with specific +coded values. An octal sequence shall consist of a + +followed by the longest sequence of one, two, or three octal-digit +characters (01234567). +.P +By default, any value that is not a string shall be interpreted as a +signed decimal number. Any such value, with a leading 0x or 0X, shall +be interpreted as an unsigned hexadecimal number; otherwise, with a +leading zero, the value shall be interpreted as an unsigned octal +number. +.P +If the value is not a string, it can be preceded by a character +indicating the comparison to be performed. Permissible characters and +the comparisons they specify are as follows: +.IP "\fR=\fP" 6 +The test shall succeed if the value from the file equals the +.IR value +field. +.IP "\fR<\fP" 6 +The test shall succeed if the value from the file is less than the +.IR value +field. +.IP "\fR>\fP" 6 +The test shall succeed if the value from the file is greater than the +.IR value +field. +.IP "\fR&\fP" 6 +The test shall succeed if all of the set bits in the +.IR value +field are set in the value from the file. +.IP "\fR^\fP" 6 +The test shall succeed if at least one of the set bits in the +.IR value +field is not set in the value from the file. +.IP "\fRx\fP" 6 +The test shall succeed if the file is large enough to contain a value +of the type specified starting at the offset specified. +.RE +.IP "\fImessage\fP" 10 +The +.IR message +to be printed if the test succeeds. The +.IR message +shall be interpreted using the notation for the +.IR printf +formatting specification; see +.IR printf . +If the +.IR value +field was a string, then the value from the file shall be the argument +for the +.IR printf +formatting specification; otherwise, the value from the file shall be +the argument. +.br +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR file +utility can only be required to guess at many of the file types because +only exhaustive testing can determine some types with certainty. For +example, binary data on some implementations might match the initial +segment of an executable or a +.IR tar +archive. +.P +Note that the table indicates that the output contains the stated +string. Systems may add text before or after the string. For +executables, as an example, the machine architecture and various facts +about how the file was link-edited may be included. Note also that on +systems that recognize shell script files starting with +.BR \(dq#!\(dq +as executable files, these may be identified as executable binary files +rather than as shell scripts. +.SH EXAMPLES +Determine whether an argument is a binary executable file: +.sp +.RS 4 +.nf +\fB +file \(mi\|\(mi "$1" | grep \(miq ':.*executable' && + printf "%s is executable.\en$1" +.fi \fR +.P +.RE +.SH RATIONALE +The +.BR \(mif +option was omitted because the same effect can (and should) be obtained +using the +.IR xargs +utility. +.P +Historical versions of the +.IR file +utility attempt to identify the following types of files: symbolic +link, directory, character special, block special, socket, +.IR tar +archive, +.IR cpio +archive, SCCS archive, archive library, empty, +.IR compress +output, +.IR pack +output, binary data, C source, FORTRAN source, assembler source, +.IR nroff /\c +.IR troff /\c +.IR eqn /\c +.IR tbl +source +.IR troff +output, shell script, C shell script, English text, ASCII text, various +executables, APL workspace, compiled terminfo entries, and CURSES +screen images. Only those types that are reasonably well specified in +POSIX or are directly related to POSIX utilities are listed in the +table. +.P +Historical systems have used a ``magic file'' named +.BR /etc/magic +to help identify file types. Because it is generally useful for users +and scripts to be able to identify special file types, the +.BR \(mim +flag and a portable format for user-created magic files has been +specified. No requirement is made that an implementation of +.IR file +use this method of identifying files, only that users be permitted to +add their own classifying tests. +.P +In addition, three options have been added to historical practice. The +.BR \(mid +flag has been added to permit users to cause their tests to follow any +default system tests. The +.BR \(mii +flag has been added to permit users to test portably for regular files +in shell scripts. The +.BR \(miM +flag has been added to permit users to ignore any default system +tests. +.P +The POSIX.1\(hy2008 description of default system tests and the interaction +between the +.BR \(mid , +.BR \(miM , +and +.BR \(mim +options did not clearly indicate that there were two types of ``default +system tests''. The ``position-sensitive tests'' determine file types +by looking for certain string or binary values at specific offsets in +the file being examined. These position-sensitive tests were +implemented in historical systems using the magic file described above. +Some of these tests are now built into the +.IR file +utility itself on some implementations so the output can provide more +detail than can be provided by magic files. For example, a magic file +can easily identify a +.BR core +file on most implementations, but cannot name the program file that +dropped the core. A magic file could produce output such as: +.sp +.RS 4 +.nf +\fB +/home/dwc/core: ELF 32-bit MSB core file SPARC Version 1 +.fi \fR +.P +.RE +.P +but by building the test into the +.IR file +utility, you could get output such as: +.sp +.RS 4 +.nf +\fB +/home/dwc/core: ELF 32-bit MSB core file SPARC Version 1, from 'testprog' +.fi \fR +.P +.RE +.P +These extended built-in tests are still to be treated as +position-sensitive default system tests even if they are not listed in +.BR /etc/magic +or any other magic file. +.P +The context-sensitive default system tests were always built into the +.IR file +utility. These tests looked for language constructs in text files +trying to identify shell scripts, C, FORTRAN, and other computer +language source files, and even plain text files. With the addition of +the +.BR \(mim +and +.BR \(miM +options the distinction between position-sensitive and +context-sensitive default system tests became important because the +order of testing is important. The context-sensitive system default +tests should never be applied before any position-sensitive tests even +if the +.BR \(mid +option is specified before a +.BR \(mim +option or +.BR \(miM +option due to the high probability that the context-sensitive system +default tests will incorrectly identify arbitrary text files as text +files before position-sensitive tests specified by the +.BR \(mim +or +.BR \(miM +option would be applied to give a more accurate identification. +.P +Leaving the meaning of +.BR "\(miM \(mi" +and +.BR "\(mim \(mi" +unspecified allows an existing prototype of these options to continue +to work in a backwards-compatible manner. (In that implementation, +.BR "\(miM \(mi" +was roughly equivalent to +.BR \(mid +in POSIX.1\(hy2008.) +.P +The historical +.BR \(mic +option was omitted as not particularly useful to users or portable +shell scripts. In addition, a reasonable implementation of the +.IR file +utility would report any errors found each time the magic file is +read. +.P +The historical format of the magic file was the same as that specified +by the Rationale in the ISO\ POSIX\(hy2:\|1993 standard for the +.IR offset , +.IR value , +and +.IR message +fields; however, it used less precise type fields than the format +specified by the current normative text. The new type field values are +a superset of the historical ones. +.P +The following is an example magic file: +.sp +.RS 4 +.nf +\fB +0 short 070707 cpio archive +0 short 0143561 Byte-swapped cpio archive +0 string 070707 ASCII cpio archive +0 long 0177555 Very old archive +0 short 0177545 Old archive +0 short 017437 Old packed data +0 string \e037\e036 Packed data +0 string \e377\e037 Compacted data +0 string \e037\e235 Compressed data +>2 byte&0x80 >0 Block compressed +>2 byte&0x1f x %d bits +0 string \e032\e001 Compiled Terminfo Entry +0 short 0433 Curses screen image +0 short 0434 Curses screen image +0 string System V Release 1 archive +0 string !\en__.SYMDEF Archive random library +0 string ! Archive +0 string ARF_BEGARF PHIGS clear text archive +0 long 0x137A2950 Scalable OpenFont binary +0 long 0x137A2951 Encrypted scalable OpenFont binary +.fi \fR +.P +.RE +.P +The use of a basic integer data type is intended to allow the +implementation to choose a word size commonly used by applications +on that architecture. +.P +Earlier versions of this standard allowed for implementations with +bytes other than eight bits, but this has been modified in this +version. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIar\fR\^", +.IR "\fIls\fR\^", +.IR "\fIpax\fR\^", +.IR "\fIprintf\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Table 5-1" ", " "Escape Sequences and Associated Actions", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/find.1p b/man-pages-posix-2013/man1p/find.1p new file mode 100644 index 0000000..5ef0743 --- /dev/null +++ b/man-pages-posix-2013/man1p/find.1p @@ -0,0 +1,1126 @@ +'\" et +.TH FIND "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +find +\(em find files +.SH SYNOPSIS +.LP +.nf +find \fB[\fR\(miH|\(miL\fB] \fIpath\fR... \fB[\fIoperand_expression\fR...\fB] +.fi +.SH DESCRIPTION +The +.IR find +utility shall recursively descend the directory hierarchy from each +file specified by +.IR path , +evaluating a Boolean expression composed of the primaries described in +the OPERANDS section for each file encountered. Each +.IR path +operand shall be evaluated unaltered as it was provided, including +all trailing + +characters; all pathnames for other files encountered in the hierarchy +shall consist of the concatenation of the current +.IR path +operand, a + +if the current +.IR path +operand did not end in one, and the filename relative to the +.IR path +operand. The relative portion shall contain no dot or dot-dot components, +no trailing + +characters, and only single + +characters between pathname components. +.P +The +.IR find +utility shall be able to descend to arbitrary depths in a file +hierarchy and shall not fail due to path length limitations (unless a +.IR path +operand specified by the application exceeds +{PATH_MAX} +requirements). +.P +The +.IR find +utility shall detect infinite loops; that is, entering a previously +visited directory that is an ancestor of the last file encountered. +When it detects an infinite loop, +.IR find +shall write a diagnostic message to standard error and shall either +recover its position in the hierarchy or terminate. +.P +If a file is removed from or added to the directory hierarchy being +searched it is unspecified whether or not +.IR find +includes that file in its search. +.SH OPTIONS +The +.IR find +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported by the implementation: +.IP "\fB\(miH\fP" 10 +Cause the file information and file type evaluated for each symbolic +link encountered as a +.IR path +operand on the command line to be those of the file referenced by the +link, and not the link itself. If the referenced file does not exist, the +file information and type shall be for the link itself. File information +and type for symbolic links encountered during the traversal of a file +hierarchy shall be that of the link itself. +.IP "\fB\(miL\fP" 10 +Cause the file information and file type evaluated for each symbolic +link encountered as a +.IR path +operand on the command line or encountered during the traversal of +a file hierarchy to be those of the file referenced by the link, and +not the link itself. If the referenced file does not exist, the file +information and type shall be for the link itself. +.P +Specifying more than one of the mutually-exclusive options +.BR \(miH +and +.BR \(miL +shall not be considered an error. The last option specified shall +determine the behavior of the utility. If neither the +.BR \(miH +nor the +.BR \(miL +option is specified, then the file information and type for symbolic +links encountered as a +.IR path +operand on the command line or encountered during the traversal of a +file hierarchy shall be that of the link itself. +.SH OPERANDS +The following operands shall be supported: +.P +The first operand and subsequent operands up to but not including the +first operand that starts with a +.BR '\(mi' , +or is a +.BR '!' +or a +.BR '(' , +shall be interpreted as +.IR path +operands. If the first operand starts with a +.BR '\(mi' , +or is a +.BR '!' +or a +.BR '(' , +the behavior is unspecified. Each +.IR path +operand is a pathname of a starting point in the file hierarchy. +.P +The first operand that starts with a +.BR '\(mi' , +or is a +.BR '!' +or a +.BR '(' , +and all subsequent arguments shall be interpreted as an +.IR expression +made up of the following primaries and operators. In the descriptions, +wherever +.IR n +is used as a primary argument, it shall be interpreted as a decimal +integer optionally preceded by a plus (\c +.BR '\(pl' ) +or minus-sign (\c +.BR '\(mi' ) +sign, as follows: +.IP "+\fIn\fR" 10 +More than +.IR n . +.IP "\fIn\fR" 10 +Exactly +.IR n . +.IP "\(mi\fIn\fR" 10 +Less than +.IR n . +.P +The following primaries shall be supported: +.IP "\fB\(miname\ \fIpattern\fR" 10 +.br +The primary shall evaluate as true if the basename of the current +pathname matches +.IR pattern +using the pattern matching notation described in +.IR "Section 2.13" ", " "Pattern Matching Notation". +The additional rules in +.IR "Section 2.13.3" ", " "Patterns Used for Filename Expansion" +do not apply as this is a matching operation, not an expansion. +.IP "\fB\(mipath\ \fIpattern\fR" 10 +.br +The primary shall evaluate as true if the current pathname matches +.IR pattern +using the pattern matching notation described in +.IR "Section 2.13" ", " "Pattern Matching Notation". +The additional rules in +.IR "Section 2.13.3" ", " "Patterns Used for Filename Expansion" +do not apply as this is a matching operation, not an expansion. +.IP "\fB\(minouser\fP" 10 +The primary shall evaluate as true if the file belongs to a user ID for +which the +\fIgetpwuid\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008 (or equivalent) returns NULL. +.IP "\fB\(minogroup\fP" 10 +The primary shall evaluate as true if the file belongs to a group ID +for which the +\fIgetgrgid\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008 (or equivalent) returns NULL. +.IP "\fB\(mixdev\fP" 10 +The primary shall always evaluate as true; it shall cause +.IR find +not to continue descending past directories that have a different +device ID (\c +.IR st_dev , +see the +\fIstat\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008). If any +.BR \(mixdev +primary is specified, it shall apply to the entire expression even if +the +.BR \(mixdev +primary would not normally be evaluated. +.IP "\fB\(miprune\fP" 10 +The primary shall always evaluate as true; it shall cause +.IR find +not to descend the current pathname if it is a directory. If the +.BR \(midepth +primary is specified, the +.BR \(miprune +primary shall have no effect. +.IP "\fB\(miperm\ [\(mi]\fImode\fR" 10 +.br +The +.IR mode +argument is used to represent file mode bits. It shall be identical in +format to the +.IR symbolic_mode +operand described in +.IR chmod , +and shall be interpreted as follows. To start, a template shall be +assumed with all file mode bits cleared. An +.IR op +symbol of +.BR '\(pl' +shall set the appropriate mode bits in the template; +.BR '\(mi' +shall clear the appropriate bits; +.BR '=' +shall set the appropriate mode bits, without regard to the contents of +the file mode creation mask of the process. The +.IR op +symbol of +.BR '\(mi' +cannot be the first character of +.IR mode ; +this avoids ambiguity with the optional leading +. +Since the initial mode is all bits off, there are not any symbolic modes +that need to use +.BR '\(mi' +as the first character. +.RS 10 +.P +If the + +is omitted, the primary shall evaluate as true when the file permission +bits exactly match the value of the resulting template. +.P +Otherwise, if +.IR mode +is prefixed by a +, +the primary shall evaluate as true if at least all the bits in the +resulting template are set in the file permission bits. +.RE +.IP "\fB\(miperm\ [\(mi]\fIonum\fR" 10 +.br +If the + +is omitted, the primary shall evaluate as true when the file mode bits +exactly match the value of the octal number +.IR onum +(see the description of the octal +.IR mode +in +.IR chmod ). +Otherwise, if +.IR onum +is prefixed by a +, +the primary shall evaluate as true if at least all of the bits specified in +.IR onum +are set. In both cases, the behavior is unspecified when +.IR onum +exceeds 07777. +.IP "\fB\(mitype\ \fIc\fR" 10 +The primary shall evaluate as true if the type of the file is +.IR c , +where +.IR c +is +.BR 'b' , +.BR 'c' , +.BR 'd' , +.BR 'l' , +.BR 'p' , +.BR 'f' , +or +.BR 's' +for block special file, character special file, directory, symbolic +link, FIFO, regular file, or socket, respectively. +.IP "\fB\(milinks\ \fIn\fR" 10 +The primary shall evaluate as true if the file has +.IR n +links. +.IP "\fB\(miuser\ \fIuname\fR" 10 +The primary shall evaluate as true if the file belongs to the user +.IR uname. +If +.IR uname +is a decimal integer and the +\fIgetpwnam\fR() +(or equivalent) function does not return a valid user name, +.IR uname +shall be interpreted as a user ID. +.IP "\fB\(migroup\ \fIgname\fR" 10 +.br +The primary shall evaluate as true if the file belongs to the group +.IR gname . +If +.IR gname +is a decimal integer and the +\fIgetgrnam\fR() +(or equivalent) function does not return a valid group name, +.IR gname +shall be interpreted as a group ID. +.IP "\fB\(misize\ \fIn\fB[c]\fR" 10 +The primary shall evaluate as true if the file size in bytes, divided +by 512 and rounded up to the next integer, is +.IR n . +If +.IR n +is followed by the character +.BR 'c' , +the size shall be in bytes. +.IP "\fB\(miatime\ \fIn\fR" 10 +The primary shall evaluate as true if the file access time subtracted +from the initialization time, divided by 86\|400 (with any remainder +discarded), is +.IR n . +.IP "\fB\(mictime\ \fIn\fR" 10 +The primary shall evaluate as true if the time of last change of file +status information subtracted from the initialization time, divided by +86\|400 (with any remainder discarded), is +.IR n . +.IP "\fB\(mimtime\ \fIn\fR" 10 +The primary shall evaluate as true if the file modification time +subtracted from the initialization time, divided by 86\|400 (with any +remainder discarded), is +.IR n . +.IP "\fB\(miexec\ \fIutility_name\ \fB[\fIargument\fR\ .\|.\|.\fB]\ ;\fR" 10 +.IP "\fB\(miexec\ \fIutility_name\ \fB[\fIargument\fR\ .\|.\|.\fB]\ \ \fR{\|}\0+" 10 +.br +The end of the primary expression shall be punctuated by a + +or by a +. +Only a + +that immediately follows an argument containing only the two characters +.BR \(dq{}\(dq +shall punctuate the end of the primary expression. Other uses of the + +shall not be treated as special. +.RS 10 +.P +If the primary expression is punctuated by a +, +the utility +.IR utility_name +shall be invoked once for each pathname and the primary shall evaluate +as true if the utility returns a zero value as exit status. A +.IR utility_name +or +.IR argument +containing only the two characters +.BR \(dq{}\(dq +shall be replaced by the current pathname. If a +.IR utility_name +or +.IR argument +string contains the two characters +.BR \(dq{}\(dq , +but not just the two characters +.BR \(dq{}\(dq , +it is implementation-defined whether +.IR find +replaces those two characters or uses the string without change. +.P +If the primary expression is punctuated by a +, +the primary shall always evaluate as true, and the pathnames for which +the primary is evaluated shall be aggregated into sets. The utility +.IR utility_name +shall be invoked once for each set of aggregated pathnames. Each +invocation shall begin after the last pathname in the set is +aggregated, and shall be completed before the +.IR find +utility exits and before the first pathname in the next set (if any) is +aggregated for this primary, but it is otherwise unspecified whether +the invocation occurs before, during, or after the evaluations of other +primaries. If any invocation returns a non-zero value as exit status, +the +.IR find +utility shall return a non-zero exit status. An argument containing +only the two characters +.BR \(dq{}\(dq +shall be replaced by the set of aggregated pathnames, with each +pathname passed as a separate argument to the invoked utility in the +same order that it was aggregated. The size of any set of two or more +pathnames shall be limited such that execution of the utility does not +cause the system's +{ARG_MAX} +limit to be exceeded. If more than one argument containing the two +characters +.BR \(dq{}\(dq +is present, the behavior is unspecified. +.P +The current directory for the invocation of +.IR utility_name +shall be the same as the current directory when the +.IR find +utility was started. If the +.IR utility_name +names any of the special built-in utilities (see +.IR "Section 2.14" ", " "Special Built-In Utilities"), +the results are undefined. +.RE +.IP "\fB\(miok\ \fIutility_name\ \fB[\fIargument\fR\ .\|.\|.\fB]\ ;\fR" 10 +.br +The +.BR \(miok +primary shall be equivalent to +.BR \(miexec , +except that the use of a + +to punctuate the end of the primary expression need not be supported, and +.IR find +shall request affirmation of the invocation of +.IR utility_name +using the current file as an argument by writing to standard error as +described in the STDERR section. If the response on standard input is +affirmative, the utility shall be invoked. Otherwise, the command +shall not be invoked and the value of the +.BR \(miok +operand shall be false. +.IP "\fB\(miprint\fR" 10 +The primary shall always evaluate as true; it shall cause the current +pathname to be written to standard output. +.IP "\fB\(minewer\ \fIfile\fR" 10 +The primary shall evaluate as true if the modification time of the +current file is more recent than the modification time of the file +named by the pathname +.IR file . +.IP "\fB\(midepth\fR" 10 +The primary shall always evaluate as true; it shall cause descent of +the directory hierarchy to be done so that all entries in a directory +are acted on before the directory itself. If a +.BR \(midepth +primary is not specified, all entries in a directory shall be acted on +after the directory itself. If any +.BR \(midepth +primary is specified, it shall apply to the entire expression even if +the +.BR \(midepth +primary would not normally be evaluated. +.P +The primaries can be combined using the following operators (in order +of decreasing precedence): +.IP "(\ \fIexpression\fR\ )" 10 +True if +.IR expression +is true. +.IP "\fB!\ \fIexpression\fR" 10 +Negation of a primary; the unary NOT operator. +.IP "\fIexpression\ \fB[\(mia]\ \fIexpression\fR" 10 +.br +Conjunction of primaries; the AND operator is implied by the +juxtaposition of two primaries or made explicit by the optional +.BR \(mia +operator. The second expression shall not be evaluated if the first +expression is false. +.IP "\fIexpression\ \fB\(mio\ \fIexpression\fR" 10 +.br +Alternation of primaries; the OR operator. The second expression shall +not be evaluated if the first expression is true. +.P +If no +.IR expression +is present, +.BR \(miprint +shall be used as the expression. Otherwise, if the given expression +does not contain any of the primaries +.BR \(miexec , +.BR \(miok , +or +.BR \(miprint , +the given expression shall be effectively replaced by: +.sp +.RS 4 +.nf +\fB +( \fIgiven_expression\fP ) \(miprint +.fi \fR +.P +.RE +.P +The +.BR \(miuser , +.BR \(migroup , +and +.BR \(minewer +primaries each shall evaluate their respective arguments only once. +.P +When the file type evaluated for the current file is a symbolic link, +the results of evaluating the +.BR \(miperm +primary are implementation-defined. +.SH STDIN +If the +.BR \(miok +primary is used, the response shall be read from the standard input. +An entire line shall be read as the response. Otherwise, the standard +input shall not be used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR find : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements used in the pattern matching +notation for the +.BR \(min +option and in the extended regular expression defined for the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_CTYPE\fP" 10 +This variable determines the locale for the interpretation of sequences +of bytes of text data as characters (for example, single-byte +as opposed to multi-byte characters in arguments), the behavior of +character classes within the pattern matching notation used for the +.BR \(min +option, and the behavior of character classes within regular +expressions used in the extended regular expression defined for the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale used to process affirmative responses, and the +locale used to affect the format and contents of diagnostic messages +and prompts written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPATH\fP" 10 +Determine the location of the +.IR utility_name +for the +.BR \(miexec +and +.BR \(miok +primaries, as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.BR \(miprint +primary shall cause the current pathnames to be written to standard +output. The format shall be: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIpath\fR> +.fi \fR +.P +.RE +.SH STDERR +The +.BR \(miok +primary shall write a prompt to standard error containing at least the +.IR utility_name +to be invoked and the current pathname. In the POSIX locale, the last +non-\c + +in the prompt shall be +.BR '?' . +The exact format used is unspecified. +.P +Otherwise, the standard error shall be used only for diagnostic +messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All +.IR path +operands were traversed successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +When used in operands, pattern matching notation, +, +, +and + +characters are special to the shell and must be quoted (see +.IR "Section 2.2" ", " "Quoting"). +.P +The bit that is traditionally used for sticky (historically 01000) is +specified in the +.BR \(miperm +primary using the octal number argument form. Since this bit is not +defined by this volume of POSIX.1\(hy2008, applications must not assume that it actually refers +to the traditional sticky bit. +.SH EXAMPLES +.IP " 1." 4 +The following commands are equivalent: +.RS 4 +.sp +.RS 4 +.nf +\fB +find . +find . \(miprint +.fi \fR +.P +.RE +.P +They both write out the entire directory hierarchy from the current +directory. +.RE +.IP " 2." 4 +The following command: +.RS 4 +.sp +.RS 4 +.nf +\fB +find / \e( \(miname tmp \(mio \(miname '*.xx' \e) \(miatime +7 \(miexec rm {} \e; +.fi \fR +.P +.RE +.P +removes all files named +.BR tmp +or ending in +.BR .xx +that have not been accessed for seven or more 24-hour periods. +.RE +.IP " 3." 4 +The following command: +.RS 4 +.sp +.RS 4 +.nf +\fB +find . \(miperm \(mio+w,+s +.fi \fR +.P +.RE +.P +prints (\c +.BR \(miprint +is assumed) the names of all files in or below the current directory, +with all of the file permission bits S_ISUID, S_ISGID, and S_IWOTH set. +.RE +.IP " 4." 4 +The following command: +.RS 4 +.sp +.RS 4 +.nf +\fB +find . \(miname SCCS \(miprune \(mio \(miprint +.fi \fR +.P +.RE +.P +recursively prints pathnames of all files in the current directory and +below, but skips directories named SCCS and files in them. +.RE +.IP " 5." 4 +The following command: +.RS 4 +.sp +.RS 4 +.nf +\fB +find . \(miprint \(miname SCCS \(miprune +.fi \fR +.P +.RE +.P +behaves as in the previous example, but prints the names of the SCCS +directories. +.RE +.IP " 6." 4 +The following command is roughly equivalent to the +.BR \(mint +extension to +.IR test : +.RS 4 +.sp +.RS 4 +.nf +\fB +if [ \(min "$(find file1 \(miprune \(minewer file2)" ]; then + printf %s\e\en "file1 is newer than file2" +fi +.fi \fR +.P +.RE +.RE +.IP " 7." 4 +The descriptions of +.BR \(miatime , +.BR \(mictime , +and +.BR \(mimtime +use the terminology +.IR n +``86\|400 second periods (days)''. For example, a file accessed at 23:59 +is selected by: +.RS 4 +.sp +.RS 4 +.nf +\fB +find . \(miatime \(mi1 \(miprint +.fi \fR +.P +.RE +.P +at 00:01 the next day (less than 24 hours later, not more than one day +ago); the midnight boundary between days has no effect on the 24-hour +calculation. +.RE +.IP " 8." 4 +The following command: +.RS 4 +.sp +.RS 4 +.nf +\fB +find . ! \(miname . \(miprune \(miname '*.old' \(miexec \e + sh \(mic 'mv "$@" ../old/' sh {} + +.fi \fR +.P +.RE +.P +performs the same task as: +.sp +.RS 4 +.nf +\fB +mv ./*.old ./.old ./.*.old ../old/ +.fi \fR +.P +.RE +.P +while avoiding an ``Argument list too long'' error if there are +a large number of files ending with +.BR .old +and without running +.IR mv +if there are no such files (and avoiding ``No such file or directory'' +errors if +.BR ./.old +does not exist or no files match +.BR ./*.old +or +.BR ./.*.old ). +.P +The alternative: +.sp +.RS 4 +.nf +\fB +find . ! \(miname . \(miprune \(miname '*.old' \(miexec mv {} ../old/ \e; +.fi \fR +.P +.RE +.P +is less efficient if there are many files to move because it executes one +.IR mv +command per file. +.RE +.IP " 9." 4 +On systems configured to mount removable media on directories under +.BR /media , +the following command searches the file hierarchy for files larger +than 100\|000 KB without searching any mounted removable media: +.RS 4 +.sp +.RS 4 +.nf +\fB +find / \(mipath /media \(miprune \(mio \(misize +200000 \(miprint +.fi \fR +.P +.RE +.RE +.IP 10. 4 +Except for the root directory, and +.BR \(dq//\(dq +on implementations where +.BR \(dq//\(dq +does not refer to the root directory, no pattern given to +.BR \(miname +will match a +, +because trailing + +characters are ignored when computing the basename of the file under +evaluation. Given two empty directories named +.BR foo +and +.BR bar , +the following command: +.RS 4 +.sp +.RS 4 +.nf +\fB +find foo/// bar/// \(miname foo \(mio \(miname 'bar?*' +.fi \fR +.P +.RE +.P +prints only the line +.BR \(dqfoo///\(dq . +.RE +.SH RATIONALE +The +.BR \(mia +operator was retained as an optional operator for compatibility with +historical shell scripts, even though it is redundant with expression +concatenation. +.P +The descriptions of the +.BR '\(mi' +modifier on the +.IR mode +and +.IR onum +arguments to the +.BR \(miperm +primary agree with historical practice on BSD and System V +implementations. System V and BSD documentation both describe it in +terms of checking additional bits; in fact, it uses the same bits, but +checks for having at least all of the matching bits set instead of +having exactly the matching bits set. +.P +The exact format of the interactive prompts is unspecified. Only the +general nature of the contents of prompts are specified because: +.IP " *" 4 +Implementations may desire more descriptive prompts than those +used on historical implementations. +.IP " *" 4 +Since the historical prompt strings do not terminate with + +characters, there is no portable way for another program to interact +with the prompts of this utility via pipes. +.P +Therefore, an application using this prompting option relies on the +system to provide the most suitable dialog directly with the user, +based on the general guidelines specified. +.P +The +.BR \(miname +.IR file +operand was changed to use the shell pattern matching notation +so that +.IR find +is consistent with other utilities using pattern matching. +.P +The +.BR \(misize +operand refers to the size of a file, rather than the number of blocks +it may occupy in the file system. The intent is that the +.IR st_size +field defined in the System Interfaces volume of POSIX.1\(hy2008 should be used, not the +.IR st_blocks +found in historical implementations. There are at least two reasons for +this: +.IP " 1." 4 +In both System V and BSD, +.IR find +only uses +.IR st_size +in size calculations for the operands specified by this volume of POSIX.1\(hy2008. (BSD uses +.IR st_blocks +only when processing the +.BR \(mils +primary.) +.IP " 2." 4 +Users usually think of file size in terms of bytes, which is also the +unit used by the +.IR ls +utility for the output from the +.BR \(mil +option. (In both System V and BSD, +.IR ls +uses +.IR st_size +for the +.BR \(mil +option size field and uses +.IR st_blocks +for the +.IR ls +.BR \(mis +calculations. This volume of POSIX.1\(hy2008 does not specify +.IR ls +.BR \(mis .) +.P +The descriptions of +.BR \(miatime , +.BR \(mictime , +and +.BR \(mimtime +were changed from the SVID description of +.IR n +``days'' to +.IR n +being the result of the integer division of the time difference in +seconds by 86\|400. The description is also different in terms of the +exact timeframe for the +.IR n +case (\fIversus\fP the +.IR +n +or +.IR \(min ), +but it matches all known historical implementations. It refers to one +86\|400 second period in the past, not any time from the beginning of +that period to the current time. For example, +.BR \(miatime +2 is true if the file was accessed any time in the period from 72 hours +to 48 hours ago. +.P +Historical implementations do not modify +.BR \(dq{}\(dq +when it appears as a substring of an +.BR \(miexec +or +.BR \(miok +.IR utility_name +or argument string. There have been numerous user requests for this +extension, so this volume of POSIX.1\(hy2008 allows the desired behavior. At least one recent +implementation does support this feature, but encountered several +problems in managing memory allocation and dealing with multiple +occurrences of +.BR \(dq{}\(dq +in a string while it was being developed, so it is not yet required +behavior. +.P +Assuming the presence of +.BR \(miprint +was added to correct a historical pitfall that plagues novice users, it +is entirely upwards-compatible from the historical System V +.IR find +utility. In its simplest form (\c +.IR find +.IR directory ), +it could be confused with the historical BSD fast +.IR find . +The BSD developers agreed that adding +.BR \(miprint +as a default expression was the correct decision and have added the +fast +.IR find +functionality within a new utility called +.IR locate . +.P +Historically, the +.BR \(miL +option was implemented using the primary +.BR \(mifollow . +The +.BR \(miH +and +.BR \(miL +options were added for two reasons. First, they offer a finer +granularity of control and consistency with other programs that walk +file hierarchies. Second, the +.BR \(mifollow +primary always evaluated to true. As they were historically really +global variables that took effect before the traversal began, some +valid expressions had unexpected results. An example is the expression +.BR \(miprint +.BR \(mio +.BR \(mifollow . +Because +.BR \(miprint +always evaluates to true, the standard order of evaluation implies that +.BR \(mifollow +would never be evaluated. This was never the case. Historical practice +for the +.BR \(mifollow +primary, however, is not consistent. Some implementations always follow +symbolic links on the command line whether +.BR \(mifollow +is specified or not. Others follow symbolic links on the command line +only if +.BR \(mifollow +is specified. Both behaviors are provided by the +.BR \(miH +and +.BR \(miL +options, but scripts using the current +.BR \(mifollow +primary would be broken if the +.BR \(mifollow +option is specified to work either way. +.P +Since the +.BR \(miL +option resolves all symbolic links and the +.BR \(mitype +.IR l +primary is true for symbolic links that still exist after symbolic +links have been resolved, the command: +.sp +.RS 4 +.nf +\fB +find \(miL . \(mitype l +.fi \fR +.P +.RE +.P +prints a list of symbolic links reachable from the current directory +that do not resolve to accessible files. +.P +A feature of SVR4's +.IR find +utility was the +.BR \(miexec +primary's +.BR + +terminator. This allowed filenames containing special characters +(especially + +characters) to be grouped together without the problems that occur if +such filenames are piped to +.IR xargs . +Other implementations have added other ways to get around this problem, +notably a +.BR \(miprint0 +primary that wrote filenames with a null byte terminator. This was +considered here, but not adopted. Using a null terminator meant that +any utility that was going to process +.IR find 's +.BR \(miprint0 +output had to add a new option to parse the null terminators it would +now be reading. +.P +The +.BR \(dq\(miexec ... {} +\(dq +syntax adopted was a result of IEEE PASC Interpretation 1003.2 #210. It +should be noted that this is an incompatible change to IEEE\ Std 1003.2\(hy1992. For example, +the following command printed all files with a +.BR '\(mi' +after their name if they are regular files, and a +.BR '\(pl' +otherwise: +.sp +.RS 4 +.nf +\fB +find / \(mitype f \(miexec echo {} \(mi ';' \(mio \(miexec echo {} + ';' +.fi \fR +.P +.RE +.P +The change invalidates usage like this. Even though the previous +standard stated that this usage would work, in practice many did not +support it and the standard developers felt it better to now state that +this was not allowable. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.2" ", " "Quoting", +.IR "Section 2.13" ", " "Pattern Matching Notation", +.IR "Section 2.14" ", " "Special Built-In Utilities", +.IR "\fIchmod\fR\^", +.IR "\fImv\fR\^", +.IR "\fIpax\fR\^", +.IR "\fIsh\fR\^", +.IR "\fItest\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIfstatat\fR\^(\|)", +.IR "\fIgetgrgid\fR\^(\|)", +.IR "\fIgetpwuid\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/fold.1p b/man-pages-posix-2013/man1p/fold.1p new file mode 100644 index 0000000..2c7469d --- /dev/null +++ b/man-pages-posix-2013/man1p/fold.1p @@ -0,0 +1,280 @@ +'\" et +.TH FOLD "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fold +\(em filter for folding lines +.SH SYNOPSIS +.LP +.nf +fold \fB[\fR\(mibs\fB] [\fR\(miw \fIwidth\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR fold +utility is a filter that shall fold lines from its input files, +breaking the lines to have a maximum of +.IR width +column positions (or bytes, if the +.BR \(mib +option is specified). Lines shall be broken by the insertion of a + +such that each output line (referred to later in this section +as a \fIsegment\fP) is the maximum width possible that does not exceed +the specified number of column positions (or bytes). A line shall not +be broken in the middle of a character. The behavior is undefined if +.IR width +is less than the number of columns any single character in the input +would occupy. +.P +If the +, +, +or + +characters are encountered in the input, and the +.BR \(mib +option is not specified, they shall be treated specially: +.IP 10 +The current count of line width shall be decremented by one, although +the count never shall become negative. The +.IR fold +utility shall not insert a + +immediately before or after any +, +unless the following character has a width greater than 1 and would +cause the line width to exceed +.IR width . +.IP 10 +.br +The current count of line width shall be set to zero. The +.IR fold +utility shall not insert a + +immediately before or after any +. +.IP 10 +Each + +encountered shall advance the column position pointer to the next tab +stop. Tab stops shall be at each column position +.IR n +such that +.IR n +modulo 8 equals 1. +.SH OPTIONS +The +.IR fold +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mib\fR" 10 +Count +.IR width +in bytes rather than column positions. +.IP "\fB\(mis\fR" 10 +If a segment of a line contains a + +within the first +.IR width +column positions (or bytes), break the line after the last such + +meeting the width constraints. If there is no + +meeting the requirements, the +.BR \(mis +option shall have no effect for that output segment of the input line. +.IP "\fB\(miw\ \fIwidth\fR" 10 +Specify the maximum line length, in column positions (or bytes if +.BR \(mib +is specified). The results are unspecified if +.IR width +is not a positive decimal number. The default value shall be 80. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a text file to be folded. If no +.IR file +operands are specified, the standard input shall be used. +.SH STDIN +The standard input shall be used if no +.IR file +operands are specified, and shall be used if a +.IR file +operand is +.BR '\(mi' +and the implementation treats the +.BR '\(mi' +as meaning standard input. +Otherwise, the standard input shall not be used. +See the INPUT FILES section. +.SH "INPUT FILES" +If the +.BR \(mib +option is specified, the input files shall be text files except that the +lines are not limited to +{LINE_MAX} +bytes in length. If the +.BR \(mib +option is not specified, the input files shall be text files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR fold : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files), and for the +determination of the width in column positions each character would +occupy on a constant-width font output device. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall be a file containing a sequence of characters +whose order shall be preserved from the input files, possibly with +inserted + +characters. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All input files were processed successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR cut +and +.IR fold +utilities can be used to create text files out of files with arbitrary +line lengths. The +.IR cut +utility should be used when the number of lines (or records) needs to +remain constant. The +.IR fold +utility should be used when the contents of long lines need to be kept +contiguous. +.P +The +.IR fold +utility is frequently used to send text files to printers that +truncate, rather than fold, lines wider than the printer is able to +print (usually 80 or 132 column positions). +.SH EXAMPLES +An example invocation that submits a file of possibly long lines to the +printer (under the assumption that the user knows the line width of the +printer to be assigned by +.IR lp ): +.sp +.RS 4 +.nf +\fB +fold \(miw 132 bigfile | lp +.fi \fR +.P +.RE +.SH RATIONALE +Although terminal input in canonical processing mode requires the erase +character (frequently set to +) +to erase the previous character (not byte or column position), terminal +output is not buffered and is extremely difficult, if not impossible, +to parse correctly; the interpretation depends entirely on the physical +device that actually displays/prints/stores the output. In all known +internationalized implementations, the utilities producing output for +mixed column-width output assume that a + +character backs up one column position and outputs enough + +characters to return to the start of the character when + +is used to provide local line motions to support underlining and +emboldening operations. Since +.IR fold +without the +.BR \(mib +option is dealing with these same constraints, + +is always treated as backing up one column position rather than backing +up one character. +.P +Historical versions of the +.IR fold +utility assumed 1 byte was one character and occupied one column +position when written out. This is no longer always true. Since the +most common usage of +.IR fold +is believed to be folding long lines for output to limited-length +output devices, this capability was preserved as the default case. The +.BR \(mib +option was added so that applications could +.IR fold +files with arbitrary length lines into text files that could then be +processed by the standard utilities. Note that although the width for +the +.BR \(mib +option is in bytes, a line is never split in the middle of a character. +(It is unspecified what happens if a width is specified that is too +small to hold a single character found in the input followed by a +.) +.P +The tab stops are hardcoded to be every eighth column to meet +historical practice. No new method of specifying other tab stops was +invented. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcut\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/fort77.1p b/man-pages-posix-2013/man1p/fort77.1p new file mode 100644 index 0000000..f14ea4f --- /dev/null +++ b/man-pages-posix-2013/man1p/fort77.1p @@ -0,0 +1,581 @@ +'\" et +.TH FORT77 "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fort77 +\(em FORTRAN compiler (\fBFORTRAN\fP) +.SH SYNOPSIS +.LP +.nf +fort77 \fB[\fR\(mic\fB] [\fR\(mig\fB] [\fR\(miL \fIdirectory\fB]\fR...\fB [\fR\(miO \fIoptlevel\fB] [\fR\(mio \fIoutfile\fB] [\fR\(mis\fB] + [\fR\(miw\fB] \fIoperand\fR... +.fi +.SH DESCRIPTION +The +.IR fort77 +utility is the interface to the FORTRAN compilation system; it shall +accept the full FORTRAN-77 language defined by the ANSI\ X3.9\(hy1978 standard. The system +conceptually consists of a compiler and link editor. The files +referenced by +.IR operand s +are compiled and linked to produce an executable file. It is +unspecified whether the linking occurs entirely within the operation of +.IR fort77 ; +some implementations may produce objects that are not fully resolved +until the file is executed. +.P +If the +.BR \(mic +option is present, for all pathname operands of the form +.IR file \c +.BR .f , +the files: +.sp +.RS 4 +.nf +\fB +$(basename \fIpathname\fR.f).o +.fi \fR +.P +.RE +.P +shall be created or overwritten as the result of successful +compilation. If the +.BR \(mic +option is not specified, it is unspecified whether such +.BR .o +files are created or deleted for the +.IR file \c +.BR .f +operands. +.P +If there are no options that prevent link editing (such as +.BR \(mic ) +and all operands compile and link without error, the resulting +executable file shall be written into the file named by the +.BR \(mio +option (if present) or to the file +.BR a.out . +The executable file shall be created as specified in the System Interfaces volume of POSIX.1\(hy2008, except +that the file permissions shall be set to: +S_IRWXO | S_IRWXG | S_IRWXU +.P +and that the bits specified by the +.IR umask +of the process shall be cleared. +.SH OPTIONS +The +.IR fort77 +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that: +.IP " *" 4 +The +.BR \(mil +.IR library +operands have the format of options, but their position within a list +of operands affects the order in which libraries are searched. +.IP " *" 4 +The order of specifying the multiple +.BR \(miL +options is significant. +.IP " *" 4 +Conforming applications shall specify each option separately; that is, +grouping option letters (for example, +.BR \(micg ) +need not be recognized by all implementations. +.P +The following options shall be supported: +.IP "\fB\(mic\fR" 10 +Suppress the link-edit phase of the compilation, and do not remove any +object files that are produced. +.IP "\fB\(mig\fR" 10 +Produce symbolic information in the object or executable files; the +nature of this information is unspecified, and may be modified by +implementation-defined interactions with other options. +.IP "\fB\(mis\fR" 10 +Produce object or executable files, or both, from which symbolic and +other information not required for proper execution using the +.IR exec +family of functions defined in the System Interfaces volume of POSIX.1\(hy2008 has been removed (stripped). +If both +.BR \(mig +and +.BR \(mis +options are present, the action taken is unspecified. +.IP "\fB\(mio\ \fIoutfile\fR" 10 +Use the pathname +.IR outfile , +instead of the default +.BR a.out , +for the executable file produced. If the +.BR \(mio +option is present with +.BR \(mic , +the result is unspecified. +.IP "\fB\(miL\ \fIdirectory\fR" 10 +Change the algorithm of searching for the libraries named in +.BR \(mil +operands to look in the directory named by the +.IR directory +pathname before looking in the usual places. Directories named in +.BR \(miL +options shall be searched in the specified order. At least ten +instances of this option shall be supported in a single +.IR fort77 +command invocation. If a directory specified by a +.BR \(miL +option contains a file named +.BR libf.a , +the results are unspecified. +.IP "\fB\(miO\ \fIoptlevel\fR" 10 +Specify the level of code optimization. If the +.IR optlevel +option-argument is the digit +.BR '0' , +all special code optimizations shall be disabled. If it is the digit +.BR '1' , +the nature of the optimization is unspecified. If the +.BR \(miO +option is omitted, the nature of the system's default optimization is +unspecified. It is unspecified whether code generated in the presence +of the +.BR \(miO +0 option is the same as that generated when +.BR \(miO +is omitted. Other +.IR optlevel +values may be supported. +.IP "\fB\(miw\fR" 10 +Suppress warnings. +.P +Multiple instances of +.BR \(miL +options can be specified. +.SH OPERANDS +An +.IR operand +is either in the form of a pathname or the form +.BR \(mil +.IR library . +At least one operand of the pathname form shall be specified. The +following operands shall be supported: +.IP "\fIfile.\fBf\fR" 10 +The pathname of a FORTRAN source file to be compiled and optionally +passed to the link editor. The filename operand shall be of this form +if the +.BR \(mic +option is used. +.IP "\fIfile.\fBa\fR" 10 +A library of object files typically produced by +.IR ar , +and passed directly to the link editor. Implementations may recognize +implementation-defined suffixes other than +.BR .a +as denoting object file libraries. +.IP "\fIfile.\fBo\fR" 10 +An object file produced by +.IR fort77 +.BR \(mic +and passed directly to the link editor. Implementations may recognize +implementation-defined suffixes other than +.BR .o +as denoting object files. +.P +The processing of other files is implementation-defined. +.IP "\fB\(mil\ \fIlibrary\fR" 10 +(The letter ell.) Search the library named: +.RS 10 +.sp +.RS 4 +.nf +\fB +lib\fIlibrary\fR.a +.fi \fR +.P +.RE +.P +A library is searched when its name is encountered, so the placement of +a +.BR \(mil +operand is significant. Several standard libraries can be specified in +this manner, as described in the EXTENDED DESCRIPTION section. +Implementations may recognize implementation-defined suffixes other +than +.BR .a +as denoting libraries. +.RE +.SH STDIN +Not used. +.SH "INPUT FILES" +The input file shall be one of the following: a text file containing +FORTRAN source code; an object file in the format produced by +.IR fort77 +.BR \(mic ; +or a library of object files, in the format produced by archiving zero +or more object files, using +.IR ar . +Implementations may supply additional utilities that produce files in +these formats. Additional input files are implementation-defined. +.P +A + +encountered within the first six characters on a line of source code +shall cause the compiler to interpret the following character as if it +were the seventh character on the line (that is, in column 7). +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR fort77 : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITMPDIR\fP" 10 +Determine the pathname that should override the default directory for +temporary files, if any. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +If more than one +.IR file +operand ending in +.BR .f +(or possibly other unspecified suffixes) is given, for each such file: +.sp +.RS 4 +.nf +\fB +"%s:\en", <\fIfile\fR> +.fi \fR +.P +.RE +.P +may be written to allow identification of the diagnostic message with +the appropriate input file. +.P +This utility may produce warning messages about certain conditions that +do not warrant returning an error (non-zero) exit value. +.SH "OUTPUT FILES" +Object files, listing files, and executable files shall be produced in +unspecified formats. +.SH "EXTENDED DESCRIPTION" +.SS "Standard Libraries" +.P +The +.IR fort77 +utility shall recognize the following +.BR \(mil +operand for the standard library: +.IP "\fB\(mil\ f\fR" 10 +This library contains all functions referenced in the ANSI\ X3.9\(hy1978 standard. This +operand shall not be required to be present to cause a search of this +library. +.P +In the absence of options that inhibit invocation of the link editor, +such as +.BR \(mic , +the +.IR fort77 +utility shall cause the equivalent of a +.BR "\(mil\ f" +operand to be passed to the link editor as the last +.BR \(mil +operand, causing it to be searched after all other object files and +libraries are loaded. +.P +It is unspecified whether the library +.BR libf.a +exists as a regular file. The implementation may accept as +.BR \(mil +operands names of objects that do not exist as regular files. +.SS "External Symbols" +.P +The FORTRAN compiler and link editor shall support the significance of +external symbols up to a length of at least 31 bytes; case folding is +permitted. The action taken upon encountering symbols exceeding the +implementation-defined maximum symbol length is unspecified. +.P +The compiler and link editor shall support a minimum of 511 external +symbols per source or object file, and a minimum of 4\|095 external +symbols total. A diagnostic message is written to standard output if +the implementation-defined limit is exceeded; other actions are +unspecified. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful compilation or link edit. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +When +.IR fort77 +encounters a compilation error, it shall write a diagnostic to standard +error and continue to compile other source code operands. It shall +return a non-zero exit status, but it is implementation-defined +whether an object module is created. If the link edit is unsuccessful, +a diagnostic message shall be written to standard error, and +.IR fort77 +shall exit with a non-zero status. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +The following usage example compiles +.BR xyz.f +and creates the executable file +.BR foo : +.sp +.RS 4 +.nf +\fB +fort77 \(mio foo xyz.f +.fi \fR +.P +.RE +.P +The following example compiles +.BR xyz.f +and creates the object file +.BR xyz.o : +.sp +.RS 4 +.nf +\fB +fort77 \(mic xyz.f +.fi \fR +.P +.RE +.P +The following example compiles +.BR xyz.f +and creates the executable file +.BR a.out : +.sp +.RS 4 +.nf +\fB +fort77 xyz.f +.fi \fR +.P +.RE +.P +The following example compiles +.BR xyz.f , +links it with +.BR b.o , +and creates the executable +.BR a.out : +.sp +.RS 4 +.nf +\fB +fort77 xyz.f b.o +.fi \fR +.P +.RE +.SH RATIONALE +The name of this utility was chosen as +.IR fort77 +to parallel the renaming of the C compiler. The name +.IR f77 +was not chosen to avoid problems with historical implementations. The +ANSI\ X3.9\(hy1978 standard was selected as a normative reference because the ISO/IEC version +of FORTRAN-77 has been superseded by the ISO/IEC\ 1539:\|1991 standard. +.P +The file inclusion and symbol definition +.BR #define +mechanisms used by the +.IR c99 +utility were not included in this volume of POSIX.1\(hy2008\(emeven though they are commonly +implemented\(emsince there is no requirement that the FORTRAN compiler +use the C preprocessor. +.P +The +.BR \(mionetrip +option was not included in this volume of POSIX.1\(hy2008, even though many historical compilers +support it, because it is derived from FORTRAN-66; it is an anachronism +that should not be perpetuated. +.P +Some implementations produce compilation listings. This aspect of +FORTRAN has been left unspecified because there was controversy +concerning the various methods proposed for implementing it: a +.BR \(miV +option overlapped with historical vendor practice and a naming +convention of creating files with +.BR .l +suffixes collided with historical +.IR lex +file naming practice. +.P +There is no +.BR \(miI +option in this version of this volume of POSIX.1\(hy2008 to specify a directory for file +inclusion. An INCLUDE directive has been a part of the Fortran-90 +discussions, but an interface supporting that standard is not in the +current scope. +.P +It is noted that many FORTRAN compilers produce an object module even +when compilation errors occur; during a subsequent compilation, the +compiler may patch the object module rather than recompiling all the +code. Consequently, it is left to the implementor whether or not an +object file is created. +.P +A reference to MIL-STD-1753 +was removed from an early proposal in response to a request from the +POSIX FORTRAN-binding standard developers. It was not the intention of +the standard developers to require certification of the FORTRAN +compiler, and IEEE\ Std\ 1003.9\(hy1992 does not specify the military standard or any +special preprocessing requirements. Furthermore, use of that document +would have been inappropriate for an international standard. +.P +The specification of optimization has been subject to changes through +early proposals. At one time, +.BR \(miO +and +.BR \(miN +were Booleans: optimize and do not optimize (with an unspecified +default). Some historical practice led this to be changed to: +.IP "\fB\(miO\fR\ 0" 10 +No optimization. +.IP "\fB\(miO\fR\ 1" 10 +Some level of optimization. +.IP "\fB\(miO\ \fIn\fR" 10 +Other, unspecified levels of optimization. +.P +It is not always clear whether ``good code generation'' is the same +thing as optimization. Simple optimizations of local actions do not +usually affect the semantics of a program. The +.BR \(miO +0 option has been included to accommodate the very particular nature of +scientific calculations in a highly optimized environment; compilers +make errors. Some degree of optimization is expected, even if it is not +documented here, and the ability to shut it off completely could be +important when porting an application. An implementation may treat +.BR \(miO +0 as ``do less than normal'' if it wishes, but this is only meaningful +if any of the operations it performs can affect the semantics of a +program. It is highly dependent on the implementation whether doing +less than normal is logical. It is not the intent of the +.BR \(miO +0 option to ask for inefficient code generation, but rather to assure +that any semantically visible optimization is suppressed. +.P +The specification of standard library access is consistent with the C +compiler specification. Implementations are not required to have +.BR /usr/lib/libf.a , +as many historical implementations do, but if not they are required to +recognize +.BR f +as a token. +.P +External symbol size limits are in normative text; conforming +applications need to know these limits. However, the minimum maximum +symbol length should be taken as a constraint on a conforming +application, not on an implementation, and consequently the action +taken for a symbol exceeding the limit is unspecified. The minimum size +for the external symbol table was added for similar reasons. +.P +The CONSEQUENCES OF ERRORS section clearly specifies the behavior of +the compiler when compilation or link-edit errors occur. The behavior +of several historical implementations was examined, and the choice was +made to be silent on the status of the executable, or +.BR a.out , +file in the face of compiler or linker errors. If a linker writes the +executable file, then links it on disk with +\fIlseek\fR()s +and +\fIwrite\fR()s, +the partially linked executable file can be left on disk and its +execute bits turned off if the link edit fails. However, if the linker +links the image in memory before writing the file to disk, it need not +touch the executable file (if it already exists) because the link edit +fails. Since both approaches are historical practice, a conforming +application shall rely on the exit status of +.IR fort77 , +rather than on the existence or mode of the executable file. +.P +The +.BR \(mig +and +.BR \(mis +options are not specified as mutually-exclusive. Historically, these two +options have been mutually-exclusive, but because both are so loosely +specified, it seemed appropriate to leave their interaction +unspecified. +.P +The requirement that conforming applications specify compiler options +separately is to reserve the multi-character option name space for +vendor-specific compiler options, which are known to exist in many +historical implementations. Implementations are not required to +recognize, for example, +.BR \(migc +as if it were +.BR \(mig +.BR \(mic ; +nor are they forbidden from doing so. The SYNOPSIS shows all of the +options separately to highlight this requirement on applications. +.P +Echoing filenames to standard error is considered a diagnostic message +because it would otherwise be difficult to associate an error message +with the erring file. They are described with ``may'' to allow +implementations to use other methods of identifying files and to +parallel the description in +.IR c99 . +.SH "FUTURE DIRECTIONS" +A compilation system based on the ISO/IEC\ 1539:\|1991 standard may be considered for a +future version; it may have a different utility name from +.IR fort77 . +.SH "SEE ALSO" +.IR "\fIar\fR\^", +.IR "\fIasa\fR\^", +.IR "\fIc99\fR\^", +.IR "\fIumask\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIexec\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/fuser.1p b/man-pages-posix-2013/man1p/fuser.1p new file mode 100644 index 0000000..1ded533 --- /dev/null +++ b/man-pages-posix-2013/man1p/fuser.1p @@ -0,0 +1,247 @@ +'\" et +.TH FUSER "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +fuser +\(em list process IDs of all processes that have one or more files open +.SH SYNOPSIS +.LP +.nf +fuser \fB[\fR\(micfu\fB] \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR fuser +utility shall write to standard output the process IDs of processes +running on the local system that have one or more named files open. +For block special devices, all processes using any file on that device +are listed. +.P +The +.IR fuser +utility shall write to standard error additional information about the +named files indicating how the file is being used. +.P +Any output for processes running on remote systems that have a named +file open is unspecified. +.P +A user may need appropriate privileges to invoke the +.IR fuser +utility. +.SH OPTIONS +The +.IR fuser +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mic\fR" 10 +The file is treated as a mount point and the utility shall report +on any files open in the file system. +.IP "\fB\(mif\fR" 10 +The report shall be only for the named files. +.IP "\fB\(miu\fR" 10 +The user name, in parentheses, associated with each process ID written +to standard output shall be written to standard error. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fP" 10 +A pathname on which the file or file system is to be reported. +.SH STDIN +Not used. +.SH "INPUT FILES" +The user database. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR fuser : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR fuser +utility shall write the process ID for each process using each file +given as an operand to standard output in the following format: +.sp +.RS 4 +.nf +\fB +"%d", <\fIprocess_id\fR> +.fi \fR +.P +.RE +.SH STDERR +The +.IR fuser +utility shall write diagnostic messages to standard error. +.P +The +.IR fuser +utility also shall write the following to standard error: +.IP " *" 4 +The pathname of each named file is written followed immediately by a +. +.IP " *" 4 +For each process ID written to standard output, the character +.BR 'c' +shall be written to standard error if the process is using the file as +its current directory and the character +.BR 'r' +shall be written to standard error if the process is using the file as +its root directory. Implementations may write other alphabetic +characters to indicate other uses of files. +.IP " *" 4 +When the +.BR \(miu +option is specified, characters indicating the use of the file shall be +followed immediately by the user name, in parentheses, corresponding to +the real user ID of the process. If the user name cannot be resolved from +the real user ID of the process, the real user ID of the process shall +be written instead of the user name. +.P +When standard output and standard error are directed to the same file, +the output shall be interleaved so that the filename appears at the +start of each line, followed by the process ID and characters +indicating the use of the file. Then, if the +.BR \(miu +option is specified, the user name or user ID for each process using +that file shall be written. +.P +A + +shall be written to standard error after the last output +described above for each +.IR file +operand. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +The command: +.sp +.RS 4 +.nf +\fB +fuser \(mifu . +.fi \fR +.P +.RE +.P +writes to standard output the process IDs of processes that are using +the current directory and writes to standard error an indication of how +those processes are using the directory and the user names associated +with the processes that are using the current directory. +.sp +.RS 4 +.nf +\fB +fuser \(mic <\fImount point\fR> +.fi \fR +.P +.RE +.P +writes to standard output the process IDs of processes that are using +any file in the file system which is mounted on <\fImount point\fR> +and writes to standard error an indication of how those processes are +using the files. +.sp +.RS 4 +.nf +\fB +fuser <\fImount point\fR> +.fi \fR +.P +.RE +.P +writes to standard output the process IDs of processes that are using +the file which is named by <\fImount point\fR> and writes to standard +error an indication of how those processes are using the file. +.sp +.RS 4 +.nf +\fB +fuser <\fIblock device\fR> +.fi \fR +.P +.RE +.P +writes to standard output the process IDs of processes that are using +any file which is on the device named by <\fIblock device\fR> and +writes to standard error an indication of how those processes are using +the file. +.sp +.RS 4 +.nf +\fB +fuser \(mif <\fIblock device\fR> +.fi \fR +.P +.RE +.P +writes to standard output the process IDs of processes that are using +the file <\fIblock device\fR> itself and writes to standard error an +indication of how those processes are using the file. +.SH RATIONALE +The definition of the +.IR fuser +utility follows existing practice. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/gencat.1p b/man-pages-posix-2013/man1p/gencat.1p new file mode 100644 index 0000000..8fa40d2 --- /dev/null +++ b/man-pages-posix-2013/man1p/gencat.1p @@ -0,0 +1,289 @@ +'\" et +.TH GENCAT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +gencat +\(em generate a formatted message catalog +.SH SYNOPSIS +.LP +.nf +gencat \fIcatfile msgfile\fR... +.fi +.SH DESCRIPTION +The +.IR gencat +utility shall merge the message text source file +.IR msgfile +into a formatted message catalog +.IR catfile . +The file +.IR catfile +shall be created if it does not already exist. If +.IR catfile +does exist, its messages shall be included in the new +.IR catfile . +If set and message numbers collide, the new message text defined in +.IR msgfile +shall replace the old message text currently contained in +.IR catfile . +.SH OPTIONS +None. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIcatfile\fR" 10 +A pathname of the formatted message catalog. If +.BR '\(mi' +is specified, standard output shall be used. The format of the message +catalog produced is unspecified. +.IP "\fImsgfile\fR" 10 +A pathname of a message text source file. If +.BR '\(mi' +is specified for an instance of +.IR msgfile , +standard input shall be used. The format of message text source files +is defined in the EXTENDED DESCRIPTION section. +.SH STDIN +The standard input shall not be used unless a +.IR msgfile +operand is specified as +.BR '\(mi' . +.SH "INPUT FILES" +The input files shall be text files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR gencat : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall not be used unless the +.IR catfile +operand is specified as +.BR '\(mi' . +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +The content of a message text file shall be in the format defined as +follows. Note that the fields of a message text source line are +separated by a single + +character. Any other + +characters are considered to be part of the subsequent field. +.IP "\fB$set\ \fIn\ comment\fR" 10 +.br +This line specifies the set identifier of the following messages until +the next +.BR $set +or end-of-file appears. The +.IR n +denotes the set identifier, which is defined as a number in the range +[1, +{NL_SETMAX}] +(see the +.IR +header defined in the Base Definitions volume of POSIX.1\(hy2008). The application shall ensure that set +identifiers are presented in ascending order within a single source +file, but need not be contiguous. Any string following the set +identifier shall be treated as a comment. If no +.BR $set +directive is specified in a message text source file, all messages +shall be located in an implementation-defined default message set +NL_SETD (see the +.IR +header defined in the Base Definitions volume of POSIX.1\(hy2008). +.IP "\fB$delset\ \fIn\ comment\fR" 10 +.br +This line deletes message set +.IR n +from an existing message catalog. The +.IR n +denotes the set number [1, +{NL_SETMAX}]. +Any string following the set number shall be treated as a comment. +.IP "\fB$\ \fIcomment\fR" 10 +A line beginning with +.BR '$' +followed by a + +shall be treated as a comment. +.IP "\fIm\ message-text\fR" 10 +.br +The +.IR m +denotes the message identifier, which is defined as a number in the +range [1, +{NL_MSGMAX}] +(see the +.IR +header). The +.IR message-text +shall be stored in the message catalog with the set identifier +specified by the last +.BR $set +directive, and with message identifier +.IR m . +If the +.IR message-text +is empty, and a + +field separator is present, an empty string shall be stored +in the message catalog. If a message source line has a message number, +but neither a field separator nor +.IR message-text , +the existing message with that number (if any) shall be deleted from +the catalog. The application shall ensure that message identifiers are +in ascending order within a single set, but need not be contiguous. The +application shall ensure that the length of +.IR message-text +is in the range [0, +{NL_TEXTMAX}] +(see the +.IR +header). +.IP "\fB$quote\ \fIn\fR" 10 +This line specifies an optional quote character +.IR c , +which can be used to surround +.IR message-text +so that trailing + +characters or null (empty) messages are visible in a message source +line. By default, or if an empty +.BR $quote +directive is supplied, no quoting of +.IR message-text +shall be recognized. +.P +Empty lines in a message text source file shall be ignored. The +effects of lines starting with any character other than those defined +above are implementation-defined. +.P +Text strings can contain the special characters and escape sequences +defined in the following table: +.TS +center tab(@) box; +cB | cB | cB +l | l | lf5. +Description@Symbol@Sequence +_ +@NL(LF)@\en +Horizontal-tab@HT@\et +@VT@\ev +@BS@\eb +@CR@\er +@FF@\ef +Backslash@\fR\e\fP@\e\e +Bit pattern@\fRddd\fP@\eddd +.TE +.P +The escape sequence +.BR \(dq\eddd\(dq +consists of + +followed by one, two, or three octal digits, which shall be taken to +specify the value of the desired character. If the character following a + +is not one of those specified, the + +shall be ignored. +.P +A + +followed by a + +is also used to continue a string on the following line. Thus, the +following two lines describe a single message string: +.sp +.RS 4 +.nf +\fB +1 This line continues \e +to the next line +.fi \fR +.P +.RE +.P +which shall be equivalent to: +.sp +.RS 4 +.nf +\fB +1 This line continues to the next line +.fi \fR +.P +.RE +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Message catalogs produced by +.IR gencat +are binary encoded, meaning that their portability cannot be guaranteed +between different types of machine. Thus, just as C programs need to +be recompiled for each type of machine, so message catalogs must be +recreated via +.IR gencat . +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiconv\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/get.1p b/man-pages-posix-2013/man1p/get.1p new file mode 100644 index 0000000..c1f1e81 --- /dev/null +++ b/man-pages-posix-2013/man1p/get.1p @@ -0,0 +1,848 @@ +'\" et +.TH GET "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +get +\(em get a version of an SCCS file (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +get \fB[\fR\(mibegkmnlLpst\fB] [\fR\(mic \fIcutoff\fB] [\fR\(mii \fIlist\fB] [\fR\(mir \fISID\fB] [\fR\(mix \fIlist\fB] \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR get +utility shall generate a text file from each named SCCS +.IR file +according to the specifications given by its options. +.P +The generated text shall normally be written into a file called the +.BR g-file +whose name is derived from the SCCS filename by simply removing the +leading +.BR \(dqs.\(dq . +.SH OPTIONS +The +.IR get +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mir\ \fISID\fR" 10 +Indicate the SCCS Identification String (SID) of the version (delta) +of an SCCS file to be retrieved. The table shows, for the most useful +cases, what version of an SCCS file is retrieved (as well as the SID of +the version to be eventually created by +.IR delta +if the +.BR \(mie +option is also used), as a function of the SID specified. +.IP "\fB\(mic\ \fIcutoff\fR" 10 +Indicate the +.IR cutoff +date-time, in the form: +.RS 10 +.sp +.RS 4 +.nf +\fB +\fIYY\fB[\fIMM\fB[\fIDD\fB[\fIHH\fB[\fIMM\fB[\fISS\fB]]]]]\fR +.fi \fR +.P +.RE +.P +For the +.IR YY +component, 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. +.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 +.P +No changes (deltas) to the SCCS file that were created after the +specified +.IR cutoff +date-time shall be included in the generated text file. Units omitted +from the date-time default to their maximum possible values; for +example, +.BR \(mic +7502 is equivalent to +.BR \(mic +750228235959. +.P +Any number of non-numeric characters may separate the various 2-digit +pieces of the +.IR cutoff +date-time. This feature allows the user to specify a +.IR cutoff +date in the form: +.BR \(mic +"77/2/2\09:22:25". +.RE +.IP "\fB\(mie\fR" 10 +Indicate that the +.IR get +is for the purpose of editing or making a change (delta) to the SCCS +file via a subsequent use of +.IR delta . +The +.BR \(mie +option used in a +.IR get +for a particular version (SID) of the SCCS file shall prevent further +.IR get +commands from editing on the same SID until +.IR delta +is executed or the +.BR j +(joint edit) flag is set in the SCCS file. Concurrent use of +.IR get +.BR \(mie +for different SIDs is always allowed. +.RS 10 +.P +If the +.BR g-file +generated by +.IR get +with a +.BR \(mie +option is accidentally ruined in the process of editing, it may be +regenerated by re-executing the +.IR get +command with the +.BR \(mik +option in place of the +.BR \(mie +option. +.P +SCCS file protection specified via the ceiling, floor, and authorized +user list stored in the SCCS file shall be enforced when the +.BR \(mie +option is used. +.RE +.IP "\fB\(mib\fR" 10 +Use with the +.BR \(mie +option to indicate that the new delta should have an SID in a new +branch as shown in the table below. This option shall be ignored if the +.BR b +flag is not present in the file or if the retrieved delta is not a leaf +delta. (A leaf delta is one that has no successors on the SCCS file tree.) +.RS 10 +.TP 10 +.BR Note: +A branch delta may always be created from a non-leaf delta. +.P +.RE +.IP "\fB\(mii\ \fIlist\fR" 10 +Indicate a +.IR list +of deltas to be included (forced to be applied) in the creation of the +generated file. The +.IR list +has the following syntax: +.RS 10 +.sp +.RS 4 +.nf +\fB + ::= | , + ::= SID | SID \(mi SID +.fi \fR +.P +.RE +.P +SID, the SCCS Identification of a delta, may be in any form shown in +the ``SID Specified'' column of the table in the EXTENDED DESCRIPTION +section, except that the result of supplying a partial SID is +unspecified. A diagnostic message shall be written if the first SID in +the range is not an ancestor of the second SID in the range. +.RE +.IP "\fB\(mix\ \fIlist\fR" 10 +Indicate a +.IR list +of deltas to be excluded (forced not to be applied) in the creation of +the generated file. See the +.BR \(mii +option for the +.IR list +format. +.IP "\fB\(mik\fR" 10 +Suppress replacement of identification keywords (see below) in the +retrieved text by their value. The +.BR \(mik +option shall be implied by the +.BR \(mie +option. +.IP "\fB\(mil\fR" 10 +Write a delta summary into an +.BR l-file . +.IP "\fB\(miL\fR" 10 +Write a delta summary to standard output. All informative output that +normally is written to standard output shall be written to standard +error instead, unless the +.BR \(mis +option is used, in which case it shall be suppressed. +.IP "\fB\(mip\fR" 10 +Write the text retrieved from the SCCS file to the standard output. No +.BR g-file +shall be created. All informative output that normally goes to the +standard output shall go to standard error instead, unless the +.BR \(mis +option is used, in which case it shall disappear. +.IP "\fB\(mis\fR" 10 +Suppress all informative output normally written to standard output. +However, fatal error messages (which shall always be written to the +standard error) shall remain unaffected. +.IP "\fB\(mim\fR" 10 +Precede each text line retrieved from the SCCS file by the SID of the +delta that inserted the text line in the SCCS file. The format shall be: +.RS 10 +.sp +.RS 4 +.nf +\fB +"%s\et%s", <\fISID\fR>, <\fItext line\fR> +.fi \fR +.P +.RE +.RE +.IP "\fB\(min\fR" 10 +Precede each generated text line with the %\fBM\fP% identification +keyword value (see below). The format shall be: +.RS 10 +.sp +.RS 4 +.nf +\fB +"%s\et%s", <\fI%M% value\fR>, <\fItext line\fR> +.fi \fR +.P +.RE +.P +When both the +.BR \(mim +and +.BR \(min +options are used, the <\fItext\ line\fP> shall be replaced by the +.BR \(mim +option-generated format. +.RE +.IP "\fB\(mig\fR" 10 +Suppress the actual retrieval of text from the SCCS file. It is +primarily used to generate an +.BR l-file , +or to verify the existence of a particular SID. +.IP "\fB\(mit\fR" 10 +Use to access the most recently created (top) delta in a given release +(for example, +.BR "\(mir 1" ), +or release and level (for example, +.BR "\(mir 1.2" ). +.br +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an existing SCCS file or a directory. If +.IR file +is a directory, the +.IR get +utility shall behave as though each file in the directory were +specified as a named file, except that non-SCCS files (last component +of the pathname does not begin with +.BR s. ) +and unreadable files shall be silently ignored. +.RS 10 +.P +If exactly one +.IR file +operand appears, and it is +.BR '\(mi' , +the standard input shall be read; each line of the standard input is +taken to be the name of an SCCS file to be processed. Non-SCCS files +and unreadable files shall be silently ignored. +.RE +.SH STDIN +The standard input shall be a text file used only if the +.IR file +operand is specified as +.BR '\(mi' . +Each line of the text file shall be interpreted as an SCCS pathname. +.SH "INPUT FILES" +The SCCS files shall be files of an unspecified format. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR get : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error, and +informative messages written to standard output (or standard error, if +the +.BR \(mip +option is used). +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITZ\fR" 10 +Determine the timezone in which the times and dates written in the +SCCS file are evaluated. If the +.IR TZ +variable is unset or NULL, an unspecified system default timezone is +used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +For each file processed, +.IR get +shall write to standard output the SID being accessed and the number of +lines retrieved from the SCCS file, in the following format: +.sp +.RS 4 +.nf +\fB +"%s\en%d lines\en", <\fISID\fR>, <\fInumber of lines\fR> +.fi \fR +.P +.RE +.P +If the +.BR \(mie +option is used, the SID of the delta to be made shall appear after the +SID accessed and before the number of lines generated, in the POSIX +locale: +.sp +.RS 4 +.nf +\fB +"%s\ennew delta %s\en%d lines\en", <\fISID accessed\fR>, + <\fISID to be made\fR>, <\fInumber of lines\fR> +.fi \fR +.P +.RE +.P +If there is more than one named file or if a directory or standard +input is named, each pathname shall be written before each of the lines +shown in one of the preceding formats: +.sp +.RS 4 +.nf +\fB +"\en%s:\en", <\fIpathname\fR> +.fi \fR +.P +.RE +.P +If the +.BR \(miL +option is used, a delta summary shall be written following the format +specified below for +.BR l-files . +.P +If the +.BR \(mii +option is used, included deltas shall be listed following the notation, +in the POSIX locale: +.sp +.RS 4 +.nf +\fB +"Included:\en" +.fi \fR +.P +.RE +.P +If the +.BR \(mix +option is used, excluded deltas shall be listed following the notation, +in the POSIX locale: +.sp +.RS 4 +.nf +\fB +"Excluded:\en" +.fi \fR +.P +.RE +.P +If the +.BR \(mip +or +.BR \(miL +options are specified, the standard output shall consist of the text +retrieved from the SCCS file. +.SH STDERR +The standard error shall be used only for diagnostic messages, except +if the +.BR \(mip +or +.BR \(miL +options are specified, it shall include all informative messages +normally sent to standard output. +.SH "OUTPUT FILES" +Several auxiliary files may be created by +.IR get . +These files are known generically as the +.BR g-file , +.BR l-file , +.BR p-file , +and +.BR z-file . +The letter before the + +is called the +.IR tag . +An auxiliary filename shall be formed from the SCCS filename: the +application shall ensure that the last component of all SCCS filenames +is of the form +.BR s. \c +.IR module-name ; +the auxiliary files shall be named by replacing the leading +.BR s +with the tag. The +.BR g-file +shall be an exception to this scheme: the +.BR g-file +is named by removing the +.BR s. +prefix. For example, for +.BR s.xyz.c , +the auxiliary filenames would be +.BR xyz.c , +.BR l.xyz.c , +.BR p.xyz.c , +and +.BR z.xyz.c , +respectively. +.P +The +.BR g-file , +which contains the generated text, shall be created in the current +directory (unless the +.BR \(mip +option is used). A +.BR g-file +shall be created in all cases, whether or not any lines of text were +generated by the +.IR get . +It shall be owned by the real user. If the +.BR \(mik +option is used or implied, the +.BR g-file +shall be writable by the owner only (read-only for everyone else); +otherwise, it shall be read-only. Only the real user need have write +permission in the current directory. +.P +The +.BR l-file +shall contain a table showing which deltas were applied in generating +the retrieved text. The +.BR l-file +shall be created in the current directory if the +.BR \(mil +option is used; it shall be read-only and it is owned by the real user. +Only the real user need have write permission in the current +directory. +.P +Lines in the +.BR l-file +shall have the following format: +.sp +.RS 4 +.nf +\fB +"%c%c%c %s\et%s %s\en", <\fIcode1\fR>, <\fIcode2\fR>, <\fIcode3\fR>, + <\fISID\fR>, <\fIdate-time\fR>, <\fIlogin\fR> +.fi \fR +.P +.RE +.P +where the entries are: +.IP "<\fIcode1\fP>" 10 +A + +if the delta was applied; +.BR '*' +otherwise. +.IP "<\fIcode2\fP>" 10 +A + +if the delta was applied or was not applied and ignored; +.BR '*' +if the delta was not applied and was not ignored. +.IP "<\fIcode3\fP>" 10 +A character indicating a special reason why the delta was or was not +applied: +.RS 10 +.IP "\fBI\fP" 6 +Included. +.IP "\fBX\fP" 6 +Excluded. +.IP "\fBC\fP" 6 +Cut off (by a +.BR \(mic +option). +.RE +.IP "<\fIdate-time\fP>" 10 +Date and time (using the format of the +.IR date +utility's +.BR %y /\c +.BR %m /\c +.BR %d +.BR %T +conversion specification format) of creation. +.IP "<\fIlogin\fP>" 10 +Login name of person who created +.IR delta . +.P +The comments and MR data shall follow on subsequent lines, indented one +. +A blank line shall terminate each entry. +.P +The +.BR p-file +shall be used to pass information resulting from a +.IR get +with a +.BR \(mie +option along to +.IR delta . +Its contents shall also be used to prevent a subsequent execution of +.IR get +with a +.BR \(mie +option for the same SID until +.IR delta +is executed or the joint edit flag, +.BR j , +is set in the SCCS file. The +.BR p-file +shall be created in the directory containing the SCCS file and the +application shall ensure that the effective user has write permission +in that directory. It shall be writable by owner only, and owned +by the effective user. Each line in the +.BR p-file +shall have the following format: +.sp +.RS 4 +.nf +\fB +"%s %s %s %s%s%s\en", <\fIg-file SID\fR>, + <\fISID of new delta\fR>, <\fIlogin-name of real user\fR>, + <\fIdate-time\fR>, <\fIi-value\fR>, <\fIx-value\fR> +.fi \fR +.P +.RE +.P +where <\fIi\(hyvalue\fP> uses the format +.BR \(dq\^\(dq +if no +.BR \(mii +option was specified, and shall use the format: +.sp +.RS 4 +.nf +\fB +" \(mii%s", <\(mii option \fIoption-argument\fR> +.fi \fR +.P +.RE +.P +if a +.BR \(mii +option was specified and <\fIx\(hyvalue\fP> uses the format +.BR \(dq\^\(dq +if no +.BR \(mix +option was specified, and shall use the format: +.sp +.RS 4 +.nf +\fB +" \(mix%s", <\(mix option \fIoption-argument\fR> +.fi \fR +.P +.RE +.P +if a +.BR \(mix +option was specified. There can be an arbitrary number of lines in the +.BR p-file +at any time; no two lines shall have the same new delta SID. +.P +The +.BR z-file +shall serve as a lock-out mechanism against simultaneous updates. Its +contents shall be the binary process ID of the command (that is, +.IR get ) +that created it. The +.BR z-file +shall be created in the directory containing the SCCS file for the +duration of +.IR get . +The same protection restrictions as those for the +.BR p-file +shall apply for the +.BR z-file . +The +.BR z-file +shall be created read-only. +.br +.SH "EXTENDED DESCRIPTION" +.TS +center tab(@) box; +cB s s s s +cB cB cB cB cB +cB cB cB cB cB +l c lw(4.5c) l l. +Determination of SCCS Identification String += +SID*@\(mib Keyletter@Other@SID@SID of Delta +Specified@Used\(dg@Conditions@Retrieved@to be Created +.sp 1.5p += +none\(dd@no@R defaults to mR@mR.mL@mR.(mL+1) +_ +none\(dd@yes@R defaults to mR@mR.mL@mR.mL.(mB+1).1 +.sp 1.5p += +R@no@R > mR@mR.mL@R.1*** +_ +R@no@R = mR@mR.mL@mR.(mL+1) +_ +R@yes@R > mR@mR.mL@mR.mL.(mB+1).1 +_ +R@yes@R = mR@mR.mL@mR.mL.(mB+1).1 +_ +R@\(mi@T{ +R < mR and +R does not exist +T}@hR.mL**@hR.mL.(mB+1).1 +_ +R@\(mi@T{ +Trunk successor in release > R +and R exists +T}@R.mL@R.mL.(mB+1).1 +.sp 1.5p += +R.L@no@No trunk successor@R.L@R.(L+1) +_ +R.L@yes@No trunk successor@R.L@R.L.(mB+1).1 +_ +R.L@\(mi@T{ +Trunk successor +in release \(>= R +T}@R.L@R.L.(mB+1).1 +.sp 1.5p += +R.L.B@no@No branch successor@R.L.B.mS@R.L.B.(mS+1) +_ +R.L.B@yes@No branch successor@R.L.B.mS@R.L.(mB+1).1 +.sp 1.5p += +R.L.B.S@no@No branch successor@R.L.B.S@R.L.B.(S+1) +_ +R.L.B.S@yes@No branch successor@R.L.B.S@R.L.(mB+1).1 +_ +R.L.B.S@\(mi@Branch successor@R.L.B.S@R.L.(mB+1).1 +.TE +.IP * 8 +R, L, B, and S are the release, level, branch, and sequence components +of the SID, respectively; m means maximum. Thus, for example, R.mL +means ``the maximum level number within release R''; R.L.(mB+1).1 means +``the first sequence number on the new branch (that is, maximum branch +number plus one) of level L within release R''. Note that if the SID +specified is of the form R.L, R.L.B, or R.L.B.S, each of the specified +components shall exist. +.IP ** 8 +hR is the highest existing release that is lower than the specified, +nonexistent, release R. +.IP *** 8 +This is used to force creation of the first delta in a new release. +.IP "\(dg" 8 +The +.BR \(mib +option is effective only if the +.BR b +flag is present in the file. An entry of +.BR '\(mi' +means ``irrelevant''. +.IP "\(dd" 8 +This case applies if the +.BR d +(default SID) flag is not present in the file. If the +.BR d +flag is present in the file, then the SID obtained from the +.BR d +flag is interpreted as if it had been specified on the command line. +Thus, one of the other cases in this table applies. +.SS "System Date and Time" +.P +When a +.BR g-file +is generated, the creation time of deltas in the SCCS file may be taken +into account. If any of these times are apparently in the future, the +behavior is unspecified. +.SS "Identification Keywords" +.P +Identifying information shall be inserted into the text retrieved from +the SCCS file by replacing identification keywords with their value +wherever they occur. The following keywords may be used in the text +stored in an SCCS file: +.IP "%\fBM\fP%" 10 +Module name: either the value of the +.BR m +flag in the file, or if absent, the name of the SCCS file with the +leading +.BR s. +removed. +.IP "%\fBI\fP%" 10 +SCCS identification (SID) (%\fBR\fR%.%\fBL\fR% or +%\fBR\fR%.%\fBL\fR%.%\fBB\fR%.%\fBS\fR%) of the retrieved text. +.IP "%\fBR\fP%" 10 +Release. +.IP "%\fBL\fP%" 10 +Level. +.IP "%\fBB\fP%" 10 +Branch. +.IP "%\fBS\fP%" 10 +Sequence. +.IP "%\fBD\fP%" 10 +Current date (\fIYY\fR/\fIMM\fR/\fIDD\fR). +.IP "%\fBH\fP%" 10 +Current date (\fIMM\fR/\fIDD\fR/\fIYY\fR). +.IP "%\fBT\fP%" 10 +Current time (\fIHH\fR:\fIMM\fR:\fISS\fR). +.IP "%\fBE\fP%" 10 +Date newest applied delta was created (\fIYY\fR/\fIMM\fR/\fIDD\fR). +.IP "%\fBG\fP%" 10 +Date newest applied delta was created (\fIMM\fR/\fIDD\fR/\fIYY\fR). +.IP "%\fBU\fP%" 10 +Time newest applied delta was created (\fIHH\fR:\fIMM\fR:\fISS\fR). +.IP "%\fBY\fP%" 10 +Module type: value of the +.BR t +flag in the SCCS file. +.IP "%\fBF\fP%" 10 +SCCS filename. +.IP "%\fBP\fP%" 10 +SCCS absolute pathname. +.IP "%\fBQ\fP%" 10 +The value of the +.BR q +flag in the file. +.IP "%\fBC\fP%" 10 +Current line number. This keyword is intended for identifying messages +output by the program, such as ``this should not have happened'' type +errors. It is not intended to be used on every line to provide +sequence numbers. +.IP "%\fBZ\fP%" 10 +The four-character string +.BR \(dq@(#)\(dq +recognizable by +.IR what . +.IP "%\fBW\fP%" 10 +A shorthand notation for constructing +.IR what +strings: +.RS 10 +.sp +.RS 4 +.nf +\fB +%\^W\^%=%\^Z\^%%\^M\^%%\^I\^% +.fi \fR +.P +.RE +.RE +.IP "%\fBA\fP%" 10 +Another shorthand notation for constructing +.IR what +strings: +.RS 10 +.sp +.RS 4 +.nf +\fB +%\^A\^%=%\^Z\^%%\^Y\^%%\^M\^%%\^I\^%%\^Z\^% +.fi \fR +.P +.RE +.RE +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Problems can arise if the system date and time have been modified (for +example, put forward and then back again, or unsynchronized clocks +across a network) and can also arise when different values of the +.IR TZ +environment variable are used. +.P +Problems of a similar nature can also arise for the operation of the +.IR delta +utility, which compares the previous file body against the working file +as part of its normal operation. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIadmin\fR\^", +.IR "\fIdelta\fR\^", +.IR "\fIprs\fR\^", +.IR "\fIwhat\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/getconf.1p b/man-pages-posix-2013/man1p/getconf.1p new file mode 100644 index 0000000..484bdf3 --- /dev/null +++ b/man-pages-posix-2013/man1p/getconf.1p @@ -0,0 +1,443 @@ +'\" et +.TH GETCONF "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getconf +\(em get configuration values +.SH SYNOPSIS +.LP +.nf +getconf \fB[\fR\(miv specification\fB] \fIsystem_var\fR +.P +getconf \fB[\fR\(miv specification\fB] \fIpath_var pathname\fR +.fi +.SH DESCRIPTION +In the first synopsis form, the +.IR getconf +utility shall write to the standard output the value of the variable +specified by the +.IR system_var +operand. +.P +In the second synopsis form, the +.IR getconf +utility shall write to the standard output the value of the variable +specified by the +.IR path_var +operand for the path specified by the +.IR pathname +operand. +.P +The value of each configuration variable shall be determined as if it +were obtained by calling the function from which it is defined to be +available by this volume of POSIX.1\(hy2008 or by the System Interfaces volume of POSIX.1\(hy2008 (see the OPERANDS section). The +value shall reflect conditions in the current operating environment. +.SH OPTIONS +The +.IR getconf +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(miv\ \fIspecification\fR" 10 +.br +Indicate a specific specification and version for which configuration +variables shall be determined. If this option is not specified, the +values returned correspond to an implementation default conforming +compilation environment. +.RS 10 +.P +If the command: +.sp +.RS 4 +.nf +\fB +getconf _POSIX_V7_ILP32_OFF32 +.fi \fR +.P +.RE +.P +does not write +.BR \(dq\(mi1\en\(dq +or +.BR \(dqundefined\en\(dq +to standard output, then commands of the form: +.sp +.RS 4 +.nf +\fB +getconf \(miv POSIX_V7_ILP32_OFF32 ... +.fi \fR +.P +.RE +.P +determine values for configuration variables corresponding to the +POSIX_V7_ILP32_OFF32 compilation environment specified in +.IR "\fIc99\fR\^", +the EXTENDED DESCRIPTION. +.P +If the command: +.sp +.RS 4 +.nf +\fB +getconf _POSIX_V7_ILP32_OFFBIG +.fi \fR +.P +.RE +.P +does not write +.BR \(dq\(mi1\en\(dq +or +.BR \(dqundefined\en\(dq +to standard output, then commands of the form: +.sp +.RS 4 +.nf +\fB +getconf \(miv POSIX_V7_ILP32_OFFBIG ... +.fi \fR +.P +.RE +.P +determine values for configuration variables corresponding to the +POSIX_V7_ILP32_OFFBIG compilation environment specified in +.IR "\fIc99\fR\^", +the EXTENDED DESCRIPTION. +.P +If the command: +.sp +.RS 4 +.nf +\fB +getconf _POSIX_V7_LP64_OFF64 +.fi \fR +.P +.RE +.P +does not write +.BR \(dq\(mi1\en\(dq +or +.BR \(dqundefined\en\(dq +to standard output, then commands of the form: +.sp +.RS 4 +.nf +\fB +getconf \(miv POSIX_V7_LP64_OFF64 ... +.fi \fR +.P +.RE +.P +determine values for configuration variables corresponding to the +POSIX_V7_LP64_OFF64 compilation environment specified in +.IR "\fIc99\fR\^", +the EXTENDED DESCRIPTION. +.P +If the command: +.sp +.RS 4 +.nf +\fB +getconf _POSIX_V7_LPBIG_OFFBIG +.fi \fR +.P +.RE +.P +does not write +.BR \(dq\(mi1\en\(dq +or +.BR \(dqundefined\en\(dq +to standard output, then commands of the form: +.sp +.RS 4 +.nf +\fB +getconf \(miv POSIX_V7_LPBIG_OFFBIG ... +.fi \fR +.P +.RE +.P +determine values for configuration variables corresponding to the +POSIX_V7_LPBIG_OFFBIG compilation environment specified in +.IR "\fIc99\fR\^", +the EXTENDED DESCRIPTION. +.RE +.SH OPERANDS +The following operands shall be supported: +.IP "\fIpath_var\fR" 10 +A name of a configuration variable. All of the variables in the +Variable column of the table in the DESCRIPTION of the +\fIfpathconf\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008, without the enclosing braces, shall be +supported. The implementation may add other local variables. +.IP "\fIpathname\fR" 10 +A pathname for which the variable specified by +.IR path_var +is to be determined. +.IP "\fIsystem_var\fR" 10 +A name of a configuration variable. All of the following variables +shall be supported: +.RS 10 +.IP " *" 4 +The names in the Variable column of the table in the DESCRIPTION of the +\fIsysconf\fR() +function in the System Interfaces volume of POSIX.1\(hy2008, except for the entries corresponding to +_SC_CLK_TCK, _SC_GETGR_R_SIZE_MAX, and _SC_GETPW_R_SIZE_MAX, without +the enclosing braces. +.RS 4 +.P +For compatibility with earlier versions, the following variable names +shall also be supported: +POSIX2_C_BIND +POSIX2_C_DEV +POSIX2_CHAR_TERM +POSIX2_FORT_DEV +POSIX2_FORT_RUN +POSIX2_LOCALEDEF +POSIX2_SW_DEV +POSIX2_UPE +POSIX2_VERSION +.P +and shall be equivalent to the same name prefixed with an +. +This requirement may be removed in a future version. +.RE +.IP " *" 4 +The names of the symbolic constants used as the +.IR name +argument of the +\fIconfstr\fR() +function in the System Interfaces volume of POSIX.1\(hy2008, without the _CS_ prefix. +.IP " *" 4 +The names of the symbolic constants listed under the headings ``Maximum +Values'' and ``Minimum Values'' in the description of the +.IR +header in the Base Definitions volume of POSIX.1\(hy2008, without the enclosing braces. +.RS 4 +.P +For compatibility with earlier versions, the following variable names +shall also be supported: +POSIX2_BC_BASE_MAX +POSIX2_BC_DIM_MAX +POSIX2_BC_SCALE_MAX +POSIX2_BC_STRING_MAX +POSIX2_COLL_WEIGHTS_MAX +POSIX2_EXPR_NEST_MAX +POSIX2_LINE_MAX +POSIX2_RE_DUP_MAX +.P +and shall be equivalent to the same name prefixed with an +. +This requirement may be removed in a future version. +.RE +.P +The implementation may add other local values. +.RE +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR getconf : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If the specified variable is defined on the system and its value is +described to be available from the +\fIconfstr\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008, its value shall be written in the +following format: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIvalue\fR> +.fi \fR +.P +.RE +.P +Otherwise, if the specified variable is defined on the system, its +value shall be written in the following format: +.sp +.RS 4 +.nf +\fB +"%d\en", <\fIvalue\fR> +.fi \fR +.P +.RE +.P +If the specified variable is valid, but is undefined on the system, +.IR getconf +shall write using the following format: +.sp +.RS 4 +.nf +\fB +"undefined\en" +.fi \fR +.P +.RE +.P +If the variable name is invalid or an error occurs, nothing shall be +written to standard output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The specified variable is valid and information about its current state +was written successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +The following example illustrates the value of +{NGROUPS_MAX}: +.sp +.RS 4 +.nf +\fB +getconf NGROUPS_MAX +.fi \fR +.P +.RE +.P +The following example illustrates the value of +{NAME_MAX} +for a specific directory: +.sp +.RS 4 +.nf +\fB +getconf NAME_MAX /usr +.fi \fR +.P +.RE +.P +The following example shows how to deal more carefully with results +that might be unspecified: +.sp +.RS 4 +.nf +\fB +if value=$(getconf PATH_MAX /usr); then + if [ "$value" = "undefined" ]; then + echo PATH_MAX in /usr is indeterminate. + else + echo PATH_MAX in /usr is $value. + fi +else + echo Error in getconf. +fi +.fi \fR +.P +.RE +.SH RATIONALE +The original need for this utility, and for the +\fIconfstr\fR() +function, was to provide a way of finding the configuration-defined +default value for the +.IR PATH +environment variable. Since +.IR PATH +can be modified by the user to include directories that could contain +utilities replacing the standard utilities, shell scripts need +a way to determine the system-supplied +.IR PATH +environment variable value that contains the correct search path for +the standard utilities. It was later suggested that access to the other +variables described in this volume of POSIX.1\(hy2008 could also be useful to applications. +.P +This functionality of +.IR getconf +would not be adequately subsumed by another command such as: +.sp +.RS 4 +.nf +\fB +grep \fIvar\fP /etc/conf +.fi \fR +.P +.RE +.P +because such a strategy would provide correct values for neither those +variables that can vary at runtime, nor those that can vary depending +on the path. +.P +Early proposal versions of +.IR getconf +specified exit status 1 when the specified variable was valid, but not +defined on the system. The output string +.BR \(dqundefined\(dq +is now used to specify this case with exit code 0 because so many +things depend on an exit code of zero when an invoked utility is +successful. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIc99\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIconfstr\fR\^(\|)", +.IR "\fIfpathconf\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)", +.IR "\fIsystem\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/getopts.1p b/man-pages-posix-2013/man1p/getopts.1p new file mode 100644 index 0000000..baf210d --- /dev/null +++ b/man-pages-posix-2013/man1p/getopts.1p @@ -0,0 +1,445 @@ +'\" et +.TH GETOPTS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +getopts +\(em parse utility options +.SH SYNOPSIS +.LP +.nf +getopts \fIoptstring name \fB[\fIarg\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR getopts +utility shall retrieve options and option-arguments from a list of +parameters. It shall support the Utility Syntax Guidelines 3 to 10, +inclusive, described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +Each time it is invoked, the +.IR getopts +utility shall place the value of the next option in the shell variable +specified by the +.IR name +operand and the index of the next argument to be processed in the shell +variable +.IR OPTIND . +Whenever the shell is invoked, +.IR OPTIND +shall be initialized to 1. +.P +When the option requires an option-argument, the +.IR getopts +utility shall place it in the shell variable +.IR OPTARG . +If no option was found, or if the option that was found does not have +an option-argument, +.IR OPTARG +shall be unset. +.P +If an option character not contained in the +.IR optstring +operand is found where an option character is expected, the shell +variable specified by +.IR name +shall be set to the + +(\c +.BR '?' ) +character. In this case, if the first character in +.IR optstring +is a + +(\c +.BR ':' ), +the shell variable +.IR OPTARG +shall be set to the option character found, but no output shall be +written to standard error; otherwise, the shell variable +.IR OPTARG +shall be unset and a diagnostic message shall be written to standard +error. This condition shall be considered to be an error detected in +the way arguments were presented to the invoking application, but shall +not be an error in +.IR getopts +processing. +.P +If an option-argument is missing: +.IP " *" 4 +If the first character of +.IR optstring +is a +, +the shell variable specified by +.IR name +shall be set to the + +character and the shell variable +.IR OPTARG +shall be set to the option character found. +.IP " *" 4 +Otherwise, the shell variable specified by +.IR name +shall be set to the + +character, the shell variable +.IR OPTARG +shall be unset, and a diagnostic message shall be written to standard +error. This condition shall be considered to be an error detected in +the way arguments were presented to the invoking application, but shall +not be an error in +.IR getopts +processing; a diagnostic message shall be written as stated, but the +exit status shall be zero. +.P +When the end of options is encountered, the +.IR getopts +utility shall exit with a return value greater than zero; the shell +variable +.IR OPTIND +shall be set to the index of the first operand, or the value +.BR \(dq$#\(dq +1 +if there are no operands; the +.IR name +variable shall be set to the + +character. Any of the following shall identify the end of options: +the first +.BR \(dq\(mi\|\(mi\(dq +argument that is not an option-argument, finding an argument that is +not an option-argument and does not begin with a +.BR '\(mi' , +or encountering an error. +.P +The shell variables +.IR OPTIND +and +.IR OPTARG +shall be local to the caller of +.IR getopts +and shall not be exported by default. +.P +The shell variable specified by the +.IR name +operand, +.IR OPTIND , +and +.IR OPTARG +shall affect the current shell execution environment; see +.IR "Section 2.12" ", " "Shell Execution Environment". +.P +If the application sets +.IR OPTIND +to the value 1, a new set of parameters can be used: either the +current positional parameters or new +.IR arg +values. Any other attempt to invoke +.IR getopts +multiple times in a single shell execution environment with parameters +(positional parameters or +.IR arg +operands) that are not the same in all invocations, or with an +.IR OPTIND +value modified to be a value other than 1, produces unspecified +results. +.SH OPTIONS +None. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIoptstring\fR" 10 +A string containing the option characters recognized by the utility +invoking +.IR getopts . +If a character is followed by a +, +the option shall be expected to have an argument, which should be supplied +as a separate argument. Applications should specify an option character +and its option-argument as separate arguments, but +.IR getopts +shall interpret the characters following an option character requiring +arguments as an argument whether or not this is done. An explicit null +option-argument need not be recognized if it is not supplied as a +separate argument when +.IR getopts +is invoked. (See also the +\fIgetopt\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008.) The characters + +and + +shall not be used as option characters by an application. The use of +other option characters that are not alphanumeric produces unspecified +results. If the option-argument is not supplied as a separate argument +from the option character, the value in +.IR OPTARG +shall be stripped of the option character and the +.BR '\(mi' . +The first character in +.IR optstring +determines how +.IR getopts +behaves if an option character is not known or an option-argument is +missing. +.IP "\fIname\fR" 10 +The name of a shell variable that shall be set by the +.IR getopts +utility to the option character that was found. +.P +The +.IR getopts +utility by default shall parse positional parameters passed to the +invoking shell procedure. If +.IR arg s +are given, they shall be parsed instead of the positional parameters. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR getopts : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIOPTIND\fP" 10 +This variable shall be used by the +.IR getopts +utility as the index of the next argument to be processed. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +Whenever an error is detected and the first character in the +.IR optstring +operand is not a + +(\c +.BR ':' ), +a diagnostic message shall be written to standard error with the +following information in an unspecified format: +.IP " *" 4 +The invoking program name shall be identified in the message. The +invoking program name shall be the value of the shell special parameter +0 (see +.IR "Section 2.5.2" ", " "Special Parameters") +at the time the +.IR getopts +utility is invoked. A name equivalent to: +.RS 4 +.sp +.RS 4 +.nf +\fB +basename "$0" +.fi \fR +.P +.RE +.P +may be used. +.RE +.IP " *" 4 +If an option is found that was not specified in +.IR optstring , +this error is identified and the invalid option character shall be +identified in the message. +.IP " *" 4 +If an option requiring an option-argument is found, but an +option-argument is not found, this error shall be identified and the +invalid option character shall be identified in the message. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +An option, specified or unspecified by +.IR optstring , +was found. +.IP >0 6 +The end of options was encountered or an error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Since +.IR getopts +affects the current shell execution environment, it is generally +provided as a shell regular built-in. If it is called in a subshell or +separate utility execution environment, such as one of the following: +.sp +.RS 4 +.nf +\fB +(getopts abc value "$@") +nohup getopts ... +find . \(miexec getopts ... \e; +.fi \fR +.P +.RE +.P +it does not affect the shell variables in the caller's environment. +.P +Note that shell functions share +.IR OPTIND +with the calling shell even though the positional parameters are +changed. If the calling shell and any of its functions uses +.IR getopts +to parse arguments, the results are unspecified. +.SH EXAMPLES +The following example script parses and displays its arguments: +.sp +.RS 4 +.nf +\fB +aflag= +bflag= +while getopts ab: name +do + case $name in + a) aflag=1;; + b) bflag=1 + bval="$OPTARG";; + ?) printf "Usage: %s: [\(mia] [\(mib value] args\en" $0 + exit 2;; + esac +done +if [ ! \(miz "$aflag" ]; then + printf "Option \(mia specified\en" +fi +if [ ! \(miz "$bflag" ]; then + printf 'Option \(mib "%s" specified\en' "$bval" +fi +shift $(($OPTIND \(mi 1)) +printf "Remaining arguments are: %s\en$*" +.fi \fR +.P +.RE +.SH RATIONALE +The +.IR getopts +utility was chosen in preference to the System V +.IR getopt +utility because +.IR getopts +handles option-arguments containing + +characters. +.P +The +.IR OPTARG +variable is not mentioned in the ENVIRONMENT VARIABLES section because +it does not affect the execution of +.IR getopts ; +it is one of the few ``output-only'' variables used by the standard +utilities. +.P +The + +is not allowed as an option character because that is not historical +behavior, and it violates the Utility Syntax Guidelines. The + +is now specified to behave as in the KornShell version of the +.IR getopts +utility; when used as the first character in the +.IR optstring +operand, it disables diagnostics concerning missing option-arguments +and unexpected option characters. This replaces the use of the +.IR OPTERR +variable that was specified in an early proposal. +.P +The formats of the diagnostic messages produced by the +.IR getopts +utility and the +\fIgetopt\fR() +function are not fully specified because implementations with superior +(``friendlier'') formats objected to the formats used by some +historical implementations. The standard developers considered it +important that the information in the messages used be uniform between +.IR getopts +and +\fIgetopt\fR(). +Exact duplication of the messages might not be possible, particularly +if a utility is built on another system that has a different +\fIgetopt\fR() +function, but the messages must have specific information included so +that the program name, invalid option character, and type of error can +be distinguished by a user. +.P +Only a rare application program intercepts a +.IR getopts +standard error message and wants to parse it. Therefore, +implementations are free to choose the most usable messages they can +devise. The following formats are used by many historical +implementations: +.sp +.RS 4 +.nf +\fB +"%s: illegal option \(mi\|\(mi %c\en", <\fIprogram name\fP>, <\fIoption character\fP> +.P +"%s: option requires an argument \(mi\|\(mi %c\en", <\fIprogram name\fP>, \e + <\fIoption character\fP> +.fi \fR +.P +.RE +.P +Historical shells with built-in versions of +\fIgetopt\fR() +or +.IR getopts +have used different formats, frequently not even indicating the option +character found in error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5.2" ", " "Special Parameters" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIgetopt\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/grep.1p b/man-pages-posix-2013/man1p/grep.1p new file mode 100644 index 0000000..43374b2 --- /dev/null +++ b/man-pages-posix-2013/man1p/grep.1p @@ -0,0 +1,529 @@ +'\" et +.TH GREP "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +grep +\(em search a file for a pattern +.SH SYNOPSIS +.LP +.nf +grep \fB[\fR\(miE|\(miF\fB] [\fR\(mic|\(mil|\(miq\fB] [\fR\(miinsvx\fB] \fR\(mie \fIpattern_list + \fB[\fR\(mie \fIpattern_list\fB]\fR... \fB[\fR\(mif \fIpattern_file\fB]\fR... \fB[\fIfile\fR...\fB]\fR +.P +grep \fB[\fR\(miE|\(miF\fB] [\fR\(mic|\(mil|\(miq\fB] [\fR\(miinsvx\fB] [\fR\(mie \fIpattern_list\fB]... + \fR\(mif \fIpattern_file \fB[\fR\(mif \fIpattern_file\fB]\fR... \fB[\fIfile\fR...\fB]\fR +.P +grep \fB[\fR\(miE|\(miF\fB] [\fR\(mic|\(mil|\(miq\fB] [\fR\(miinsvx\fB] \fIpattern_list\fB [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR grep +utility shall search the input files, selecting lines matching one or +more patterns; the types of patterns are controlled by the options +specified. The patterns are specified by the +.BR \(mie +option, +.BR \(mif +option, or the +.IR pattern_list +operand. The +.IR pattern_list 's +value shall consist of one or more patterns separated by + +characters; the +.IR pattern_file 's +contents shall consist of one or more patterns terminated by a + +character. By default, an input line shall be selected if any +pattern, treated as an entire basic regular expression (BRE) as +described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.3" ", " "Basic Regular Expressions", +matches any part of the line excluding the terminating +; +a null BRE shall match every line. By default, each selected input +line shall be written to the standard output. +.P +Regular expression matching shall be based on text lines. Since a + +separates or terminates patterns (see the +.BR \(mie +and +.BR \(mif +options below), regular expressions cannot contain a +. +Similarly, since patterns are matched against individual lines +(excluding the terminating + +characters) of the input, there is no way for a pattern to match a + +found in the input. +.SH OPTIONS +The +.IR grep +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(miE\fP" 10 +Match using extended regular expressions. +Treat each pattern specified as an ERE, as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.4" ", " "Extended Regular Expressions". +If any entire ERE pattern matches some part of an input line excluding +the terminating +, +the line shall be matched. A null ERE shall match every line. +.IP "\fB\(miF\fP" 10 +Match using fixed strings. Treat each pattern specified as a string +instead of a regular expression. If an input line contains any of the +patterns as a contiguous sequence of bytes, the line shall be matched. +A null string shall match every line. +.IP "\fB\(mic\fP" 10 +Write only a count of selected lines to standard output. +.IP "\fB\(mie\ \fIpattern_list\fR" 10 +.br +Specify one or more patterns to be used during the search for input. +The application shall ensure that patterns in +.IR pattern_list +are separated by a +. +A null pattern can be specified by two adjacent + +characters in +.IR pattern_list . +Unless the +.BR \(miE +or +.BR \(miF +option is also specified, each pattern shall be treated as a BRE, as +described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.3" ", " "Basic Regular Expressions". +Multiple +.BR \(mie +and +.BR \(mif +options shall be accepted by the +.IR grep +utility. All of the specified patterns shall be used when matching +lines, but the order of evaluation is unspecified. +.IP "\fB\(mif\ \fIpattern_file\fR" 10 +.br +Read one or more patterns from the file named by the pathname +.IR pattern_file . +Patterns in +.IR pattern_file +shall be terminated by a +. +A null pattern can be specified by an empty line in +.IR pattern_file . +Unless the +.BR \(miE +or +.BR \(miF +option is also specified, each pattern shall be treated as a BRE, as +described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.3" ", " "Basic Regular Expressions". +.IP "\fB\(mii\fP" 10 +Perform pattern matching in searches without regard to case; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.2" ", " "Regular Expression General Requirements". +.IP "\fB\(mil\fP" 10 +(The letter ell.) Write only the names of files containing selected +lines to standard output. Pathnames shall be written once per file +searched. If the standard input is searched, a pathname of +.BR \(dq(standard input)\(dq +shall be written, in the POSIX locale. In other locales, +.BR \(dqstandard input\(dq +may be replaced by something more appropriate in those locales. +.IP "\fB\(min\fP" 10 +Precede each output line by its relative line number in the file, each +file starting at line 1. The line number counter shall be reset for +each file processed. +.IP "\fB\(miq\fP" 10 +Quiet. Nothing shall be written to the standard output, regardless of +matching lines. Exit with zero status if an input line is selected. +.IP "\fB\(mis\fP" 10 +Suppress the error messages ordinarily written for nonexistent or +unreadable files. Other error messages shall not be suppressed. +.IP "\fB\(miv\fP" 10 +Select lines not matching any of the specified patterns. If the +.BR \(miv +option is not specified, selected lines shall be those that match any +of the specified patterns. +.IP "\fB\(mix\fP" 10 +Consider only input lines that use all characters in the line excluding +the terminating + +to match an entire fixed string or regular expression to be matching +lines. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIpattern_list\fR" 10 +Specify one or more patterns to be used during the search for input. +This operand shall be treated as if it were specified as +.BR \(mie +.IR pattern_list . +.IP "\fIfile\fR" 10 +A pathname of a file to be searched for the patterns. If no +.IR file +operands are specified, the standard input shall be used. +.SH STDIN +The standard input shall be used if no +.IR file +operands are specified, and shall be used if a +.IR file +operand is +.BR '\(mi' +and the implementation treats the +.BR '\(mi' +as meaning standard input. +Otherwise, the standard input shall not be used. +See the INPUT FILES section. +.SH "INPUT FILES" +The input files shall be text files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR grep : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular expressions. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files) and the behavior of +character classes within regular expressions. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If the +.BR \(mil +option is in effect, the following shall be written for each file +containing at least one selected input line: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIfile\fR> +.fi \fR +.P +.RE +.P +Otherwise, if more than one +.IR file +argument appears, and +.BR \(miq +is not specified, the +.IR grep +utility shall prefix each output line by: +.sp +.RS 4 +.nf +\fB +"%s:", <\fIfile\fR> +.fi \fR +.P +.RE +.P +The remainder of each output line shall depend on the other options +specified: +.IP " *" 4 +If the +.BR \(mic +option is in effect, the remainder of each output line shall contain: +.RS 4 +.sp +.RS 4 +.nf +\fB +"%d\en", <\fIcount\fR> +.fi \fR +.P +.RE +.RE +.IP " *" 4 +Otherwise, if +.BR \(mic +is not in effect and the +.BR \(min +option is in effect, the following shall be written to standard +output: +.RS 4 +.sp +.RS 4 +.nf +\fB +"%d:", <\fIline number\fR> +.fi \fR +.P +.RE +.RE +.IP " *" 4 +Finally, the following shall be written to standard output: +.RS 4 +.sp +.RS 4 +.nf +\fB +"%s", <\fIselected-line contents\fR> +.fi \fR +.P +.RE +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +One or more lines were selected. +.IP "\01" 6 +No lines were selected. +.IP >1 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If the +.BR \(miq +option is specified, the exit status shall be zero if an input line is +selected, even if an error was detected. Otherwise, default actions +shall be performed. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Care should be taken when using characters in +.IR pattern_list +that may also be meaningful to the command interpreter. It is safest +to enclose the entire +.IR pattern_list +argument in single-quotes: +.sp +.RS 4 +.nf +\fB +\&'...' +.fi \fR +.P +.RE +.P +The +.BR \(mie +.IR pattern_list +option has the same effect as the +.IR pattern_list +operand, but is useful when +.IR pattern_list +begins with the + +delimiter. It is also useful when it is more convenient to provide +multiple patterns as separate arguments. +.P +Multiple +.BR \(mie +and +.BR \(mif +options are accepted and +.IR grep +uses all of the patterns it is given while matching input text lines. +(Note that the order of evaluation is not specified. If an +implementation finds a null string as a pattern, it is allowed to use +that pattern first, matching every line, and effectively ignore any +other patterns.) +.P +The +.BR \(miq +option provides a means of easily determining whether or not a pattern +(or string) exists in a group of files. When searching several files, +it provides a performance improvement (because it can quit as soon as +it finds the first match) and requires less care by the user in +choosing the set of files to supply as arguments (because it exits zero +if it finds a match even if +.IR grep +detected an access or read error on earlier +.IR file +operands). +.SH EXAMPLES +.IP " 1." 4 +To find all uses of the word +.BR \(dqPosix\(dq +(in any case) in file +.BR text.mm +and write with line numbers: +.RS 4 +.sp +.RS 4 +.nf +\fB +grep \(mii \(min posix text.mm +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +To find all empty lines in the standard input: +.RS 4 +.sp +.RS 4 +.nf +\fB +grep ^$ +.fi \fR +.P +.RE +.P +or: +.sp +.RS 4 +.nf +\fB +grep \(miv . +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +Both of the following commands print all lines containing strings +.BR \(dqabc\(dq +or +.BR \(dqdef\(dq +or both: +.RS 4 +.sp +.RS 4 +.nf +\fB +grep \(miE 'abc|def' +.P +grep \(miF 'abc +def' +.fi \fR +.P +.RE +.RE +.IP " 4." 4 +Both of the following commands print all lines matching exactly +.BR \(dqabc\(dq +or +.BR \(dqdef\(dq : +.RS 4 +.sp +.RS 4 +.nf +\fB +grep \(miE '^abc$|^def$' +.P +grep \(miF \(mix 'abc +def' +.fi \fR +.P +.RE +.RE +.SH RATIONALE +This +.IR grep +has been enhanced in an upwards-compatible way to provide the exact +functionality of the historical +.IR egrep +and +.IR fgrep +commands as well. It was the clear intention of the standard +developers to consolidate the three +.IR grep s +into a single command. +.P +The old +.IR egrep +and +.IR fgrep +commands are likely to be supported for many years to come as +implementation extensions, allowing historical applications to operate +unmodified. +.P +Historical implementations usually silently ignored all but one of +multiply-specified +.BR \(mie +and +.BR \(mif +options, but were not consistent as to which specification was actually +used. +.P +The +.BR \(mib +option was omitted from the OPTIONS section because block numbers are +implementation-defined. +.P +The System V restriction on using +.BR \(mi +to mean standard input was omitted. +.P +A definition of action taken when given a null BRE or ERE is specified. +This is an error condition in some historical implementations. +.P +The +.BR \(mil +option previously indicated that its use was undefined when no files +were explicitly named. This behavior was historical and placed an +unnecessary restriction on future implementations. It has been +removed. +.P +The historical BSD +.IR grep +.BR \(mis +option practice is easily duplicated by redirecting standard output to +.BR /dev/null . +The +.BR \(mis +option required here is from System V. +.P +The +.BR \(mix +option, historically available only with +.IR fgrep , +is available here for all of the non-obsolescent versions. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsed\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Chapter 9" ", " "Regular Expressions", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/hash.1p b/man-pages-posix-2013/man1p/hash.1p new file mode 100644 index 0000000..00c2821 --- /dev/null +++ b/man-pages-posix-2013/man1p/hash.1p @@ -0,0 +1,189 @@ +'\" et +.TH HASH "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +hash +\(em remember or report utility locations +.SH SYNOPSIS +.LP +.nf +hash \fB[\fIutility\fR...\fB]\fR +.P +hash \(mir +.fi +.SH DESCRIPTION +The +.IR hash +utility shall affect the way the current shell environment remembers +the locations of utilities found as described in +.IR "Section 2.9.1.1" ", " "Command Search and Execution". +Depending on the arguments specified, it shall add utility locations to +its list of remembered locations or it shall purge the contents of the +list. When no arguments are specified, it shall report on the contents +of the list. +.P +Utilities provided as built-ins to the shell shall not be reported by +.IR hash . +.SH OPTIONS +The +.IR hash +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(mir\fP" 10 +Forget all previously remembered utility locations. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIutility\fR" 10 +The name of a utility to be searched for and added to the list of +remembered locations. If +.IR utility +contains one or more + +characters, the results are unspecified. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR hash : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPATH\fP" 10 +Determine the location of +.IR utility , +as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output of +.IR hash +shall be used when no arguments are specified. Its format is +unspecified, but includes the pathname of each utility in the list of +remembered locations for the current shell environment. This list +shall consist of those utilities named in previous +.IR hash +invocations that have been invoked, and may contain those invoked and +found through the normal command search process. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Since +.IR hash +affects the current shell execution environment, it is always provided +as a shell regular built-in. If it is called in a separate utility +execution environment, such as one of the following: +.sp +.RS 4 +.nf +\fB +nohup hash \(mir +find . \(mitype f | xargs hash +.fi \fR +.P +.RE +.P +it does not affect the command search process of the caller's +environment. +.P +The +.IR hash +utility may be implemented as an alias\(emfor example, +.IR alias +.BR "\(mit\ \(mi" , +in which case utilities found through normal command search are not +listed by the +.IR hash +command. +.P +The effects of +.IR hash +.BR \(mir +can also be achieved portably by resetting the value of +.IR PATH ; +in the simplest form, this can be: +.sp +.RS 4 +.nf +\fB +PATH="$PATH" +.fi \fR +.P +.RE +.P +The use of +.IR hash +with +.IR utility +names is unnecessary for most applications, but may provide a +performance improvement on a few implementations; normally, the hashing +process is included by default. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.9.1.1" ", " "Command Search and Execution" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/head.1p b/man-pages-posix-2013/man1p/head.1p new file mode 100644 index 0000000..477328d --- /dev/null +++ b/man-pages-posix-2013/man1p/head.1p @@ -0,0 +1,207 @@ +'\" et +.TH HEAD "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +head +\(em copy the first part of files +.SH SYNOPSIS +.LP +.nf +head \fB[\fR\(min \fInumber\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR head +utility shall copy its input files to the standard output, ending the +output for each file at a designated point. +.P +Copying shall end at the point in each input file indicated by the +.BR \(min +.IR number +option. The option-argument +.IR number +shall be counted in units of lines. +.SH OPTIONS +The +.IR head +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(min\ \fInumber\fR" 10 +The first +.IR number +lines of each input file shall be copied to standard output. The +application shall ensure that the +.IR number +option-argument is a positive decimal integer. +.P +When a file contains less than +.IR number +lines, it shall be copied to standard output in its entirety. This +shall not be an error. +.P +If no options are specified, +.IR head +shall act as if +.BR "\(min 10" +had been specified. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an input file. If no +.IR file +operands are specified, the standard input shall be used. +.SH STDIN +The standard input shall be used if no +.IR file +operands are specified, and shall be used if a +.IR file +operand is +.BR '\(mi' +and the implementation treats the +.BR '\(mi' +as meaning standard input. +Otherwise, the standard input shall not be used. +See the INPUT FILES section. +.SH "INPUT FILES" +Input files shall be text files, but the line length is not restricted +to +{LINE_MAX} +bytes. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR head : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall contain designated portions of the input +files. +.P +If multiple +.IR file +operands are specified, +.IR head +shall precede the output for each with the header: +.sp +.RS 4 +.nf +\fB +"\en==> %s <==\en", <\fIpathname\fR> +.fi \fR +.P +.RE +.P +except that the first header written shall not include the initial +. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +To write the first ten lines of all files (except those with a leading +period) in the directory: +.sp +.RS 4 +.nf +\fB +head \(mi\|\(mi * +.fi \fR +.P +.RE +.SH RATIONALE +Although it is possible to simulate +.IR head +with +.IR sed +10q for a single file, the standard developers decided that the +popularity of +.IR head +on historical BSD systems warranted its inclusion alongside +.IR tail . +.P +POSIX.1\(hy2008 version of +.IR head +follows the Utility Syntax Guidelines. The +.BR \(min +option was added to this new interface so that +.IR head +and +.IR tail +would be more logically related. Earlier versions of this standard +allowed a +.BR \(minumber +option. This form is no longer specified by POSIX.1\(hy2008 but may +be present in some implementations. +.P +There is no +.BR \(mic +option (as there is in +.IR tail ) +because it is not historical practice and because other utilities in +\&this volume of POSIX.1\(hy2008 provide similar functionality. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsed\fR\^", +.IR "\fItail\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/iconv.1p b/man-pages-posix-2013/man1p/iconv.1p new file mode 100644 index 0000000..41b3b09 --- /dev/null +++ b/man-pages-posix-2013/man1p/iconv.1p @@ -0,0 +1,288 @@ +'\" et +.TH ICONV "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +.SH SYNOPSIS +.LP +.nf +iconv \fB[\fR\(mics\fB]\fR \(mif \fIfrommap\fR \(mit \fItomap \fB[\fIfile\fR...\fB]\fR +.P +iconv \(mif \fIfromcode \fB[\fR\(mics\fB] [\fR\(mit \fItocode\fB] [\fIfile\fR...\fB]\fR +.P +iconv \(mit \fItocode \fB[\fR\(mics\fB] [\fR\(mif \fIfromcode\fB] [\fIfile\fR...\fB]\fR +.P +iconv \(mil +.fi +.SH DESCRIPTION +The +.IR iconv +utility shall convert the encoding of characters in +.IR file +from one codeset to another and write the results to standard output. +.P +When the options indicate that charmap files are used to specify the +codesets (see OPTIONS), the codeset conversion shall be accomplished by +performing a logical join on the symbolic character names in the two +charmaps. The implementation need not support the use of charmap files +for codeset conversion unless the POSIX2_LOCALEDEF symbol is defined on +the system. +.SH OPTIONS +The +.IR iconv +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mic\fR" 10 +Omit any characters that are invalid in the codeset of the input file +from the output. When +.BR \(mic +is not used, the results of encountering invalid characters in the +input stream (either those that are not characters in the codeset of +the input file or that have no corresponding character in the codeset +of the output file) shall be specified in the system documentation. The +presence or absence of +.BR \(mic +shall not affect the exit status of +.IR iconv . +.IP "\fB\(mif\ \fIfromcodeset\fR" 10 +.br +Identify the codeset of the input file. The implementation shall +recognize the following two forms of the +.IR fromcodeset +option-argument: +.RS 10 +.IP "\fIfromcode\fR" 10 +The +.IR fromcode +option-argument must not contain a + +character. It shall be interpreted as the name of one of the codeset +descriptions provided by the implementation in an unspecified +format. Valid values of +.IR fromcode +are implementation-defined. +.IP "\fIfrommap\fR" 10 +The +.IR frommap +option-argument must contain a + +character. It shall be interpreted as the pathname of a charmap file as +defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.4" ", " "Character Set Description File". +If the pathname does not represent a valid, readable charmap file, +the results are undefined. +.P +If this option is omitted, the codeset of the current locale shall +be used. +.RE +.IP "\fB\(mil\fR" 10 +Write all supported +.IR fromcode +and +.IR tocode +values to standard output in an unspecified format. +.IP "\fB\(mis\fR" 10 +Suppress any messages written to standard error concerning invalid +characters. When +.BR \(mis +is not used, the results of encountering invalid characters in the +input stream (either those that are not valid characters in the codeset +of the input file or that have no corresponding character in the +codeset of the output file) shall be specified in the system +documentation. The presence or absence of +.BR \(mis +shall not affect the exit status of +.IR iconv . +.IP "\fB\(mit\ \fItocodeset\fR" 10 +Identify the codeset to be used for the output file. The implementation +shall recognize the following two forms of the +.IR tocodeset +option-argument: +.RS 10 +.IP "\fItocode\fR" 10 +The semantics shall be equivalent to the +.BR \(mif +.IR fromcode +option. +.IP "\fItomap\fR" 10 +The semantics shall be equivalent to the +.BR \(mif +.IR frommap +option. +.P +If this option is omitted, the codeset of the current locale shall be +used. +.RE +.P +If either +.BR \(mif +or +.BR \(mit +represents a charmap file, but the other does not (or is omitted), or +both +.BR \(mif +and +.BR \(mit +are omitted, the results are undefined. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an input file. If no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' , +the standard input shall be used. +.SH STDIN +The standard input shall be used only if no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' . +.SH "INPUT FILES" +The input file shall be a text file. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR iconv : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). During translation of the file, +this variable is superseded by the use of the +.IR fromcode +option-argument. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +When the +.BR \(mil +option is used, the standard output shall contain all supported +.IR fromcode +and +.IR tocode +values, written in an unspecified format. +.P +When the +.BR \(mil +option is not used, the standard output shall contain the sequence of +characters read from the input files, translated to the specified +codeset. Nothing else shall be written to the standard output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The user must ensure that both charmap files use the same symbolic +names for characters the two codesets have in common. +.SH EXAMPLES +The following example converts the contents of file +.BR mail.x400 +from the ISO/IEC\ 6937:\|2001 standard codeset to the ISO/IEC\ 8859\(hy1:\|1998 standard codeset, and stores the results in +file +.BR mail.local : +.sp +.RS 4 +.nf +\fB +iconv \(mif IS6937 \(mit IS8859 mail.x400 > mail.local +.fi \fR +.P +.RE +.SH RATIONALE +The +.IR iconv +utility can be used portably only when the user provides two charmap +files as option-arguments. This is because a single charmap provided by +the user cannot reliably be joined with the names in a system-provided +character set description. The valid values for +.IR fromcode +and +.IR tocode +are implementation-defined and do not have to have any relation to +the charmap mechanisms. As an aid to interactive users, the +.BR \(mil +option was adopted from the Plan 9 operating system. It writes +information concerning these implementation-defined values. The +format is unspecified because there are many possible useful formats +that could be chosen, such as a matrix of valid combinations of +.IR fromcode +and +.IR tocode . +The +.BR \(mil +option is not intended for shell script usage; conforming applications +will have to use charmaps. +.P +The +.IR iconv +utility may support the conversion between ASCII and EBCDIC-based +encodings, but is not required to do so. In an XSI-compliant +implementation, the +.IR dd +utility is the only method guaranteed to support conversion between +these two character sets. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdd\fR\^", +.IR "\fIgencat\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.4" ", " "Character Set Description File", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/id.1p b/man-pages-posix-2013/man1p/id.1p new file mode 100644 index 0000000..319f76f --- /dev/null +++ b/man-pages-posix-2013/man1p/id.1p @@ -0,0 +1,351 @@ +'\" et +.TH ID "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +id +\(em return user identity +.SH SYNOPSIS +.LP +.nf +id \fB[\fIuser\fB]\fR +.P +id \(miG \fB[\fR\(min\fB] [\fIuser\fB]\fR +.P +id \(mig \fB[\fR\(minr\fB] [\fIuser\fB]\fR +.P +id \(miu \fB[\fR\(minr\fB] [\fIuser\fB]\fR +.fi +.SH DESCRIPTION +If no +.IR user +operand is provided, the +.IR id +utility shall write the user and group IDs and the corresponding user +and group names of the invoking process to standard output. If the +effective and real IDs do not match, both shall be written. If +multiple groups are supported by the underlying system (see the +description of +{NGROUPS_MAX} +in the System Interfaces volume of POSIX.1\(hy2008), the supplementary group affiliations of the invoking +process shall also be written. +.P +If a +.IR user +operand is provided and the process has appropriate privileges, the +user and group IDs of the selected user shall be written. In this +case, effective IDs shall be assumed to be identical to real IDs. If +the selected user has more than one allowable group membership listed +in the group database, these shall be written in the same manner as the +supplementary groups described in the preceding paragraph. +.SH OPTIONS +The +.IR id +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(miG\fP" 10 +Output all different group IDs (effective, real, and supplementary) +only, using the format +.BR \(dq%u\en\(dq . +If there is more than one distinct group affiliation, output each such +affiliation, using the format +.BR \(dq\ %u\(dq , +before the + +is output. +.IP "\fB\(mig\fP" 10 +Output only the effective group ID, using the format +.BR \(dq%u\en\(dq . +.IP "\fB\(min\fP" 10 +Output the name in the format +.BR \(dq%s\(dq +instead of the numeric ID using the format +.BR \(dq%u\(dq . +.IP "\fB\(mir\fP" 10 +Output the real ID instead of the effective ID. +.IP "\fB\(miu\fP" 10 +Output only the effective user ID, using the format +.BR \(dq%u\en\(dq . +.SH OPERANDS +The following operand shall be supported: +.IP "\fIuser\fR" 10 +The login name for which information is to be written. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR id : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The following formats shall be used when the +.IR LC_MESSAGES +locale category specifies the POSIX locale. In other locales, the +strings +.IR uid , +.IR gid , +.IR euid , +.IR egid , +and +.IR groups +may be replaced with more appropriate strings corresponding to the +locale. +.sp +.RS 4 +.nf +\fB +"uid=%u(%s) gid=%u(%s)\en", <\fIreal user ID\fR>, <\fIuser-name\fR>, + <\fIreal group ID\fR>, <\fIgroup-name\fR> +.fi \fR +.P +.RE +.P +If the effective and real user IDs do not match, the following shall be +inserted immediately before the +.BR '\en' +character in the previous format: +.sp +.RS 4 +.nf +\fB +" euid=%u(%s)" +.fi \fR +.P +.RE +.P +with the following arguments added at the end of the argument list: +.sp +.RS 4 +.nf +\fB +<\fIeffective user ID\fR>, <\fIeffective user-name\fR> +.fi \fR +.P +.RE +.P +If the effective and real group IDs do not match, the following shall +be inserted directly before the +.BR '\en' +character in the format string (and after any addition resulting from +the effective and real user IDs not matching): +.sp +.RS 4 +.nf +\fB +" egid=%u(%s)" +.fi \fR +.P +.RE +.P +with the following arguments added at the end of the argument list: +.sp +.RS 4 +.nf +\fB +<\fIeffective group-ID\fR>, <\fIeffective group name\fR> +.fi \fR +.P +.RE +.P +If the process has supplementary group affiliations or the selected +user is allowed to belong to multiple groups, the first shall be added +directly before the + +in the format string: +.sp +.RS 4 +.nf +\fB +" groups=%u(%s)" +.fi \fR +.P +.RE +.P +with the following arguments added at the end of the argument list: +.sp +.RS 4 +.nf +\fB +<\fIsupplementary group ID\fR>, <\fIsupplementary group name\fR> +.fi \fR +.P +.RE +.P +and the necessary number of the following added after that for any +remaining supplementary group IDs: +.sp +.RS 4 +.nf +\fB +",%u(%s)" +.fi \fR +.P +.RE +.P +and the necessary number of the following arguments added at the end of +the argument list: +.sp +.RS 4 +.nf +\fB +<\fIsupplementary group ID\fR>, <\fIsupplementary group name\fR> +.fi \fR +.P +.RE +.P +If any of the user ID, group ID, effective user ID, effective group ID, +or supplementary/multiple group IDs cannot be mapped by the system into +printable user or group names, the corresponding +.BR \(dq(%s)\(dq +and +.IR name +argument shall be omitted from the corresponding format string. +.P +When any of the options are specified, the output format shall be as +described in the OPTIONS section. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Output produced by the +.BR \(miG +option and by the default case could potentially produce very long +lines on systems that support large numbers of supplementary groups. +(On systems with user and group IDs that are 32-bit integers and with +group names with a maximum of 8 bytes per name, 93 supplementary groups +plus distinct effective and real group and user IDs could theoretically +overflow the 2\|048-byte +{LINE_MAX} +text file line limit on the default output case. It would take about +186 supplementary groups to overflow the 2\|048-byte barrier using +.IR id +.BR \(miG ). +This is not expected to be a problem in practice, but in cases where it +is a concern, applications should consider using +.IR fold +.BR \(mis +before post-processing the output of +.IR id . +.SH EXAMPLES +None. +.SH RATIONALE +The functionality provided by the 4 BSD +.IR groups +utility can be simulated using: +.sp +.RS 4 +.nf +\fB +id \(miGn [ user ] +.fi \fR +.P +.RE +.P +The 4 BSD command +.IR groups +was considered, but it was not included because it did not provide the +functionality of the +.IR id +utility of the SVID. Also, it was thought that it would be easier to +modify +.IR id +to provide the additional functionality necessary to systems with +multiple groups than to invent another command. +.P +The options +.BR \(miu , +.BR \(mig , +.BR \(min , +and +.BR \(mir +were added to ease the use of +.IR id +with shell commands substitution. Without these options it is +necessary to use some preprocessor such as +.IR sed +to select the desired piece of information. Since output such as that +produced by: +.sp +.RS 4 +.nf +\fB +id \(miu \(min +.fi \fR +.P +.RE +.P +is frequently wanted, it seemed desirable to add the options. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfold\fR\^", +.IR "\fIlogname\fR\^", +.IR "\fIwho\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIgetgid\fR\^(\|)", +.IR "\fIgetgroups\fR\^(\|)", +.IR "\fIgetuid\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/ipcrm.1p b/man-pages-posix-2013/man1p/ipcrm.1p new file mode 100644 index 0000000..032e835 --- /dev/null +++ b/man-pages-posix-2013/man1p/ipcrm.1p @@ -0,0 +1,150 @@ +'\" et +.TH IPCRM "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ipcrm +\(em remove an XSI message queue, semaphore set, or shared memory +segment identifier +.SH SYNOPSIS +.LP +.nf +ipcrm \fB[\fR\(miq msgid|\(miQ msgkey|\(mis semid|\(miS semkey|\(mim shmid|\(miM shmkey\fB]\fR... +.fi +.SH DESCRIPTION +The +.IR ipcrm +utility shall remove zero or more message queues, semaphore sets, or +shared memory segments. The interprocess communication facilities to be +removed are specified by the options. +.P +Only a user with appropriate privileges shall be allowed to remove an +interprocess communication facility that was not created by or owned by +the user invoking +.IR ipcrm . +.SH OPTIONS +The +.IR ipcrm +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(miq\ \fImsgid\fR" 10 +Remove the message queue identifier +.IR msgid +from the system and destroy the message queue and data structure +associated with it. +.IP "\fB\(mim\ \fIshmid\fR" 10 +Remove the shared memory identifier +.IR shmid +from the system. The shared memory segment and data structure +associated with it shall be destroyed after the last detach. +.IP "\fB\(mis\ \fIsemid\fR" 10 +Remove the semaphore identifier +.IR semid +from the system and destroy the set of semaphores and data structure +associated with it. +.IP "\fB\(miQ\ \fImsgkey\fR" 10 +Remove the message queue identifier, created with key +.IR msgkey , +from the system and destroy the message queue and data structure +associated with it. +.IP "\fB\(miM\ \fIshmkey\fR" 10 +Remove the shared memory identifier, created with key +.IR shmkey , +from the system. The shared memory segment and data structure +associated with it shall be destroyed after the last detach. +.IP "\fB\(miS\ \fIsemkey\fR" 10 +Remove the semaphore identifier, created with key +.IR semkey , +from the system and destroy the set of semaphores and data structure +associated with it. +.SH OPERANDS +None. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR ipcrm : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIipcs\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fImsgctl\fR\^(\|)", +.IR "\fIsemctl\fR\^(\|)", +.IR "\fIshmctl\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/ipcs.1p b/man-pages-posix-2013/man1p/ipcs.1p new file mode 100644 index 0000000..54456e9 --- /dev/null +++ b/man-pages-posix-2013/man1p/ipcs.1p @@ -0,0 +1,556 @@ +'\" et +.TH IPCS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ipcs +\(em report XSI interprocess communication facilities status +.SH SYNOPSIS +.LP +.nf +ipcs \fB[\fR\(miqms\fB] [\fR\(mia|\(mibcopt\fB]\fR +.fi +.SH DESCRIPTION +The +.IR ipcs +utility shall write information about active interprocess communication +facilities. +.P +Without options, information shall be written in short format for +message queues, shared memory segments, and semaphore sets that are +currently active in the system. Otherwise, the information that is +displayed is controlled by the options specified. +.SH OPTIONS +The +.IR ipcs +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The +.IR ipcs +utility accepts the following options: +.IP "\fB\(miq\fP" 10 +Write information about active message queues. +.IP "\fB\(mim\fP" 10 +Write information about active shared memory segments. +.IP "\fB\(mis\fP" 10 +Write information about active semaphore sets. +.P +If +.BR \(miq , +.BR \(mim , +or +.BR \(mis +are specified, only information about those facilities shall be +written. If none of these three are specified, information about all +three shall be written subject to the following options: +.IP "\fB\(mia\fP" 10 +Use all print options. (This is a shorthand notation for +.BR \(mib , +.BR \(mic , +.BR \(mio , +.BR \(mip , +and +.BR \(mit .) +.IP "\fB\(mib\fP" 10 +Write information on maximum allowable size. (Maximum number of bytes +in messages on queue for message queues, size of segments for shared +memory, and number of semaphores in each set for semaphores.) +.IP "\fB\(mic\fP" 10 +Write creator's user name and group name; see below. +.IP "\fB\(mio\fP" 10 +Write information on outstanding usage. (Number of messages on queue +and total number of bytes in messages on queue for message queues, and +number of processes attached to shared memory segments.) +.IP "\fB\(mip\fP" 10 +Write process number information. (Process ID of the last process to +send a message and process ID of the last process to receive a message +on message queues, process ID of the creating process, and process ID +of the last process to attach or detach on shared memory segments.) +.IP "\fB\(mit\fP" 10 +Write time information. (Time of the last control operation that +changed the access permissions for all facilities, time of the last +\fImsgsnd\fR() +and +\fImsgrcv\fR() +operations on message queues, time of the last +\fIshmat\fR() +and +\fIshmdt\fR() +operations on shared memory, and time of the last +\fIsemop\fR() +operation on semaphores.) +.SH OPERANDS +None. +.SH STDIN +Not used. +.SH "INPUT FILES" +.IP " *" 4 +The group database +.IP " *" 4 +The user database +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR ipcs : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITZ\fP" 10 +Determine the timezone for the date and time strings written by +.IR ipcs . +If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +An introductory line shall be written with the format: +.sp +.RS 4 +.nf +\fB +"IPC status from %s as of %s\en", <\fIsource\fP>, <\fIdate\fP> +.fi \fR +.P +.RE +.P +where <\fIsource\fP> indicates the source used to gather the statistics +and <\fIdate\fP> is the information that would be produced by the +.IR date +command when invoked in the POSIX locale. +.P +The +.IR ipcs +utility then shall create up to three reports depending upon the +.BR \(miq , +.BR \(mim , +and +.BR \(mis +options. The first report shall indicate the status of message queues, +the second report shall indicate the status of shared memory segments, +and the third report shall indicate the status of semaphore sets. +.P +If the corresponding facility is not installed or has not been used +since the last reboot, then the report shall be written out in the +format: +.sp +.RS 4 +.nf +\fB +"%s facility not in system.\en", <\fIfacility\fP> +.fi \fR +.P +.RE +.P +where <\fIfacility\fP> is +.IR "Message Queue" , +.IR "Shared Memory" , +or +.IR "Semaphore" , +as appropriate. If the facility has been installed and has been used +since the last reboot, column headings separated by one or more + +characters and followed by a + +shall be written as indicated below followed by the facility name +written out using the format: +.sp +.RS 4 +.nf +\fB +"%s:\en", <\fIfacility\fP> +.fi \fR +.P +.RE +.P +where <\fIfacility\fP> is +.IR "Message Queues" , +.IR "Shared Memory" , +or +.IR "Semaphores" , +as appropriate. On the second and third reports the column headings +need not be written if the last column headings written already provide +column headings for all information in that report. +.P +The column headings provided in the first column below and the meaning +of the information in those columns shall be given in order below; the +letters in parentheses indicate the options that shall cause the +corresponding column to appear; ``all'' means that the column shall +always appear. Each column is separated by one or more + +characters. Note that these options only determine what information is +provided for each report; they do not determine which reports are written. +.IP "T (all)" 12 +Type of facility: +.RS 12 +.IP "\fRq\fP" 8 +Message queue. +.IP "\fRm\fP" 8 +Shared memory segment. +.IP "\fRs\fP" 8 +Semaphore. +.P +This field is a single character written using the format +.BR %c . +.RE +.IP "ID (all)" 12 +The identifier for the facility entry. This field shall be written +using the format +.BR %d . +.IP "KEY (all)" 12 +The key used as an argument to +\fImsgget\fR(), +\fIsemget\fR(), +or +\fIshmget\fR() +to create the facility entry. +.RS 12 +.TP 10 +.BR Note: +The key of a shared memory segment is changed to IPC_PRIVATE when the +segment has been removed until all processes attached to the segment +detach it. +.P +This field shall be written using the format \fR0x%x\fR. +.RE +.IP "MODE (all)" 12 +The facility access modes and flags. The mode shall consist of 11 +characters that are interpreted as follows. +.RS 12 +.P +The first character shall be: +.IP "\fRS\fP" 8 +If a process is waiting on a +\fImsgsnd\fR() +operation. +.IP "\fR\(mi\fP" 8 +If the above is not true. +.P +The second character shall be: +.IP "\fRR\fP" 8 +If a process is waiting on a +\fImsgrcv\fR() +operation. +.IP "\fRC\fP\ or\ \fR\(mi\fP" 8 +If the associated shared memory segment is to be cleared when the first +attach operation is executed. +.IP "\fR\(mi\fP" 8 +If none of the above is true. +.P +The next nine characters shall be interpreted as three sets of three +bits each. The first set refers to the owner's permissions; the next +to permissions of others in the usergroup of the facility entry; and +the last to all others. Within each set, the first character indicates +permission to read, the second character indicates permission to write +or alter the facility entry, and the last character is a minus-sign (\c +.BR '\(mi' ). +.P +The permissions shall be indicated as follows: +.IP "\fIr\fP" 8 +If read permission is granted. +.IP "\fIw\fP" 8 +If write permission is granted. +.IP "\fIa\fP" 8 +If alter permission is granted. +.IP "\fR\(mi\fP" 8 +If the indicated permission is not granted. +.P +The first character following the permissions specifies if there is an +alternate or additional access control method associated with the +facility. If there is no alternate or additional access control method +associated with the facility, a single + +shall be written; otherwise, another printable character is +written. +.RE +.IP "OWNER (all)" 12 +The user name of the owner of the facility entry. If the user name of +the owner is found in the user database, at least the first eight +column positions of the name shall be written using the format +.BR %s . +Otherwise, the user ID of the owner shall be written using the format +.BR %d . +.IP "GROUP (all)" 12 +The group name of the owner of the facility entry. If the group name +of the owner is found in the group database, at least the first eight +column positions of the name shall be written using the format +.BR %s . +Otherwise, the group ID of the owner shall be written using the format +.BR %d . +.P +The following nine columns shall be only written out for message +queues: +.IP "CREATOR (\fBa\fP,\fBc\fP)" 12 +The user name of the creator of the facility entry. If the user name +of the creator is found in the user database, at least the first eight +column positions of the name shall be written using the format +.BR %s . +Otherwise, the user ID of the creator shall be written using the format +.BR %d . +.IP "CGROUP (\fBa\fP,\fBc\fP)" 12 +The group name of the creator of the facility entry. If the group name +of the creator is found in the group database, at least the first eight +column positions of the name shall be written using the format +.BR %s . +Otherwise, the group ID of the creator shall be written using the format +.BR %d . +.IP "CBYTES (\fBa\fP,\fBo\fP)" 12 +The number of bytes in messages currently outstanding on the associated +message queue. This field shall be written using the format +.BR %d . +.IP "QNUM (\fBa\fP,\fBo\fP)" 12 +The number of messages currently outstanding on the associated message +queue. This field shall be written using the format +.BR %d . +.IP "QBYTES (\fBa\fP,\fBb\fP)" 12 +The maximum number of bytes allowed in messages outstanding on the +associated message queue. This field shall be written using the format +.BR %d . +.IP "LSPID (\fBa\fP,\fBp\fP)" 12 +The process ID of the last process to send a message to the associated +queue. This field shall be written using the format: +.RS 12 +.sp +.RS 4 +.nf +\fB +"%d", <\fIpid\fP> +.fi \fR +.P +.RE +.P +where <\fIpid\fP> is 0 if no message has been sent to the corresponding +message queue; otherwise, <\fIpid\fP> shall be the process ID of the +last process to send a message to the queue. +.RE +.IP "LRPID (\fBa\fP,\fBp\fP)" 12 +The process ID of the last process to receive a message from the +associated queue. This field shall be written using the format: +.RS 12 +.sp +.RS 4 +.nf +\fB +"%d", <\fIpid\fP> +.fi \fR +.P +.RE +.P +where <\fIpid\fP> is 0 if no message has been received from the +corresponding message queue; otherwise, <\fIpid\fP> shall be the +process ID of the last process to receive a message from the queue. +.RE +.IP "STIME (\fBa\fP,\fBt\fP)" 12 +The time the last message was sent to the associated queue. +If a message has been sent to the corresponding message queue, +the hour, minute, and second of the last time a message +was sent to the queue shall be written using the format +.BR %d :\c +.BR %2.2d :\c +.BR %2.2d . +Otherwise, the format +.BR \(dq\ no-entry\(dq +shall be written. +.IP "RTIME (\fBa\fP,\fBt\fP)" 12 +The time the last message was received from the associated queue. +If a message has been received from the corresponding message queue, +the hour, minute, and second of the last time a message was received +from the queue shall be written using the format +.BR %d :\c +.BR %2.2d :\c +.BR %2.2d . +Otherwise, the format +.BR \(dq\ no-entry\(dq +shall be written. +.P +The following eight columns shall be only written out for shared memory +segments. +.IP "CREATOR (\fBa\fP,\fBc\fP)" 12 +The user of the creator of the facility entry. If the user name of the +creator is found in the user database, at least the first eight column +positions of the name shall be written using the format +.BR %s . +Otherwise, the user ID of the creator shall be written using the format +.BR %d . +.IP "CGROUP (\fBa\fP,\fBc\fP)" 12 +The group name of the creator of the facility entry. If the group name +of the creator is found in the group database, at least the first eight +column positions of the name shall be written using the format +.BR %s . +Otherwise, the group ID of the creator shall be written using the format +.BR %d . +.IP "NATTCH (\fBa\fP,\fBo\fP)" 12 +The number of processes attached to the associated shared memory +segment. This field shall be written using the format +.BR %d . +.IP "SEGSZ (\fBa\fP,\fBb\fP)" 12 +The size of the associated shared memory segment. This field shall be +written using the format +.BR %d . +.IP "CPID (\fBa\fP,\fBp\fP)" 12 +The process ID of the creator of the shared memory entry. This field +shall be written using the format +.BR %d . +.IP "LPID (\fBa\fP,\fBp\fP)" 12 +The process ID of the last process to attach or detach the shared +memory segment. This field shall be written using the format: +.RS 12 +.sp +.RS 4 +.nf +\fB +"%d", <\fIpid\fP> +.fi \fR +.P +.RE +.P +where <\fIpid\fP> is 0 if no process has attached the corresponding +shared memory segment; otherwise, <\fIpid\fP> shall be the process ID +of the last process to attach or detach the segment. +.RE +.IP "ATIME (\fBa\fP,\fBt\fP)" 12 +The time the last attach on the associated shared memory segment was +completed. If the corresponding shared memory segment has ever been +attached, the hour, minute, and second of the last time the segment was +attached shall be written using the format +.BR %d :\c +.BR %2.2d :\c +.BR %2.2d . +Otherwise, the format +.BR \(dq\ no-entry\(dq +shall be written. +.IP "DTIME (\fBa\fP,\fBt\fP)" 12 +The time the last detach on the associated shared memory segment was +completed. If the corresponding shared memory segment has ever been +detached, the hour, minute, and second of the last time the segment was +detached shall be written using the format +.BR %d :\c +.BR %2.2d :\c +.BR %2.2d . +Otherwise, the format +.BR \(dq\ no-entry\(dq +shall be written. +.P +The following four columns shall be only written out for semaphore +sets: +.IP "CREATOR (\fBa\fP,\fBc\fP)" 12 +The user of the creator of the facility entry. If the user name of the +creator is found in the user database, at least the first eight column +positions of the name shall be written using the format +.BR %s . +Otherwise, the user ID of the creator shall be written using the format +.BR %d . +.IP "CGROUP (\fBa\fP,\fBc\fP)" 12 +The group name of the creator of the facility entry. If the group name +of the creator is found in the group database, at least the first eight +column positions of the name shall be written using the format +.BR %s . +Otherwise, the group ID of the creator shall be written using the +format +.BR %d . +.IP "NSEMS (\fBa\fP,\fBb\fP)" 12 +The number of semaphores in the set associated with the semaphore +entry. This field shall be written using the format +.BR %d . +.IP "OTIME (\fBa\fP,\fBt\fP)" 12 +The time the last semaphore operation on the set associated with the +semaphore entry was completed. If a semaphore operation has ever been +performed on the corresponding semaphore set, the hour, minute, and +second of the last semaphore operation on the semaphore set shall be +written using the format +.BR %d :\c +.BR %2.2d :\c +.BR %2.2d . +Otherwise, the format +.BR \(dq\ no-entry\(dq +shall be written. +.P +The following column shall be written for all three reports when it is +requested: +.IP "CTIME (\fBa\fP,\fBt\fP)" 12 +The time the associated entry was created or changed. The hour, +minute, and second of the time when the associated entry was created +shall be written using the format +.BR %d :\c +.BR %2.2d :\c +.BR %2.2d . +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Things can change while +.IR ipcs +is running; the information it gives is guaranteed to be accurate +only when it was retrieved. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIipcrm\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fImsgrcv\fR\^(\|)", +.IR "\fImsgsnd\fR\^(\|)", +.IR "\fIsemget\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fIshmat\fR\^(\|)", +.IR "\fIshmdt\fR\^(\|)", +.IR "\fIshmget\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/jobs.1p b/man-pages-posix-2013/man1p/jobs.1p new file mode 100644 index 0000000..96288b4 --- /dev/null +++ b/man-pages-posix-2013/man1p/jobs.1p @@ -0,0 +1,343 @@ +'\" et +.TH JOBS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +jobs +\(em display status of jobs in the current session +.SH SYNOPSIS +.LP +.nf +jobs \fB[\fR\(mil|\(mip\fB] [\fIjob_id\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR jobs +utility shall display the status of jobs that were started in the +current shell environment; see +.IR "Section 2.12" ", " "Shell Execution Environment". +.P +When +.IR jobs +reports the termination status of a job, the shell shall remove its +process ID from the list of those ``known in the current shell +execution environment''; see +.IR "Section 2.9.3.1" ", " "Examples". +.SH OPTIONS +The +.IR jobs +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mil\fP" 10 +(The letter ell.) Provide more information about each job listed. This +information shall include the job number, current job, process group +ID, state, and the command that formed the job. +.IP "\fB\(mip\fP" 10 +Display only the process IDs for the process group leaders of the +selected jobs. +.P +By default, the +.IR jobs +utility shall display the status of all stopped jobs, running +background jobs and all jobs whose status has changed and have not been +reported by the shell. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIjob_id\fR" 10 +Specifies the jobs for which the status is to be displayed. If no +.IR job_id +is given, the status information for all jobs shall be displayed. The +format of +.IR job_id +is described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.204" ", " "Job Control Job ID". +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR jobs : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If the +.BR \(mip +option is specified, the output shall consist of one line for each +process ID: +.sp +.RS 4 +.nf +\fB +"%d\en", <\fIprocess ID\fR> +.fi \fR +.P +.RE +.P +Otherwise, if the +.BR \(mil +option is not specified, the output shall be a series of lines of the +form: +.sp +.RS 4 +.nf +\fB +"[%d] %c %s %s\en", <\fIjob-number\fR>, <\fIcurrent\fR>, <\fIstate\fR>, <\fIcommand\fR> +.fi \fR +.P +.RE +.P +where the fields shall be as follows: +.IP "<\fIcurrent\fP>" 10 +The character +.BR '\(pl' +identifies the job that would be used as a default for the +.IR fg +or +.IR bg +utilities; this job can also be specified using the +.IR job_id +%+ or +.BR \(dq%%\(dq . +The character +.BR '\(mi' +identifies the job that would become the default if the current default +job were to exit; this job can also be specified using the +.IR job_id +%\(mi. For other jobs, this field is a +. +At most one job can be identified with +.BR '\(pl' +and at most one job can be identified with +.BR '\(mi' . +If there is any suspended job, then the current job shall be a +suspended job. If there are at least two suspended jobs, then the +previous job also shall be a suspended job. +.IP "<\fIjob-number\fP>" 10 +A number that can be used to identify the process group to the +.IR wait , +.IR fg , +.IR bg , +and +.IR kill +utilities. Using these utilities, the job can be identified by +prefixing the job number with +.BR '%' . +.IP "<\fIstate\fP>" 10 +One of the following strings (in the POSIX locale): +.RS 10 +.IP "\fBRunning\fR" 10 +Indicates that the job has not been suspended by a signal and has not +exited. +.IP "\fBDone\fR" 10 +Indicates that the job completed and returned exit status zero. +.IP "\fBDone\fR(\fIcode\fR)" 10 +Indicates that the job completed normally and that it exited with the +specified non-zero exit status, +.IR code , +expressed as a decimal number. +.IP "\fBStopped\fR" 10 +Indicates that the job was suspended by the SIGTSTP signal. +.IP "\fBStopped\fR\ (\fBSIGTSTP\fR)" 10 +.br +Indicates that the job was suspended by the SIGTSTP signal. +.IP "\fBStopped\fR\ (\fBSIGSTOP\fR)" 10 +.br +Indicates that the job was suspended by the SIGSTOP signal. +.IP "\fBStopped\fR\ (\fBSIGTTIN\fR)" 10 +.br +Indicates that the job was suspended by the SIGTTIN signal. +.IP "\fBStopped\fR\ (\fBSIGTTOU\fR)" 10 +.br +Indicates that the job was suspended by the SIGTTOU signal. +.P +The implementation may substitute the string +.BR Suspended +in place of +.BR Stopped . +If the job was terminated by a signal, the format of <\fIstate\fP> is +unspecified, but it shall be visibly distinct from all of the other +<\fIstate\fP> formats shown here and shall indicate the name or +description of the signal causing the termination. +.RE +.IP "<\fIcommand\fR>" 10 +The associated command that was given to the shell. +.P +If the +.BR \(mil +option is specified, a field containing the process group ID shall be +inserted before the <\fIstate\fP> field. Also, more processes in a +process group may be output on separate lines, using only the process +ID and <\fIcommand\fP> fields. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.BR \(mip +option is the only portable way to find out the process group of a job +because different implementations have different strategies for +defining the process group of the job. Usage such as $(\c +.IR jobs +.BR \(mip ) +provides a way of referring to the process group of the job in an +implementation-independent way. +.P +The +.IR jobs +utility does not work as expected when it is operating in its own +utility execution environment because that environment has no +applicable jobs to manipulate. See the APPLICATION USAGE section for +.IR "\fIbg\fR\^". +For this reason, +.IR jobs +is generally implemented as a shell regular built-in. +.SH EXAMPLES +None. +.SH RATIONALE +Both +.BR \(dq%%\(dq +and +.BR \(dq%+\(dq +are used to refer to the current job. Both forms are of equal +validity\(emthe +.BR \(dq%%\(dq +mirroring +.BR \(dq$$\(dq +and +.BR \(dq%+\(dq +mirroring the output of +.IR jobs . +Both forms reflect historical practice of the KornShell and the C shell +with job control. +.P +The job control features provided by +.IR bg , +.IR fg , +and +.IR jobs +are based on the KornShell. The standard developers examined the +characteristics of the C shell versions of these utilities and found +that differences exist. Despite widespread use of the C shell, the +KornShell versions were selected for this volume of POSIX.1\(hy2008 to maintain a degree of +uniformity with the rest of the KornShell features selected (such as +the very popular command line editing features). +.P +The +.IR jobs +utility is not dependent on the job control option, as are the +seemingly related +.IR bg +and +.IR fg +utilities because +.IR jobs +is useful for examining background jobs, regardless of the condition of +job control. When the user has invoked a +.IR set +.BR +m +command and job control has been turned off, +.IR jobs +can still be used to examine the background jobs associated with that +current session. Similarly, +.IR kill +can then be used to kill background jobs with +.IR kill +%<\fIbackground job number\fP>. +.P +The output for terminated jobs is left unspecified to accommodate +various historical systems. The following formats have been witnessed: +.IP " 1." 4 +.BR Killed (\c +.IR "signal name" ) +.IP " 2." 4 +.IR "signal name" +.IP " 3." 4 +.IR "signal name" (\c +.BR coredump ) +.IP " 4." 4 +.IR "signal description" \(mi +.BR "core dumped" +.P +Most users should be able to understand these formats, although it +means that applications have trouble parsing them. +.P +The calculation of job IDs was not described since this would suggest +an implementation, which may impose unnecessary restrictions. +.P +In an early proposal, a +.BR \(min +option was included to ``Display the status of jobs that have changed, +exited, or stopped since the last status report''. It was removed +because the shell always writes any changed status of jobs before each +prompt. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.12" ", " "Shell Execution Environment", +.IR "\fIbg\fR\^", +.IR "\fIfg\fR\^", +.IR "\fIkill\fR\^", +.IR "\fIwait\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.204" ", " "Job Control Job ID", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/join.1p b/man-pages-posix-2013/man1p/join.1p new file mode 100644 index 0000000..a52a155 --- /dev/null +++ b/man-pages-posix-2013/man1p/join.1p @@ -0,0 +1,507 @@ +'\" et +.TH JOIN "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +join +\(em relational database operator +.SH SYNOPSIS +.LP +.nf +join \fB[\fR\(mia \fIfile_number\fR|\(miv \fIfile_number\fB] [\fR\(mie \fIstring\fB] [\fR\(mio \fIlist\fB] [\fR\(mit \fIchar\fB] + [\fR\(mi1 \fIfield\fB] [\fR\(mi2 \fIfield\fB]\fI file1 file2\fR +.fi +.SH DESCRIPTION +The +.IR join +utility shall perform an equality join on the files +.IR file1 +and +.IR file2 . +The joined files shall be written to the standard output. +.P +The join field is a field in each file on which the files are +compared. The +.IR join +utility shall write one line in the output for each pair of lines in +.IR file1 +and +.IR file2 +that have identical join fields. The output line by default shall +consist of the join field, then the remaining fields from +.IR file1 , +then the remaining fields from +.IR file2 . +This format can be changed by using the +.BR \(mio +option (see below). The +.BR \(mia +option can be used to add unmatched lines to the output. The +.BR \(miv +option can be used to output only unmatched lines. +.P +The files +.IR file1 +and +.IR file2 +shall be ordered in the collating sequence of +.IR sort +.BR \(mib +on the fields on which they shall be joined, by default the first in +each line. All selected output shall be written in the same collating +sequence. +.P +The default input field separators shall be + +characters. In this case, multiple separators shall count as one field +separator, and leading separators shall be ignored. The default output +field separator shall be a +. +.P +The field separator and collating sequence can be changed by using the +.BR \(mit +option (see below). +.P +If the same key appears more than once in either file, all combinations +of the set of remaining fields in +.IR file1 +and the set of remaining fields in +.IR file2 +are output in the order of the lines encountered. +.P +If the input files are not in the appropriate collating sequence, the +results are unspecified. +.SH OPTIONS +The +.IR join +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mia\ \fIfile_number\fR" 10 +.br +Produce a line for each unpairable line in file +.IR file_number , +where +.IR file_number +is 1 or 2, in addition to the default output. If both +.BR \(mia 1 +and +.BR \(mia 2 +are specified, all unpairable lines shall be output. +.IP "\fB\(mie\ \fIstring\fR" 10 +Replace empty output fields in the list selected by +.BR \(mio +with the string +.IR string . +.IP "\fB\(mio\ \fIlist\fR" 10 +Construct the output line to comprise the fields specified in +.IR list , +each element of which shall have one of the following two forms: +.RS 10 +.IP " 1." 4 +\fIfile_number.field\fR, where +.IR file_number +is a file number and +.IR field +is a decimal integer field number +.IP " 2." 4 +0 (zero), representing the join field +.P +The elements of +.IR list +shall be either +-separated +or +-separated, +as specified in Guideline 8 of the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +The fields specified by +.IR list +shall be written for all selected output lines. Fields selected by +.IR list +that do not appear in the input shall be treated as empty output +fields. (See the +.BR \(mie +option.) Only specifically requested fields shall be written. The +application shall ensure that +.IR list +is a single command line argument. +.RE +.IP "\fB\(mit\ \fIchar\fR" 10 +Use character +.IR char +as a separator, for both input and output. Every appearance of +.IR char +in a line shall be significant. When this option is specified, the +collating sequence shall be the same as +.IR sort +without the +.BR \(mib +option. +.IP "\fB\(miv\ \fIfile_number\fR" 10 +.br +Instead of the default output, produce a line only for each unpairable +line in +.IR file_number , +where +.IR file_number +is 1 or 2. If both +.BR \(miv 1 +and +.BR \(miv 2 +are specified, all unpairable lines shall be output. +.IP "\fB\(mi1\ \fIfield\fR" 10 +Join on the +.IR field th +field of file 1. Fields are decimal integers starting with 1. +.IP "\fB\(mi2\ \fIfield\fR" 10 +Join on the +.IR field th +field of file 2. Fields are decimal integers starting with 1. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile1\fR,\ \fIfile2\fR" 10 +A pathname of a file to be joined. If either of the +.IR file1 +or +.IR file2 +operands is +.BR '\(mi' , +the standard input shall be used in its place. +.SH STDIN +The standard input shall be used only if the +.IR file1 +or +.IR file2 +operand is +.BR '\(mi' . +See the INPUT FILES section. +.SH "INPUT FILES" +The input files shall be text files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR join : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale of the collating sequence +.IR join +expects to have been used when the input files were sorted. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR join +utility output shall be a concatenation of selected character fields. +When the +.BR \(mio +option is not specified, the output shall be: +.sp +.RS 4 +.nf +\fB +"%s%s%s\en", <\fIjoin field\fR>, <\fIother file1 fields\fR>, + <\fIother file2 fields\fR> +.fi \fR +.P +.RE +.P +If the join field is not the first field in a file, the +<\fIother\ file\ fields\fP> for that file shall be: +.sp +.RS 4 +.nf +\fB +<\fIfields preceding join field\fR>, <\fIfields following join field\fR> +.fi \fR +.P +.RE +.P +When the +.BR \(mio +option is specified, the output format shall be: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIconcatenation of fields\fR> +.fi \fR +.P +.RE +.P +where the concatenation of fields is described by the +.BR \(mio +option, above. +.P +For either format, each field (except the last) shall be written with +its trailing separator character. If the separator is the default (\c + +characters), a single + +shall be written after each field (except the last). +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All input files were output successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Pathnames consisting of numeric digits or of the form +.IR string.string +should not be specified directly following the +.BR \(mio +list. +.SH EXAMPLES +The +.BR \(mio +0 field essentially selects the union of the join fields. For example, +given file +.BR phone : +.sp +.RS 4 +.nf +\fB +!Name Phone Number +Don +1 123-456-7890 +Hal +1 234-567-8901 +Yasushi +2 345-678-9012 +.fi \fR +.P +.RE +.P +and file +.BR fax : +.sp +.RS 4 +.nf +\fB +!Name Fax Number +Don +1 123-456-7899 +Keith +1 456-789-0122 +Yasushi +2 345-678-9011 +.fi \fR +.P +.RE +.P +(where the large expanses of white space are meant to each represent a +single +), +the command: +.sp +.RS 4 +.nf +\fB +join \(mit "" \(mia 1 \(mia 2 \(mie '(unknown)' \(mio 0,1.2,2.2 phone fax +.fi \fR +.P +.RE +.P +would produce: +.sp +.RS 4 +.nf +\fB +!Name Phone Number Fax Number +Don +1 123-456-7890 +1 123-456-7899 +Hal +1 234-567-8901 (unknown) +Keith (unknown) +1 456-789-0122 +Yasushi +2 345-678-9012 +2 345-678-9011 +.fi \fR +.P +.RE +.P +Multiple instances of the same key will produce combinatorial results. +The following: +.sp +.RS 4 +.nf +\fB +fa: + a x + a y + a z +fb: + a p +.fi \fR +.P +.RE +.P +will produce: +.sp +.RS 4 +.nf +\fB +a x p +a y p +a z p +.fi \fR +.P +.RE +.P +And the following: +.sp +.RS 4 +.nf +\fB +fa: + a b c + a d e +fb: + a w x + a y z + a o p +.fi \fR +.P +.RE +.P +will produce: +.sp +.RS 4 +.nf +\fB +a b c w x +a b c y z +a b c o p +a d e w x +a d e y z +a d e o p +.fi \fR +.P +.RE +.SH RATIONALE +The +.BR \(mie +option is only effective when used with +.BR \(mio +because, unless specific fields are identified using +.BR \(mio , +.IR join +is not aware of what fields might be empty. The exception to this is +the join field, but identifying an empty join field with the +.BR \(mie +string is not historical practice and some scripts might break if this +were changed. +.P +The 0 field in the +.BR \(mio +list was adopted from the Tenth Edition version of +.IR join +to satisfy international objections that the +.IR join +in the base documents does not support the ``full join'' or ``outer +join'' described in relational database literature. Although it has +been possible to include a join field in the output (by default, or by +field number using +.BR \(mio ), +the join field could not be included for an unpaired line selected by +.BR \(mia . +The +.BR \(mio +0 field essentially selects the union of the join fields. +.P +This sort of outer join was not possible with the +.IR join +commands in the base documents. The +.BR \(mio +0 field was chosen because it is an upwards-compatible change for +applications. An alternative was considered: have the join field +represent the union of the fields in the files (where they are +identical for matched lines, and one or both are null for unmatched +lines). This was not adopted because it would break some historical +applications. +.P +The ability to specify +.IR file2 +as +.BR \(mi +is not historical practice; it was added for completeness. +.P +The +.BR \(miv +option is not historical practice, but was considered necessary because +it permitted the writing of +.IR only +those lines that do not match on the join field, as opposed to the +.BR \(mia +option, which prints both lines that do and do not match. This +additional facility is parallel with the +.BR \(miv +option of +.IR grep . +.P +Some historical implementations have been encountered where a blank +line in one of the input files was considered to be the end of the +file; the description in this volume of POSIX.1\(hy2008 does not cite this as an allowable case. +.P +Earlier versions of this standard allowed +.BR \(mij , +.BR \(mij1 , +.BR \(mij2 +options, and a form of the +.BR \(mio +option that allowed the +.IR list +option-argument to be multiple arguments. These forms are no longer +specified by POSIX.1\(hy2008 but may be present in some implementations. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIawk\fR\^", +.IR "\fIcomm\fR\^", +.IR "\fIsort\fR\^", +.IR "\fIuniq\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/kill.1p b/man-pages-posix-2013/man1p/kill.1p new file mode 100644 index 0000000..af6c32b --- /dev/null +++ b/man-pages-posix-2013/man1p/kill.1p @@ -0,0 +1,460 @@ +'\" et +.TH KILL "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 terminate or signal processes +.SH SYNOPSIS +.LP +.nf +kill \(mis \fIsignal_name pid\fR... +.P +kill \(mil \fB[\fIexit_status\fB]\fR +.P +kill \fB[\fR\(mi\fIsignal_name\fB] \fIpid\fR... +.P +kill \fB[\fR\(mi\fIsignal_number\fB] \fIpid\fR... +.fi +.SH DESCRIPTION +The +.IR kill +utility shall send a signal to the process or processes specified by +each +.IR pid +operand. +.P +For each +.IR pid +operand, the +.IR kill +utility shall perform actions equivalent to the +\fIkill\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008 called with the following arguments: +.IP " *" 4 +The value of the +.IR pid +operand shall be used as the +.IR pid +argument. +.IP " *" 4 +The +.IR sig +argument is the value specified by the +.BR \(mis +option, +.BR \(mi \c +.IR signal_number +option, or the +.BR \(mi \c +.IR signal_name +option, or by SIGTERM, if none of these options is specified. +.SH OPTIONS +The +.IR kill +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that in the last two SYNOPSIS forms, the +.BR \(mi \c +.IR signal_number +and +.BR \(mi \c +.IR signal_name +options are usually more than a single character. +.P +The following options shall be supported: +.IP "\fB\(mil\fP" 10 +(The letter ell.) Write all values of +.IR signal_name +supported by the implementation, if no operand is given. If an +.IR exit_status +operand is given and it is a value of the +.BR '?' +shell special parameter (see +.IR "Section 2.5.2" ", " "Special Parameters" +and +.IR wait ) +corresponding to a process that was terminated by a signal, the +.IR signal_name +corresponding to the signal that terminated the process shall be +written. If an +.IR exit_status +operand is given and it is the unsigned decimal integer value of a +signal number, the +.IR signal_name +(the symbolic constant name without the +.BR SIG +prefix defined in the Base Definitions volume of POSIX.1\(hy2008) corresponding to that signal shall be +written. Otherwise, the results are unspecified. +.IP "\fB\(mis\ \fIsignal_name\fR" 10 +.br +Specify the signal to send, using one of the symbolic names defined in +the +.IR +header. Values of +.IR signal_name +shall be recognized in a case-independent fashion, without the +.BR SIG +prefix. In addition, the symbolic name 0 shall be recognized, +representing the signal value zero. The corresponding signal shall be +sent instead of SIGTERM. +.IP "\fB\(mi\fIsignal_name\fR" 10 +.br +Equivalent to +.BR \(mis +.IR signal_name . +.IP "\fB\(mi\fIsignal_number\fR" 10 +.br +Specify a non-negative decimal integer, +.IR signal_number , +representing the signal to be used instead of SIGTERM, as the +.IR sig +argument in the effective call to +\fIkill\fR(). +The correspondence between integer values and the +.IR sig +value used is shown in the following list. +.RS 10 +.P +The effects of specifying any +.IR signal_number +other than those listed below are undefined. +.IP 0 6 +0 +.IP 1 6 +SIGHUP +.IP 2 6 +SIGINT +.IP 3 6 +SIGQUIT +.IP 6 6 +SIGABRT +.IP 9 6 +SIGKILL +.IP 14 6 +SIGALRM +.IP 15 6 +SIGTERM +.P +If the first argument is a negative integer, it shall be interpreted as a +.BR \(mi \c +.IR signal_number +option, not as a negative +.IR pid +operand specifying a process group. +.RE +.SH OPERANDS +The following operands shall be supported: +.IP "\fIpid\fR" 10 +One of the following: +.RS 10 +.IP " 1." 4 +A decimal integer specifying a process or process group to be signaled. +The process or processes selected by positive, negative, and zero +values of the +.IR pid +operand shall be as described for the +\fIkill\fR() +function. If process number 0 is specified, all processes in the +current process group shall be signaled. For the effects of negative +.IR pid +numbers, see the +\fIkill\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008. If the first +.IR pid +operand is negative, it should be preceded by +.BR \(dq\(mi\|\(mi\(dq +to keep it from being interpreted as an option. +.IP " 2." 4 +A job control job ID (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.204" ", " "Job Control Job ID") +that identifies a background process group to be signaled. The job +control job ID notation is applicable only for invocations of +.IR kill +in the current shell execution environment; see +.IR "Section 2.12" ", " "Shell Execution Environment". +.RE +.IP "\fIexit_status\fR" 10 +A decimal integer specifying a signal number or the exit status of a +process terminated by a signal. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR kill : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +When the +.BR \(mil +option is not specified, the standard output shall not be used. +.P +When the +.BR \(mil +option is specified, the symbolic name of each signal shall be written +in the following format: +.sp +.RS 4 +.nf +\fB +"%s%c", <\fIsignal_name\fR>, <\fIseparator\fR> +.fi \fR +.P +.RE +.P +where the <\fIsignal_name\fP> is in uppercase, without the +.BR SIG +prefix, and the <\fIseparator\fP> shall be either a + +or a +. +For the last signal written, <\fIseparator\fP> shall be a +. +.P +When both the +.BR \(mil +option and +.IR exit_status +operand are specified, the symbolic name of the corresponding signal +shall be written in the following format: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIsignal_name\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +At least one matching process was found for each +.IR pid +operand, and the specified signal was successfully processed for at +least one matching process. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Process numbers can be found by using +.IR ps . +.P +The job control job ID notation is not required to work as expected +when +.IR kill +is operating in its own utility execution environment. In either of +the following examples: +.sp +.RS 4 +.nf +\fB +nohup kill %1 & +system("kill %1"); +.fi \fR +.P +.RE +.P +the +.IR kill +operates in a different environment and does not share the shell's +understanding of job numbers. +.SH EXAMPLES +Any of the commands: +.sp +.RS 4 +.nf +\fB +kill \(mi9 100 \(mi165 +kill \(mis kill 100 \(mi165 +kill \(mis KILL 100 \(mi165 +.fi \fR +.P +.RE +.P +sends the SIGKILL signal to the process whose process ID is 100 and to +all processes whose process group ID is 165, assuming the sending +process has permission to send that signal to the specified processes, +and that they exist. +.P +The System Interfaces volume of POSIX.1\(hy2008 and this volume of POSIX.1\(hy2008 do not require specific signal numbers for any +.IR signal_names . +Even the +.BR \(mi \c +.IR signal_number +option provides symbolic (although numeric) names for signals. If a +process is terminated by a signal, its exit status indicates the signal +that killed it, but the exact values are not specified. The +.IR kill +.BR \(mil +option, however, can be used to map decimal signal numbers and exit +status values into the name of a signal. The following example reports +the status of a terminated job: +.sp +.RS 4 +.nf +\fB +job +stat=$? +if [ $stat \(mieq 0 ] +then + echo job completed successfully. +elif [ $stat \(migt 128 ] +then + echo job terminated by signal SIG$(kill \(mil $stat). +else + echo job terminated with error code $stat. +fi +.fi \fR +.P +.RE +.P +To send the default signal to a process group (say 123), an application +should use a command similar to one of the following: +.sp +.RS 4 +.nf +\fB +kill \(miTERM \(mi123 +kill \(mi\|\(mi \(mi123 +.fi \fR +.P +.RE +.SH RATIONALE +The +.BR \(mil +option originated from the C shell, and is also implemented in the +KornShell. The C shell output can consist of multiple output lines +because the signal names do not always fit on a single line on some +terminal screens. The KornShell output also included the +implementation-defined signal numbers and was considered by the +standard developers to be too difficult for scripts to parse +conveniently. The specified output format is intended not only to +accommodate the historical C shell output, but also to permit an +entirely vertical or entirely horizontal listing on systems for which +this is appropriate. +.P +An early proposal invented the name SIGNULL as a +.IR signal_name +for signal 0 (used by the System Interfaces volume of POSIX.1\(hy2008 to test for the existence of a process +without sending it a signal). Since the +.IR signal_name +0 can be used in this case unambiguously, SIGNULL has been removed. +.P +An early proposal also required symbolic +.IR signal_name s +to be recognized with or without the +.BR SIG +prefix. Historical versions of +.IR kill +have not written the +.BR SIG +prefix for the +.BR \(mil +option and have not recognized the +.BR SIG +prefix on +.IR signal_name s. +Since neither applications portability nor ease-of-use would be improved +by requiring this extension, it is no longer required. +.P +To avoid an ambiguity of an initial negative number argument specifying +either a signal number or a process group, POSIX.1\(hy2008 mandates that it is +always considered the former by implementations that support the XSI +option. It also requires that conforming applications always use the +.BR \(dq\(mi\|\(mi\(dq +options terminator argument when specifying a process group, unless an +option is also specified. +.P +The +.BR \(mis +option was added in response to international interest in providing +some form of +.IR kill +that meets the Utility Syntax Guidelines. +.P +The job control job ID notation is not required to work as expected +when +.IR kill +is operating in its own utility execution environment. In either of +the following examples: +.sp +.RS 4 +.nf +\fB +nohup kill %1 & +system("kill %1"); +.fi \fR +.P +.RE +.P +the +.IR kill +operates in a different environment and does not understand how the +shell has managed its job numbers. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIps\fR\^", +.IR "\fIwait\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.204" ", " "Job Control Job ID", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIkill\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/lex.1p b/man-pages-posix-2013/man1p/lex.1p new file mode 100644 index 0000000..dc02c3f --- /dev/null +++ b/man-pages-posix-2013/man1p/lex.1p @@ -0,0 +1,1374 @@ +'\" et +.TH LEX "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +lex +\(em generate programs for lexical tasks (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +lex \fB[\fR\(mit\fB] [\fR\(min|\(miv\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR lex +utility shall generate C programs to be used in lexical processing of +character input, and that can be used as an interface to +.IR yacc . +The C programs shall be generated from +.IR lex +source code and conform to the ISO\ C standard, without depending on any undefined, +unspecified, or implementation-defined behavior, except in cases where +the code is copied directly from the supplied source, or in cases that +are documented by the implementation. Usually, the +.IR lex +utility shall write the program it generates to the file +.BR lex.yy.c ; +the state of this file is unspecified if +.IR lex +exits with a non-zero exit status. See the EXTENDED DESCRIPTION +section for a complete description of the +.IR lex +input language. +.SH OPTIONS +The +.IR lex +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except for Guideline 9. +.P +The following options shall be supported: +.IP "\fB\(min\fP" 10 +Suppress the summary of statistics usually written with the +.BR \(miv +option. If no table sizes are specified in the +.IR lex +source code and the +.BR \(miv +option is not specified, then +.BR \(min +is implied. +.IP "\fB\(mit\fP" 10 +Write the resulting program to standard output instead of +.BR lex.yy.c . +.IP "\fB\(miv\fP" 10 +Write a summary of +.IR lex +statistics to the standard output. (See the discussion of +.IR lex +table sizes in +.IR "Definitions in lex".) +If the +.BR \(mit +option is specified and +.BR \(min +is not specified, this report shall be written to standard error. If +table sizes are specified in the +.IR lex +source code, and if the +.BR \(min +option is not specified, the +.BR \(miv +option may be enabled. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an input file. If more than one such +.IR file +is specified, all files shall be concatenated to produce a single +.IR lex +program. If no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' , +the standard input shall be used. +.SH STDIN +The standard input shall be used if no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' . +See INPUT FILES. +.SH "INPUT FILES" +The input files shall be text files containing +.IR lex +source code, as described in the EXTENDED DESCRIPTION section. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR lex : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular expressions. If +this variable is not set to the POSIX locale, the results are +unspecified. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files), and the behavior +of character classes within regular expressions. If this variable is +not set to the POSIX locale, the results are unspecified. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If the +.BR \(mit +option is specified, the text file of C source code output of +.IR lex +shall be written to standard output. +.P +If the +.BR \(mit +option is not specified: +.IP " *" 4 +Implementation-defined informational, error, and warning messages +concerning the contents of +.IR lex +source code input shall be written to either the standard output or +standard error. +.IP " *" 4 +If the +.BR \(miv +option is specified and the +.BR \(min +option is not specified, +.IR lex +statistics shall also be written to either the standard output or +standard error, in an implementation-defined format. These +statistics may also be generated if table sizes are specified with a +.BR '%' +operator in the +.IR Definitions +section, as long as the +.BR \(min +option is not specified. +.SH STDERR +If the +.BR \(mit +option is specified, implementation-defined informational, error, and +warning messages concerning the contents of +.IR lex +source code input shall be written to the standard error. +.P +If the +.BR \(mit +option is not specified: +.IP " 1." 4 +Implementation-defined informational, error, and warning messages +concerning the contents of +.IR lex +source code input shall be written to either the standard output or +standard error. +.IP " 2." 4 +If the +.BR \(miv +option is specified and the +.BR \(min +option is not specified, +.IR lex +statistics shall also be written to either the standard output or +standard error, in an implementation-defined format. These +statistics may also be generated if table sizes are specified with a +.BR '%' +operator in the +.IR Definitions +section, as long as the +.BR \(min +option is not specified. +.SH "OUTPUT FILES" +A text file containing C source code shall be written to +.BR lex.yy.c , +or to the standard output if the +.BR \(mit +option is present. +.SH "EXTENDED DESCRIPTION" +Each input file shall contain +.IR lex +source code, which is a table of regular expressions with corresponding +actions in the form of C program fragments. +.P +When +.BR lex.yy.c +is compiled and linked with the +.IR lex +library (using the +.BR "\(mil\ l" +operand with +.IR c99 ), +the resulting program shall read character input from the standard +input and shall partition it into strings that match the given +expressions. +.br +.P +When an expression is matched, these actions shall occur: +.IP " *" 4 +The input string that was matched shall be left in +.IR yytext +as a null-terminated string; +.IR yytext +shall either be an external character array or a pointer to a +character string. As explained in +.IR "Definitions in lex", +the type can be explicitly selected using the +.BR %array +or +.BR %pointer +declarations, but the default is implementation-defined. +.IP " *" 4 +The external +.BR int +.IR yyleng +shall be set to the length of the matching string. +.IP " *" 4 +The expression's corresponding program fragment, or action, shall be +executed. +.P +During pattern matching, +.IR lex +shall search the set of patterns for the single longest possible +match. Among rules that match the same number of characters, the rule +given first shall be chosen. +.P +The general format of +.IR lex +source shall be: +.sp +.RS +.IR Definitions +.BR %% +.IR Rules +.BR %% +.IR User Subroutines +.RE +.P +The first +.BR \(dq%%\(dq +is required to mark the beginning of the rules (regular expressions and +actions); the second +.BR \(dq%%\(dq +is required only if user subroutines follow. +.P +Any line in the +.IR Definitions +section beginning with a + +shall be assumed to be a C program fragment and shall be copied to the +external definition area of the +.BR lex.yy.c +file. Similarly, anything in the +.IR Definitions +section included between delimiter lines containing only +.BR \(dq%{\(dq +and +.BR \(dq%}\(dq +shall also be copied unchanged to the external definition area of the +.BR lex.yy.c +file. +.P +Any such input (beginning with a + +or within +.BR \(dq%{\(dq +and +.BR \(dq%}\(dq +delimiter lines) appearing at the beginning of the +.IR Rules +section before any rules are specified shall be written to +.BR lex.yy.c +after the declarations of variables for the +\fIyylex\fR() +function and before the first line of code in +\fIyylex\fR(). +Thus, user variables local to +\fIyylex\fR() +can be declared here, as well as application code to execute upon entry +to +\fIyylex\fR(). +.P +The action taken by +.IR lex +when encountering any input beginning with a + +or within +.BR \(dq%{\(dq +and +.BR \(dq%}\(dq +delimiter lines appearing in the +.IR Rules +section but coming after one or more rules is undefined. The presence +of such input may result in an erroneous definition of the +\fIyylex\fR() +function. +.P +C-language code in the input shall not contain C-language trigraphs. +The C-language code within +.BR \(dq%{\(dq +and +.BR \(dq%}\(dq +delimiter lines shall not contain any lines consisting only of +.BR \(dq%}\(dq , +or only of +.BR \(dq%%\(dq . +.SS "Definitions in lex" +.P +.IR Definitions +appear before the first +.BR \(dq%%\(dq +delimiter. Any line in this section not contained between +.BR \(dq%{\(dq +and +.BR \(dq%}\(dq +lines and not beginning with a + +shall be assumed to define a +.IR lex +substitution string. The format of these lines shall be: +.sp +.RS 4 +.nf +\fB +\fIname substitute\fR +.fi \fR +.P +.RE +.P +If a +.IR name +does not meet the requirements for identifiers in the ISO\ C standard, the result +is undefined. The string +.IR substitute +shall replace the string {\c +.IR name } +when it is used in a rule. The +.IR name +string shall be recognized in this context only when the braces are +provided and when it does not appear within a bracket expression or +within double-quotes. +.P +In the +.IR Definitions +section, any line beginning with a + +(\c +.BR '%' ) +character and followed by an alphanumeric word beginning with either +.BR 's' +or +.BR 'S' +shall define a set of start conditions. Any line beginning with a +.BR '%' +followed by a word beginning with either +.BR 'x' +or +.BR 'X' +shall define a set of exclusive start conditions. When the generated +scanner is in a +.BR %s +state, patterns with no state specified shall be also active; in a +.BR %x +state, such patterns shall not be active. The rest of the line, after +the first word, shall be considered to be one or more +-separated +names of start conditions. Start condition names shall be constructed +in the same way as definition names. Start conditions can be used to +restrict the matching of regular expressions to one or more states as +described in +.IR "Regular Expressions in lex". +.P +Implementations shall accept either of the following two +mutually-exclusive declarations in the +.IR Definitions +section: +.IP "\fB%array\fR" 10 +Declare the type of +.IR yytext +to be a null-terminated character array. +.IP "\fB%pointer\fR" 10 +Declare the type of +.IR yytext +to be a pointer to a null-terminated character string. +.P +The default type of +.IR yytext +is implementation-defined. If an application refers to +.IR yytext +outside of the scanner source file (that is, via an +.BR extern ), +the application shall include the appropriate +.BR %array +or +.BR %pointer +declaration in the scanner source file. +.P +Implementations shall accept declarations in the +.IR Definitions +section for setting certain internal table sizes. The declarations are +shown in the following table. +.sp +.ce 1 +\fBTable: Table Size Declarations in \fIlex\fP\fR +.TS +center tab(!) box; +cB | cB | cB +l | l | n. +Declaration!Description!Minimum Value +_ +%\fBp \fIn\fR!Number of positions!2\|500 +%\fBn \fIn\fR!Number of states!500 +%\fBa \fIn\fR!Number of transitions!2\|000 +%\fBe \fIn\fR!Number of parse tree nodes!1\|000 +%\fBk \fIn\fR!Number of packed character classes!1\|000 +%\fBo \fIn\fR!Size of the output array!3\|000 +.TE +.P +In the table, +.IR n +represents a positive decimal integer, preceded by one or more + +characters. The exact meaning of these table size numbers is +implementation-defined. The implementation shall document how these +numbers affect the +.IR lex +utility and how they are related to any output that may be generated by +the implementation should limitations be encountered during the +execution of +.IR lex . +It shall be possible to determine from this output which of the table +size values needs to be modified to permit +.IR lex +to successfully generate tables for the input language. The values in +the column Minimum Value represent the lowest values conforming +implementations shall provide. +.SS "Rules in lex" +.P +The rules in +.IR lex +source files are a table in which the left column contains regular +expressions and the right column contains actions (C program fragments) +to be executed when the expressions are recognized. +.sp +.RS 4 +.nf +\fB +\fIERE action +ERE action\fP +\&... +.fi \fR +.P +.RE +.P +The extended regular expression (ERE) portion of a row shall be +separated from +.IR action +by one or more + +characters. A regular expression containing + +characters shall be recognized under one of the following conditions: +.IP " *" 4 +The entire expression appears within double-quotes. +.IP " *" 4 +The + +characters appear within double-quotes or square brackets. +.IP " *" 4 +Each + +is preceded by a + +character. +.SS "User Subroutines in lex" +.P +Anything in the user subroutines section shall be copied to +.BR lex.yy.c +following +\fIyylex\fR(). +.SS "Regular Expressions in lex" +.P +The +.IR lex +utility shall support the set of extended regular expressions (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.4" ", " "Extended Regular Expressions"), +with the following additions and exceptions to the syntax: +.IP "\fR\&\(dq...\&\(dq\fR" 10 +Any string enclosed in double-quotes shall represent the characters +within the double-quotes as themselves, except that +-escapes +(which appear in the following table) shall be recognized. Any +-escape +sequence shall be terminated by the closing quote. For example, +.BR \(dq\e01\(dq \c +.BR \(dq1\(dq +represents a single string: the octal value 1 followed by the +character +.BR '1' . +.IP "<\fIstate\fR>\fIr\fR,\ <\fIstate1,state2,\fR.\|.\|.>\fIr\fR" 10 +.br +The regular expression +.IR r +shall be matched only when the program is in one of the start +conditions indicated by +.IR state , +.IR state1 , +and so on; see +.IR "Actions in lex". +(As an exception to the typographical conventions of the rest of this volume of POSIX.1\(hy2008, +in this case <\fIstate\fP> does not represent a metavariable, but the +literal angle-bracket characters surrounding a symbol.) The start +condition shall be recognized as such only at the beginning of a +regular expression. +.IP "\fIr\fP/\fIx\fP" 10 +The regular expression +.IR r +shall be matched only if it is followed by an occurrence of regular +expression +.IR x +(\c +.IR x +is the instance of trailing context, further defined below). The token +returned in +.IR yytext +shall only match +.IR r . +If the trailing portion of +.IR r +matches the beginning of +.IR x , +the result is unspecified. The +.IR r +expression cannot include further trailing context or the +.BR '$' +(match-end-of-line) operator; +.IR x +cannot include the +.BR '^' +(match-beginning-of-line) operator, nor trailing context, nor the +.BR '$' +operator. That is, only one occurrence of trailing context is allowed +in a +.IR lex +regular expression, and the +.BR '^' +operator only can be used at the beginning of such an expression. +.IP "{\fIname\fR}" 10 +When +.IR name +is one of the substitution symbols from the +.IR Definitions +section, the string, including the enclosing braces, shall be replaced +by the +.IR substitute +value. The +.IR substitute +value shall be treated in the extended regular expression as if it were +enclosed in parentheses. No substitution shall occur if {\c +.IR name } +occurs within a bracket expression or within double-quotes. +.P +Within an ERE, a + +character shall be considered to begin an escape sequence as specified +in the table in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation" +(\c +.BR '\e\e' , +.BR '\ea' , +.BR '\eb' , +.BR '\ef' , +.BR '\en' , +.BR '\er' , +.BR '\et' , +.BR '\ev' ). +In addition, the escape sequences in the following table shall be +recognized. +.P +A literal + +cannot occur within an ERE; the escape sequence +.BR '\en' +can be used to represent a +. +A + +shall not be matched by a period operator. +.br +.sp +.ce 1 +\fBTable: Escape Sequences in \fIlex\fP\fR +.ad l +.TS +center tab(@) box; +cB | cB | cB +cB | cB | cB +lf5 | lw(2.4i) | lw(2.4i). +Escape +Sequence@Description@Meaning +_ +\e\fIdigits\fP@T{ +A + +character followed by the longest sequence of one, two, or three +octal-digit characters (01234567). If all of the digits are 0 (that is, +representation of the NUL character), the behavior is undefined. +T}@T{ +The character whose encoding is represented by the one, two, or +three-digit octal integer. Multi-byte characters require +multiple, concatenated escape sequences of this type, including the +leading + +for each byte. +T} +_ +\ex\fIdigits\fP@T{ +A + +character followed by the longest sequence of hexadecimal-digit +characters (01234567abcdefABCDEF). If all of the digits are 0 (that is, +representation of the NUL character), the behavior is undefined. +T}@T{ +The character whose encoding is represented by the hexadecimal +integer. +T} +_ +\ec@T{ +A + +character followed by any character not described in this +table or in the table in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation" +(\c +.BR '\e\e' , +.BR '\ea' , +.BR '\eb' , +.BR '\ef' , +.BR '\en' , +.BR '\er' , +.BR '\et' , +.BR '\ev' ). +T}@T{ +The character +.BR 'c' , +unchanged. +T} +.TE +.ad b +.TP 10 +.BR Note: +If a +.BR '\ex' +sequence needs to be immediately followed by a hexadecimal digit +character, a sequence such as +.BR \(dq\ex1\(dq \c +.BR \(dq1\(dq +can be used, which represents a character containing the value 1, +followed by the character +.BR '1' . +.P +.P +The order of precedence given to extended regular expressions for +.IR lex +differs from that specified in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.4" ", " "Extended Regular Expressions". +The order of precedence for +.IR lex +shall be as shown in the following table, from high to low. +.TP 10 +.BR Note: +The escaped characters entry is not meant to imply that these are +operators, but they are included in the table to show their +relationships to the true operators. The start condition, trailing +context, and anchoring notations have been omitted from the table +because of the placement restrictions described in this section; they +can only appear at the beginning or ending of an ERE. +.P +.br +.sp +.ce 1 +\fBTable: ERE Precedence in \fIlex\fP\fR +.TS +center tab(@) box; +cB | cB +lf2 | lf5. +Extended Regular Expression@Precedence +_ +collation-related bracket symbols@[= =] [: :] [. .] +escaped characters@\e<\fIspecial character\fP> +bracket expression@[ ] +quoting@"..." +grouping@( ) +definition@{\fIname\fP} +single-character RE duplication@* + ? +concatenation +interval expression@{m,n} +alternation@| +.TE +.P +The ERE anchoring operators +.BR '^' +and +.BR '$' +do not appear in the table. With +.IR lex +regular expressions, these operators are restricted in their use: the +.BR '^' +operator can only be used at the beginning of an entire regular +expression, and the +.BR '$' +operator only at the end. The operators apply to the entire regular +expression. Thus, for example, the pattern +.BR \(dq(^abc)|(def$)\(dq +is undefined; it can instead be written as two separate rules, one with +the regular expression +.BR \(dq^abc\(dq +and one with +.BR \(dqdef$\(dq , +which share a common action via the special +.BR '|' +action (see below). If the pattern were written +.BR \(dq^abc|def$\(dq , +it would match either +.BR \(dqabc\(dq +or +.BR \(dqdef\(dq +on a line by itself. +.P +Unlike the general ERE rules, embedded anchoring is not allowed by most +historical +.IR lex +implementations. An example of embedded anchoring would be for +patterns such as +.BR \(dq(^|\ )foo(\ |$)\(dq +to match +.BR \(dqfoo\(dq +when it exists as a complete word. This functionality can be obtained +using existing +.IR lex +features: +.sp +.RS 4 +.nf +\fB +^foo/[ \en] | +" foo"/[ \en] /* Found foo as a separate word. */ +.fi \fR +.P +.RE +.P +Note also that +.BR '$' +is a form of trailing context (it is equivalent to +.BR \(dq/\en\(dq ) +and as such cannot be used with regular expressions containing another +instance of the operator (see the preceding discussion of trailing +context). +.P +The additional regular expressions trailing-context operator +.BR '/' +can be used as an ordinary character if presented within double-quotes, +.BR \(dq/\(dq ; +preceded by a +, +.BR \(dq\e/\(dq ; +or within a bracket expression, +.BR \(dq[/]\(dq . +The start-condition +.BR '<' +and +.BR '>' +operators shall be special only in a start condition at the beginning +of a regular expression; elsewhere in the regular expression they shall +be treated as ordinary characters. +.SS "Actions in lex" +.P +The action to be taken when an ERE is matched can be a C program +fragment or the special actions described below; the program fragment +can contain one or more C statements, and can also include special +actions. The empty C statement +.BR ';' +shall be a valid action; any string in the +.BR lex.yy.c +input that matches the pattern portion of such a rule is effectively +ignored or skipped. However, the absence of an action shall not be +valid, and the action +.IR lex +takes in such a condition is undefined. +.P +The specification for an action, including C statements and special +actions, can extend across several lines if enclosed in braces: +.sp +.RS 4 +.nf +\fB +\fIERE\fP <\fIone or more blanks\fR> { \fIprogram statement + program statement\fP } +.fi \fR +.P +.RE +.P +The program statements shall not contain unbalanced curly brace +preprocessing tokens. +.P +The default action when a string in the input to a +.BR lex.yy.c +program is not matched by any expression shall be to copy the string to +the output. Because the default behavior of a program generated by +.IR lex +is to read the input and copy it to the output, a minimal +.IR lex +source program that has just +.BR \(dq%%\(dq +shall generate a C program that simply copies the input to the output +unchanged. +.P +Four special actions shall be available: +.sp +.RS 4 +.nf +\fB +| ECHO; REJECT; BEGIN +.fi \fR +.P +.RE +.IP "\fR|\fR" 10 +The action +.BR '|' +means that the action for the next rule is the action for this rule. +Unlike the other three actions, +.BR '|' +cannot be enclosed in braces or be +-terminated; +the application shall ensure that it is specified alone, with no other +actions. +.IP "\fBECHO;\fR" 10 +Write the contents of the string +.IR yytext +on the output. +.IP "\fBREJECT;\fR" 10 +Usually only a single expression is matched by a given string in the +input. +.BR REJECT +means ``continue to the next expression that matches the current +input'', and shall cause whatever rule was the second choice after the +current rule to be executed for the same input. Thus, multiple rules +can be matched and executed for one input string or overlapping input +strings. For example, given the regular expressions +.BR \(dqxyz\(dq +and +.BR \(dqxy\(dq +and the input +.BR \(dqxyz\(dq , +usually only the regular expression +.BR \(dqxyz\(dq +would match. The next attempted match would start after +.BR z. +If the last action in the +.BR \(dqxyz\(dq +rule is +.BR REJECT , +both this rule and the +.BR \(dqxy\(dq +rule would be executed. The +.BR REJECT +action may be implemented in such a fashion that flow of control does +not continue after it, as if it were equivalent to a +.BR goto +to another part of +\fIyylex\fR(). +The use of +.BR REJECT +may result in somewhat larger and slower scanners. +.IP "\fBBEGIN\fR" 10 +The action: +.RS 10 +.sp +.RS 4 +.nf +\fB +BEGIN \fInewstate\fP; +.fi \fR +.P +.RE +.P +switches the state (start condition) to +.IR newstate . +If the string +.IR newstate +has not been declared previously as a start condition in the +.IR Definitions +section, the results are unspecified. The initial state is indicated +by the digit +.BR '0' +or the token +.BR INITIAL . +.RE +.P +The functions or macros described below are accessible to user code +included in the +.IR lex +input. It is unspecified whether they appear in the C code output of +.IR lex , +or are accessible only through the +.BR "\(mil\ l" +operand to +.IR c99 +(the +.IR lex +library). +.IP "\fBint\ \fIyylex\fR(\fBvoid\fR)" 6 +.br +Performs lexical analysis on the input; this is the primary function +generated by the +.IR lex +utility. The function shall return zero when the end of input is +reached; otherwise, it shall return non-zero values (tokens) determined +by the actions that are selected. +.IP "\fBint\ \fIyymore\fR(\fBvoid\fR)" 6 +.br +When called, indicates that when the next input string is recognized, +it is to be appended to the current value of +.IR yytext +rather than replacing it; the value in +.IR yyleng +shall be adjusted accordingly. +.IP "\fBint\ \fIyyless\fR(\fBint\ \fIn\fR)" 6 +.br +Retains +.IR n +initial characters in +.IR yytext , +NUL-terminated, and treats the remaining characters as if they had not +been read; the value in +.IR yyleng +shall be adjusted accordingly. +.IP "\fBint\ \fIinput\fR(\fBvoid\fR)" 6 +.br +Returns the next character from the input, or zero on end-of-file. It +shall obtain input from the stream pointer +.IR yyin , +although possibly via an intermediate buffer. Thus, once scanning has +begun, the effect of altering the value of +.IR yyin +is undefined. The character read shall be removed from the input +stream of the scanner without any processing by the scanner. +.IP "\fBint\ \fIunput\fR(\fBint\ \fIc\fR)" 6 +.br +Returns the character +.BR 'c' +to the input; +.IR yytext +and +.IR yyleng +are undefined until the next expression is matched. The result of +using +\fIunput\fR() +for more characters than have been input is unspecified. +.P +The following functions shall appear only in the +.IR lex +library accessible through the +.BR "\(mil\ l" +operand; they can therefore be redefined by a conforming application: +.IP "\fBint\ \fIyywrap\fR(\fBvoid\fR)" 6 +.br +Called by +\fIyylex\fR() +at end-of-file; the default +\fIyywrap\fR() +shall always return 1. If the application requires +\fIyylex\fR() +to continue processing with another source of input, then the +application can include a function +\fIyywrap\fR(), +which associates another file with the external variable +.BR "FILE *" +.IR yyin +and shall return a value of zero. +.IP "\fBint\ \fImain\fR(\fBint\ \fIargc\fR, \fBchar *\fIargv\fR[\|])" 6 +.br +Calls +\fIyylex\fR() +to perform lexical analysis, then exits. The user code can contain +\fImain\fR() +to perform application-specific operations, calling +\fIyylex\fR() +as applicable. +.P +Except for +\fIinput\fR(), +\fIunput\fR(), +and +\fImain\fR(), +all external and static names generated by +.IR lex +shall begin with the prefix +.BR yy +or +.BR YY . +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Conforming applications are warned that in the +.IR Rules +section, an ERE without an action is not acceptable, but need not be +detected as erroneous by +.IR lex . +This may result in compilation or runtime errors. +.P +The purpose of +\fIinput\fR() +is to take characters off the input stream and discard them as far as +the lexical analysis is concerned. A common use is to discard the body +of a comment once the beginning of a comment is recognized. +.P +The +.IR lex +utility is not fully internationalized in its treatment of regular +expressions in the +.IR lex +source code or generated lexical analyzer. It would seem desirable to +have the lexical analyzer interpret the regular expressions given in +the +.IR lex +source according to the environment specified when the lexical analyzer +is executed, but this is not possible with the current +.IR lex +technology. Furthermore, the very nature of the lexical analyzers +produced by +.IR lex +must be closely tied to the lexical requirements of the input language +being described, which is frequently locale-specific anyway. (For +example, writing an analyzer that is used for French text is not +automatically useful for processing other languages.) +.SH EXAMPLES +The following is an example of a +.IR lex +program that implements a rudimentary scanner for a Pascal-like +syntax: +.sp +.RS 4 +.nf +\fB +%{ +/* Need this for the call to atof() below. */ +#include +/* Need this for printf(), fopen(), and stdin below. */ +#include +%} +.P +DIGIT [0\(mi9] +ID [a\(miz][a\(miz0\(mi9]* +.P +%% +.P +{DIGIT}+ { + printf("An integer: %s (%d)\en", yytext, + atoi(yytext)); + } +.P +{DIGIT}+"."{DIGIT}* { + printf("A float: %s (%g)\en", yytext, + atof(yytext)); + } +.P +if|then|begin|end|procedure|function { + printf("A keyword: %s\en", yytext); + } +.P +{ID} printf("An identifier: %s\en", yytext); +.P +"+"|"\(mi"|"*"|"/" printf("An operator: %s\en", yytext); +.P +"{"[^}\en]*"}" /* Eat up one-line comments. */ +.P +[ \et\en]+ /* Eat up white space. */ +.P +\&. printf("Unrecognized character: %s\en", yytext); +.P +%% +.P +int main(int argc, char *argv[]) +{ + ++argv, \(mi\|\(miargc; /* Skip over program name. */ + if (argc > 0) + yyin = fopen(argv[0], "r"); + else + yyin = stdin; +.P + yylex(); +} +.fi \fR +.P +.RE +.SH RATIONALE +Even though the +.BR \(mic +option and references to the C language are retained in this +description, +.IR lex +may be generalized to other languages, as was done at one time for EFL, +the Extended FORTRAN Language. Since the +.IR lex +input specification is essentially language-independent, versions of +this utility could be written to produce Ada, Modula-2, or Pascal code, +and there are known historical implementations that do so. +.P +The current description of +.IR lex +bypasses the issue of dealing with internationalized EREs in the +.IR lex +source code or generated lexical analyzer. If it follows the model used +by +.IR awk +(the source code is assumed to be presented in the POSIX locale, but +input and output are in the locale specified by the environment +variables), then the tables in the lexical analyzer produced by +.IR lex +would interpret EREs specified in the +.IR lex +source in terms of the environment variables specified when +.IR lex +was executed. The desired effect would be to have the lexical analyzer +interpret the EREs given in the +.IR lex +source according to the environment specified when the lexical analyzer +is executed, but this is not possible with the current +.IR lex +technology. +.P +The description of octal and hexadecimal-digit escape sequences agrees +with the ISO\ C standard use of escape sequences. +.P +Earlier versions of this standard allowed for implementations with +bytes other than eight bits, but this has been modified in this +version. +.P +There is no detailed output format specification. The observed behavior +of +.IR lex +under four different historical implementations was that none of these +implementations consistently reported the line numbers for error and +warning messages. Furthermore, there was a desire that +.IR lex +be allowed to output additional diagnostic messages. Leaving message +formats unspecified avoids these formatting questions and problems with +internationalization. +.P +Although the +.BR %x +specifier for +.IR exclusive +start conditions is not historical practice, it is believed to be a +minor change to historical implementations and greatly enhances the +usability of +.IR lex +programs since it permits an application to obtain the expected +functionality with fewer statements. +.P +The +.BR %array +and +.BR %pointer +declarations were added as a compromise between historical systems. +The System V-based +.IR lex +copies the matched text to a +.IR yytext +array. The +.IR flex +program, supported in BSD and GNU systems, uses a pointer. In the +latter case, significant performance improvements are available for +some scanners. Most historical programs should require no change in +porting from one system to another because the string being referenced +is null-terminated in both cases. (The method used by +.IR flex +in its case is to null-terminate the token in place by remembering the +character that used to come right after the token and replacing it +before continuing on to the next scan.) Multi-file programs with +external references to +.IR yytext +outside the scanner source file should continue to operate on their +historical systems, but would require one of the new declarations to be +considered strictly portable. +.P +The description of EREs avoids unnecessary duplication of ERE details +because their meanings within a +.IR lex +ERE are the same as that for the ERE in this volume of POSIX.1\(hy2008. +.P +The reason for the undefined condition associated with text beginning +with a + +or within +.BR \(dq%{\(dq +and +.BR \(dq%}\(dq +delimiter lines appearing in the +.IR Rules +section is historical practice. Both the BSD and System V +.IR lex +copy the indented (or enclosed) input in the +.IR Rules +section (except at the beginning) to unreachable areas of the +\fIyylex\fR() +function (the code is written directly after a +.IR break +statement). In some cases, the System V +.IR lex +generates an error message or a syntax error, depending on the form of +indented input. +.P +The intention in breaking the list of functions into those that may +appear in +.BR lex.yy.c +\fIversus\fR those that only appear in +.BR libl.a +is that only those functions in +.BR libl.a +can be reliably redefined by a conforming application. +.P +The descriptions of standard output and standard error are somewhat +complicated because historical +.IR lex +implementations chose to issue diagnostic messages to standard output +(unless +.BR \(mit +was given). POSIX.1\(hy2008 allows this behavior, but leaves an opening +for the more expected behavior of using standard error for diagnostics. +Also, the System V behavior of writing the statistics when any table +sizes are given is allowed, while BSD-derived systems can avoid it. The +programmer can always precisely obtain the desired results by using +either the +.BR \(mit +or +.BR \(min +options. +.P +The OPERANDS section does not mention the use of +.BR \(mi +as a synonym for standard input; not all historical implementations +support such usage for any of the +.IR file +operands. +.P +A description of the +.IR "translation table" +was deleted from early proposals because of its relatively low usage in +historical applications. +.P +The change to the definition of the +\fIinput\fR() +function that allows buffering of input presents the opportunity for +major performance gains in some applications. +.P +The following examples clarify the differences between +.IR lex +regular expressions and regular expressions appearing elsewhere in +\&this volume of POSIX.1\(hy2008. For regular expressions of the form +.BR \(dqr/x\(dq , +the string matching +.IR r +is always returned; confusion may arise when the beginning of +.IR x +matches the trailing portion of +.IR r . +For example, given the regular expression +.BR \(dqa*b/cc\(dq +and the input +.BR \(dqaaabcc\(dq , +.IR yytext +would contain the string +.BR \(dqaaab\(dq +on this match. But given the regular expression +.BR \(dqx*/xy\(dq +and the input +.BR \(dqxxxy\(dq , +the token +.BR xxx , +not +.BR xx , +is returned by some implementations because +.BR xxx +matches +.BR \(dqx*\(dq . +.P +In the rule +.BR \(dqab*/bc\(dq , +the +.BR \(dqb*\(dq +at the end of +.IR r +extends +.IR r 's +match into the beginning of the trailing context, so the result is +unspecified. If this rule were +.BR \(dqab/bc\(dq , +however, the rule matches the text +.BR \(dqab\(dq +when it is followed by the text +.BR \(dqbc\(dq . +In this latter case, the matching of +.IR r +cannot extend into the beginning of +.IR x , +so the result is specified. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIc99\fR\^", +.IR "\fIed\fR\^", +.IR "\fIyacc\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Chapter 9" ", " "Regular Expressions", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/link.1p b/man-pages-posix-2013/man1p/link.1p new file mode 100644 index 0000000..12b08e0 --- /dev/null +++ b/man-pages-posix-2013/man1p/link.1p @@ -0,0 +1,122 @@ +'\" et +.TH LINK "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(em call +\fIlink\fR() +function +.SH SYNOPSIS +.LP +.nf +link \fIfile1 file2\fR +.fi +.SH DESCRIPTION +The +.IR link +utility shall perform the function call: +.sp +.RS 4 +.nf +\fB +link(\fIfile1\fR, \fIfile2\fR); +.fi \fR +.P +.RE +.P +A user may need appropriate privileges to invoke the +.IR link +utility. +.SH OPTIONS +None. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile1\fP" 10 +The pathname of an existing file. +.IP "\fIfile2\fP" 10 +The pathname of the new directory entry to be created. +.SH STDIN +Not used. +.SH "INPUT FILES" +Not used. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR link : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +None. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIln\fR\^", +.IR "\fIunlink\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIlink\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/ln.1p b/man-pages-posix-2013/man1p/ln.1p new file mode 100644 index 0000000..d3e62a0 --- /dev/null +++ b/man-pages-posix-2013/man1p/ln.1p @@ -0,0 +1,469 @@ +'\" et +.TH LN "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ln +\(em link files +.SH SYNOPSIS +.LP +.nf +ln \fB[\fR\(mifs\fB] [\fR\(miL|\(miP\fB] \fIsource_file target_file\fR +.P +ln \fB[\fR\(mifs\fB] [\fR\(miL|\(miP\fB] \fIsource_file\fR... \fItarget_dir\fR +.fi +.SH DESCRIPTION +In the first synopsis form, the +.IR ln +utility shall create a new directory entry (link) at the +destination path specified by the +.IR target_file +operand. If the +.BR \(mis +option is specified, a symbolic link shall be created for the file +specified by the +.IR source_file +operand. This first synopsis form shall be assumed when the final +operand does not name an existing directory; if more than two operands +are specified and the final is not an existing directory, an error +shall result. +.P +In the second synopsis form, the +.IR ln +utility shall create a new directory entry (link), or if the +.BR \(mis +option is specified a symbolic link, for each file specified by a +.IR source_file +operand, at a destination path in the existing directory named by +.IR target_dir . +.P +If the last operand specifies an existing file of a type not +specified by the System Interfaces volume of POSIX.1\(hy2008, the behavior is implementation-defined. +.P +The corresponding destination path for each +.IR source_file +shall be the concatenation of the target directory pathname, a + +character if the target directory pathname did not end in a +, +and the last pathname component of the +.IR source_file . +The second synopsis form shall be assumed when the final operand names +an existing directory. +.P +For each +.IR source_file : +.IP " 1." 4 +If the destination path exists and was created by a previous step, +it is unspecified whether +.IR ln +shall write a diagnostic message to standard error, do nothing more with +the current +.IR source_file , +and go on to any remaining +.IR source_file s; +or will continue processing the current +.IR source_file . +If the destination path exists: +.RS 4 +.IP " a." 4 +If the +.BR \(mif +option is not specified, +.IR ln +shall write a diagnostic message to standard error, do nothing more +with the current +.IR source_file , +and go on to any remaining +.IR source_file s. +.IP " b." 4 +If +.IR destination +names the same directory entry as the current +.IR source_file +.IR ln +shall write a diagnostic message to standard error, do nothing more with +the current +.IR source_file , +and go on to any remaining +.IR source_file s . +.IP " c." 4 +Actions shall be performed equivalent to the +\fIunlink\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008, called using +.IR destination +as the +.IR path +argument. If this fails for any reason, +.IR ln +shall write a diagnostic message to standard error, do nothing more +with the current +.IR source_file , +and go on to any remaining +.IR source_file s. +.RE +.IP " 2." 4 +If the +.BR \(mis +option is specified, actions shall be performed equivalent to the +\fIsymlink\fR() +function with +.IR source_file +as the +.IR path1 +argument and the destination path as the +.IR path2 +argument. The +.IR ln +utility shall do nothing more with +.IR source_file +and shall go on to any remaining files. +.IP " 3." 4 +If +.IR source_file +is a symbolic link: +.RS 4 +.IP " a." 4 +If the +.BR \(miP +option is in effect, actions shall be performed equivalent to the +\fIlinkat\fR() +function with +.IR source_file +as the +.IR path1 +argument, the destination path as the +.IR path2 +argument, AT_FDCWD as the +.IR fd1 +and +.IR fd2 +arguments, and zero as the +.IR flag +argument. +.IP " b." 4 +If the +.BR \(miL +option is in effect, actions shall be performed equivalent to the +\fIlinkat\fR() +function with +.IR source_file +as the +.IR path1 +argument, the destination path as the +.IR path2 +argument, AT_FDCWD as the +.IR fd1 +and +.IR fd2 +arguments, and AT_SYMLINK_FOLLOW as the +.IR flag +argument. +.P +The +.IR ln +utility shall do nothing more with +.IR source_file +and shall go on to any remaining files. +.RE +.IP " 4." 4 +Actions shall be performed equivalent to the +\fIlink\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008 using +.IR source_file +as the +.IR path1 +argument, and the destination path as the +.IR path2 +argument. +.SH OPTIONS +The +.IR ln +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mif\fP" 10 +Force existing destination pathnames to be removed to allow the link. +.IP "\fB\(miL\fP" 10 +For each +.IR source_file +operand that names a file of type symbolic link, create a (hard) +link to the file referenced by the symbolic link. +.IP "\fB\(miP\fP" 10 +For each +.IR source_file +operand that names a file of type symbolic link, create a (hard) +link to the symbolic link itself. +.IP "\fB\(mis\fP" 10 +Create symbolic links instead of hard links. If the +.BR \(mis +option is specified, the +.BR \(miL +and +.BR \(miP +options shall be silently ignored. +.P +Specifying more than one of the mutually-exclusive options +.BR \(miL +and +.BR \(miP +shall not be considered an error. The last option specified shall +determine the behavior of the utility (unless the +.BR \(mis +option causes it to be ignored). +.P +If the +.BR \(mis +option is not specified and neither a +.BR \(miL +nor a +.BR \(miP +option is specified, it is implementation-defined which of the +.BR \(miL +and +.BR \(miP +options will be used as the default. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIsource_file\fR" 10 +A pathname of a file to be linked. If the +.BR \(mis +option is specified, no restrictions on the type of file or on its +existence shall be made. If the +.BR \(mis +option is not specified, whether a directory can be linked is +implementation-defined. +.IP "\fItarget_file\fR" 10 +The pathname of the new directory entry to be created. +.IP "\fItarget_dir\fR" 10 +A pathname of an existing directory in which the new directory entries +are created. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR ln : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All the specified files were linked successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The CONSEQUENCES OF ERRORS section does not require +.IR ln +.BR \(mif +.IR "a b" +to remove +.IR b +if a subsequent link operation would fail. +.P +Some historic versions of +.IR ln +(including the one specified by the SVID) unlink the destination file, +if it exists, by default. If the mode does not permit writing, these +versions prompt for confirmation before attempting the unlink. In these +versions the +.BR \(mif +option causes +.IR ln +not to attempt to prompt for confirmation. +.P +This allows +.IR ln +to succeed in creating links when the target file already exists, even +if the file itself is not writable (although the directory must be). +Early proposals specified this functionality. +.P +This volume of POSIX.1\(hy2008 does not allow the +.IR ln +utility to unlink existing destination paths by default for the +following reasons: +.IP " *" 4 +The +.IR ln +utility has historically been used to provide locking for shell +applications, a usage that is incompatible with +.IR ln +unlinking the destination path by default. There was no corresponding +technical advantage to adding this functionality. +.IP " *" 4 +This functionality gave +.IR ln +the ability to destroy the link structure of files, which changes the +historical behavior of +.IR ln . +.IP " *" 4 +This functionality is easily replicated with a combination of +.IR rm +and +.IR ln . +.IP " *" 4 +It is not historical practice in many systems; BSD and BSD-derived +systems do not support this behavior. Unfortunately, whichever behavior +is selected can cause scripts written expecting the other behavior to +fail. +.IP " *" 4 +It is preferable that +.IR ln +perform in the same manner as the +\fIlink\fR() +function, which does not permit the target to exist already. +.P +This volume of POSIX.1\(hy2008 retains the +.BR \(mif +option to provide support for shell scripts depending on the SVID +semantics. It seems likely that shell scripts would not be written to +handle prompting by +.IR ln +and would therefore have specified the +.BR \(mif +option. +.P +The +.BR \(mif +option is an undocumented feature of many historical versions of the +.IR ln +utility, allowing linking to directories. These versions require +modification. +.P +Early proposals of this volume of POSIX.1\(hy2008 also required a +.BR \(mii +option, which behaved like the +.BR \(mii +options in +.IR cp +and +.IR mv , +prompting for confirmation before unlinking existing files. This was +not historical practice for the +.IR ln +utility and has been omitted. +.P +The +.BR \(miL +and +.BR \(miP +options allow for implementing both common behaviors of the +.IR ln +utility. Earlier versions of this standard did not specify these options +and required the behavior now described for the +.BR \(miL +option. Many systems by default or as an alternative provided a +non-conforming +.IR ln +utility with the behavior now described for the +.BR \(miP +option. Since applications could not rely on +.IR ln +following links in practice, the +.BR \(miL +and +.BR \(miP +options were added to specify the desired behavior for the application. +.P +The +.BR \(miL +and +.BR \(miP +options are ignored when +.BR \(mis +is specified in order to allow an alias to be created to alter the +default behavior when creating hard links (for example, +.IR alias +.IR ln ='\c +.IR ln +.BR \(miL '). +They serve no purpose when +.BR \(mis +is specified, since +.IR source_file +is then just a string to be used as the contents of the created symbolic +link and need not exist as a file. +.P +The specification ensures that +.IR ln +.BR a +.BR a +with or without the +.BR \(mif +option will not unlink the file +.BR a . +Earlier versions of this standard were unclear in this case. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^", +.IR "\fIfind\fR\^", +.IR "\fIpax\fR\^", +.IR "\fIrm\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIlink\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/locale.1p b/man-pages-posix-2013/man1p/locale.1p new file mode 100644 index 0000000..8855008 --- /dev/null +++ b/man-pages-posix-2013/man1p/locale.1p @@ -0,0 +1,560 @@ +'\" et +.TH LOCALE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +locale +\(em get locale-specific information +.SH SYNOPSIS +.LP +.nf +locale \fB[\fR\(mia|\(mim\fB]\fR +.P +locale \fB[\fR\(mick\fB] \fIname\fR... +.fi +.SH DESCRIPTION +The +.IR locale +utility shall write information about the current locale environment, +or all public locales, to the standard output. For the purposes of +this section, a +.IR "public locale" +is one provided by the implementation that is accessible to the +application. +.P +When +.IR locale +is invoked without any arguments, it shall summarize the current locale +environment for each locale category as determined by the settings of +the environment variables defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale". +.P +When invoked with operands, it shall write values that have been +assigned to the keywords in the locale categories, as follows: +.IP " *" 4 +Specifying a keyword name shall select the named keyword and the +category containing that keyword. +.IP " *" 4 +Specifying a category name shall select the named category and all +keywords in that category. +.SH OPTIONS +The +.IR locale +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mia\fP" 10 +Write information about all available public locales. The available +locales shall include +.BR POSIX , +representing the POSIX locale. The manner in which the implementation +determines what other locales are available is +implementation-defined. +.IP "\fB\(mic\fP" 10 +Write the names of selected locale categories; see the STDOUT section. +The +.BR \(mic +option increases readability when more than one category is selected +(for example, via more than one keyword name or via a category name). +It is valid both with and without the +.BR \(mik +option. +.IP "\fB\(mik\fP" 10 +Write the names and values of selected keywords. The implementation +may omit values for some keywords; see the OPERANDS section. +.IP "\fB\(mim\fP" 10 +Write names of available charmaps; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set". +.SH OPERANDS +The following operand shall be supported: +.IP "\fIname\fR" 10 +The name of a locale category as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +the name of a keyword in a locale category, or the reserved name +.BR charmap . +The named category or keyword shall be selected for output. If a +single +.IR name +represents both a locale category name and a keyword name in the +current locale, the results are unspecified. Otherwise, both category +and keyword names can be specified as +.IR name +operands, in any sequence. It is implementation-defined whether any +keyword values are written for the categories +.IR LC_CTYPE +and +.IR LC_COLLATE . +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR locale : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.P +The application shall ensure that the +.IR LANG , +.IR LC_* , +and +.IR NLSPATH +environment variables specify the current locale environment to be +written out; they shall be used if the +.BR \(mia +option is not specified. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR LANG +variable shall be written first using the format: +.sp +.RS 4 +.nf +\fB +"LANG=%s\en", <\fIvalue\fR> +.fi \fR +.P +.RE +.P +If +.IR LANG +is not set or is an empty string, the value is the empty string. +.P +If +.IR locale +is invoked without any options or operands, the names and values of the +.IR LC_* +environment variables described in this volume of POSIX.1\(hy2008 shall be written to the +standard output, one variable per line, and each line using the +following format. Only those variables set in the environment and not +overridden by +.IR LC_ALL +shall be written using this format: +.sp +.RS 4 +.nf +\fB +"%s=%s\en", <\fIvariable_name\fR>, <\fIvalue\fR> +.fi \fR +.P +.RE +.P +The names of those +.IR LC_* +variables associated with locale categories defined in this volume of POSIX.1\(hy2008 that are +not set in the environment or are overridden by +.IR LC_ALL +shall be written in the following format: +.sp +.RS 4 +.nf +\fB +"%s=\e"%s\e"\en", <\fIvariable_name\fR>, <\fIimplied value\fR> +.fi \fR +.P +.RE +.P +The <\fIimplied\ value\fP> shall be the name of the locale that has +been selected for that category by the implementation, based on the +values in +.IR LANG +and +.IR LC_ALL , +as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +.P +The <\fIvalue\fP> and <\fIimplied\ value\fP> shown above shall be +properly quoted for possible later reentry to the shell. The +<\fIvalue\fP> shall not be quoted using double-quotes (so that it can +be distinguished by the user from the <\fIimplied\ value\fP> case, +which always requires double-quotes). +.P +The +.IR LC_ALL +variable shall be written last, using the first format shown above. If +it is not set, it shall be written as: +.sp +.RS 4 +.nf +\fB +"LC_ALL=\en" +.fi \fR +.P +.RE +.P +If any arguments are specified: +.IP " 1." 4 +If the +.BR \(mia +option is specified, the names of all the public locales shall be +written, each in the following format: +.RS 4 +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIlocale\ name\fR> +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +If the +.BR \(mic +option is specified, the names of all selected categories shall be +written, each in the following format: +.RS 4 +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIcategory\ name\fR> +.fi \fR +.P +.RE +.P +If keywords are also selected for writing (see following items), the +category name output shall precede the keyword output for that +category. +.P +If the +.BR \(mic +option is not specified, the names of the categories shall not be +written; only the keywords, as selected by the <\fIname\fP> operand, +shall be written. +.RE +.IP " 3." 4 +If the +.BR \(mik +option is specified, the names and values of selected keywords shall be +written. If a value is non-numeric and is not a compound keyword +value, it shall be written in the following format: +.RS 4 +.sp +.RS 4 +.nf +\fB +"%s=\e"%s\e"\en", <\fIkeyword name\fR>, <\fIkeyword value\fR> +.fi \fR +.P +.RE +.P +If a value is a non-numeric compound keyword value, it shall either be +written in the format: +.sp +.RS 4 +.nf +\fB +"%s=\e"%s\e"\en", <\fIkeyword name\fR>, <\fIkeyword value\fR> +.fi \fR +.P +.RE +.P +where the <\fIkeyword value\fR> is a single string of values separated by + +characters, or it shall be written in the format: +.sp +.RS 4 +.nf +\fB +"%s=%s\en", <\fIkeyword name\fR>, <\fIkeyword value\fR> +.fi \fR +.P +.RE +.P +where the <\fIkeyword value\fP> is encoded as a set of strings, each +enclosed in double-quotation-marks, separated by + +characters. +.P +If the keyword was +.BR charmap , +the name of the charmap (if any) that was specified via the +.IR localedef +.BR \(mif +option when the locale was created shall be written, with the word +.BR charmap +as <\fIkeyword\ name\fP>. +.P +If a value is numeric, it shall be written in one of the following +formats: +.sp +.RS 4 +.nf +\fB +"%s=%d\en", <\fIkeyword name\fR>, <\fIkeyword value\fR> +.P +"%s=%c%o\en", <\fIkeyword name\fR>, <\fIescape character\fR>, <\fIkeyword value\fR> +.P +"%s=%cx%x\en", <\fIkeyword name\fR>, <\fIescape character\fR>, <\fIkeyword value\fR> +.fi \fR +.P +.RE +.P +where the <\fIescape\ character\fP> is that identified by the +.BR escape_char +keyword in the current locale; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 7.3" ", " "Locale Definition". +.P +Compound keyword values (list entries) shall be separated in the output by + +characters. When included in keyword values, the +, +, +double-quote, and any control character shall be preceded (escaped) +with the escape character. +.RE +.IP " 4." 4 +If the +.BR \(mik +option is not specified, selected keyword values shall be written, each +in the following format: +.RS 4 +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIkeyword value\fR> +.fi \fR +.P +.RE +.P +If the keyword was +.BR charmap , +the name of the charmap (if any) that was specified via the +.IR localedef +.BR \(mif +option when the locale was created shall be written. +.RE +.IP " 5." 4 +If the +.BR \(mim +option is specified, then a list of all available charmaps shall be +written, each in the format: +.RS 4 +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIcharmap\fR> +.fi \fR +.P +.RE +.P +where <\fIcharmap\fP> is in a format suitable for use as the +option-argument to the +.IR localedef +.BR \(mif +option. +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All the requested information was found and output successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +If the +.IR LANG +environment variable is not set or set to an empty value, or one of the +.IR LC_* +environment variables is set to an unrecognized value, the actual +locales assumed (if any) are implementation-defined as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +.P +Implementations are not required to write out the actual values for +keywords in the categories +.IR LC_CTYPE +and +.IR LC_COLLATE ; +however, they must write out the categories (allowing an application to +determine, for example, which character classes are available). +.SH EXAMPLES +In the following examples, the assumption is that locale environment +variables are set as follows: +.sp +.RS 4 +.nf +\fB +LANG=locale_x +LC_COLLATE=locale_y +.fi \fR +.P +.RE +.P +The command +.IR locale +would result in the following output: +.sp +.RS 4 +.nf +\fB +LANG=locale_x +LC_CTYPE="locale_x" +LC_COLLATE=locale_y +LC_TIME="locale_x" +LC_NUMERIC="locale_x" +LC_MONETARY="locale_x" +LC_MESSAGES="locale_x" +LC_ALL= +.fi \fR +.P +.RE +.P +The order of presentation of the categories is not specified by this volume of POSIX.1\(hy2008. +.P +The command: +.sp +.RS 4 +.nf +\fB +LC_ALL=POSIX locale \(mick decimal_point +.fi \fR +.P +.RE +.P +would produce: +.sp +.RS 4 +.nf +\fB +LC_NUMERIC +decimal_point="." +.fi \fR +.P +.RE +.P +The following command shows an application of +.IR locale +to determine whether a user-supplied response is affirmative: +.sp +.RS 4 +.nf +\fB +if printf "%s\en$response" | grep \(miEq "$(locale yesexpr)" +then + affirmative processing goes here +else + non-affirmative processing goes here +fi +.fi \fR +.P +.RE +.SH RATIONALE +The output for categories +.IR LC_CTYPE +and +.IR LC_COLLATE +has been made implementation-defined because there is a questionable +value in having a shell script receive an entire array of characters. +It is also difficult to return a logical collation description, short +of returning a complete +.IR localedef +source. +.P +The +.BR \(mim +option was included to allow applications to query for the existence of +charmaps. +The output is a list of the charmaps (implementation-supplied and +user-supplied, if any) on the system. +.P +The +.BR \(mic +option was included for readability when more than one category is +selected (for example, via more than one keyword name or via a category +name). It is valid both with and without the +.BR \(mik +option. +.P +The +.BR charmap +keyword, which returns the name of the charmap (if any) that was used +when the current locale was created, was included to allow applications +needing the information to retrieve it. +.P +According to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set", +the standard requires that all supported locales must have the same +encoding for + +and +, +because these two characters are used within the locale-independent +pathname resolution sequence. Therefore, it would be an error if +.IR locale +.BR \(mia +listed both ASCII and EBCDIC-based locales, since those two encodings +do not share the same representation for either + +or +. +Any system that supports both environments would be expected to provide two +POSIX locales, one in either codeset, where only the locales appropriate +to the current environment can be visible at a time. In an XSI-compliant +implementation, the +.IR dd +utility is the only portable means for performing conversions between +the two character sets. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIlocaledef\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set", +.IR "Chapter 7" ", " "Locale", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/localedef.1p b/man-pages-posix-2013/man1p/localedef.1p new file mode 100644 index 0000000..e314661 --- /dev/null +++ b/man-pages-posix-2013/man1p/localedef.1p @@ -0,0 +1,327 @@ +'\" et +.TH LOCALEDEF "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +localedef \(em define locale environment +.SH SYNOPSIS +.LP +.nf +localedef \fB[\fR\(mic\fB] [\fR\(mif \fIcharmap\fB] [\fR\(mii \fIsourcefile\fB] [\fR\(miu \fIcode_set_name\fB] \fIname\fR +.fi +.SH DESCRIPTION +The +.IR localedef +utility shall convert source definitions for locale categories into a +format usable by the functions and utilities whose operational behavior +is determined by the setting of the locale environment variables +defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale". +It is implementation-defined whether users have the capability to create +new locales, in addition to those supplied by the implementation. If +the symbolic constant POSIX2_LOCALEDEF is defined, the system supports +the creation of new locales. +On XSI-conformant systems, the symbolic constant POSIX2_LOCALEDEF +shall be defined. +.P +The utility shall read source definitions for one or more locale +categories belonging to the same locale from the file named in the +.BR \(mii +option (if specified) or from standard input. +.P +The +.IR name +operand identifies the target locale. The utility shall support the +creation of +.IR public , +or generally accessible locales, as well as +.IR private , +or restricted-access locales. Implementations may restrict the +capability to create or modify public locales to users with +appropriate privileges. +.P +Each category source definition shall be identified by the +corresponding environment variable name and terminated by an +.BR END +.IR category-name +statement. The following categories shall be supported. In addition, +the input may contain source for implementation-defined categories. +.IP "\fILC_CTYPE\fR" 10 +Defines character classification and case conversion. +.IP "\fILC_COLLATE\fR" 10 +.br +Defines collation rules. +.IP "\fILC_MONETARY\fR" 10 +.br +Defines the format and symbols used in formatting of monetary +information. +.IP "\fILC_NUMERIC\fR" 10 +.br +Defines the decimal delimiter, grouping, and grouping symbol for +non-monetary numeric editing. +.IP "\fILC_TIME\fR" 10 +Defines the format and content of date and time information. +.IP "\fILC_MESSAGES\fR" 10 +.br +Defines the format and values of affirmative and negative responses. +.SH OPTIONS +The +.IR localedef +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mic\fP" 10 +Create permanent output even if warning messages have been issued. +.IP "\fB\(mif\ \fIcharmap\fR" 10 +Specify the pathname of a file containing a mapping of character +symbols and collating element symbols to actual character encodings. +The format of the +.IR charmap +is described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.4" ", " "Character Set Description File". +The application shall ensure that this option is specified if symbolic +names (other than collating symbols defined in a +.BR collating-symbol +keyword) are used. If the +.BR \(mif +option is not present, an implementation-defined character mapping +shall be used. +.IP "\fB\(mii\ \fIinputfile\fR" 10 +The pathname of a file containing the source definitions. If this +option is not present, source definitions shall be read from standard +input. The format of the +.IR inputfile +is described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 7.3" ", " "Locale Definition". +.IP "\fB\(miu\ \fIcode_set_name\fR" 10 +.br +Specify the name of a codeset used as the target mapping of character +symbols and collating element symbols whose encoding values are defined +in terms of the ISO/IEC\ 10646\(hy1:\|2000 standard position constant values. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIname\fR" 10 +Identifies the locale; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale" +for a description of the use of this name. If the name contains one +or more + +characters, +.IR name +shall be interpreted as a pathname where the created locale definitions +shall be stored. If +.IR name +does not contain any + +characters, the interpretation of the name is implementation-defined +and the locale shall be public. The ability to create public locales in +this way may be restricted to users with appropriate privileges. (As a +consequence of specifying one +.IR name , +although several categories can be processed in one execution, only +categories belonging to the same locale can be processed.) +.SH STDIN +Unless the +.BR \(mii +option is specified, the standard input shall be a text file containing +one or more locale category source definitions, as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 7.3" ", " "Locale Definition". +When lines are continued using the escape character mechanism, +there is no limit to the length of the accumulated continued line. +.SH "INPUT FILES" +The character set mapping file specified as the +.IR charmap +option-argument is described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.4" ", " "Character Set Description File". +If a locale category source definition contains a +.BR copy +statement, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +and the +.BR copy +statement names a valid, existing locale, then +.IR localedef +shall behave as if the source definition had contained a valid category +source definition for the named locale. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR localedef : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +(This variable has no affect on +.IR localedef ; +the POSIX locale is used for this category.) +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). This variable has +no affect on the processing of +.IR localedef +input data; the POSIX locale is used for this purpose, regardless of +the value of this variable. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The utility shall report all categories successfully processed, in an +unspecified format. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The format of the created output is unspecified. If the +.IR name +operand does not contain a +, +the existence of an output file for the locale is unspecified. +.SH "EXTENDED DESCRIPTION" +When the +.BR \(miu +option is used, the +.IR code_set_name +option-argument shall be interpreted as an implementation-defined +name of a codeset to which the ISO/IEC\ 10646\(hy1:\|2000 standard position constant values shall be +converted via an implementation-defined method. Both the ISO/IEC\ 10646\(hy1:\|2000 standard +position constant values and other formats (decimal, hexadecimal, or +octal) shall be valid as encoding values within the +.IR charmap +file. The codeset represented by the implementation-defined name can +be any codeset that is supported by the implementation. +.P +When conflicts occur between the +.IR charmap +specification of <\fIcode_set_name\fP>, <\fImb_cur_max\fP>, or +<\fImb_cur_min\fP> and the implementation-defined interpretation of +these respective items for the codeset represented by the +.BR \(miu +option-argument +.IR code_set_name , +the result is unspecified. +.P +When conflicts occur between the +.IR charmap +encoding values specified for symbolic names of characters of the +portable character set and the implementation-defined assignment of +character encoding values, the result is unspecified. +.P +If a non-printable character in the +.IR charmap +has a width specified that is not +.BR \(mi1 , +the result will be undefined. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +No errors occurred and the locales were successfully created. +.IP "\01" 6 +Warnings occurred and the locales were successfully created. +.IP "\02" 6 +The locale specification exceeded implementation limits or the coded +character set or sets used were not supported by the implementation, +and no locale was created. +.IP "\03" 6 +The capability to create new locales is not supported by the +implementation. +.IP >3 6 +Warnings or errors occurred and no output was created. +.SH "CONSEQUENCES OF ERRORS" +If an error is detected, no permanent output shall be created. +.P +If warnings occur, permanent output shall be created if the +.BR \(mic +option was specified. The following conditions shall cause warning +messages to be issued: +.IP " *" 4 +If a symbolic name not found in the +.IR charmap +file is used for the descriptions of the +.IR LC_CTYPE +or +.IR LC_COLLATE +categories (for other categories, this shall be an error condition). +.IP " *" 4 +If the number of operands to the +.BR order +keyword exceeds the +{COLL_WEIGHTS_MAX} +limit. +.IP " *" 4 +If optional keywords not supported by the implementation are present in +the source. +.P +Other implementation-defined conditions may also cause warnings. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR charmap +definition is optional, and is contained outside the locale +definition. This allows both completely self-defined source files, and +generic sources (applicable to more than one codeset). To aid +portability, all +.IR charmap +definitions must use the same symbolic names for the portable character +set. As explained in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.4" ", " "Character Set Description File", +it is implementation-defined whether or not users or applications can +provide additional character set description files. Therefore, the +.BR \(mif +option might be operable only when an implementation-defined +.IR charmap +is named. +.SH EXAMPLES +None. +.SH RATIONALE +The output produced by the +.IR localedef +utility is implementation-defined. The +.IR name +operand is used to identify the specific locale. (As a consequence, +although several categories can be processed in one execution, only +categories belonging to the same locale can be processed.) +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIlocale\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.4" ", " "Character Set Description File", +.IR "Chapter 7" ", " "Locale", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/logger.1p b/man-pages-posix-2013/man1p/logger.1p new file mode 100644 index 0000000..fffb689 --- /dev/null +++ b/man-pages-posix-2013/man1p/logger.1p @@ -0,0 +1,163 @@ +'\" et +.TH LOGGER "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +logger +\(em log messages +.SH SYNOPSIS +.LP +.nf +logger \fIstring\fR... +.fi +.SH DESCRIPTION +The +.IR logger +utility saves a message, in an unspecified manner and format, +containing the +.IR string +operands provided by the user. The messages are expected to be +evaluated later by personnel performing system administration tasks. +.P +It is implementation-defined whether messages written in locales +other than the POSIX locale are effective. +.SH OPTIONS +None. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIstring\fR" 10 +One of the string arguments whose contents are concatenated together, +in the order specified, separated by single + +characters. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR logger : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. (This means +diagnostics from +.IR logger +to the user or application, not diagnostic messages that the user is +sending to the system administrator.) +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +Unspecified. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +This utility allows logging of information for later use by a system +administrator or programmer in determining why non-interactive +utilities have failed. The locations of the saved messages, their +format, and retention period are all unspecified. There is no method +for a conforming application to read messages, once written. +.SH EXAMPLES +A batch application, running non-interactively, tries to read a +configuration file and fails; it may attempt to notify the system +administrator with: +.sp +.RS 4 +.nf +\fB +logger myname: unable to read file foo. [timestamp] +.fi \fR +.P +.RE +.SH RATIONALE +The standard developers believed strongly that some method of alerting +administrators to errors was necessary. The obvious example is a batch +utility, running non-interactively, that is unable to read its +configuration files or that is unable to create or write its results +file. However, the standard developers did not wish to define the +format or delivery mechanisms as they have historically been (and will +probably continue to be) very system-specific, as well as involving +functionality clearly outside the scope of this volume of POSIX.1\(hy2008. +.P +The text with +.IR LC_MESSAGES +about diagnostic messages means diagnostics from +.IR logger +to the user or application, not diagnostic messages that the user is +sending to the system administrator. +.P +Multiple +.IR string +arguments are allowed, similar to +.IR echo , +for ease-of-use. +.P +Like the utilities +.IR mailx +and +.IR lp , +.IR logger +is admittedly difficult to test. This was not deemed sufficient +justification to exclude these utilities from this volume of POSIX.1\(hy2008. It is also +arguable that they are, in fact, testable, but that the tests +themselves are not portable. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIlp\fR\^", +.IR "\fImailx\fR\^", +.IR "\fIwrite\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/logname.1p b/man-pages-posix-2013/man1p/logname.1p new file mode 100644 index 0000000..c8fc7aa --- /dev/null +++ b/man-pages-posix-2013/man1p/logname.1p @@ -0,0 +1,132 @@ +'\" et +.TH LOGNAME "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +logname +\(em return the user's login name +.SH SYNOPSIS +.LP +.nf +logname +.fi +.SH DESCRIPTION +The +.IR logname +utility shall write the user's login name to standard output. The +login name shall be the string that would be returned by the +\fIgetlogin\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008. Under the conditions where the +\fIgetlogin\fR() +function would fail, the +.IR logname +utility shall write a diagnostic message to standard error and exit +with a non-zero exit status. +.SH OPTIONS +None. +.SH OPERANDS +None. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR logname : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR logname +utility output shall be a single line consisting of the user's login +name: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIlogin name\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR logname +utility explicitly ignores the +.IR LOGNAME +environment variable because environment changes could produce +erroneous results. +.SH EXAMPLES +None. +.SH RATIONALE +The +.BR passwd +file is not listed as required because the implementation may have +other means of mapping login names. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIid\fR\^", +.IR "\fIwho\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIgetlogin\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/lp.1p b/man-pages-posix-2013/man1p/lp.1p new file mode 100644 index 0000000..2aa2969 --- /dev/null +++ b/man-pages-posix-2013/man1p/lp.1p @@ -0,0 +1,480 @@ +'\" et +.TH LP "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +lp +\(em send files to a printer +.SH SYNOPSIS +.LP +.nf +lp \fB[\fR\(mic\fB] [\fR\(mid \fIdest\fB] [\fR\(min \fIcopies\fB] [\fR\(mimsw\fB] [\fR\(mio \fIoption\fB]\fR... \fB[\fR\(mit \fItitle\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR lp +utility shall copy the input files to an output destination in an +unspecified manner. The default output destination should be to a +hardcopy device, such as a printer or microfilm recorder, that produces +non-volatile, human-readable documents. If such a device is not +available to the application, or if the system provides no such device, +the +.IR lp +utility shall exit with a non-zero exit status. +.P +The actual writing to the output device may occur some time after the +.IR lp +utility successfully exits. During the portion of the writing that +corresponds to each input file, the implementation shall guarantee +exclusive access to the device. +.P +The +.IR lp +utility shall associate a unique +.IR "request ID" +with each request. +.P +Normally, a banner page is produced to separate and identify each print +job. This page may be suppressed by implementation-defined +conditions, such as an operator command or one of the +.BR \(mio +.IR option +values. +.SH OPTIONS +The +.IR lp +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mic\fP" 10 +Exit only after further access to any of the input files is no longer +required. The application can then safely delete or modify the files +without affecting the output operation. Normally, files are not +copied, but are linked whenever possible. If the +.BR \(mic +option is not given, then the user should be careful not to remove any +of the files before the request has been printed in its entirety. It +should also be noted that in the absence of the +.BR \(mic +option, any changes made to the named files after the request is made +but before it is printed may be reflected in the printed output. +On some implementations, +.BR \(mic +may be on by default. +.IP "\fB\(mid\ \fIdest\fR" 10 +Specify a string that names the destination (\c +.IR dest ). +If +.IR dest +is a printer, the request shall be printed only on that specific +printer. If +.IR dest +is a class of printers, the request shall be printed on the first +available printer that is a member of the class. Under certain +conditions (printer unavailability, file space limitation, and so on), +requests for specific destinations need not be accepted. Destination +names vary between systems. +.RS 10 +.P +If +.BR \(mid +is not specified, and neither the +.IR LPDEST +nor +.IR PRINTER +environment variable is set, an unspecified destination is used. The +.BR \(mid +.IR dest +option shall take precedence over +.IR LPDEST , +which in turn shall take precedence over +.IR PRINTER . +Results are undefined when +.IR dest +contains a value that is not a valid destination name. +.RE +.IP "\fB\(mim\fP" 10 +Send mail (see +.IR "\fImailx\fR\^") +after the files have been printed. By default, no mail is sent upon +normal completion of the print request. +.IP "\fB\(min\ \fIcopies\fR" 10 +Write +.IR copies +number of copies of the files, where +.IR copies +is a positive decimal integer. The methods for producing multiple +copies and for arranging the multiple copies when multiple +.IR file +operands are used are unspecified, except that each file shall be +output as an integral whole, not interleaved with portions of other +files. +.IP "\fB\(mio\ \fIoption\fR" 10 +Specify printer-dependent or class-dependent +.IR option s. +Several such +.IR option s +may be collected by specifying the +.BR \(mio +option more than once. +.IP "\fB\(mis\fP" 10 +Suppress messages from +.IR lp . +.IP "\fB\(mit\ \fItitle\fR" 10 +Write +.IR title +on the banner page of the output. +.IP "\fB\(miw\fP" 10 +Write a message on the user's terminal after the files have been +printed. If the user is not logged in, then mail shall be sent +instead. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file to be output. If no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' , +the standard input shall be used. If a +.IR file +operand is used, but the +.BR \(mic +option is not specified, the process performing the writing to the +output device may have user and group permissions that differ from that +of the process invoking +.IR lp . +.SH STDIN +The standard input shall be used only if no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' . +See the INPUT FILES section. +.SH "INPUT FILES" +The input files shall be text files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR lp : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fILC_TIME\fP" 10 +Determine the format and contents of date and time strings displayed in +the +.IR lp +banner page, if any. +.IP "\fILPDEST\fP" 10 +Determine the destination. If the +.IR LPDEST +environment variable is not set, the +.IR PRINTER +environment variable shall be used. The +.BR \(mid +.IR dest +option takes precedence over +.IR LPDEST . +Results are undefined when +.BR \(mid +is not specified and +.IR LPDEST +contains a value that is not a valid destination name. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPRINTER\fP" 10 +Determine the output device or destination. If the +.IR LPDEST +and +.IR PRINTER +environment variables are not set, an unspecified output device is +used. The +.BR \(mid +.IR dest +option and the +.IR LPDEST +environment variable shall take precedence over +.IR PRINTER . +Results are undefined when +.BR \(mid +is not specified, +.IR LPDEST +is unset, and +.IR PRINTER +contains a value that is not a valid device or destination name. +.IP "\fITZ\fP" 10 +Determine the timezone used to calculate date and time strings +displayed in the +.IR lp +banner page, if any. If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR lp +utility shall write a +.IR "request ID" +to the standard output, unless +.BR \(mis +is specified. The format of the message is unspecified. The request +ID can be used on systems supporting the historical +.IR cancel +and +.IR lpstat +utilities. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All input files were processed successfully. +.IP >0 6 +No output device was available, or an error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR pr +and +.IR fold +utilities can be used to achieve reasonable formatting for the +implementation's default page size. +.P +A conforming application can use one of the +.IR file +operands only with the +.BR \(mic +option or if the file is publicly readable and guaranteed to be +available at the time of printing. This is because POSIX.1\(hy2008 gives +the implementation the freedom to queue up the request for printing at +some later time by a different process that might not be able to access +the file. +.SH EXAMPLES +.IP " 1." 4 +To print file +.IR file : +.RS 4 +.sp +.RS 4 +.nf +\fB +lp \(mic \fIfile\fR +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +To print multiple files with headers: +.RS 4 +.sp +.RS 4 +.nf +\fB +pr \fIfile1 file2\fP | lp +.fi \fR +.P +.RE +.RE +.SH RATIONALE +The +.IR lp +utility was designed to be a basic version of a utility that is already +available in many historical implementations. The standard developers +considered that it should be implementable simply as: +.sp +.RS 4 +.nf +\fB +cat "$@" > /dev/lp +.fi \fR +.P +.RE +.P +after appropriate processing of options, if that is how the +implementation chose to do it and if exclusive access could be granted +(so that two users did not write to the device simultaneously). +Although in the future the standard developers may add other options to +this utility, it should always be able to execute with no options or +operands and send the standard input to an unspecified output device. +.P +This volume of POSIX.1\(hy2008 makes no representations concerning the format of the printed +output, except that it must be ``human-readable'' and ``non-volatile''. +Thus, writing by default to a disk or tape drive or a display terminal +would not qualify. (Such destinations are not prohibited when +.BR \(mid +.IR dest , +.IR LPDEST , +or +.IR PRINTER +are used, however.) +.P +This volume of POSIX.1\(hy2008 is worded such that a ``print job'' consisting of multiple input +files, possibly in multiple copies, is guaranteed to print so that any +one file is not intermixed with another, but there is no statement that +all the files or copies have to print out together. +.P +The +.BR \(mic +option may imply a spooling operation, but this is not required. The +utility can be implemented to wait until the printer is ready and then +wait until it is finished. Because of that, there is no attempt to +define a queuing mechanism (priorities, classes of output, and so on). +.P +On some historical systems, the request ID reported on the STDOUT +can be used to later cancel or find the status of a request using +utilities not defined in this volume of POSIX.1\(hy2008. +.P +Although the historical System V +.IR lp +and BSD +.IR lpr +utilities have provided similar functionality, they used different +names for the environment variable specifying the destination printer. +Since the name of the utility here is +.IR lp , +.IR LPDEST +(used by the System V +.IR lp +utility) was given precedence over +.IR PRINTER +(used by the BSD +.IR lpr +utility). Since environments of users frequently contain one or the +other environment variable, the +.IR lp +utility is required to recognize both. If this was not done, many +applications would send output to unexpected output devices when users +moved from system to system. +.P +Some have commented that +.IR lp +has far too little functionality to make it worthwhile. Requests have +proposed additional options or operands or both that added +functionality. The requests included: +.IP " *" 4 +Wording +.IR requiring +the output to be ``hardcopy'' +.IP " *" 4 +A requirement for multiple printers +.IP " *" 4 +Options for supporting various page-description languages +.P +Given that a compliant system is not required to even have a printer, +placing further restrictions upon the behavior of the printer is not +useful. Since hardcopy format is so application-dependent, it is +difficult, if not impossible, to select a reasonable subset of +functionality that should be required on all compliant systems. +.P +The term \fIunspecified\fR is used in this section in lieu of +\fIimplementation-defined\fR as most known implementations would not be +able to make definitive statements in their conformance documents; the +existence and usage of printers is very dependent on how the system +administrator configures each individual system. +.P +Since the default destination, device type, queuing mechanisms, and +acceptable forms of input are all unspecified, usage guidelines for +what a conforming application can do are as follows: +.IP " *" 4 +Use the command in a pipeline, or with +.BR \(mic , +so that there are no permission problems and the files can be safely +deleted or modified. +.IP " *" 4 +Limit output to text files of reasonable line lengths and printable +characters and include no device-specific formatting information, such +as a page description language. The meaning of ``reasonable'' in this +context can only be answered as a quality-of-implementation issue, but +it should be apparent from historical usage patterns in the industry +and the locale. The +.IR pr +and +.IR fold +utilities can be used to achieve reasonable formatting for the default +page size of the implementation. +.P +Alternatively, the application can arrange its installation in such a +way that it requires the system administrator or operator to provide +the appropriate information on +.IR lp +options and environment variable values. +.P +At a minimum, having this utility in this volume of POSIX.1\(hy2008 tells the industry that +conforming applications require a means to print output and provides at +least a command name and +.IR LPDEST +routing mechanism that can be used for discussions between vendors, +application developers, and users. The use of ``should'' in the +DESCRIPTION of +.IR lp +clearly shows the intent of the standard developers, even if they +cannot mandate that all systems (such as laptops) have printers. +.P +This volume of POSIX.1\(hy2008 does not specify what the ownership of the process performing the +writing to the output device may be. If +.BR \(mic +is not used, it is unspecified whether the process performing the +writing to the output device has permission to read +.IR file +if there are any restrictions in place on who may read +.IR file +until after it is printed. Also, if +.BR \(mic +is not used, the results of deleting +.IR file +before it is printed are unspecified. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImailx\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/ls.1p b/man-pages-posix-2013/man1p/ls.1p new file mode 100644 index 0000000..0131cc3 --- /dev/null +++ b/man-pages-posix-2013/man1p/ls.1p @@ -0,0 +1,1134 @@ +'\" et +.TH LS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ls +\(em list directory contents +.SH SYNOPSIS +.LP +.nf +ls \fB[\fR\(miikqrs\fB] [\fR\(mig\|lno\|\fB] [\fR\(miA|\(mia\fB] [\fR\(miC|\(mim|\(mix|\(mi1\fB]\fR \e + \fB[\fR\(miF|\(mip\fB] [\fR\(miH|\(miL\fB] [\fR\(miR|\(mid\fB] [\fR\(miS|\(mif|\(mit\fB] [\fR\(mic|\(miu\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +For each operand that names a file of a type other than directory or +symbolic link to a directory, +.IR ls +shall write the name of the file as well as any requested, associated +information. For each operand that names a file of type directory, +.IR ls +shall write the names of files contained within the directory as well +as any requested, associated information. Filenames beginning +with a + +(\c +.BR '.' ) +and any associated information shall not be written out unless +explicitly referenced, the +.BR \(miA +or +.BR \(mia +option is supplied, or an implementation-defined condition causes them +to be written. If one or more of the +.BR \(mid , +.BR \(miF , +or +.BR \(mil +options are specified, and neither the +.BR \(miH +nor the +.BR \(miL +option is specified, for each operand that names a file of type +symbolic link to a directory, +.IR ls +shall write the name of the file as well as any requested, associated +information. If none of the +.BR \(mid , +.BR \(miF , +or +.BR \(mil +options are specified, or the +.BR \(miH +or +.BR \(miL +options are specified, for each operand that names a file of type +symbolic link to a directory, +.IR ls +shall write the names of files contained within the directory as well +as any requested, associated information. In each case where the names +of files contained within a directory are written, if the directory +contains any symbolic links then +.IR ls +shall evaluate the file information and file type to be those of +the symbolic link itself, unless the +.BR \(miL +option is specified. +.P +If no operands are specified, +.IR ls +shall behave as if a single operand of dot (\c +.BR '.' ) +had been specified. If more than one operand is specified, +.IR ls +shall write non-directory operands first; it shall sort directory and +non-directory operands separately according to the collating sequence +in the current locale. +.P +The +.IR ls +utility shall detect infinite loops; that is, entering a previously +visited directory that is an ancestor of the last file encountered. +When it detects an infinite loop, +.IR ls +shall write a diagnostic message to standard error and shall either +recover its position in the hierarchy or terminate. +.SH OPTIONS +The +.IR ls +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(miA\fP" 10 +Write out all directory entries, including those whose names begin with a + +(\c +.BR '.' ) +but excluding the entries dot and dot-dot (if they exist). +.IP "\fB\(miC\fP" 10 +Write multi-text-column output with entries sorted down the columns, +according to the collating sequence. The number of text columns and the +column separator characters are unspecified, but should be adapted to +the nature of the output device. This option disables long format output. +.IP "\fB\(miF\fP" 10 +Do not follow symbolic links named as operands unless the +.BR \(miH +or +.BR \(miL +options are specified. Write a + +(\c +.BR '/' ) +immediately after each pathname that is a directory, an + +(\c +.BR '*' ) +after each that is executable, a + +(\c +.BR '|' ) +after each that is a FIFO, and an at-sign (\c +.BR '@' ) +after each that is a symbolic link. For other file types, other +symbols may be written. +.IP "\fB\(miH\fP" 10 +Evaluate the file information and file type for symbolic links specified +on the command line to be those of the file referenced by the link, +and not the link itself; however, +.IR ls +shall write the name of the link itself and not the file referenced by +the link. +.IP "\fB\(miL\fP" 10 +Evaluate the file information and file type for all symbolic links +(whether named on the command line or encountered in a file hierarchy) +to be those of the file referenced by the link, and not the link +itself; however, +.IR ls +shall write the name of the link itself and not the file referenced by +the link. When +.BR \(miL +is used with +.BR \(mil , +write the contents of symbolic links in the long format (see the STDOUT +section). +.IP "\fB\(miR\fP" 10 +Recursively list subdirectories encountered. When a symbolic link to a +directory is encountered, the directory shall not be recursively listed +unless the +.BR \(miL +option is specified. +The use of +.BR \(miR +with +.BR \(mid +or +.BR \(mif +produces unspecified results. +.IP "\fB\(miS\fP" 10 +Sort with the primary key being file size (in decreasing order) and the +secondary key being filename in the collating sequence (in increasing +order). +.IP "\fB\(mia\fP" 10 +Write out all directory entries, including those whose names begin with a + +(\c +.BR '.' ). +.IP "\fB\(mic\fP" 10 +Use time of last modification of the file status information (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP") +instead of last modification of the file itself for sorting (\c +.BR \(mit ) +or writing (\c +.BR \(mil ). +.IP "\fB\(mid\fP" 10 +Do not follow symbolic links named as operands unless the +.BR \(miH +or +.BR \(miL +options are specified. Do not treat directories differently than other +types of files. The use of +.BR \(mid +with +.BR \(miR +or +.BR \(mif +produces unspecified results. +.IP "\fB\(mif\fP" 10 +List the entries in directory operands in the order they appear in the +directory. The behavior for non-directory operands is unspecified. This +option shall turn on +.BR \(mia . +When +.BR \(mif +is specified, any occurrences of the +.BR \(mir , +.BR \(miS , +and +.BR \(mit +options shall be ignored and any occurrences of the +.BR \(miA , +.BR \(mig , +.BR \(mil , +.BR \(min , +.BR \(mio , +and +.BR \(mis +options may be ignored. The use of +.BR \(mif +with +.BR \(miR +or +.BR \(mid +produces unspecified results. +.IP "\fB\(mig\fP" 10 +Turn on the +.BR \(mil +(ell) option, but disable writing the file's owner name or number. +Disable the +.BR \(miC , +.BR \(mim , +and +.BR \(mix +options. +.IP "\fB\(mii\fP" 10 +For each file, write the file's file serial number (see +\fIstat\fR() +in the System Interfaces volume of POSIX.1\(hy2008). +.IP "\fB\(mik\fP" 10 +Set the block size for the +.BR \(mis +option and the per-directory block count written for the +.BR \(mil , +.BR \(min , +.BR \(mis , +.BR \(mig , +and +.BR \(mio +options (see the STDOUT section) to 1\|024 bytes. +.IP "\fB\(mil\fP" 10 +(The letter ell.) Do not follow symbolic links named as operands unless +the +.BR \(miH +or +.BR \(miL +options are specified. Write out in long format (see the STDOUT +section). Disable the +.BR \(miC , +.BR \(mim , +and +.BR \(mix +options. +.IP "\fB\(mim\fP" 10 +Stream output format; list pathnames across the page, separated by a + +character followed by a + +character. Use a + +character as the list terminator and after the separator sequence when +there is not room on a line for the next list entry. This option disables +long format output. +.IP "\fB\(min\fP" 10 +Turn on the +.BR \(mil +(ell) option, but when writing the file's owner or group, write +the file's numeric UID or GID rather than the user or group name, +respectively. Disable the +.BR \(miC , +.BR \(mim , +and +.BR \(mix +options. +.IP "\fB\(mio\fP" 10 +Turn on the +.BR \(mil +(ell) option, but disable writing the file's group name or number. +Disable the +.BR \(miC , +.BR \(mim , +and +.BR \(mix +options. +.IP "\fB\(mip\fP" 10 +Write a + +(\c +.BR '/' ) +after each filename if that file is a directory. +.IP "\fB\(miq\fP" 10 +Force each instance of non-printable filename characters and + +characters to be written as the + +(\c +.BR '?' ) +character. Implementations may provide this option by default if the +output is to a terminal device. +.IP "\fB\(mir\fP" 10 +Reverse the order of the sort to get reverse collating sequence oldest +first, or smallest file size first depending on the other options +given. +.IP "\fB\(mis\fP" 10 +Indicate the total number of file system blocks consumed by each file +displayed. If the +.BR \(mik +option is also specified, the block size shall be 1\|024 bytes; +otherwise, the block size is implementation-defined. +.IP "\fB\(mit\fP" 10 +Sort with the primary key being time modified (most recently modified +first) and the secondary key being filename in the collating sequence. +For a symbolic link, the time used as the sort key is that of the +symbolic link itself, unless +.IR ls +is evaluating its file information to be that of the file referenced +by the link (see the +.BR \(miH +and +.BR \(miL +options). +.IP "\fB\(miu\fP" 10 +Use time of last access (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP") +instead of last modification of the file for sorting (\c +.BR \(mit ) +or writing (\c +.BR \(mil ). +.IP "\fB\(mix\fP" 10 +The same as +.BR \(miC , +except that the multi-text-column output is produced with entries sorted +across, rather than down, the columns. This option disables long format +output. +.IP "\fB\(mi1\fP" 10 +(The numeric digit one.) Force output to be one entry per line. +This option does not disable long format output. (Long format output is +enabled by +.BR \(mig , +.BR \(mil +(ell), +.BR \(min , +and +.BR \(mio ; +and disabled by +.BR \(miC , +.BR \(mim , +and +.BR \(mix .) +.P +If an option that enables long format output (\c +.BR \(mig , +.BR \(mil +(ell), +.BR \(min , +and +.BR "\\(mio\|\" ) +is given with an option that disables long format output (\c +.BR \(miC , +.BR \(mim , +and +.BR \(mix ), +this shall not be considered an error. The last of these options +specified shall determine whether long format output is written. +.P +If +.BR \(miR , +.BR \(mid , +or +.BR \(mif +are specified, the results of specifying these mutually-exclusive options +are specified by the descriptions of these options above. If more +than one of any of the other options shown in the SYNOPSIS section in +mutually-exclusive sets are given, this shall not be considered an error; +the last option specified in each set shall determine the output. +.P +Note that if +.BR \(mit +is specified, +.BR \(mic +and +.BR \(miu +are not only mutually-exclusive with each other, they are also +mutually-exclusive with +.BR \(miS +when determining sort order. But even if +.BR \(miS +is specified after all occurrences of +.BR \(mic , +.BR \(mit , +and +.BR \(miu , +the last use of +.BR \(mic +or +.BR \(miu +determines the timestamp printed when producing long format output. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file to be written. If the file specified is not +found, a diagnostic message shall be output on standard error. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.br +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR ls : +.IP "\fICOLUMNS\fP" 10 +Determine the user's preferred column position width for writing +multiple text-column output. If this variable contains a string +representing a decimal integer, the +.IR ls +utility shall calculate how many pathname text columns to write (see +.BR \(miC ) +based on the width provided. If +.IR COLUMNS +is not set or invalid, an implementation-defined number of column +positions shall be assumed, based on the implementation's knowledge of +the output device. The column width chosen to write the names of files +in any given directory shall be constant. Filenames shall not be +truncated to fit into the multiple text-column output. +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for character collation information in determining +the pathname collation sequence. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to multi-byte +characters in arguments) and which characters are defined as printable +(character class +.BR print ). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILC_TIME\fP" 10 +Determine the format and contents for date and time strings written by +.IR ls . +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITZ\fP" 10 +Determine the timezone for date and time strings written by +.IR ls . +If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The default format shall be to list one entry per line to standard +output; the exceptions are to terminals or when one of the +.BR \(miC , +.BR \(mim , +or +.BR \(mix +options is specified. If the output is to a terminal, the format is +implementation-defined. +.P +When +.BR \(mim +is specified, the format used for the last element of the list +shall be: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIfilename\fR> +.fi \fR +.P +.RE +.P +The format used for each other element of the list shall be: +.sp +.RS 4 +.nf +\fB +"%s,%s", <\fIfilename\fR>, <\fIseparator\fR> +.fi \fR +.P +.RE +.P +where, if there is not room for the next element of the list to fit +within the current line length, <\fIseparator\fP> is a string containing +an optional + +character and a mandatory + +character; otherwise it is a single + +character. +.P +If the +.BR \(mii +option is specified, the file's file serial number (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP") +shall be written in the following format before any other output for +the corresponding entry: +.sp +.RS 4 +.nf +\fB +%u ", <\fIfile serial number\fR> +.fi \fR +.P +.RE +.P +If the +.BR \(mil +option is specified, the following information shall be written for +files other than character special and block special files: +.sp +.RS 4 +.nf +\fB +"%s %u %s %s %u %s %s\en", <\fIfile mode\fR>, <\fInumber of links\fR>, + <\fIowner name\fR>, <\fIgroup name\fR>, <\fIsize\fR>, <\fIdate and time\fR>, + <\fIpathname\fR> +.fi \fR +.P +.RE +.P +If the +.BR \(mil +option is specified, the following information shall be written +for character special and block special files: +.sp +.RS 4 +.nf +\fB +"%s %u %s %s %s %s %s\en", <\fIfile mode\fR>, <\fInumber of links\fR>, + <\fIowner name\fR>, <\fIgroup name\fR>, <\fIdevice info\fR>, <\fIdate and time\fR>, + <\fIpathname\fR> +.fi \fR +.P +.RE +.P +In both cases if the file is a symbolic link and the +.BR \(miL +option is also specified, this information shall be for the file +resolved from the symbolic link, except that the <\fIpathname\fP> field +shall contain the pathname of the symbolic link itself. If the file is +a symbolic link and the +.BR \(miL +option is not specified, this information shall be about the link itself +and the <\fIpathname\fP> field shall be of the form: +.sp +.RS 4 +.nf +\fB +"%s \(mi> %s", <\fIpathname of link\fR>, <\fIcontents of link\fR> +.fi \fR +.P +.RE +.P +The +.BR \(min , +.BR \(mig , +and +.BR \(mio +options use the same format as +.BR \(mil , +but with omitted items and their associated + +characters. See the OPTIONS section. +.P +In both the preceding +.BR \(mil +forms, if <\fIowner name\fR> or <\fIgroup name\fR> cannot be +determined, or if +.BR \(min +is given, they shall be replaced with their associated numeric values +using the format +.BR %u . +.P +The <\fIsize\fP> field shall contain the value that would be returned +for the file in the +.IR st_size +field of +.BR "struct stat" +(see the Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP"). +Note that for some file types this value is unspecified. +.P +The <\fIdevice\ info\fP> field shall contain implementation-defined +information associated with the device in question. +.P +The <\fIdate\ and\ time\fP> field shall contain the appropriate date +and timestamp of when the file was last modified. In the POSIX locale, +the field shall be the equivalent of the output of the following +.IR date +command: +.sp +.RS 4 +.nf +\fB +date "+%b %e %H:%M" +.fi \fR +.P +.RE +.P +if the file has been modified in the last six months, or: +.sp +.RS 4 +.nf +\fB +date "+%b %e %Y" +.fi \fR +.P +.RE +.P +(where two + +characters are used between +.BR %e +and +.BR %Y ) +if the file has not been modified in the last six months or if the +modification date is in the future, except that, in both cases, the final + +produced by +.IR date +shall not be included and the output shall be as if the +.IR date +command were executed at the time of the last modification date of the +file rather than the current time. When the +.IR LC_TIME +locale category is not set to the POSIX locale, a different format and +order of presentation of this field may be used. +.P +If the pathname was specified as a +.IR file +operand, it shall be written as specified. +.P +The file mode written under the +.BR \(mil , +.BR \(min , +.BR \(mig , +and +.BR \(mio +options shall consist of the following format: +.sp +.RS 4 +.nf +\fB +"%c%s%s%s%s", <\fIentry type\fR>, <\fIowner permissions\fR>, + <\fIgroup permissions\fR>, <\fIother permissions\fR>, + <\fIoptional alternate access method flag\fR> +.fi \fR +.P +.RE +.P +The <\fIoptional\ alternate\ access\ method\ flag\fP> shall be the +empty string if there is no alternate or additional access control +method associated with the file; otherwise, it shall be a string +containing a single printable character that is not a +. +.P +The <\fIentry\ type\fP> character shall describe the type of file, as +follows: +.IP "\fRd\fP" 8 +Directory. +.IP "\fRb\fP" 8 +Block special file. +.IP "\fRc\fP" 8 +Character special file. +.IP "\fRl\fP\ (ell)" 8 +Symbolic link. +.IP "\fRp\fP" 8 +FIFO. +.IP "\fR\(mi\fP" 8 +Regular file. +.P +Implementations may add other characters to this list to represent +other implementation-defined file types. +.P +The next three fields shall be three characters each: +.IP "<\fIowner permissions\fP>" 6 +.br +Permissions for the file owner class (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.4" ", " "File Access Permissions"). +.IP "<\fIgroup permissions\fP>" 6 +.br +Permissions for the file group class. +.IP "<\fIother permissions\fP>" 6 +.br +Permissions for the file other class. +.P +Each field shall have three character positions: +.IP " 1." 4 +If +.BR 'r' , +the file is readable; if +.BR '\(mi' , +the file is not readable. +.IP " 2." 4 +If +.BR 'w' , +the file is writable; if +.BR '\(mi' , +the file is not writable. +.IP " 3." 4 +The first of the following that applies: +.RS 4 +.IP "\fRS\fR" 6 +If in <\fIowner\ permissions\fP>, the file is not executable and +set-user-ID mode is set. If in <\fIgroup\ permissions\fP>, the file is +not executable and set-group-ID mode is set. +.IP "\fRs\fR" 6 +If in <\fIowner\ permissions\fP>, the file is executable and +set-user-ID mode is set. If in <\fIgroup\ permissions\fP>, the file is +executable and set-group-ID mode is set. +.IP "\fRT\fR" 6 +If in <\fIother\ permissions\fP> and the file is a directory, search +permission is not granted to others, and the restricted deletion flag +is set. +.IP "\fRt\fR" 6 +If in <\fIother\ permissions\fP> and the file is a directory, search +permission is granted to others, and the restricted deletion flag +is set. +.IP "\fRx\fR" 6 +The file is executable or the directory is searchable. +.IP "\fR\(mi\fR" 6 +None of the attributes of +.BR 'S' , +.BR 's' , +.BR 'T' , +.BR 't' , +or +.BR 'x' +applies. +.P +Implementations may add other characters to this list for the third +character position. Such additions shall, however, be written in +lowercase if the file is executable or searchable, and in uppercase if +it is not. +.RE +.P +If any of the +.BR \(mil , +.BR \(min , +.BR \(mis , +.BR \(mig , +or +.BR \(mio +options is specified, each list of files within the directory shall be +preceded by a status line indicating the number of file system blocks +occupied by files in the directory in 512-byte units if the +.BR \(mik +option is not specified, or 1\|024-byte units if the +.BR \(mik +option is specified, rounded up to the next integral number of units, +if necessary. In the POSIX locale, the format shall be: +.sp +.RS 4 +.nf +\fB +"total %u\en", <\fInumber of units in the directory\fR> +.fi \fR +.P +.RE +.P +If more than one directory, or a combination of non-directory files and +directories are written, either as a result of specifying multiple +operands, or the +.BR \(miR +option, each list of files within a directory shall be preceded by: +.sp +.RS 4 +.nf +\fB +"\en%s:\en", <\fIdirectory name\fR> +.fi \fR +.P +.RE +.P +If this string is the first thing to be written, the first + +shall not be written. This output shall precede the number of units in +the directory. +.P +If the +.BR \(mis +option is given, each file shall be written with the number of blocks +used by the file. Along with +.BR \(miC , +.BR \(mi1 , +.BR \(mim , +or +.BR \(mix , +the number and a + +shall precede the filename; with +.BR \(mil , +.BR \(min , +.BR \(mig , +or +.BR \(mio , +they shall precede each line describing a file. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Many implementations use the + +(\c +.BR '=' ) +to denote sockets bound to the file system for the +.BR \(miF +option. Similarly, many historical implementations use the +.BR 's' +character to denote sockets as the entry type characters for the +.BR \(mil +option. +.P +It is difficult for an application to use every part of the file modes +field of +.IR ls +.BR \(mil +in a portable manner. Certain file types and executable bits are not +guaranteed to be exactly as shown, as implementations may have +extensions. Applications can use this field to pass directly to a user +printout or prompt, but actions based on its contents should generally +be deferred, instead, to the +.IR test +utility. +.P +The output of +.IR ls +(with the +.BR \(mil +and related options) contains information that logically could be used +by utilities such as +.IR chmod +and +.IR touch +to restore files to a known state. However, this information is +presented in a format that cannot be used directly by those utilities +or be easily translated into a format that can be used. A character +has been added to the end of the permissions string so that +applications at least have an indication that they may be working in an +area they do not understand instead of assuming that they can translate +the permissions string into something that can be used. Future versions +or related documents may define one or more specific characters to be +used based on different standard additional or alternative access +control mechanisms. +.P +As with many of the utilities that deal with filenames, the output of +.IR ls +for multiple files or in one of the long listing formats must be used +carefully on systems where filenames can contain embedded white +space. Systems and system administrators should institute policies and +user training to limit the use of such filenames. +.P +The number of disk blocks occupied by the file that it reports varies +depending on underlying file system type, block size units reported, +and the method of calculating the number of blocks. On some file +system types, the number is the actual number of blocks occupied by the +file (counting indirect blocks and ignoring holes in the file); on +others it is calculated based on the file size (usually making an +allowance for indirect blocks, but ignoring holes). +.SH EXAMPLES +An example of a small directory tree being fully listed with +.IR ls +.BR "\(milaRF\ a" +in the POSIX locale: +.sp +.RS 4 +.nf +\fB +total 11 +drwxr-xr-x 3 fox prog 64 Jul 4 12:07 ./ +drwxrwxrwx 4 fox prog 3264 Jul 4 12:09 ../ +drwxr-xr-x 2 fox prog 48 Jul 4 12:07 b/ +-rwxr--r-- 1 fox prog 572 Jul 4 12:07 foo* +.P +a/b: +total 4 +drwxr-xr-x 2 fox prog 48 Jul 4 12:07 ./ +drwxr-xr-x 3 fox prog 64 Jul 4 12:07 ../ +-rw-r--r-- 1 fox prog 700 Jul 4 12:07 bar +.fi \fR +.P +.RE +.SH RATIONALE +Some historical implementations of the +.IR ls +utility show all entries in a directory except dot and dot-dot when a +superuser invokes +.IR ls +without specifying the +.BR \(mia +option. When ``normal'' users invoke +.IR ls +without specifying +.BR \(mia , +they should not see information about any files with names beginning +with a + +unless they were named as +.IR file +operands. +.P +Implementations are expected to traverse arbitrary depths when +processing the +.BR \(miR +option. The only limitation on depth should be based on running out of +physical storage for keeping track of untraversed directories. +.P +The +.BR \(mi1 +(one) option was historically found in BSD and BSD-derived +implementations only. It is required in this volume of POSIX.1\(hy2008 so that conforming +applications might ensure that output is one entry per line, even if +the output is to a terminal. +.P +The +.BR \(miS +option was added in Issue 7, but had been provided by several +implementations for many years. The description given in the +standard documents historic practice, but does not match much of the +documentation that described its behavior. Historical documentation +typically described it as something like: +.IP "\fB\(miS\fP" 10 +Sort by size (largest size first) instead of by name. Special character +devices (listed last) are sorted by name. +.P +even though the file type was never considered when sorting the output. +Character special files do typically sort close to the end of the list +because their file size on most implementations is zero. But they are +sorted alphabetically with any other files that happen to have the same +file size (zero), not sorted separately and added to the end. +.P +This volume of POSIX.1\(hy2008 is frequently silent about what happens when mutually-exclusive +options are specified. Except for +.BR \(miR , +.BR \(mid , +and +.BR \(mif , +the +.IR ls +utility is required to accept multiple options from each +mutually-exclusive option set without treating them as errors and to use +the behavior specified by the last option given in each mutually-exclusive +set. Since +.IR ls +is one of the most aliased commands, it is important that the +implementation perform intuitively. For example, if the alias were: +.sp +.RS 4 +.nf +\fB +alias ls="ls \(miC" +.fi \fR +.P +.RE +.P +and the user typed +.IR ls +.BR \(mi1 +(one), single-text-column output should result, not an error. +.P +The +.BR \(mig , +.BR \(mil +(ell), +.BR \(min , +and +.BR \(mio +options are not mutually-exclusive options. They all enable long format +output. They work together to determine whether the file's owner is +written (no if +.BR \(mig +is present), file's group is written (no if +.BR \(mio +is present), and if the file's group or owner is written whether it is +written as the name (default) or a string representation of the UID or +GID number (if +.BR \(min +is present). The +.BR \(miC , +.BR \(mim , +.BR \(mix , +and +.BR \(mi1 +(one) are mutually-exclusive options and the first three of these disable +long format output. The +.BR \(mi1 +(one) option does not directly change whether or not long format output +is enabled, but by overriding +.BR \(miC , +.BR \(mim , +and +.BR \(mix , +it can re-enable long format output that had been disabled by one of +these options. +.P +Earlier versions of this standard did not describe the BSD +.BR \(miA +option (like +.BR \(mia , +but dot and dot-dot are not written out). It has been added due to +widespread implementation. +.P +Implementations may make +.BR \(miq +the default for terminals to prevent trojan horse attacks on terminals +with special escape sequences. +This is not required because: +.IP " *" 4 +Some control characters may be useful on some terminals; for example, a +system might write them as +.BR \(dq\e001\(dq +or +.BR \(dq^A\(dq . +.IP " *" 4 +Special behavior for terminals is not relevant to applications +portability. +.P +An early proposal specified that the +<\fIoptional\ alternate\ access\ method\ flag\fR> had to be +.BR '\(pl' +if there was an alternate access method used on the file or + +if there was not. This was changed to be + +if there is not and a single printable character if there is. This was +done for three reasons: +.IP " 1." 4 +There are historical implementations using characters other than +.BR '\(pl' . +.IP " 2." 4 +There are implementations that vary this character used in that +position to distinguish between various alternate access methods in +use. +.IP " 3." 4 +The standard developers did not want to preclude future specifications +that might need a way to specify more than one alternate access +method. +.P +Nonetheless, implementations providing a single alternate access method +are encouraged to use +.BR '\(pl' . +.P +Earlier versions of this standard did not have the +.BR \(mik +option, which meant that the +.BR \(mis +option could not be used portably as its block size was +implementation-defined, and the units used to specify the +number of blocks occupied by files in a directory in an +.IR ls +.BR \(mil +listing were fixed as 512-byte units. The +.BR \(mik +option has been added to provide a way for the +.BR \(mis +option to be used portably, and for consistency it also changes the +aforementioned units from 512-byte to 1\|024-byte. +.P +The <\fIdate\ and\ time\fP> field in the +.BR \(mil +format is specified only for the POSIX locale. As noted, the format can +be different in other locales. No mechanism for defining this is +present in this volume of POSIX.1\(hy2008, as the appropriate vehicle is a messaging system; +that is, the format should be specified as a ``message''. +.SH "FUTURE DIRECTIONS" +Allowing +.BR \(mif +to ignore the +.BR \(miA , +.BR \(mig , +.BR \(mil , +.BR \(min , +.BR \(mio , +and +.BR \(mis +options may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^", +.IR "\fIfind\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.4" ", " "File Access Permissions", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIfstatat\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/m4.1p b/man-pages-posix-2013/man1p/m4.1p new file mode 100644 index 0000000..3e533cf --- /dev/null +++ b/man-pages-posix-2013/man1p/m4.1p @@ -0,0 +1,841 @@ +'\" et +.TH M4 "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +m4 \(em macro processor +.SH SYNOPSIS +.LP +.nf +m4 \fB[\fR\(mis\fB] [\fR\(miD \fIname\fB[\fR=\fIval\fB]]\fR...\fB [\fR\(miU \fIname\fB]\fR... \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR m4 +utility is a macro processor that shall read one or more text files, +process them according to their included macro statements, and write +the results to standard output. +.SH OPTIONS +The +.IR m4 +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that the order of the +.BR \(miD +and +.BR \(miU +options shall be significant, and options can be interspersed with +operands. +.P +The following options shall be supported: +.IP "\fB\(mis\fP" 10 +Enable line synchronization output for the +.IR c99 +preprocessor phase (that is, +.BR #line +directives). +.IP "\fB\(miD\ \fIname\fB[\fR=\fIval\fB]\fR" 10 +.br +Define +.IR name +to +.IR val +or to null if =\c +.IR val +is omitted. +.IP "\fB\(miU\ \fIname\fR" 10 +Undefine +.IR name . +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a text file to be processed. If no +.IR file +is given, or if it is +.BR '\(mi' , +the standard input shall be read. +.SH STDIN +The standard input shall be a text file that is used if no +.IR file +operand is given, or if it is +.BR '\(mi' . +.SH "INPUT FILES" +The input file named by the +.IR file +operand shall be a text file. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR m4 : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall be the same as the input files, after being +processed for macro expansion. +.SH STDERR +The standard error shall be used to display strings with the +.BR errprint +macro, macro tracing enabled by the +.BR traceon +macro, the defined text for macros written by the +.BR dumpdef +macro, or for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +The +.IR m4 +utility shall compare each token from the input against the set of +built-in and user-defined macros. If the token matches the name of a +macro, then the token shall be replaced by the macro's defining text, if +any, and rescanned for matching macro names. Once no portion of the +token matches the name of a macro, it shall be written to standard +output. Macros may have arguments, in which case the arguments shall +be substituted into the defining text before it is rescanned. +.P +Macro calls have the form: +.sp +.RS 4 +.nf +\fB +\fIname\fR(\fIarg1\fR, \fIarg2\fR, ..., \fIargn\fR) +.fi \fR +.P +.RE +.P +Macro names shall consist of letters, digits, and underscores, where +the first character is not a digit. Tokens not of this form shall not +be treated as macros. +.P +The application shall ensure that the + +immediately follows the name of the macro. If a token matching the name +of a macro is not followed by a +, +it is handled as a use of that macro without arguments. +.P +If a macro name is followed by a +, +its arguments are the +-separated +tokens between the + +and the matching +. +Unquoted white-space characters preceding each argument shall be +ignored. All other characters, including trailing white-space characters, +are retained. + +characters enclosed between + +and + +characters do not delimit arguments. +.P +Arguments are positionally defined and referenced. The string +.BR \(dq$1\(dq +in the defining text shall be replaced by the first argument. Systems +shall support at least nine arguments; only the first nine can be +referenced, using the strings +.BR \(dq$1\(dq +to +.BR \(dq$9\(dq , +inclusive. The string +.BR \(dq$0\(dq +is replaced with the name of the macro. The string +.BR \(dq$#\(dq +is replaced by the number of arguments as a string. The string +.BR \(dq$*\(dq +is replaced by a list of all of the arguments, separated by + +characters. The string +.BR \(dq$@\(dq +is replaced by a list of all of the arguments separated by + +characters, and each argument is quoted using the current left and right +quoting strings. The string +.BR \(dq${\(dq +produces unspecified behavior. +.P +If fewer arguments are supplied than are in the macro definition, the +omitted arguments are taken to be null. It is not an error if more +arguments are supplied than are in the macro definition. +.P +No special meaning is given to any characters enclosed between matching +left and right quoting strings, but the quoting strings are themselves +discarded. By default, the left quoting string consists of a grave accent +(backquote) and the right quoting string consists of an acute accent +(single-quote); see also the +.BR changequote +macro. +.P +Comments are written but not scanned for matching macro names; by +default, the begin-comment string consists of the + +character and the end-comment string consists of a +. +See also the +.BR changecom +and +.BR dnl +macros. +.P +The +.IR m4 +utility shall make available the following built-in macros. They can be +redefined, but once this is done the original meaning is lost. Their +values shall be null unless otherwise stated. In the descriptions +below, the term +.IR "defining text" +refers to the value of the macro: the second argument to the +.BR define +macro, among other things. Except for the first argument to the +.BR eval +macro, all numeric arguments to built-in macros shall be interpreted as +decimal values. The string values produced as the defining text of the +.BR decr , +.BR divnum , +.BR incr , +.BR index , +.BR len , +and +.BR sysval +built-in macros shall be in the form of a decimal-constant as defined +in the C language. +.IP "\fBchangecom\fR" 10 +The +.BR changecom +macro shall set the begin-comment and end-comment strings. With no +arguments, the comment mechanism shall be disabled. With a single non-null +argument, that argument shall become the begin-comment and the + +shall become the end-comment string. With two non-null arguments, +the first argument shall become the begin-comment string and the second +argument shall become the end-comment string. The behavior is unspecified +if either argument is provided but null. Systems shall support comment +strings of at least five characters. +.IP "\fBchangequote\fR" 10 +The +.BR changequote +macro shall set the begin-quote and end-quote strings. With no +arguments, the quote strings shall be set to the default values (that +is, \fR`\|'\fP). The behavior is unspecified if there is a single argument +or either argument is null. With two non-null arguments, the first +argument shall become the begin-quote string and the second argument +shall become the end-quote string. Systems shall support quote strings +of at least five characters. +.IP "\fBdecr\fR" 10 +The defining text of the +.BR decr +macro shall be its first argument decremented by 1. It shall be an +error to specify an argument containing any non-numeric characters. +The behavior is unspecified if +.BR decr +is not immediately followed by a +. +.IP "\fBdefine\fR" 10 +The second argument shall become the defining text of the macro +whose name is the first argument. It is unspecified whether the +.BR define +macro deletes all prior definitions of the macro named by its first +argument or preserves all but the current definition of the macro. +The behavior is unspecified if +.BR define +is not immediately followed by a +. +.IP "\fBdefn\fR" 10 +The defining text of the +.BR defn +macro shall be the quoted definition (using the current quoting +strings) of its arguments. The behavior is unspecified if +.BR defn +is not immediately followed by a +. +.IP "\fBdivert\fR" 10 +The +.IR m4 +utility maintains nine temporary buffers, numbered 1 to 9, inclusive. +When the last of the input has been processed, any output that has been +placed in these buffers shall be written to standard output in +buffer-numerical order. The +.BR divert +macro shall divert future output to the buffer specified by its +argument. Specifying no argument or an argument of 0 shall resume the +normal output process. Output diverted to a stream with a negative +number shall be discarded. Behavior is implementation-defined if +a stream number larger than 9 is specified. It shall be an error to +specify an argument containing any non-numeric characters. +.IP "\fBdivnum\fR" 10 +The defining text of the +.BR divnum +macro shall be the number of the current output stream as a string. +.IP "\fBdnl\fR" 10 +The +.BR dnl +macro shall cause +.IR m4 +to discard all input characters up to and including the next +. +.IP "\fBdumpdef\fR" 10 +The +.BR dumpdef +macro shall write the defined text to standard error for each of the +macros specified as arguments, or, if no arguments are specified, for +all macros. +.IP "\fBerrprint\fR" 10 +The +.BR errprint +macro shall write its arguments to standard error. The behavior +is unspecified if +.BR errprint +is not immediately followed by a +. +.IP "\fBeval\fR" 10 +The +.BR eval +macro shall evaluate its first argument as an arithmetic expression, +using signed integer arithmetic with at least 32-bit precision. At least +the following C-language operators shall be supported, with precedence, +associativity, and behavior as described in +.IR "Section 1.1.2.1" ", " "Arithmetic Precision and Operations": +.RS 10 +.sp +.RS 4 +.nf +\fB +() +unary + +unary \(mi +\&~ +.P +\&! +binary * +/ +% +binary + +binary \(mi +<< +>> +< +<= +> +>= +=\|= +!= +binary & +\&^ +| +&& +|| +.fi \fR +.P +.RE +.P +Systems shall support octal and hexadecimal numbers as in the ISO\ C standard. +The second argument, if specified, shall set the radix for the result; +if the argument is blank or unspecified, the default is 10. Behavior is +unspecified if the radix falls outside the range 2 to 36, inclusive. The +third argument, if specified, sets the minimum number of digits in the +result. Behavior is unspecified if the third argument is less than +zero. It shall be an error to specify the second or third argument +containing any non-numeric characters. The behavior is unspecified if +.BR eval +is not immediately followed by a +. +.RE +.IP "\fBifdef\fR" 10 +If the first argument to the +.BR ifdef +macro is defined, the defining text shall be the second argument. +Otherwise, the defining text shall be the third argument, if specified, +or the null string, if not. The behavior is unspecified if +.BR ifdef +is not immediately followed by a +. +.IP "\fBifelse\fR" 10 +The +.BR ifelse +macro takes three or more arguments. If the first two arguments compare +as equal strings (after macro expansion of both arguments), the +defining text shall be the third argument. If the first two arguments +do not compare as equal strings and there are three arguments, the +defining text shall be null. If the first two arguments do not compare +as equal strings and there are four or five arguments, the defining +text shall be the fourth argument. If the first two arguments do not +compare as equal strings and there are six or more arguments, the first +three arguments shall be discarded and processing shall restart with +the remaining arguments. The behavior is unspecified if +.BR ifelse +is not immediately followed by a +. +.IP "\fBinclude\fR" 10 +The defining text for the +.BR include +macro shall be the contents of the file named by the first argument. It +shall be an error if the file cannot be read. The behavior is unspecified if +.BR include +is not immediately followed by a +. +.IP "\fBincr\fR" 10 +The defining text of the +.BR incr +macro shall be its first argument incremented by 1. It shall be an +error to specify an argument containing any non-numeric characters. +The behavior is unspecified if +.BR incr +is not immediately followed by a +. +.IP "\fBindex\fR" 10 +The defining text of the +.BR index +macro shall be the first character position (as a string) in the first +argument where a string matching the second argument begins (zero +origin), or \(mi1 if the second argument does not occur. +The behavior is unspecified if +.BR index +is not immediately followed by a +. +.IP "\fBlen\fR" 10 +The defining text of the +.BR len +macro shall be the length (as a string) of the first argument. +The behavior is unspecified if +.BR len +is not immediately followed by a +. +.IP "\fBm4exit\fR" 10 +Exit from the +.IR m4 +utility. If the first argument is specified, it is the exit code. The +default is zero. It shall be an error to specify an argument containing +any non-numeric characters. +.IP "\fBm4wrap\fR" 10 +The first argument shall be processed when EOF is reached. If the +.BR m4wrap +macro is used multiple times, the arguments specified shall be +processed in the order in which the +.BR m4wrap +macros were processed. The behavior is unspecified if +.BR m4wrap +is not immediately followed by a +. +.IP "\fBmaketemp\fR" 10 +The defining text shall be the first argument, with any trailing +.BR 'X' +characters replaced with the current process ID as a string. +The behavior is unspecified if +.BR maketemp +is not immediately followed by a +. +.IP "\fBmkstemp\fR" 10 +The first argument shall be taken as a template for creating an +empty file, with trailing +.BR 'X' +characters replaced with characters from the portable filename +character set. The behavior is unspecified if the first argument +does not end in at least six +.BR 'X' +characters. If a temporary file is successfully created, then the +defining text of the macro shall be the name of the new 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. The file access permission bits are set such that +only the owner can both read and write the file, regardless of +the current +.IR umask +of the process. If a file could not be created, the defining text +of the macro shall be the empty string. The behavior is unspecified if +.BR mkstemp +is not immediately followed by a +. +.IP "\fBpopdef\fR" 10 +The +.BR popdef +macro shall delete the current definition of its arguments, replacing +that definition with the previous one. If there is no previous +definition, the macro is undefined. The behavior is unspecified if +.BR popdef +is not immediately followed by a +. +.IP "\fBpushdef\fR" 10 +The +.BR pushdef +macro shall be equivalent to the +.BR define +macro with the exception that it shall preserve any current definition +for future retrieval using the +.BR popdef +macro. The behavior is unspecified if +.BR pushdef +is not immediately followed by a +. +.IP "\fBshift\fR" 10 +The defining text for the +.BR shift +macro shall be a comma-separated list of its arguments except the first +one. Each argument shall be quoted using the current quoting strings. +The behavior is unspecified if +.BR shift +is not immediately followed by a +. +.IP "\fBsinclude\fR" 10 +The +.BR sinclude +macro shall be equivalent to the +.BR include +macro, except that it shall not be an error if the file is inaccessible. +The behavior is unspecified if +.BR sinclude +is not immediately followed by a +. +.IP "\fBsubstr\fR" 10 +The defining text for the +.BR substr +macro shall be the substring of the first argument beginning at the +zero-offset character position specified by the second argument. The +third argument, if specified, shall be the number of characters to +select; if not specified, the characters from the starting point to the +end of the first argument shall become the defining text. It shall not +be an error to specify a starting point beyond the end of the first +argument and the defining text shall be null. It shall be an error to +specify an argument containing any non-numeric characters. +The behavior is unspecified if +.BR substr +is not immediately followed by a +. +.IP "\fBsyscmd\fR" 10 +The +.BR syscmd +macro shall interpret its first argument as a shell command line. The +defining text shall be the string result of that command. The string +result shall not be rescanned for macros while setting the defining +text. No output redirection shall be performed by the +.IR m4 +utility. The exit status value from the command can be retrieved using +the +.BR sysval +macro. The behavior is unspecified if +.BR syscmd +is not immediately followed by a +. +.IP "\fBsysval\fR" 10 +The defining text of the +.BR sysval +macro shall be the exit value of the utility last invoked by the +.BR syscmd +macro (as a string). +.IP "\fBtraceon\fR" 10 +The +.BR traceon +macro shall enable tracing for the macros specified as arguments, or, +if no arguments are specified, for all macros. The trace output shall +be written to standard error in an unspecified format. +.IP "\fBtraceoff\fR" 10 +The +.BR traceoff +macro shall disable tracing for the macros specified as arguments, or, +if no arguments are specified, for all macros. +.IP "\fBtranslit\fR" 10 +The defining text of the +.BR translit +macro shall be the first argument with every character that occurs in +the second argument replaced with the corresponding character from the +third argument. If no replacement character is specified for some +source character because the second argument is longer than the third +argument, that character shall be deleted from the first argument in +.BR translit 's +defining text. The behavior is unspecified if the +.BR '\(mi' +character appears within the second or third argument anywhere besides +the first or last character. The behavior is unspecified if the same +character appears more than once in the second argument. The behavior +is unspecified if +.BR translit +is not immediately followed by a +. +.IP "\fBundefine\fR" 10 +The +.BR undefine +macro shall delete all definitions (including those preserved using the +.BR pushdef +macro) of the macros named by its arguments. The behavior is unspecified if +.BR undefine +is not immediately followed by a +. +.IP "\fBundivert\fR" 10 +The +.BR undivert +macro shall cause immediate output of any text in temporary buffers +named as arguments, or all temporary buffers if no arguments are +specified. Buffers can be undiverted into other temporary buffers. +Undiverting shall discard the contents of the temporary buffer. The +behavior is unspecified if an argument contains any non-numeric +characters. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred +.P +If the +.BR m4exit +macro is used, the exit value can be specified by the input file. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.BR defn +macro is useful for renaming macros, especially built-ins. +.P +Since +.BR eval +defers to the ISO\ C standard, some operations have undefined behavior. In some +implementations, division or remainder by zero cause a fatal signal, +even if the division occurs on the short-circuited branch of +.BR \(dq&&\(dq +or +.BR \(dq||\(dq . +Any operation that overflows in signed arithmetic produces undefined +behavior. Likewise, using the +.BR shift +operators with a shift amount that is not positive and smaller +than the precision is undefined, as is shifting a negative number to +the right. Historically, not all implementations obeyed C-language +precedence rules: +.BR '~' +and +.BR '!' +were lower than +.BR '==' ; +.BR '==' +and +.BR '!=' +were not lower than +.BR '<' ; +and +.BR '|' +was not lower than +.BR '^' ; +the liberal use of +.BR \(dq()\(dq +can force the desired precedence even with these non-compliant +implementations. Furthermore, some traditional implementations treated +.BR '^' +as an exponentiation operator, although most implementations now use +.BR \(dq**\(dq +as an extension for this purpose. +.P +When a macro has been multiply defined via the +.BR pushdef +macro, it is unspecified whether the +.BR define +macro will alter only the most recent definition (as though by +.BR popdef +and +.BR pushdef ), +or replace the entire stack of definitions with a single definition +(as though by +.BR undefine +and +.BR pushdef ). +An application desiring particular behavior for the +.BR define +macro in this case can redefine it accordingly. +.P +Applications should use the +.BR mkstemp +macro instead of the obsolescent +.BR maketemp +macro for creating temporary files. +.SH EXAMPLES +If the file +.BR m4src +contains the lines: +.sp +.RS 4 +.nf +\fB +The value of `VER' is "VER". +ifdef(`VER', ``VER'' is defined to be VER., VER is not defined.) +ifelse(VER, 1, ``VER'' is `VER'.) +ifelse(VER, 2, ``VER'' is `VER'., ``VER'' is not 2.) +end +.fi \fR +.P +.RE +.P +then the command +.sp +.RS 4 +.nf +\fB +m4 m4src +.fi \fR +.P +.RE +.P +or the command: +.sp +.RS 4 +.nf +\fB +m4 \(miU VER m4src +.fi \fR +.P +.RE +.P +produces the output: +.sp +.RS 4 +.nf +\fB +The value of VER is "VER". +VER is not defined. +.P +VER is not 2. +end +.fi \fR +.P +.RE +.P +The command: +.sp +.RS 4 +.nf +\fB +m4 \(miD VER m4src +.fi \fR +.P +.RE +.P +produces the output: +.sp +.RS 4 +.nf +\fB +The value of VER is "". +VER is defined to be . +.P +VER is not 2. +end +.fi \fR +.P +.RE +.P +The command: +.sp +.RS 4 +.nf +\fB +m4 \(miD VER=1 m4src +.fi \fR +.P +.RE +.P +produces the output: +.sp +.RS 4 +.nf +\fB +The value of VER is "1". +VER is defined to be 1. +VER is 1. +VER is not 2. +end +.fi \fR +.P +.RE +.P +The command: +.sp +.RS 4 +.nf +\fB +m4 \(miD VER=2 m4src +.fi \fR +.P +.RE +.P +produces the output: +.sp +.RS 4 +.nf +\fB +The value of VER is "2". +VER is defined to be 2. +.P +VER is 2. +end +.fi \fR +.P +.RE +.SH RATIONALE +Historic System V-based behavior treated +.BR \(dq${\(dq +in a macro definition as two literal characters. However, this sequence +is left unspecified so that implementations may offer extensions +such as +.BR \(dq${11}\(dq +meaning the eleventh positional parameter. Macros can still be defined with +appropriate uses of nested quoting to result in a literal +.BR \(dq${\(dq +in the output after rescanning removes the nested quotes. +.P +In the +.BR translit +built-in, historic System V-based behavior treated +.BR '\(mi' +as a literal; GNU behavior treats it as a range. This version of +the standard allows either behavior. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIc99\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/mailx.1p b/man-pages-posix-2013/man1p/mailx.1p new file mode 100644 index 0000000..8657e30 --- /dev/null +++ b/man-pages-posix-2013/man1p/mailx.1p @@ -0,0 +1,3090 @@ +'\" et +.TH MAILX "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mailx +\(em process messages +.SH SYNOPSIS +.SS "Send Mode" +.sp +.RS 4 +.nf +\fB +mailx \fB[\fR\(mis \fIsubject\fB]\fI address\fR... +.fi \fR +.P +.RE +.SS "Receive Mode" +.sp +.RS 4 +.nf +\fB +mailx \(mie +.P +mailx \fB[\fR\(miHiNn\fB] [\fR\(miF\fB] [\fR\(miu \fIuser\fB]\fR +.P +mailx \(mif \fB[\fR\(miHiNn\fB] [\fR\(miF\fB] [\fIfile\fB]\fR +.fi \fR +.P +.RE +.SH DESCRIPTION +The +.IR mailx +utility provides a message sending and receiving facility. It has two +major modes, selected by the options used: Send Mode and Receive +Mode. +.P +On systems that do not support the User Portability Utilities option, +an application using +.IR mailx +shall have the ability to send messages in an unspecified manner (Send +Mode). Unless the first character of one or more lines is + +(\c +.BR '~' ), +all characters in the input message shall appear in the delivered +message, but additional characters may be inserted in the message +before it is retrieved. +.P +On systems supporting the User Portability Utilities option, +mail-receiving capabilities and other interactive features, Receive +Mode, described below, also shall be enabled. +.SS "Send Mode" +.P +Send Mode can be used by applications or users to send messages from +the text in standard input. +.SS "\*!Receive Mode" +.P +Receive Mode is more oriented towards interactive users. Mail can be read +and sent in this interactive mode. +.P +When reading mail, +.IR mailx +provides commands to facilitate saving, deleting, and responding to +messages. When sending mail, +.IR mailx +allows editing, reviewing, and other modification of the message as it +is entered. +.P +Incoming mail shall be stored in one or more unspecified locations for +each user, collectively called the system +.IR mailbox +for that user. When +.IR mailx +is invoked in Receive Mode, the system mailbox shall be the default +place to find new mail. As messages are read, they shall be marked to +be moved to a secondary file for storage, unless specific action is +taken. This secondary file is called the +.BR mbox +and is normally located in the directory referred to by the +.IR HOME +environment variable (see +.IR MBOX +in the ENVIRONMENT VARIABLES section for a description of this file). +Messages shall remain in this file until explicitly removed. When the +.BR \(mif +option is used to read mail messages from secondary files, messages +shall be retained in those files unless specifically removed. All +three of these locations\(emsystem mailbox, +.BR mbox , +and secondary file\(emare referred to in this section as simply +``mailboxes'', unless more specific identification is required. +.SH OPTIONS +The +.IR mailx +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported. (Only the +.BR \(mis +.IR subject +option shall be required on all systems. The other options are required +only on systems supporting the User Portability Utilities option.) +.IP "\fB\(mie\fP" 10 +Test for the presence of mail in the system mailbox. The +.IR mailx +utility shall write nothing and exit with a successful return code if +there is mail to read. +.IP "\fB\(mif\fP" 10 +Read messages from the file named by the +.IR file +operand instead of the system mailbox. (See also +.BR folder .) +If no +.IR file +operand is specified, read messages from +.BR mbox +instead of the system mailbox. +.IP "\fB\(miF\fP" 10 +Record the message in a file named after the first recipient. The name +is the login-name portion of the address found first on the +.BR To: +line in the mail header. Overrides the +.BR record +variable, if set (see +.IR "Internal Variables in mailx"). +.IP "\fB\(miH\fP" 10 +Write a header summary only. +.IP "\fB\(mii\fP" 10 +Ignore interrupts. (See also +.BR ignore .) +.IP "\fB\(min\fP" 10 +Do not initialize from the system default start-up file. See the +EXTENDED DESCRIPTION section. +.IP "\fB\(miN\fP" 10 +Do not write an initial header summary. +.IP "\fB\(mis\0\fIsubject\fR" 10 +Set the +.BR Subject +header field to +.IR subject . +All characters in the +.IR subject +string shall appear in the delivered message. The results are +unspecified if +.IR subject +is longer than +{LINE_MAX} +\(mi 10 bytes or contains a +. +.IP "\fB\(miu\0\fIuser\fR" 10 +Read the system mailbox of the login name +.IR user . +This shall only be successful if the invoking user has appropriate +privileges to read the system mailbox of that user. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIaddress\fR" 10 +Addressee of message. When +.BR \(min +is specified and no user start-up files are accessed (see the EXTENDED +DESCRIPTION section), the user or application shall ensure this is an +address to pass to the mail delivery system. Any system or user +start-up files may enable aliases (see +.BR alias +under +.IR "Commands in mailx") +that may modify the form of +.IR address +before it is passed to the mail delivery system. +.IP "\fIfile\fR" 10 +A pathname of a file to be read instead of the system mailbox when +.BR \(mif +is specified. The meaning of the +.IR file +option-argument shall be affected by the contents of the +.BR folder +internal variable; see +.IR "Internal Variables in mailx". +.SH STDIN +When +.IR mailx +is invoked in Send Mode (the first synopsis line), standard input shall +be the message to be delivered to the specified addresses. +When in Receive Mode, user commands shall be accepted from +.IR stdin . +If the User Portability Utilities option is not supported, standard +input lines beginning with a + +(\c +.BR '~' ) +character produce unspecified results. +.P +If the User Portability Utilities option is supported, then in both +Send and Receive Modes, standard input lines beginning with the escape +character (usually + +(\c +.BR '~' )) +shall affect processing as described in +.IR "Command Escapes in mailx". +.SH "INPUT FILES" +When +.IR mailx +is used as described by this volume of POSIX.1\(hy2008, the +.IR file +option-argument (see the +.BR \(mif +option) and the +.BR mbox +shall be text files containing mail messages, formatted as described in +the OUTPUT FILES section. The nature of the system mailbox is +unspecified; it need not be a file. +.SH "ENVIRONMENT VARIABLES" +Some of the functionality described in this section shall be provided on +implementations that support the User Portability Utilities option +as described in the text, and is not further shaded for this option. +.P +The following environment variables shall affect the execution of +.IR mailx : +.IP "\fIDEAD\fP" 10 +Determine the pathname of the file in which to save partial messages in +case of interrupts or delivery errors. The default shall be +.BR dead.letter +in the directory named by the +.IR HOME +variable. The behavior of +.IR mailx +in saving partial messages is unspecified if the User Portability +Utilities option is not supported and +.IR DEAD +is not defined with the value +.BR /dev/null . +.IP "\fIEDITOR\fP" 10 +Determine the name of a utility to invoke when the +.BR edit +(see +.IR "Commands in mailx") +or +.BR ~e +(see +.IR "Command Escapes in mailx") +command is used. The default editor is unspecified. +On XSI-conformant systems it is +.IR ed . +The effects of this variable are unspecified if the User Portability +Utilities option is not supported. +.IP "\fIHOME\fP" 10 +Determine the pathname of the user's home directory. +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files) and the handling of +case-insensitive address and header-field comparisons. +.IP "\fILC_TIME\fP" 10 +This variable may determine the format and contents of the date and +time strings written by +.IR mailx . +This volume of POSIX.1\(hy2008 specifies the effects of this variable only for systems +supporting the User Portability Utilities option. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fILISTER\fP" 10 +Determine a string representing the command for writing the contents of +the +.BR folder +directory to standard output when the +.BR folders +command is given (see +.BR folders +in +.IR "Commands in mailx"). +Any string acceptable as a +.IR command_string +operand to the +.IR sh +.BR \(mic +command shall be valid. If this variable is null or not set, the output +command shall be +.IR ls . +The effects of this variable are unspecified if the User Portability +Utilities option is not supported. +.IP "\fIMAILRC\fP" 10 +Determine the pathname of the start-up file. The default shall be +.BR .mailrc +in the directory referred to by the +.IR HOME +environment variable. The behavior of +.IR mailx +is unspecified if the User Portability Utilities option is not +supported and +.IR MAILRC +is not defined with the value +.BR /dev/null . +.IP "\fIMBOX\fP" 10 +Determine a pathname of the file to save messages from the system +mailbox that have been read. The +.BR exit +command shall override this function, as shall saving the message +explicitly in another file. The default shall be +.BR mbox +in the directory named by the +.IR HOME +variable. The effects of this variable are unspecified if the User +Portability Utilities option is not supported. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPAGER\fP" 10 +Determine a string representing an output filtering or pagination +command for writing the output to the terminal. Any string acceptable +as a +.IR command_string +operand to the +.IR sh +.BR \(mic +command shall be valid. When standard output is a terminal device, the +message output shall be piped through the command if the +.IR mailx +internal variable +.BR crt +is set to a value less the number of lines in the message; see +.IR "Internal Variables in mailx". +If the +.IR PAGER +variable is null or not set, the paginator shall be either +.IR more +or another paginator utility documented in the system documentation. +The effects of this variable are unspecified if the User Portability +Utilities option is not supported. +.IP "\fISHELL\fP" 10 +Determine the name of a preferred command interpreter. The default +shall be +.IR sh . +The effects of this variable are unspecified if the User Portability +Utilities option is not supported. +.IP "\fITERM\fP" 10 +If the internal variable +.BR screen +is not specified, determine the name of the terminal type to indicate +in an unspecified manner the number of lines in a screenful of headers. +If +.IR TERM +is not set or is set to null, an unspecified default terminal type +shall be used and the value of a screenful is unspecified. The effects +of this variable are unspecified if the User Portability Utilities +option is not supported. +.IP "\fITZ\fP" 10 +This variable may determine the timezone used to calculate date and +time strings written by +.IR mailx . +If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.IP "\fIVISUAL\fP" 10 +Determine a pathname of a utility to invoke when the +.BR visual +command (see +.IR "Commands in mailx") +or +.BR ~v +command-escape (see +.IR "Command Escapes in mailx") +is used. If this variable is null or not set, the full-screen editor +shall be +.IR vi . +The effects of this variable are unspecified if the User Portability +Utilities option is not supported. +.SH "ASYNCHRONOUS EVENTS" +When +.IR mailx +is in Send Mode and standard input is not a terminal, it shall take the +standard action for all signals. +.P +In +Receive Mode, or in +Send Mode when standard input is a terminal, if a SIGINT signal +is received: +.IP " 1." 4 +If in command mode, the current command, if there is one, shall be +aborted, and a command-mode prompt shall be written. +.IP " 2." 4 +If in input mode: +.RS 4 +.IP " a." 4 +If +.BR ignore +is set, +.IR mailx +shall write +.BR \(dq@\en\(dq , +discard the current input line, and continue processing, bypassing the +message-abort mechanism described in item 2b. +.IP " b." 4 +If the interrupt was received while sending mail, either when in +Receive Mode or in +Send Mode, a message shall be written, and another +subsequent interrupt, with no other intervening characters typed, shall +be required to abort the mail message. +If in Receive Mode and another +interrupt is received, a command-mode prompt shall be written. +If in Send Mode and another interrupt is received, +.IR mailx +shall terminate with a non-zero status. +.RS 4 +.P +In both cases listed in item b, if the message is not empty: +.IP " i." 5 +If +.BR save +is enabled and the file named by +.IR DEAD +can be created, the message shall be written to the file named by +.IR DEAD . +If the file exists, the message shall be written to replace the +contents of the file. +.IP ii. 5 +If +.BR save +is not enabled, or +the file named by +.IR DEAD +cannot be created, the message shall not be saved. +.RE +.RE +.P +The +.IR mailx +utility shall take the standard action for all other signals. +.SH STDOUT +In command and input modes, all output, including prompts and messages, +shall be written to standard output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +Various +.IR mailx +commands and command escapes can create or add to files, including the +.BR mbox , +the dead-letter file, and secondary mailboxes. When +.IR mailx +is used as described in this volume of POSIX.1\(hy2008, these files shall be text files, +formatted as follows: +.sp +.RS +\fRline beginning with \fBFrom +.br +[\fRone or more \fIheader-lines\fR; see +.IR "Commands in mailx"] +.br +\fIempty line +.br +\fB[\fRzero or more \fIbody lines +.br +\fIempty line] +.br +\fB[\fRline beginning with \fBFrom...]\fR +.RE +.P +where each message begins with the +.BR "From\0" +line shown, preceded by the beginning of the file or an empty line. +(The +.BR "From " +line is considered to be part of the message header, but not one of the +header-lines referred to in +.IR "Commands in mailx"; +thus, it shall not be affected by the +.BR discard , +.BR ignore , +or +.BR retain +commands.) The formats of the remainder of the +.BR "From " +line and any additional header lines are unspecified, except that none +shall be empty. The format of a message body line is also unspecified, +except that no line following an empty line shall start with +.BR "From " ; +.IR mailx +shall modify any such user-entered message body lines (following an +empty line and beginning with +.BR "From " ) +by adding one or more characters to precede the +.BR 'F' ; +it may add these characters to +.BR "From " +lines that are not preceded by an empty line. +.P +When a message from the system mailbox or entered by the user is not a +text file, it is implementation-defined how such a message is stored +in files written by +.IR mailx . +.SH "EXTENDED DESCRIPTION" +The functionality in the entire EXTENDED DESCRIPTION section shall +be provided on implementations supporting the User Portability +Utilities option. +The functionality described in this section shall be provided on +implementations that support the User Portability Utilities option +(and the rest of this section is not further shaded for this option). +.P +The +.IR mailx +utility need not support for all character encodings in all +circumstances. For example, inter-system mail may be restricted to +7-bit data by the underlying network, 8-bit data need not be portable +to non-internationalized systems, and so on. Under these +circumstances, it is recommended that only characters defined in the +ISO/IEC\ 646:\|1991 standard International Reference Version (equivalent to ASCII) 7-bit range +of characters be used. +.P +When +.IR mailx +is invoked using one of the Receive Mode synopsis forms, it shall write +a page of header-summary lines (if +.BR \(miN +was not specified and there are messages, see below), followed by a +prompt indicating that +.IR mailx +can accept regular commands (see +.IR "Commands in mailx"); +this is termed +.IR "command mode" . +The page of header-summary lines shall contain the first new message if +there are new messages, or the first unread message if there are unread +messages, or the first message. When +.IR mailx +is invoked using the Send Mode synopsis and standard input is a +terminal, if no subject is specified on the command line and the +.BR asksub +variable is set, a prompt for the subject shall be written. At this +point, +.IR mailx +shall be in input mode. This input mode shall also be entered when using +one of the Receive Mode synopsis forms and a reply or new message is +composed using the +.BR reply , +.BR Reply , +.BR followup , +.BR Followup , +or +.BR mail +commands and standard input is a terminal. When the message is typed +and the end of the message is encountered, the message shall be passed to +the mail delivery software. Commands can be entered by beginning a line +with the escape character (by default, + +(\c +.BR '~' )) +followed by a single command letter and optional arguments. See +.IR "Commands in mailx" +for a summary of these commands. It is unspecified what effect these +commands will have if standard input is not a terminal when a message +is entered using either the Send Mode synopsis, or the Read Mode +commands +.BR reply , +.BR Reply , +.BR followup , +.BR Followup , +or +.BR mail . +.TP 10 +.BR Note: +For notational convenience, this section uses the default escape +character, +, +in all references and examples. +.P +.P +At any time, the behavior of +.IR mailx +shall be governed by a set of environmental and internal variables. +These are flags and valued parameters that can be set and cleared via +the +.IR mailx +.BR set +and +.BR unset +commands. +.P +Regular commands are of the form: +.sp +.RS 4 +.nf +\fB +\fB[\fIcommand\fB] [\fImsglist\fB] [\fIargument \fR...\fB] +.fi \fR +.P +.RE +.P +If no +.IR command +is specified in command mode, +.BR next +shall be assumed. In input mode, commands shall be recognized by the +escape character, and lines not treated as commands shall be taken as +input for the message. +.P +In command mode, each message shall be assigned a sequential number, +starting with 1. +.P +All messages have a state that shall affect how they are displayed in +the header summary and how they are retained or deleted upon +termination of +.IR mailx . +There is at any time the notion of a +.IR current +message, which shall be marked by a +.BR '>' +at the beginning of a line in the header summary. When +.IR mailx +is invoked using one of the Receive Mode synopsis forms, the current +message shall be the first new message, if there is a new message, or +the first unread message if there is an unread message, or the first +message if there are any messages, or unspecified if there are no +messages in the mailbox. Each command that takes an optional list of +messages (\fImsglist\fP) or an optional single message (\fImessage\fP) +on which to operate shall leave the current message set to the +highest-numbered message of the messages specified, unless the command +deletes messages, in which case the current message shall be set to the +first undeleted message (that is, a message not in the deleted state) +after the highest-numbered message deleted by the command, if one +exists, or the first undeleted message before the highest-numbered +message deleted by the command, if one exists, or to an unspecified +value if there are no remaining undeleted messages. All messages +shall be in one of the following states: +.IP "\fInew\fR" 10 +The message is present in the system mailbox and has not been viewed by +the user or moved to any other state. Messages in state +.IR new +when +.IR mailx +quits shall be retained in the system mailbox. +.IP "\fIunread\fR" 10 +The message has been present in the system mailbox for more than one +invocation of +.IR mailx +and has not been viewed by the user or moved to any other state. +Messages in state +.IR unread +when +.IR mailx +quits shall be retained in the system mailbox. +.IP "\fIread\fR" 10 +The message has been processed by one of the following commands: +.BR ~f , +.BR ~m , +.BR ~F , +.BR ~M , +.BR copy , +.BR mbox , +.BR next , +.BR pipe , +.BR print , +.BR Print , +.BR top , +.BR type , +.BR Type , +.BR undelete . +The +.BR delete , +.BR dp , +and +.BR dt +commands may also cause the next message to be marked as +.IR read , +depending on the value of the +.BR autoprint +variable. Messages that are in the system mailbox and in state +.IR read +when +.IR mailx +quits shall be saved in the +.BR mbox , +unless the internal variable +.BR hold +was set. Messages that are in the +.BR mbox +or in a secondary mailbox and in state +.IR read +when +.IR mailx +quits shall be retained in their current location. +.IP "\fIdeleted\fR" 10 +The message has been processed by one of the following commands: +.BR delete , +.BR dp , +.BR dt . +Messages in state +.IR deleted +when +.IR mailx +quits shall be deleted. Deleted messages shall be ignored until +.IR mailx +quits or changes mailboxes or they are specified to the undelete +command; for example, the message specification /\c +.IR string +shall only search the subject lines of messages that have not yet been +deleted, unless the command operating on the list of messages is +.BR undelete . +No deleted message or deleted message header shall be displayed by any +.IR mailx +command other than +.BR undelete . +.IP "\fIpreserved\fR" 10 +The message has been processed by a +.BR preserve +command. When +.IR mailx +quits, the message shall be retained in its current location. +.IP "\fIsaved\fR" 10 +The message has been processed by one of the following commands: +.BR save +or +.BR write . +If the current mailbox is the system mailbox, and the internal variable +.BR keepsave +is set, messages in the state saved shall be saved to the file +designated by the +.IR MBOX +variable (see the ENVIRONMENT VARIABLES section). If the current +mailbox is the system mailbox, messages in the state +.IR saved +shall be deleted from the current mailbox, when the +.BR quit +or +.BR file +command is used to exit the current mailbox. +.P +The header-summary line for each message shall indicate the state of +the message. +.P +Many commands take an optional list of messages (\c +.IR msglist ) +on which to operate, which defaults to the current message. A +.IR msglist +is a list of message specifications separated by + +characters, which can include: +.IP "\fRn\fR" 8 +Message number +.IR n . +.IP "\fR+\fR" 8 +The next undeleted message, or the next deleted message for the +.BR undelete +command. +.IP "\fR\(mi\fR" 8 +The next previous undeleted message, or the next previous deleted +message for the +.BR undelete +command. +.IP "\fR.\fR" 8 +The current message. +.IP "\fR^\fR" 8 +The first undeleted message, or the first deleted message for the +.BR undelete +command. +.IP "\fR$\fR" 8 +The last message. +.IP "\fR*\fR" 8 +All messages. +.IP "\fRn\(hym\fR" 8 +An inclusive range of message numbers. +.IP "\fIaddress\fR" 8 +All messages from +.IR address ; +any address as shown in a header summary shall be matchable in this +form. +.IP "/\fIstring\fR" 8 +All messages with +.IR string +in the subject line (case ignored). +.IP "\fR:c\fR" 8 +All messages of type +.IR c , +where +.IR c +shall be one of: +.RS 8 +.IP "\fRd\fR" 6 +Deleted messages. +.IP "\fRn\fR" 6 +New messages. +.IP "\fRo\fR" 6 +Old messages (any not in state +.IR read +or +.IR new ). +.IP "\fRr\fR" 6 +Read messages. +.IP "\fRu\fR" 6 +Unread messages. +.RE +.P +Other commands take an optional message (\c +.IR message ) +on which to operate, which defaults to the current message. All of the +forms allowed for +.IR msglist +are also allowed for +.IR message , +but if more than one message is specified, only the first shall be +operated on. +.P +Other arguments are usually arbitrary strings whose usage depends on +the command involved. +.SS "Start-Up in mailx" +.P +At start-up time, +.IR mailx +shall take the following steps in sequence: +.IP " 1." 4 +Establish all variables at their stated default values. +.IP " 2." 4 +Process command line options, overriding corresponding default values. +.IP " 3." 4 +Import any of the +.IR DEAD , +.IR EDITOR , +.IR MBOX , +.IR LISTER , +.IR PAGER , +.IR SHELL , +or +.IR VISUAL +variables that are present in the environment, overriding the +corresponding default values. +.IP " 4." 4 +Read +.IR mailx +commands from an unspecified system start-up file, unless the +.BR \(min +option is given, to initialize any internal +.IR mailx +variables and aliases. +.IP " 5." 4 +Process the start-up file of +.IR mailx +commands named in the user +.IR MAILRC +variable. +.P +Most regular +.IR mailx +commands are valid inside start-up files, the most common use being to +set up initial display options and alias lists. The following commands +shall be invalid in the start-up file: +.BR ! , +.BR edit , +.BR hold , +.BR mail , +.BR preserve , +.BR reply , +.BR Reply , +.BR shell , +.BR visual , +.BR Copy , +.BR followup , +and +.BR Followup . +Any errors in the start-up file shall either cause +.IR mailx +to terminate with a diagnostic message and a non-zero status or to +continue after writing a diagnostic message, ignoring the remainder of +the lines in the start-up file. +.P +A blank line in a start-up file shall be ignored. +.SS "Internal Variables in mailx" +.P +The following variables are internal +.IR mailx +variables. Each internal variable can be set via the +.IR mailx +.BR set +command at any time. The +.BR unset +and +.BR "set\0no" +.IR name +commands can be used to erase variables. +.P +In the following list, variables shown as: +.sp +.RS 4 +.nf +\fB +variable +.fi \fR +.P +.RE +.P +represent Boolean values. Variables shown as: +.sp +.RS 4 +.nf +\fB +variable=\fIvalue\fP +.fi \fR +.P +.RE +.P +shall be assigned string or numeric values. For string values, the +rules in +.IR "Commands in mailx" +concerning filenames and quoting shall also apply. +.P +The defaults specified here may be changed by the unspecified system +start-up file unless the user specifies the +.BR \(min +option. +.IP "\fBallnet\fP" 10 +All network names whose login name components match shall be treated as +identical. This shall cause the +.IR msglist +message specifications to behave similarly. The default shall be +.BR noallnet . +See also the +.BR alternates +command and the +.BR metoo +variable. +.IP "\fBappend\fR" 10 +Append messages to the end of the +.BR mbox +file upon termination instead of placing them at the beginning. The +default shall be +.BR noappend . +This variable shall not affect the +.BR save +command when saving to +.BR mbox . +.IP "\fBask\fR,\0\fBasksub\fR" 10 +Prompt for a subject line on outgoing mail if one is not specified on +the command line with the +.BR \(mis +option. The +.BR ask +and +.BR asksub +forms are synonyms; the system shall refer to +.BR asksub +and +.BR noasksub +in its messages, but shall accept +.BR ask +and +.BR noask +as user input to mean +.BR asksub +and +.BR noasksub . +It shall not be possible to set both +.BR ask +and +.BR noasksub , +or +.BR noask +and +.BR asksub . +The default shall be +.BR asksub , +but no prompting shall be done if standard input is not a terminal. +.IP "\fBaskbcc\fR" 10 +Prompt for the blind copy list. The default shall be +.BR noaskbcc . +.IP "\fBaskcc\fR" 10 +Prompt for the copy list. The default shall be +.BR noaskcc . +.IP "\fBautoprint\fR" 10 +Enable automatic writing of messages after +.BR delete +and +.BR undelete +commands. The default shall be +.BR noautoprint . +.IP "\fBbang\fR" 10 +Enable the special-case treatment of + +characters (\c +.BR '!' ) +in escape command lines; see the +.BR escape +command and +.IR "Command Escapes in mailx". +The default shall be +.BR nobang , +disabling the expansion of +.BR '!' +in the +.IR command +argument to the +.BR ~! +command and the +.BR ~ +on a line by itself during message input from a terminal shall also +signify end-of-file (in addition to normal end-of-file). The default +shall be +.BR nodot . +If +.BR ignoreeof +is set (see below), a setting of +.BR nodot +shall be ignored and the + +is the only method to terminate input mode. +.IP "\fBescape\fR=\fIc\fR" 10 +Set the command escape character to be the character +.BR 'c' . +By default, the command escape character shall be +. +If +.BR escape +is unset, + +shall be used; if it is set to null, command escaping shall be disabled. +.IP "\fBflipr\fR" 10 +Reverse the meanings of the +.BR R +and +.BR r +commands. The default shall be +.BR noflipr . +.IP "\fBfolder\fR=\fIdirectory\fR" 10 +.br +The default directory for saving mail files. User-specified filenames +beginning with a + +(\c +.BR '\(pl' ) +shall be expanded by preceding the filename with this directory name +to obtain the real pathname. If +.IR directory +does not start with a + +(\c +.BR '/' ), +the contents of +.IR HOME +shall be prefixed to it. The default shall be +.BR nofolder . +If +.BR folder +is unset or set to null, user-specified filenames beginning with +.BR '\(pl' +shall refer to files in the current directory that begin with the +literal +.BR '\(pl' +character. See also +.BR outfolder +below. The +.BR folder +value need not affect the processing of the files named in +.IR MBOX +and +.IR DEAD . +.IP "\fBheader\fR" 10 +Enable writing of the header summary when entering +.IR mailx +in Receive Mode. The default shall be +.BR header . +.IP "\fBhold\fR" 10 +Preserve all messages that are read in the system mailbox instead of +putting them in the +.BR mbox +save file. The default shall be +.BR nohold . +.IP "\fBignore\fR" 10 +Ignore interrupts while entering messages. The default shall be +.BR noignore . +.IP "\fBignoreeof\fR" 10 +Ignore normal end-of-file during message input. Input can be +terminated only by entering a + +(\c +.BR '.' ) +on a line by itself or by the +.BR ~. +command escape. The default shall be +.BR noignoreeof . +See also +.BR dot +above. +.IP "\fBindentprefix\fR=\fIstring\fR" 10 +.br +A string that shall be added as a prefix to each line that is inserted +into the message by the +.BR ~m +command escape. This variable shall default to one +. +.IP "\fBkeep\fR" 10 +When a system mailbox, secondary mailbox, or +.BR mbox +is empty, truncate it to zero length instead of removing it. The +default shall be +.BR nokeep . +.IP "\fBkeepsave\fR" 10 +Keep the messages that have been saved from the system mailbox into +other files in the file designated by the variable +.IR MBOX , +instead of deleting them. The default shall be +.BR nokeepsave . +.IP "\fBmetoo\fR" 10 +Suppress the deletion of the login name of the user from the recipient +list when replying to a message or sending to a group. The default +shall be +.BR nometoo . +.IP "\fBonehop\fR" 10 +When responding to a message that was originally sent to several +recipients, the other recipient addresses are normally forced to be +relative to the originating author's machine for the response. This +flag disables alteration of the recipients' addresses, improving +efficiency in a network where all machines can send directly to all +other machines (that is, one hop away). The default shall be +.BR noonehop . +.IP "\fBoutfolder\fR" 10 +Cause the files used to record outgoing messages to be located in the +directory specified by the +.BR folder +variable unless the pathname is absolute. The default shall be +.BR nooutfolder . +See the +.BR record +variable. +.IP "\fBpage\fR" 10 +Insert a + +after each message sent through the pipe created by the +.BR pipe +command. The default shall be +.BR nopage . +.IP "\fBprompt\fR=\fIstring\fR" 10 +.br +Set the command-mode prompt to +.IR string . +If +.IR string +is null or if +.BR noprompt +is set, no prompting shall occur. The default shall be to prompt with +the string +.BR \(dq?\0\(dq . +.IP "\fBquiet\fR" 10 +Refrain from writing the opening message and version when entering +.IR mailx . +The default shall be +.BR noquiet . +.IP "\fBrecord\fR=\fIfile\fR" 10 +Record all outgoing mail in the file with the pathname +.IR file . +The default shall be +.BR norecord . +See also +.BR outfolder +above. +.IP "\fBsave\fR" 10 +Enable saving of messages in the dead-letter file on interrupt or +delivery error. See the variable +.IR DEAD +for the location of the dead-letter file. The default shall be +.BR save . +.IP "\fBscreen\fR=\fInumber\fR" 10 +.br +Set the number of lines in a screenful of headers for the +.BR headers +and +.BR z +commands. If +.BR screen +is not specified, a value based on the terminal type identified by the +.IR TERM +environment variable, the window size, the baud rate, or some +combination of these shall be used. +.IP "\fBsendwait\fR" 10 +Wait for the background mailer to finish before returning. The default +shall be +.BR nosendwait . +.IP "\fBshowto\fR" 10 +When the sender of the message was the user who is invoking +.IR mailx , +write the information from the +.BR To: +line instead of the +.BR From: +line in the header summary. The default shall be +.BR noshowto . +.IP "\fBsign\fR=\fIstring\fR" 10 +Set the variable inserted into the text of a message when the +.BR ~a +command escape is given. The default shall be +.BR nosign . +The character sequences +.BR '\et' +and +.BR '\en' +shall be recognized in the variable as + +and + +characters, respectively. (See also +.BR ~i +in +.IR "Command Escapes in mailx".) +.IP "\fBSign\fR=\fIstring\fR" 10 +Set the variable inserted into the text of a message when the +.BR ~A +command escape is given. The default shall be +.BR noSign . +The character sequences +.BR '\et' +and +.BR '\en' +shall be recognized in the variable as + +and + +characters, respectively. +.IP "\fBtoplines\fR=\fInumber\fR" 10 +.br +Set the number of lines of the message to write with the +.BR top +command. The default shall be 5. +.SS "Commands in mailx" +.P +The following +.IR mailx +commands shall be provided. In the following list, header refers to +lines from the message header, as shown in the OUTPUT FILES section. +Header-line refers to lines within the header that begin with one or +more non-white-space characters, immediately followed by a + +and white space and continuing until the next line beginning with a +non-white-space character or an empty line. Header-field refers to the +portion of a header line prior to the first + +in that line. +.P +For each of the commands listed below, the command can be entered as +the abbreviation (those characters in the Synopsis command word +preceding the +.BR '[' ), +the full command (all characters shown for the command word, omitting +the +.BR '[' +and +.BR ']' ), +or any truncation of the full command down to the abbreviation. For +example, the +.BR exit +command (shown as \fBex[it]\fR in the Synopsis) can be entered as +.BR ex , +.BR exi , +or +.BR exit . +.P +The arguments to commands can be quoted, using the following methods: +.IP " *" 4 +An argument can be enclosed between paired double-quotes (\c +.BR \(dq\^\(dq ) +or single-quotes (\c +.BR '\^' ); +any white space, shell word expansion, or + +characters within the quotes shall be treated literally as part of the +argument. A double-quote shall be treated literally within single-quotes +and \fIvice versa\fP. These special properties of the + +characters shall occur only when they are paired at the beginning and +end of the argument. +.IP " *" 4 +A + +outside of the enclosing quotes shall be discarded and the following +character treated literally as part of the argument. +.IP " *" 4 +An unquoted + +at the end of a command line shall be discarded and the next line shall +continue the command. +.br +.P +Filenames, where expected, shall be subjected to the following +transformations, in sequence: +.IP " *" 4 +If the filename begins with an unquoted +, +and the +.BR folder +variable is defined (see the +.BR folder +variable), the + +shall be replaced by the value of the +.BR folder +variable followed by a +. +If the +.BR folder +variable is unset or is set to null, the filename shall be unchanged. +.IP " *" 4 +Shell word expansions shall be applied to the filename (see +.IR "Section 2.6" ", " "Word Expansions"). +If more than a single pathname results from this expansion and the +command is expecting one file, the effects are unspecified. +.SS "Declare Aliases" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +a\fB[\fRlias\fB] [\fIalias \fB[\fIaddress\fR...\fB]]\fR +g\fB[\fRroup\fB] [\fIalias \fB[\fIaddress\fR...\fB]]\fR +.fi \fR +.P +.RE +.RE +.P +Add the given addresses to the alias specified by +.IR alias . +The names shall be substituted when +.IR alias +is used as a recipient address specified by the user in an outgoing +message (that is, other recipients addressed indirectly through the +.BR reply +command shall not be substituted in this manner). Mail address alias +substitution shall apply only when the alias string is used as a full +address; for example, when +.BR hlj +is an alias, +.IR hlj@posix.com +does not trigger the alias substitution. If no arguments are given, +write a listing of the current aliases to standard output. If only an +.IR alias +argument is given, write a listing of the specified alias to standard +output. These listings need not reflect the same order of addresses +that were entered. +.SS "Declare Alternatives" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +alt\fB[\fRernates\fB] \fIname\fR... +.fi \fR +.P +.RE +.RE +.P +(See also the +.BR metoo +variable.) Declare a list of alternative names for the user's login. +When responding to a message, these names shall be removed from the +list of recipients for the response. The comparison of names shall be +in a case-insensitive manner. With no arguments, +.BR alternates +shall write the current list of alternative names. +.SS "Change Current Directory" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +cd \fB[\fIdirectory\fB]\fR +ch\fB[\fRdir\fB] [\fIdirectory\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Change directory. If +.IR directory +is not specified, the contents of +.IR HOME +shall be used. +.SS "Copy Messages" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +c\fB[\fRopy\fB] [\fIfile\fB]\fR +c\fB[\fRopy\fB] [\fImsglist\fB] \fIfile\fR +C\fB[\fRopy\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Copy messages to the file named by the pathname +.IR file +without marking the messages as saved. Otherwise, it shall be +equivalent to the +.BR save +command. +.P +In the capitalized form, save the specified messages in a file whose +name is derived from the author of the message to be saved, without +marking the messages as saved. Otherwise, it shall be equivalent to +the +.BR Save +command. +.SS "Delete Messages" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +d\fB[\fRelete\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Mark messages for deletion from the mailbox. The deletions shall not +occur until +.IR mailx +quits (see the +.BR quit +command) or changes mailboxes (see the +.BR folder +command). If +.BR autoprint +is set and there are messages remaining after the +.BR delete +command, the current message shall be written as described for the +.BR print +command (see the +.BR print +command); otherwise, the +.IR mailx +prompt shall be written. +.SS "Discard Header Fields" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +di\fB[\fRscard\fB] [\fIheader-field\fR...\fB]\fR +ig\fB[\fRnore\fB] [\fIheader-field\fR...\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Suppress the specified header fields when writing messages. Specified +.IR header-fields +shall be added to the list of suppressed header fields. Examples of +header fields to ignore are +.BR status +and +.BR cc . +The fields shall be included when the message is saved. The +.BR Print +and +.BR Type +commands shall override this command. The comparison of header fields +shall be in a case-insensitive manner. If no arguments are specified, +write a list of the currently suppressed header fields to standard +output; the listing need not reflect the same order of header fields +that were entered. +.P +If both +.BR retain +and +.BR discard +commands are given, +.BR discard +commands shall be ignored. +.SS "Delete Messages and Display" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +dp \fB[\fImsglist\fB]\fR +dt \fB[\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Delete the specified messages as described for the +.BR delete +command, except that the +.BR autoprint +variable shall have no effect, and the current message shall be written +only if it was set to a message after the last message deleted by the +command. Otherwise, an informational message to the effect that there +are no further messages in the mailbox shall be written, followed by +the +.IR mailx +prompt. +.SS "Echo a String" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +ec\fB[\fRho\fB] \fIstring\fR ... +.fi \fR +.P +.RE +.RE +.P +Echo the given strings, equivalent to the shell +.IR echo +utility. +.SS "Edit Messages" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +e\fB[\fRdit\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Edit the given messages. The messages shall be placed in a temporary +file and the utility named by the +.IR EDITOR +variable is invoked to edit each file in sequence. The default +.IR EDITOR +is unspecified. +.P +The +.BR edit +command does not modify the contents of those messages in the mailbox. +.SS "Exit" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +ex\fB[\fRit\fB]\fR +x\fB[\fRit\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Exit from +.IR mailx +without changing the mailbox. No messages shall be saved in the +.BR mbox +(see also +.BR quit ). +.SS "Change Folder" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +fi\fB[\fRle\fB] [\fIfile\fB]\fR +fold\fB[\fRer\fB] [\fIfile\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Quit (see the +.BR quit +command) from the current file of messages and read in the file named +by the pathname +.IR file . +If no argument is given, the name and status of the current mailbox +shall be written. +.P +Several unquoted special characters shall be recognized when used as +.IR file +names, with the following substitutions: +.IP "\fR%\fR" 8 +The system mailbox for the invoking user. +.IP "\fR%\fIuser\fR" 8 +The system mailbox for +.IR user . +.IP "\fR#\fR" 8 +The previous file. +.IP "\fR&\fR" 8 +The current +.BR mbox . +.IP "\fR+\fIfile\fR" 8 +The named file in the +.BR folder +directory. (See the +.BR folder +variable.) +.P +The default file shall be the current mailbox. +.SS "Display List of Folders" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fRfolders\fR +.fi \fR +.P +.RE +.RE +.P +Write the names of the files in the directory set by the +.BR folder +variable. The command specified by the +.IR LISTER +environment variable shall be used (see the ENVIRONMENT VARIABLES +section). +.SS "Follow Up Specified Messages" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +fo\fB[\fRllowup\fB] [\fImessage\fB]\fR +F\fB[\fRollowup\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +In the lowercase form, respond to a message, recording the response in +a file whose name is derived from the author of the message. See also +the +.BR save +and +.BR copy +commands and +.BR outfolder . +.P +In the capitalized form, respond to the first message in the +.IR msglist , +sending the message to the author of each message in the +.IR msglist . +The subject line shall be taken from the first message and the response +shall be recorded in a file whose name is derived from the author of +the first message. See also the +.BR Save +and +.BR Copy +commands and +.BR outfolder . +.P +Both forms shall override the +.BR record +variable, if set. +.SS "Display Header Summary for Specified Messages" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +f\fB[\fRrom\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Write the header summary for the specified messages. +.SS "Display Header Summary" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +h\fB[\fReaders\fB] [\fImessage\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Write the page of headers that includes the message specified. If the +.IR message +argument is not specified, the current message shall not change. +However, if the +.IR message +argument is specified, the current message shall become the message +that appears at the top of the page of headers that includes the +message specified. The +.BR screen +variable sets the number of headers per page. See also the +.BR z +command. +.SS "Help" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +hel\fB[\fRp\fB]\fR +? +.fi \fR +.P +.RE +.RE +.P +Write a summary of commands. +.SS "Hold Messages" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +ho\fB[\fRld\fB] [\fImsglist\fB]\fR +pre\fB[\fRserve\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Mark the messages in +.IR msglist +to be retained in the mailbox when +.IR mailx +terminates. This shall override any commands that might previously +have marked the messages to be deleted. During the current invocation +of +.IR mailx , +only the +.BR delete , +.BR dp , +or +.BR dt +commands shall remove the +.IR preserve +marking of a message. +.SS "Execute Commands Conditionally" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +i\fB[\fRf\fB]\fR s|r +\fImail-command\fRs +el\fB[\fRse\fB] +\fImail-command\fRs +en\fB[\fRdif\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Execute commands conditionally, where +.BR "if\0s" +executes the following +.IR mail-command s, +up to an +.BR else +or +.BR endif , +if the program is in Send Mode, and +.BR "if\0r" +shall cause the +.IR mail-command s +to be executed only in Receive Mode. +.SS "List Available Commands" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +l\fB[\fRist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Write a list of all commands available. No explanation shall be +given. +.SS "Mail a Message" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +m\fB[\fRail\fB] \fIaddress\fR... +.fi \fR +.P +.RE +.RE +.P +Mail a message to the specified addresses or aliases. +.SS "Direct Messages to mbox" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +mb\fB[\fRox\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Arrange for the given messages to end up in the +.BR mbox +save file when +.IR mailx +terminates normally. See +.IR MBOX . +See also the +.BR exit +and +.BR quit +commands. +.SS "Process Next Specified Message" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +n\fB[\fRext\fB] [\fImessage\fB]\fR +.fi \fR +.P +.RE +.RE +.P +If the current message has not been written (for example, by the +.BR print +command) since +.IR mailx +started or since any other message was the current message, behave as +if the +.BR print +command was entered. Otherwise, if there is an undeleted message after +the current message, make it the current message and behave as if the +.BR print +command was entered. Otherwise, an informational message to the effect +that there are no further messages in the mailbox shall be written, +followed by the +.IR mailx +prompt. Should the current message location be the result of an +immediately preceding +.BR hold , +.BR mbox , +.BR preserve , +or +.BR touch +command, +.BR next +will act as if the current message has already been written. +.SS "Pipe Message" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +pi\fB[\fRpe\fB] [[\fImsglist\fB] \fIcommand\fB]\fR +| \fB[[\fImsglist\fB] \fIcommand\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Pipe the messages through the given +.IR command +by invoking the command interpreter specified by +.IR SHELL +with two arguments: +.BR \(mic +and +.IR command . +(See also +.IR sh +.BR \(mic .) +The application shall ensure that the command is given as a single +argument. Quoting, described previously, can be used to accomplish +this. If no arguments are given, the current message shall be piped +through the command specified by the value of the +.BR cmd +variable. If the +.BR page +variable is set, a + +shall be inserted after each message. +.SS "Display Message with Headers" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +P\fB[\fRrint\fB] [\fImsglist\fB]\fR +T\fB[\fRype\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Write the specified messages, including all header lines, to standard +output. Override suppression of lines by the +.BR discard , +.BR ignore , +and +.BR retain +commands. If +.BR crt +is set, the messages longer than the number of lines specified by the +.BR crt +variable shall be paged through the command specified by the +.IR PAGER +environment variable. +.SS "Display Message" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +p\fB[\fRrint\fB] [\fImsglist\fB]\fR +t\fB[\fRype\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Write the specified messages to standard output. If +.BR crt +is set, the messages longer than the number of lines specified by the +.BR crt +variable shall be paged through the command specified by the +.IR PAGER +environment variable. +.SS "Quit" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +q\fB[\fRuit\fB] +\fIend-of-file\fR +.fi \fR +.P +.RE +.RE +.P +Terminate +.IR mailx , +storing messages that were read in +.BR mbox +(if the current mailbox is the system mailbox and unless +.BR hold +is set), deleting messages that have been explicitly saved (unless +.BR keepsave +is set), discarding messages that have been deleted, and saving all +remaining messages in the mailbox. +.SS "Reply to a Message List" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +R\fB[\fReply\fB] [\fImsglist\fB]\fR +R\fB[\fRespond\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Mail a reply message to the sender of each message in the +.IR msglist . +The subject line shall be formed by concatenating +.BR Re: \c + +(unless it already begins with that string) and the subject from the +first message. If +.BR record +is set to a filename, the response shall be saved at the end of that +file. +.P +See also the +.BR flipr +variable. +.SS "Reply to a Message" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +r\fB[\fReply\fB] [\fImessage\fB]\fR +r\fB[\fRespond\fB] [\fImessage\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Mail a reply message to all recipients included in the header of the +message. The subject line shall be formed by concatenating +.BR Re: \c + +(unless it already begins with that string) and the subject from the +message. If +.BR record +is set to a filename, the response shall be saved at the end of that +file. +.P +See also the +.BR flipr +variable. +.SS "Retain Header Fields" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +ret\fB[\fRain\fB] [\fIheader-field\fR...\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Retain the specified header fields when writing messages. This command +shall override all +.BR discard +and +.BR ignore +commands. The comparison of header fields shall be in a +case-insensitive manner. If no arguments are specified, write a list +of the currently retained header fields to standard output; the listing +need not reflect the same order of header fields that were entered. +.SS "Save Messages" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +s\fB[\fRave\fB] [\fIfile\fB]\fR +s\fB[\fRave\fB] [\fImsglist\fB] \fIfile\fR +S\fB[\fRave\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Save the specified messages in the file named by the pathname +.IR file , +or the +.BR mbox +if the +.IR file +argument is omitted. The file shall be created if it does not exist; +otherwise, the messages shall be appended to the file. The message +shall be put in the state +.IR saved , +and shall behave as specified in the description of the +.IR saved +state when the current mailbox is exited by the +.BR quit +or +.BR file +command. +.P +In the capitalized form, save the specified messages in a file whose +name is derived from the author of the first message. The name of the +file shall be taken to be the author's name with all network addressing +stripped off. See also the +.BR Copy , +.BR followup , +and +.BR Followup +commands and +.BR outfolder +variable. +.SS "Set Variables" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +se\fB[\fRt\fB] [\fIname\fB[\fR=\fB[\fIstring\fB]] \fR...\fB] [\fIname\fR=\fInumber \fR...\fB] [\fRno\fIname \fR...\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Define one or more variables called +.IR name . +The variable can be given a null, string, or numeric value. Quoting and +-escapes +can occur anywhere in +.IR string , +as described previously, as if the +.IR string +portion of the argument were the entire argument. The forms +.IR name +and +.IR name = +shall be equivalent to +.IR name ="" +for variables that take string values. The +.BR set +command without arguments shall write a list of all defined variables +and their values. The +.BR no +.IR name +form shall be equivalent to +.BR unset +.IR name . +.SS "Invoke a Shell" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +sh\fB[\fRell\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Invoke an interactive command interpreter (see also +.IR SHELL ). +.SS "Display Message Size" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +si\fB[\fRze\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Write the size in bytes of each of the specified messages. +.SS "Read mailx Commands From a File" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +so\fB[\fRurce\fB] \fIfile\fR +.fi \fR +.P +.RE +.RE +.P +Read and execute commands from the file named by the pathname +.IR file +and return to command mode. +.SS "Display Beginning of Messages" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +to\fB[\fRp\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Write the top few lines of each of the specified messages. If the +.BR toplines +variable is set, it is taken as the number of lines to write. The +default shall be 5. +.SS "Touch Messages" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +tou\fB[\fRch\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Touch the specified messages. If any message in +.IR msglist +is not specifically deleted nor saved in a file, it shall be placed in +the +.BR mbox +upon normal termination. See +.BR exit +and +.BR quit . +.SS "Delete Aliases" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +una\fB[\fRlias\fB] [\fIalias\fB]\fR... +.fi \fR +.P +.RE +.RE +.P +Delete the specified alias names. If a specified alias does not exist, +the results are unspecified. +.SS "Undelete Messages" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +u\fB[\fRndelete\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Change the state of the specified messages from deleted to read. If +.BR autoprint +is set, the last message of those restored shall be written. If +.IR msglist +is not specified, the message shall be selected as follows: +.IP " *" 4 +If there are any deleted messages that follow the current message, the +first of these shall be chosen. +.IP " *" 4 +Otherwise, the last deleted message that also precedes the current +message shall be chosen. +.SS "Unset Variables" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +uns\fB[\fRet\fB] \fIname\fR... +.fi \fR +.P +.RE +.RE +.P +Cause the specified variables to be erased. +.SS "Edit Message with Full-Screen Editor" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +v\fB[\fRisual\fB] [\fImsglist\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Edit the given messages with a screen editor. Each message shall be +placed in a temporary file, and the utility named by the +.IR VISUAL +variable shall be invoked to edit each file in sequence. The default +editor shall be +.IR vi . +.P +The +.BR visual +command does not modify the contents of those messages in the mailbox. +.SS "Write Messages to a File" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +w\fB[\fRrite\fB] [\fImsglist\fB] \fIfile\fR +.fi \fR +.P +.RE +.RE +.P +Write the given messages to the file specified by the pathname +.IR file , +minus the message header. Otherwise, it shall be equivalent to the +.BR save +command. +.SS "Scroll Header Display" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +z\fB[\fR+|\(mi\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Scroll the header display forward (if +.BR '\(pl' +is specified or if no option is specified) or backward (if +.BR '\(mi' +is specified) one screenful. The number of headers written shall be +set by the +.BR screen +variable. +.SS "Invoke Shell Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +!\fIcommand\fR +.fi \fR +.P +.RE +.RE +.P +Invoke the command interpreter specified by +.IR SHELL +with two arguments: +.BR \(mic +and +.IR command . +(See also +.IR sh +.BR \(mic .) +If the +.BR bang +variable is set, each unescaped occurrence of +.BR '!' +in +.IR command +shall be replaced with the command executed by the previous +.BR ! +command or +.BR ~! +command escape. +.SS "Null Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +# \fIcomment\fR +.fi \fR +.P +.RE +.RE +.P +This null command (comment) shall be ignored by +.IR mailx . +.SS "Display Current Message Number" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB += +.fi \fR +.P +.RE +.RE +.P +Write the current message number. +.SS "Command Escapes in mailx" +.P +The following commands can be entered only from input mode, by +beginning a line with the escape character (by default, + +(\c +.BR '~' )). +See the +.BR escape +variable description for changing this special character. The format +for the commands shall be: +.sp +.RS 4 +.nf +\fB +<\fIescape-character\fR><\fIcommand-char\fR><\fIseparator\fR>\fB[\fR<\fIarguments\fR>\fB]\fR +.fi \fR +.P +.RE +.P +where the <\fIseparator\fP> can be zero or more + +characters. +.P +In the following descriptions, the application shall ensure that the +argument +.IR command +(but not +.IR mailx-command) +is a shell command string. Any string acceptable to the command +interpreter specified by the +.IR SHELL +variable when it is invoked as +.IR SHELL +.BR \(mic +.IR command_string +shall be valid. The command can be presented as multiple arguments +(that is, quoting is not required). +.P +Command escapes that are listed with +.IR msglist +or +.IR mailx-command +arguments are invalid in Send Mode and produce unspecified results. +.IP "\fB~!\0\fIcommand\fR" 10 +Invoke the command interpreter specified by +.IR SHELL +with two arguments: +.BR \(mic +and +.IR command ; +and then return to input mode. If the +.BR bang +variable is set, each unescaped occurrence of +.BR '!' +in +.IR command +shall be replaced with the command executed by the previous +.BR ! +command or +.BR ~! +command escape. +.IP "\fB~.\fR" 10 +Simulate end-of-file (terminate message input). +.IP "\fB~:\0\fImailx-command\fR,\0\fB~_\0\fImailx-command\fR" 10 +.br +Perform the command-level request. +.IP "\fB~?\fR" 10 +Write a summary of command escapes. +.IP "\fB~A\fR" 10 +This shall be equivalent to +.BR "~i\0Sign" . +.IP "\fB~a\fR" 10 +This shall be equivalent to +.BR "~i\0sign" . +.IP "\fB~b\0\fIname\fR.\|.\|." 10 +Add the +.IR name s +to the blind carbon copy (\c +.BR Bcc ) +list. +.IP "\fB~c\0\fIname\fR.\|.\|." 10 +Add the +.IR name s +to the carbon copy (\c +.BR Cc ) +list. +.IP "\fB~d\fR" 10 +Read in the dead-letter file. See +.IR DEAD +for a description of this file. +.IP "\fB~e\fR" 10 +Invoke the editor, as specified by the +.IR EDITOR +environment variable, on the partial message. +.IP "\fB~\|f\0[\fImsglist\fB]\fR" 10 +Forward the specified messages. The specified messages shall be +inserted into the current message without alteration. This command +escape also shall insert message headers into the message with field +selection affected by the +.BR discard , +.BR ignore , +and +.BR retain +commands. +.IP "\fB~\|F\0[\fImsglist\fB]\fR" 10 +This shall be the equivalent of the +.BR ~f +command escape, except that all headers shall be included in the +message, regardless of previous +.BR discard , +.BR ignore , +and +.BR retain +commands. +.IP "\fB~h\fR" 10 +If standard input is a terminal, prompt for a +.BR Subject +line and the +.BR To , +.BR Cc , +and +.BR Bcc +lists. Other implementation-defined headers may also be presented +for editing. If the field is written with an initial value, it can be +edited as if it had just been typed. +.IP "\fB~i\0\fIstring\fR" 10 +Insert the value of the named variable, followed by a +, +into the text of the message. If the string is unset or null, the +message shall not be changed. +.IP "\fB~\|m\0[\fImsglist\fB]\fR" 10 +Insert the specified messages into the message, prefixing non-empty +lines with the string in the +.BR indentprefix +variable. This command escape also shall insert message headers into +the message, with field selection affected by the +.BR discard , +.BR ignore , +and +.BR retain +commands. +.IP "\fB~\|M\0[\fImsglist\fB]\fR" 10 +This shall be the equivalent of the +.BR ~m +command escape, except that all headers shall be included in the +message, regardless of previous +.BR discard , +.BR ignore , +and +.BR retain +commands. +.IP "\fB~p\fR" 10 +Write the message being entered. If the message is longer than +.BR crt +lines (see +.IR "Internal Variables in mailx"), +the output shall be paginated as described for the +.IR PAGER +variable. +.IP "\fB~q\fR" 10 +Quit (see the +.BR quit +command) from input mode by simulating an interrupt. If the body of +the message is not empty, the partial message shall be saved in the +dead-letter file. See +.IR DEAD +for a description of this file. +.IP "\fB~r\0\fIfile\fR,\0\fB~<\0\fIfile\fR,\0\fB~r\0!\fIcommand\fR,\0\fB~<\0!\fIcommand\fR" 10 +.br +Read in the file specified by the pathname +.IR file . +If the argument begins with an + +(\c +.BR '!' ), +the rest of the string shall be taken as an arbitrary system command; +the command interpreter specified by +.IR SHELL +shall be invoked with two arguments: +.BR \(mic +and +.IR command . +The standard output of +.IR command +shall be inserted into the message. +.IP "\fB~s\0\fIstring\fR" 10 +Set the subject line to +.IR string . +.IP "\fB~t\0\fIname\fR.\|.\|." 10 +Add the given +.IR name s +to the +.BR To +list. +.IP "\fB~v\fR" 10 +Invoke the full-screen editor, as specified by the +.IR VISUAL +environment variable, on the partial message. +.IP "\fB~w\0\fIfile\fR" 10 +Write the partial message, without the header, onto the file named by +the pathname +.IR file . +The file shall be created or the message shall be appended to it if the +file exists. +.IP "\fB~x\fR" 10 +Exit as with +.BR ~q , +except the message shall not be saved in the dead-letter file. +.IP "\fB~|\0\fIcommand\fR" 10 +Pipe the body of the message through the given +.IR command +by invoking the command interpreter specified by +.IR SHELL +with two arguments: +.BR \(mic +and +.IR command . +If the +.IR command +returns a successful exit status, the standard output of the command +shall replace the message. Otherwise, the message shall remain +unchanged. If the +.IR command +fails, an error message giving the exit status shall be written. +.br +.SH "EXIT STATUS" +When the +.BR \(mie +option is specified, the following exit values are returned: +.IP "\00" 6 +Mail was found. +.IP >0 6 +Mail was not found or an error occurred. +.P +Otherwise, the following exit values are returned: +.IP "\00" 6 +Successful completion; note that this status implies that all messages +were +.IR sent , +but it gives no assurances that any of them were actually +.IR delivered . +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +When in +input mode (Receive Mode) +or Send Mode: +.IP " *" 4 +If an error is encountered processing an input line beginning +with a + +(\c +.BR '~' ) +character, +(see +.IR "Command Escapes in mailx"), +a diagnostic message shall be written to standard error, and the +message being composed may be modified, but this condition shall not +prevent the message from being sent. +.IP " *" 4 +Other errors shall prevent the sending of the message. +.P +When in command mode: +.IP " *" 4 +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Delivery of messages to remote systems requires the existence of +communication paths to such systems. These need not exist. +.P +Input lines are limited to +{LINE_MAX} +bytes, but mailers between systems may impose more severe line-length +restrictions. This volume of POSIX.1\(hy2008 does not place any restrictions on the length of +messages handled by +.IR mailx , +and for delivery of local messages the only limitations should be the +normal problems of available disk space for the target mail file. When +sending messages to external machines, applications are advised to +limit messages to less than 100\|000 bytes because some mail gateways +impose message-length restrictions. +.P +The format of the system mailbox is intentionally unspecified. Not all +systems implement system mailboxes as flat files, particularly with the +advent of multimedia mail messages. Some system mailboxes may be +multiple files, others records in a database. The internal format of +the messages themselves is specified with the historical format from +Version\ 7, but only after the messages have been saved in some file +other than the system mailbox. This was done so that many historical +applications expecting text-file mailboxes are not broken. +.P +Some new formats for messages can be expected in the future, probably +including binary data, bit maps, and various multimedia objects. As +described here, +.IR mailx +is not prohibited from handling such messages, but it must store them +as text files in secondary mailboxes (unless some extension, such as a +variable or command line option, is used to change the stored format). +Its method of doing so is implementation-defined and might include +translating the data into text file-compatible or readable form or +omitting certain portions of the message from the stored output. +.P +The +.BR discard +and +.BR ignore +commands are not inverses of the +.BR retain +command. The +.BR retain +command discards all header-fields except those explicitly retained. +The +.BR discard +command keeps all header-fields except those explicitly discarded. If +headers exist on the retained header list, +.BR discard +and +.BR ignore +commands are ignored. +.SH EXAMPLES +None. +.SH RATIONALE +The standard developers felt strongly that a method for applications to +send messages to specific users was necessary. The obvious example is a +batch utility, running non-interactively, that wishes to communicate +errors or results to a user. However, the actual format, delivery +mechanism, and method of reading the message are clearly beyond the +scope of this volume of POSIX.1\(hy2008. +.P +The intent of this command is to provide a simple, portable interface +for sending messages non-interactively. It merely defines a +``front-end'' to the historical mail system. It is suggested that +implementations explicitly denote the sender and recipient in the body +of the delivered message. Further specification of formats for either +the message envelope or the message itself were deliberately not made, +as the industry is in the midst of changing from the current standards +to a more internationalized standard and it is probably incorrect, at +this time, to require either one. +.P +Implementations are encouraged to conform to the various delivery +mechanisms described in the CCITT X.400 standards or to the equivalent +Internet standards, described in Internet Request for Comment (RFC) +documents RFC\ 819, RFC\ 822, RFC\ 920, RFC\ 921, and RFC\ 1123. +.P +Many historical systems modified each body line that started with +.BR "From\0" +by prefixing the +.BR 'F' +with +.BR '>' . +It is unnecessary, but allowed, to do that when the string does not +follow a blank line because it cannot be confused with the next +header. +.P +The +.BR edit +and +.BR visual +commands merely edit the specified messages in a temporary file. They +do not modify the contents of those messages in the mailbox; such a +capability could be added as an extension, such as by using different +command names. +.P +The restriction on a subject line being +{LINE_MAX}\(mi10 +bytes is based on the historical format that consumes 10 bytes for +.BR "Subject:\0" +and the trailing +. +Many historical mailers that a message may encounter on other systems +are not able to handle lines that long, however. +.P +Like the utilities +.IR logger +and +.IR lp , +.IR mailx +admittedly is difficult to test. This was not deemed sufficient +justification to exclude this utility from this volume of POSIX.1\(hy2008. It is also arguable +that it is, in fact, testable, but that the tests themselves are not +portable. +.P +When +.IR mailx +is being used by an application that wishes to receive the results as +if none of the User Portability Utilities option features were +supported, the +.IR DEAD +environment variable must be set to +.BR /dev/null . +Otherwise, it may be subject to the file creations described in +.IR mailx +ASYNCHRONOUS EVENTS. Similarly, if the +.IR MAILRC +environment variable is not set to +.BR /dev/null , +historical versions of +.IR mailx +and +.IR Mail +read initialization commands from a file before processing begins. +Since the initialization that a user specifies could alter the contents +of messages an application is trying to send, such applications must +set +.IR MAILRC +to +.BR /dev/null . +.P +The description of +.IR LC_TIME +uses ``may affect'' because many historical implementations do not or +cannot manipulate the date and time strings in the incoming mail +headers. Some headers found in incoming mail do not have enough +information to determine the timezone in which the mail originated, +and, therefore, +.IR mailx +cannot convert the date and time strings into the internal form that +then is parsed by routines like +\fIstrftime\fR() +that can take +.IR LC_TIME +settings into account. Changing all these times to a user-specified +format is allowed, but not required. +.P +The paginator selected when +.IR PAGER +is null or unset is partially unspecified to allow the System V +historical practice of using +.IR pg +as the default. Bypassing the pagination function, such as by declaring +that +.IR cat +is the paginator, would not meet with the intended meaning of this +description. However, any ``portable user'' would have to set +.IR PAGER +explicitly to get his or her preferred paginator on all systems. The +paginator choice was made partially unspecified, unlike the +.IR VISUAL +editor choice (mandated to be +.IR vi ) +because most historical pagers follow a common theme of user input, +whereas editors differ dramatically. +.P +Options to specify addresses as +.BR cc +(carbon copy) or +.BR bcc +(blind carbon copy) were considered to be format details and were +omitted. +.P +A zero exit status implies that all messages were +.IR sent , +but it gives no assurances that any of them were actually +.IR delivered . +The reliability of the delivery mechanism is unspecified and is an +appropriate marketing distinction between systems. +.P +In order to conform to the Utility Syntax Guidelines, a solution was +required to the optional +.IR file +option-argument to +.BR \(mif . +By making +.IR file +an operand, the guidelines are satisfied and users remain portable. +However, it does force implementations to support usage such as: +.sp +.RS 4 +.nf +\fB +mailx \(mifin mymail.box +.fi \fR +.P +.RE +.P +The +.BR no +.IR name +method of unsetting variables is not present in all historical systems, +but it is in System V and provides a logical set of commands +corresponding to the format of the display of options from the +.IR mailx +.IR set +command without arguments. +.P +The +.BR ask +and +.BR asksub +variables are the names selected by BSD and System V, respectively, for +the same feature. They are synonyms in this volume of POSIX.1\(hy2008. +.P +The +.IR mailx +.IR echo +command was not documented in the BSD version and has been omitted here +because it is not obviously useful for interactive users. +.P +The default prompt on the System V +.IR mailx +is a +, +on BSD +.IR Mail +an +. +Since this volume of POSIX.1\(hy2008 chose the +.IR mailx +name, it kept the System V default, assuming that BSD users would not +have difficulty with this minor incompatibility (that they can +override). +.P +The meanings of +.BR r +and +.BR R +are reversed between System V +.IR mailx +and SunOS +.IR Mail . +Once again, since this volume of POSIX.1\(hy2008 chose the +.IR mailx +name, it kept the System V default, but allows the SunOS user to +achieve the desired results using +.BR flipr , +an internal variable in System V +.IR mailx , +although it has not been documented in the SVID. +.P +The +.BR indentprefix +variable, the +.BR retain +and +.BR unalias +commands, and the +.BR ~F +and +.BR ~M +command escapes were adopted from 4.3 BSD +.IR Mail . +.P +The +.BR version +command was not included because no sufficiently general specification +of the version information could be devised that would still be useful +to a portable user. This command name should be used by suppliers who +wish to provide version information about the +.IR mailx +command. +.P +The ``implementation-specific (unspecified) system start-up file'' +historically has been named +.BR /etc/mailx.rc , +but this specific name and location are not required. +.P +The intent of the wording for the +.BR next +command is that if any command has already displayed the current +message it should display a following message, but, otherwise, it +should display the current message. Consider the command sequence: +.sp +.RS 4 +.nf +\fB +next 3 +delete 3 +next +.fi \fR +.P +.RE +.P +where the +.BR autoprint +option was not set. The normative text specifies that the second +.BR next +command should display a message following the third message, because +even though the current message has not been displayed since it was set +by the +.BR delete +command, it has been displayed since the current message was anything +other than message number 3. This does not always match historical +practice in some implementations, where the command file address +followed by +.BR next +(or the default command) would skip the message for which the user had +searched. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIed\fR\^", +.IR "\fIls\fR\^", +.IR "\fImore\fR\^", +.IR "\fIvi\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/make.1p b/man-pages-posix-2013/man1p/make.1p new file mode 100644 index 0000000..44f900f --- /dev/null +++ b/man-pages-posix-2013/man1p/make.1p @@ -0,0 +1,2487 @@ +'\" et +.TH MAKE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +make +\(em maintain, update, and regenerate groups of programs +(\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +make \fB[\fR\(mieinpqrst\fB] [\fR\(mif \fImakefile\fB]\fR... \fB[\fR\(mik|\(miS\fB] [\fImacro\fR=\fIvalue\fR...\fB] + \fB[\fItarget_name\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR make +utility shall update files that are derived from other files. A typical +case is one where object files are derived from the corresponding +source files. The +.IR make +utility examines time relationships and shall update those derived files +(called targets) that have modified times earlier than the modified +times of the files (called prerequisites) from which they are derived. +A description file (makefile) contains a description of the +relationships between files, and the commands that need to be executed +to update the targets to reflect changes in their prerequisites. Each +specification, or rule, shall consist of a target, optional +prerequisites, and optional commands to be executed when a prerequisite +is newer than the target. There are two types of rule: +.IP " 1." 4 +\fIInference rules\fP, +which have one target name with at least one + +(\c +.BR '.' ) +and no + +(\c +.BR '/' ) +.IP " 2." 4 +\fITarget rules\fP, +which can have more than one target name +.P +In addition, +.IR make +shall have a collection of built-in macros and inference rules that +infer prerequisite relationships to simplify maintenance of programs. +.P +To receive exactly the behavior described in this section, the +user shall ensure that a portable makefile shall: +.IP " *" 4 +Include the special target +.BR .POSIX +.IP " *" 4 +Omit any special target reserved for implementations (a leading period +followed by uppercase letters) that has not been specified by this +section +.P +The behavior of +.IR make +is unspecified if either or both of these conditions are not met. +.SH OPTIONS +The +.IR make +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except for Guideline 9. +.P +The following options shall be supported: +.IP "\fB\(mie\fP" 10 +Cause environment variables, including those with null values, to +override macro assignments within makefiles. +.IP "\fB\(mif\ \fImakefile\fR" 10 +Specify a different makefile. The argument +.IR makefile +is a pathname of a description file, which is also referred to as the +.IR makefile . +A pathname of +.BR '\(mi' +shall denote the standard input. There can be multiple instances of +this option, and they shall be processed in the order specified. The +effect of specifying the same option-argument more than once is +unspecified. +.IP "\fB\(mii\fP" 10 +Ignore error codes returned by invoked commands. This mode is the same +as if the special target +.BR .IGNORE +were specified without prerequisites. +.IP "\fB\(mik\fP" 10 +Continue to update other targets that do not depend on the current +target if a non-ignored error occurs while executing the commands to +bring a target up-to-date. +.IP "\fB\(min\fP" 10 +Write commands that would be executed on standard output, but do not +execute them. However, lines with a + +(\c +.BR '\(pl' ) +prefix shall be executed. In this mode, lines with an at-sign (\c +.BR '@' ) +character prefix shall be written to standard output. +.IP "\fB\(mip\fP" 10 +Write to standard output the complete set of macro definitions and +target descriptions. The output format is unspecified. +.IP "\fB\(miq\fP" 10 +Return a zero exit value if the target file is up-to-date; otherwise, +return an exit value of 1. Targets shall not be updated if this option +is specified. However, a makefile command line (associated with the +targets) with a + +(\c +.BR '\(pl' ) +prefix shall be executed. +.IP "\fB\(mir\fP" 10 +Clear the suffix list and do not use the built-in rules. +.IP "\fB\(miS\fP" 10 +Terminate +.IR make +if an error occurs while executing the commands to bring a target +up-to-date. This shall be the default and the opposite of +.BR \(mik . +.IP "\fB\(mis\fP" 10 +Do not write makefile command lines or touch messages (see +.BR \(mit ) +to standard output before executing. This mode shall be the same as if +the special target +.BR .SILENT +were specified without prerequisites. +.IP "\fB\(mit\fP" 10 +Update the modification time of each target as though a +.IR touch +.IR target +had been executed. Targets that have prerequisites but no commands (see +.IR "Target Rules"), +or that are already up-to-date, shall not be touched in this manner. +Write messages to standard output for each target file indicating the +name of the file and that it was touched. Normally, the +.IR makefile +command lines associated with each target are not executed. However, a +command line with a + +(\c +.BR '\(pl' ) +prefix shall be executed. +.P +Any options specified in the +.IR MAKEFLAGS +environment variable shall be evaluated before any options specified on +the +.IR make +utility command line. If the +.BR \(mik +and +.BR \(miS +options are both specified on the +.IR make +utility command line or by the +.IR MAKEFLAGS +environment variable, the last option specified shall take precedence. +If the +.BR \(mif +or +.BR \(mip +options appear in the +.IR MAKEFLAGS +environment variable, the result is undefined. +.SH OPERANDS +The following operands shall be supported: +.IP "\fItarget_name\fR" 10 +Target names, as defined in the EXTENDED DESCRIPTION section. If no +target is specified, while +.IR make +is processing the makefiles, the first target that +.IR make +encounters that is not a special target or an inference rule shall be +used. +.IP "\fImacro\fR=\fIvalue\fR" 10 +Macro definitions, as defined in +.IR "Macros". +.P +If the +.IR target_name +and +.IR macro =\c +.IR value +operands are intermixed on the +.IR make +utility command line, the results are unspecified. +.SH STDIN +The standard input shall be used only if the +.IR makefile +option-argument is +.BR '\(mi' . +See the INPUT FILES section. +.SH "INPUT FILES" +The input file, otherwise known as the makefile, is a text file +containing rules, macro definitions, and comments. See the +EXTENDED DESCRIPTION section. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR make : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fIMAKEFLAGS\fP" 10 +.br +This variable shall be interpreted as a character string representing a +series of option characters to be used as the default options. The +implementation shall accept both of the following formats (but need not +accept them when intermixed): +.RS 10 +.IP " *" 4 +The characters are option letters without the leading + +characters or + +separation used on a +.IR make +utility command line. +.IP " *" 4 +The characters are formatted in a manner similar to a portion of the +.IR make +utility command line: options are preceded by + +characters and +-separated +as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +The +.IR macro =\c +.IR value +macro definition operands can also be included. The difference between +the contents of +.IR MAKEFLAGS +and the +.IR make +utility command line is that the contents of the variable shall not be +subjected to the word expansions (see +.IR "Section 2.6" ", " "Word Expansions") +associated with parsing the command line values. +.RE +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPROJECTDIR\fP" 10 +.br +Provide a directory to be used to search for SCCS files not found in +the current directory. In all of the following cases, the search for +SCCS files is made in the directory +.BR SCCS +in the identified directory. If the value of +.IR PROJECTDIR +begins with a +, +it shall be considered an absolute pathname; otherwise, the value of +.IR PROJECTDIR +is treated as a user name and that user's initial working directory +shall be examined for a subdirectory +.BR src +or +.BR source . +If such a directory is found, it shall be used. Otherwise, the value +is used as a relative pathname. +.RS 10 +.P +If +.IR PROJECTDIR +is not set or has a null value, the search for SCCS files shall be made +in the directory +.BR SCCS +in the current directory. +.P +The setting of +.IR PROJECTDIR +affects all files listed in the remainder of this utility description +for files with a component named +.BR SCCS . +.RE +.P +The value of the +.IR SHELL +environment variable shall not be used as a macro and shall not be +modified by defining the +.BR SHELL +macro in a makefile or on the command line. All other environment +variables, including those with null values, shall be used as macros, +as defined in +.IR "Macros". +.SH "ASYNCHRONOUS EVENTS" +If not already ignored, +.IR make +shall trap SIGHUP, SIGTERM, SIGINT, and SIGQUIT and remove the current +target unless the target is a directory or the target is a prerequisite +of the special target +.BR .PRECIOUS +or unless one of the +.BR \(min , +.BR \(mip , +or +.BR \(miq +options was specified. Any targets removed in this manner shall be +reported in diagnostic messages of unspecified format, written to +standard error. After this cleanup process, if any, +.IR make +shall take the standard action for all other signals. +.SH STDOUT +The +.IR make +utility shall write all commands to be executed to standard output +unless the +.BR \(mis +option was specified, the command is prefixed with an at-sign, or the +special target +.BR .SILENT +has either the current target as a prerequisite or has no +prerequisites. If +.IR make +is invoked without any work needing to be done, it shall write a +message to standard output indicating that no action was taken. If the +.BR \(mit +option is present and a file is touched, +.IR make +shall write to standard output a message of unspecified format +indicating that the file was touched, including the filename of the +file. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +Files can be created when the +.BR \(mit +option is present. Additional files can also be created by the +utilities invoked by +.IR make . +.SH "EXTENDED DESCRIPTION" +The +.IR make +utility attempts to perform the actions required to ensure that the +specified targets are up-to-date. A target is considered out-of-date +if it is older than any of its prerequisites or if it does not exist. +The +.IR make +utility shall treat all prerequisites as targets themselves and +recursively ensure that they are up-to-date, processing them in the +order in which they appear in the rule. The +.IR make +utility shall use the modification times of files to determine whether +the corresponding targets are out-of-date. +.P +After +.IR make +has ensured that all of the prerequisites of a target are up-to-date +and if the target is out-of-date, the commands associated with the +target entry shall be executed. If there are no commands listed for +the target, the target shall be treated as up-to-date. +.SS "Makefile Syntax" +.P +A makefile can contain rules, macro definitions (see +.IR "Macros"), +include lines, and comments. There are two kinds of rules: +.IR "inference rules" +and +.IR "target rules" . +The +.IR make +utility shall contain a set of built-in inference rules. If the +.BR \(mir +option is present, the built-in rules shall not be used and the suffix +list shall be cleared. Additional rules of both types can be specified +in a makefile. If a rule is defined more than once, the value of the +rule shall be that of the last one specified. Macros can also be +defined more than once, and the value of the macro is specified in +.IR "Macros". +Comments start with a + +(\c +.BR '#' ) +and continue until an unescaped + +is reached. +.P +By default, the following files shall be tried in sequence: +.BR ./makefile +and +.BR ./Makefile . +If neither +.BR ./makefile +or +.BR ./Makefile +are found, other implementation-defined files may also be tried. +On XSI-conformant systems, the additional files +.BR ./s.makefile , +.BR SCCS/s.makefile , +.BR ./s.Makefile , +and +.BR SCCS/s.Makefile +shall also be tried. +.P +The +.BR \(mif +option shall direct +.IR make +to ignore any of these default files and use the specified argument as +a makefile instead. If the +.BR '\(mi' +argument is specified, standard input shall be used. +.P +The term +.IR makefile +is used to refer to any rules provided by the user, whether in +.BR ./makefile +or its variants, or specified by the +.BR \(mif +option. +.P +The rules in makefiles shall consist of the following types of lines: +target rules, including special targets (see +.IR "Target Rules"), +inference rules (see +.IR "Inference Rules"), +macro definitions (see +.IR "Macros"), +empty lines, and comments. +.P +Target and Inference Rules may contain +.IR "command lines" . +Command lines can have a prefix that shall be removed before +execution (see +.IR "Makefile Execution"). +.P +When an escaped + +(one preceded by a +) +is found anywhere in the makefile except in a command line, an include +line, or a line immediately preceding an include line, it shall be +replaced, along with any leading white space on the following line, +with a single +. +When an escaped + +is found in a command line in a makefile, the command line shall +contain the +, +the +, +and the next line, except that the first character of the next line +shall not be included if it is a +. +When an escaped + +is found in an include line or in a line immediately preceding an +include line, the behavior is unspecified. +.SS "Include Lines" +.P +If the word +.BR include +appears at the beginning of a line and is followed by one or more + +characters, the string formed by the remainder of the line shall be +processed as follows to produce a pathname: +.IP " *" 4 +The trailing + +and any comment shall be discarded. If the resulting string contains +any double-quote characters (\c +.BR '\&"' ) +the behavior is unspecified. +.IP " *" 4 +The resulting string shall be processed for macro expansion (see +.IR "Macros". +.IP " *" 4 +Any + +characters that appear after the first non-\c + +shall be used as separators to divide the macro-expanded string into +fields. It is unspecified whether any other white-space characters +are also used as separators. It is unspecified whether pathname +expansion (see +.IR "Section 2.13" ", " "Pattern Matching Notation") +is also performed. +.IP " *" 4 +If the processing of separators and optional pathname expansion +results in either zero or two or more non-empty fields, the +behavior is unspecified. If it results in one non-empty field, +that field is taken as the pathname. +.P +If the pathname does not begin with a +.BR '/' +it shall be treated as relative to the current working directory +of the process, not relative to the directory containing the makefile. +If the file does not exist in this location, it is unspecified whether +additional directories are searched. +.P +The contents of the file specified by the pathname shall be read +and processed as if they appeared in the makefile in place of the +include line. If the file ends with an escaped + +the behavior is unspecified. +.P +The file may itself contain further include lines. Implementations +shall support nesting of include files up to a depth of at least 16. +.SS "Makefile Execution" +.P +Makefile command lines shall be processed one at a time. +.P +Makefile command lines can have one or more of the following prefixes: a + +(\c +.BR '-' ), +an at-sign (\c +.BR '@' ), +or a + +(\c +.BR '+' ). +These shall modify the way in which +.IR make +processes the command. +.IP "\fR\(mi\fR" 6 +If the command prefix contains a +, +or the +.BR \(mii +option is present, or the special target +.BR .IGNORE +has either the current target as a prerequisite or has no prerequisites, +any error found while executing the command shall be ignored. +.IP "\fR@\fR" 6 +If the command prefix contains an at-sign and the +.IR make +utility command line +.BR \(min +option is not specified, or the +.BR \(mis +option is present, or the special target +.BR .SILENT +has either the current target as a prerequisite or has no prerequisites, +the command shall not be written to standard output before it is executed. +.IP "\fR+\fR" 6 +If the command prefix contains a +, +this indicates a makefile command line that shall be executed even if +.BR \(min , +.BR \(miq , +or +.BR \(mit +is specified. +.P +An +.IR "execution line" +is built from the command line by removing any prefix characters. Except +as described under the at-sign prefix, the execution line shall be +written to the standard output, optionally preceded by a +. +The execution line shall then be executed by a shell as if it were passed +as the argument to the +\fIsystem\fR() +interface, except that if errors are not being ignored then the shell +.BR \(mie +option shall also be in effect. If errors are being ignored for the +command (as a result of the +.BR \(mii +option, a +.BR '\(mi' +command prefix, or a +.BR .IGNORE +special target), the shell +.BR \(mie +option shall not be in effect. The environment for the command being +executed shall contain all of the variables in the environment of +.IR make . +.P +By default, when +.IR make +receives a non-zero status from the execution of a command, it shall +terminate with an error message to standard error. +.SS "Target Rules" +.P +Target rules are formatted as follows: +.sp +.RS 4 +.nf +\fB +\fItarget \fB[\fItarget\fR...\fB]\fR: \fB[\fIprerequisite\fR...\fB][;\fIcommand\fB] +[\fR\fIcommand\fR +\fIcommand\fR +\&...\fB]\fR +.P +\fIline that does not begin with \fR +.fi \fR +.P +.RE +.P +Target entries are specified by a +-separated, +non-null list of targets, then a +, +then a +-separated, +possibly empty list of prerequisites. Text following a +, +if any, and all following lines that begin with a +, +are makefile command lines to be executed to update the target. The +first non-empty line that does not begin with a + +or +.BR '#' +shall begin a new entry. An empty or blank line, or a line beginning +with +.BR '#' , +may begin a new entry. +.P +Applications shall select target names from the set of characters +consisting solely of periods, underscores, digits, and alphabetics from +the portable character set (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set"). +Implementations may allow other characters in target names as +extensions. The interpretation of targets containing the characters +.BR '%' +and +.BR '\&"' +is implementation-defined. +.P +A target that has prerequisites, but does not have any commands, can be +used to add to the prerequisite list for that target. Only one target +rule for any given target can contain commands. +.P +Lines that begin with one of the following are called +.IR "special targets" +and control the operation of +.IR make : +.IP "\&\fB.DEFAULT\fR" 10 +If the makefile uses this special target, the application shall ensure +that it is specified with commands, but without prerequisites. The +commands shall be used by +.IR make +if there are no other rules available to build a target. +.IP "\&\fB.IGNORE\fR" 10 +Prerequisites of this special target are targets themselves; this shall +cause errors from commands associated with them to be ignored in the +same manner as specified by the +.BR \(mii +option. Subsequent occurrences of +.BR .IGNORE +shall add to the list of targets ignoring command errors. If no +prerequisites are specified, +.IR make +shall behave as if the +.BR \(mii +option had been specified and errors from all commands associated with +all targets shall be ignored. +.IP "\&\fB.POSIX\fR" 10 +The application shall ensure that this special target is specified +without prerequisites or commands. If it appears as the first +non-comment line in the makefile, +.IR make +shall process the makefile as specified by this section; otherwise, the +behavior of +.IR make +is unspecified. +.IP "\&\fB.PRECIOUS\fR" 10 +Prerequisites of this special target shall not be removed if +.IR make +receives one of the asynchronous events explicitly described in the +ASYNCHRONOUS EVENTS section. Subsequent occurrences of +.BR .PRECIOUS +shall add to the list of precious files. If no prerequisites are +specified, all targets in the makefile shall be treated as if specified +with +.BR .PRECIOUS . +.IP "\fB.SCCS_GET\fR" 10 +The application shall ensure that this special target is specified +without prerequisites. If this special target is included in a +makefile, the commands specified with this target shall replace the +default commands associated with this special target (see +.IR "Default Rules"). +The commands specified with this target are used to get all SCCS files +that are not found in the current directory. +.RS 10 +.P +When source files are named in a dependency list, +.IR make +shall treat them just like any other target. Because the source file is +presumed to be present in the directory, there is no need to add an +entry for it to the makefile. When a target has no dependencies, but is +present in the directory, +.IR make +shall assume that that file is up-to-date. If, however, an SCCS file +named +.BR SCCS/s. \c +.IR source_file +is found for a target +.IR source_file , +.IR make +compares the timestamp of the target file with that of the +.BR SCCS/s.source_file +to ensure the target is up-to-date. If the target is missing, or if the +SCCS file is newer, +.IR make +shall automatically issue the commands specified for the +.BR .SCCS_GET +special target to retrieve the most recent version. However, if the +target is writable by anyone, +.IR make +shall not retrieve a new version. +.RE +.IP "\&\fB.SILENT\fR" 10 +Prerequisites of this special target are targets themselves; this shall +cause commands associated with them not to be written to the standard +output before they are executed. Subsequent occurrences of +.BR .SILENT +shall add to the list of targets with silent commands. If no +prerequisites are specified, +.IR make +shall behave as if the +.BR \(mis +option had been specified and no commands or touch messages associated +with any target shall be written to standard output. +.IP "\&\fB.SUFFIXES\fR" 10 +Prerequisites of +.BR .SUFFIXES +shall be appended to the list of known suffixes and are used in +conjunction with the inference rules (see +.IR "Inference Rules"). +If +.BR .SUFFIXES +does not have any prerequisites, the list of known suffixes shall be +cleared. +.P +The special targets +.BR .IGNORE , +.BR .POSIX , +.BR .PRECIOUS , +.BR .SILENT , +and +.BR .SUFFIXES +shall be specified without commands. +.P +Targets with names consisting of a leading + +followed by the uppercase letters +.BR \(dqPOSIX\(dq +and then any other characters are reserved for future standardization. +Targets with names consisting of a leading + +followed by one or more uppercase letters are reserved for implementation +extensions. +.SS "Macros" +.P +Macro definitions are in the form: +.sp +.RS 4 +.nf +\fB +\fIstring1\fR = \fB[\fIstring2\fB]\fR +.fi \fR +.P +.RE +.P +The macro named +.IR string1 +is defined as having the value of +.IR string2 , +where +.IR string2 +is defined as all characters, if any, after the +, +up to a comment character (\c +.BR '#' ) +or an unescaped +. +Any + +characters immediately before or after the + +shall be ignored. +.P +Applications shall select macro names from the set of characters +consisting solely of periods, underscores, digits, and alphabetics from +the portable character set (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set"). +A macro name shall not contain an +. +Implementations may allow other characters in macro names as extensions. +.P +Macros can appear anywhere in the makefile. Macro expansions using +the forms $(\c +.IR string1 ) +or ${\c +.IR string1 } +shall be replaced by +.IR string2 , +as follows: +.IP " *" 4 +Macros in target lines shall be evaluated when the target line is read. +.IP " *" 4 +Macros in makefile command lines shall be evaluated when the command is +executed. +.IP " *" 4 +Macros in the string before the + +in a macro definition shall be evaluated when the macro assignment +is made. +.IP " *" 4 +Macros after the + +in a macro definition shall not be evaluated until the defined macro +is used in a rule or command, or before the + +in a macro definition. +.P +The parentheses or braces are optional if +.IR string1 +is a single character. The macro $$ shall be replaced by the single +character +.BR '$' . +If +.IR string1 +in a macro expansion contains a macro expansion, the results are +unspecified. +.P +Macro expansions using the forms $(\c +.IR string1 \c +.BR [: \c +.IR subst1 \c +.BR =[ \c +.IR subst2 \c +.BR ]] ) +or ${\c +.IR string1 \c +.BR [: \c +.IR subst1 \c +.BR =[ \c +.IR subst2 \c +.BR ]] } +can be used to replace all occurrences of +.IR subst1 +with +.IR subst2 +when the macro substitution is performed. The +.IR subst1 +to be replaced shall be recognized when it is a suffix at the end of a +word in +.IR string1 +(where a +.IR word , +in this context, is defined to be a string delimited by the beginning +of the line, a +, +or a +). +If +.IR string1 +in a macro expansion contains a macro expansion, the results are +unspecified. +.P +Macro expansions in +.IR string1 +of macro definition lines shall be evaluated when read. Macro +expansions in +.IR string2 +of macro definition lines shall be performed when the macro identified +by +.IR string1 +is expanded in a rule or command. +.P +Macro definitions shall be taken from the following sources, in the +following logical order, before the makefile(s) are read. +.IP " 1." 4 +Macros specified on the +.IR make +utility command line, in the order specified on the command line. It is +unspecified whether the internal macros defined in +.IR "Internal Macros" +are accepted from this source. +.IP " 2." 4 +Macros defined by the +.IR MAKEFLAGS +environment variable, in the order specified in the environment +variable. It is unspecified whether the internal macros defined in +.IR "Internal Macros" +are accepted from this source. +.IP " 3." 4 +The contents of the environment, excluding the +.IR MAKEFLAGS +and +.IR SHELL +variables and including the variables with null values. +.IP " 4." 4 +Macros defined in the inference rules built into +.IR make . +.P +Macro definitions from these sources shall not override macro +definitions from a lower-numbered source. Macro definitions from a +single source (for example, the +.IR make +utility command line, the +.IR MAKEFLAGS +environment variable, or the other environment variables) shall +override previous macro definitions from the same source. +.P +Macros defined in the makefile(s) shall override macro definitions that +occur before them in the makefile(s) and macro definitions from source +4. If the +.BR \(mie +option is not specified, macros defined in the makefile(s) shall +override macro definitions from source 3. Macros defined in the +makefile(s) shall not override macro definitions from source 1 or +source 2. +.P +Before the makefile(s) are read, all of the +.IR make +utility command line options (except +.BR \(mif +and +.BR \(mip ) +and +.IR make +utility command line macro definitions (except any for the +.IR MAKEFLAGS +macro), not already included in the +.IR MAKEFLAGS +macro, shall be added to the +.IR MAKEFLAGS +macro, quoted in an implementation-defined manner such that when +.IR MAKEFLAGS +is read by another instance of the +.IR make +command, the original macro's value is recovered. Other +implementation-defined options and macros may also be added to the +.IR MAKEFLAGS +macro. If this modifies the value of the +.IR MAKEFLAGS +macro, or, if the +.IR MAKEFLAGS +macro is modified at any subsequent time, the +.IR MAKEFLAGS +environment variable shall be modified to match the new value of the +.IR MAKEFLAGS +macro. The result of setting +.IR MAKEFLAGS +in the Makefile is unspecified. +.P +Before the makefile(s) are read, all of the +.IR make +utility command line macro definitions (except the +.IR MAKEFLAGS +macro or the +.IR SHELL +macro) shall be added to the environment of +.IR make . +Other implementation-defined variables may also be added to the +environment of +.IR make . +.P +The +.BR SHELL +macro shall be treated specially. It shall be provided by +.IR make +and set to the pathname of the shell command language interpreter (see +.IR "\fIsh\fR\^"). +The +.IR SHELL +environment variable shall not affect the value of the +.BR SHELL +macro. If +.BR SHELL +is defined in the makefile or is specified on the command line, it +shall replace the original value of the +.BR SHELL +macro, but shall not affect the +.IR SHELL +environment variable. Other effects of defining +.BR SHELL +in the makefile or on the command line are implementation-defined. +.SS "Inference Rules" +.P +Inference rules are formatted as follows: +.sp +.RS 4 +.nf +\fB +\fItarget\fR: +\fIcommand +\fB[\fR\fIcommand\fB]\fR +\&... +.P +\fIline that does not begin with \fR\fI or \fR# +.fi \fR +.P +.RE +.P +The application shall ensure that the +.IR target +portion is a valid target name (see +.IR "Target Rules") +of the form +.BR .s2 +or +.BR .s1.s2 +(where +.BR .s1 +and +.BR .s2 +are suffixes that have been given as prerequisites of the +.BR .SUFFIXES +special target and +.IR s1 +and +.IR s2 +do not contain any + +or + +characters.) If there is only one + +in the target, it is a single-suffix inference rule. Targets with two +periods are double-suffix inference rules. Inference rules can have +only one target before the +. +.P +The application shall ensure that the makefile does not specify +prerequisites for inference rules; no characters other than white space +shall follow the + +in the first line, except when creating the +.IR "empty rule," +described below. Prerequisites are inferred, as described below. +.P +Inference rules can be redefined. A target that matches an existing +inference rule shall overwrite the old inference rule. An empty rule +can be created with a command consisting of simply a + +(that is, the rule still exists and is found during inference rule search, +but since it is empty, execution has no effect). The empty rule can also +be formatted as follows: +.sp +.RS 4 +.nf +\fB +\fIrule\fR: ; +.fi \fR +.P +.RE +.P +where zero or more + +characters separate the + +and +. +.P +The +.IR make +utility uses the suffixes of targets and their prerequisites to infer +how a target can be made up-to-date. A list of inference rules defines +the commands to be executed. By default, +.IR make +contains a built-in set of inference rules. Additional rules can be +specified in the makefile. +.P +The special target +.BR .SUFFIXES +contains as its prerequisites a list of suffixes that shall be used by +the inference rules. The order in which the suffixes are specified +defines the order in which the inference rules for the suffixes are +used. New suffixes shall be appended to the current list by specifying +a +.BR .SUFFIXES +special target in the makefile. A +.BR .SUFFIXES +target with no prerequisites shall clear the list of suffixes. An +empty +.BR .SUFFIXES +target followed by a new +.BR .SUFFIXES +list is required to change the order of the suffixes. +.P +Normally, the user would provide an inference rule for each suffix. +The inference rule to update a target with a suffix +.BR .s1 +from a prerequisite with a suffix +.BR .s2 +is specified as a target +.BR .s2.s1 . +The internal macros provide the means to specify general inference +rules (see +.IR "Internal Macros"). +.P +When no target rule is found to update a target, the inference rules +shall be checked. The suffix of the target (\c +.BR .s1 ) +to be built is compared to the list of suffixes specified by the +.BR .SUFFIXES +special targets. If the +.BR .s1 +suffix is found in +.BR .SUFFIXES , +the inference rules shall be searched in the order defined for the +first +.BR .s2.s1 +rule whose prerequisite file (\c +.BR $*.s2 ) +exists. If the target is out-of-date with respect to this +prerequisite, the commands for that inference rule shall be executed. +.P +If the target to be built does not contain a suffix and there is no +rule for the target, the single suffix inference rules shall be +checked. The single-suffix inference rules define how to build a +target if a file is found with a name that matches the target name with +one of the single suffixes appended. A rule with one suffix +.BR .s2 +is the definition of how to build +.IR target +from +.BR target.s2 . +The other suffix (\c +.BR .s1 ) +is treated as null. +.P +A + +(\c +.BR '~' ) +in the above rules refers to an SCCS file in the current directory. +Thus, the rule +.BR .c~.o +would transform an SCCS C-language source file into an object file (\c +.BR .o ). +Because the +.BR s. +of the SCCS files is a prefix, it is incompatible with +.IR make 's +suffix point of view. Hence, the +.BR '~' +is a way of changing any file reference into an SCCS file reference. +.SS "Libraries" +.P +If a target or prerequisite contains parentheses, it shall be treated +as a member of an archive library. For the +.IR lib (\c +.IR member \c +.BR .o ) +expression +.IR lib +refers to the name of the archive library and +.IR member \c +.BR .o +to the member name. The application shall ensure that the member is an +object file with the +.BR .o +suffix. The modification time of the expression is the modification +time for the member as kept in the archive library; see +.IR "\fIar\fR\^". +The +.BR .a +suffix shall refer to an archive library. The +.BR .s2.a +rule shall be used to update a member in the library from a file +with a suffix +.BR .s2 . +.SS "Internal Macros" +.P +The +.IR make +utility shall maintain five internal macros that can be used in target +and inference rules. In order to clearly define the meaning of these +macros, some clarification of the terms +.IR "target rule" , +.IR "inference rule" , +.IR target , +and +.IR prerequisite +is necessary. +.P +Target rules are specified by the user in a makefile for a particular +target. Inference rules are user-specified or +.IR make -specified +rules for a particular class of target name. Explicit prerequisites +are those prerequisites specified in a makefile on target lines. +Implicit prerequisites are those prerequisites that are generated when +inference rules are used. Inference rules are applied to implicit +prerequisites or to explicit prerequisites that do not have target +rules defined for them in the makefile. Target rules are applied to +targets specified in the makefile. +.P +Before any target in the makefile is updated, each of its prerequisites +(both explicit and implicit) shall be updated. This shall be +accomplished by recursively processing each prerequisite. Upon +recursion, each prerequisite shall become a target itself. Its +prerequisites in turn shall be processed recursively until a target is +found that has no prerequisites, at which point the recursion stops. +The recursion shall then back up, updating each target as it goes. +.P +In the definitions that follow, the word +.IR target +refers to one of: +.IP " *" 4 +A target specified in the makefile +.IP " *" 4 +An explicit prerequisite specified in the makefile that becomes the +target when +.IR make +processes it during recursion +.IP " *" 4 +An implicit prerequisite that becomes a target when +.IR make +processes it during recursion +.P +In the definitions that follow, the word +.IR prerequisite +refers to one of the following: +.IP " *" 4 +An explicit prerequisite specified in the makefile for a particular +target +.IP " *" 4 +An implicit prerequisite generated as a result of locating an +appropriate inference rule and corresponding file that matches the +suffix of the target +.P +The five internal macros are: +.IP $@ 8 +The $@ shall evaluate to the full target name of the current target, or +the archive filename part of a library archive target. It shall be +evaluated for both target and inference rules. +.RS 8 +.P +For example, in the +.BR .c.a +inference rule, $@ represents the out-of-date +.BR .a +file to be built. Similarly, in a makefile target rule to build +.BR lib.a +from +.BR file.c , +$@ represents the out-of-date +.BR lib.a . +.RE +.IP $% 8 +The $% macro shall be evaluated only when the current target is an +archive library member of the form +.IR libname (\c +.IR member \c +.BR .o ). +In these cases, $@ shall evaluate to +.IR libname +and $% shall evaluate to +.IR member \c +.BR .o . +The $% macro shall be evaluated for both target and inference rules. +.RS 8 +.P +For example, in a makefile target rule to build +.BR lib.a (\c +.BR file.o ), +$% represents +.BR file.o , +as opposed to $@, which represents +.BR lib.a . +.RE +.IP $? 8 +The $? macro shall evaluate to the list of prerequisites that are +newer than the current target. It shall be evaluated for both target +and inference rules. +.RS 8 +.P +For example, in a makefile target rule to build +.IR prog +from +.BR file1.o , +.BR file2.o , +and +.BR file3.o , +and where +.IR prog +is not out-of-date with respect to +.BR file1.o , +but is out-of-date with respect to +.BR file2.o +and +.BR file3.o , +$? represents +.BR file2.o +and +.BR file3.o . +.RE +.IP $< 8 +In an inference rule, the $< macro shall evaluate to the filename +whose existence allowed the inference rule to be chosen for the target. +In the +.BR .DEFAULT +rule, the $< macro shall evaluate to the current target name. The +meaning of the $< macro shall be otherwise unspecified. +.RS 8 +.P +For example, in the +.BR .c.a +inference rule, $< represents the prerequisite +.BR .c +file. +.RE +.IP $* 8 +The $* macro shall evaluate to the current target name with its suffix +deleted. It shall be evaluated at least for inference rules. +.RS 8 +.P +For example, in the +.BR .c.a +inference rule, $*.o represents the out-of-date +.BR .o +file that corresponds to the prerequisite +.BR .c +file. +.RE +.P +Each of the internal macros has an alternative form. When an uppercase +.BR 'D' +or +.BR 'F' +is appended to any of the macros, the meaning shall be changed to the +.IR "directory part" +for +.BR 'D' +and +.IR "filename part" +for +.BR 'F' . +The directory part is the path prefix of the file without a trailing +; +for the current directory, the directory part is +.BR '.' . +When the $? macro contains more than one prerequisite filename, the +$(?D) and $(?F) (or ${?D} and ${?F}) macros expand to a list of +directory name parts and filename parts respectively. +.P +For the target +.IR lib (\c +.IR member \c +.BR .o ) +and the +.BR s2.a +rule, the internal macros shall be defined as: +.IP $< 8 +.IR member \c +.BR .s2 +.IP $* 8 +.IR member +.IP $@ 8 +.IR lib +.IP $? 8 +.IR member \c +.BR .s2 +.IP $% 8 +.IR member \c +.BR .o +.SS "Default Rules" +.P +The default rules for +.IR make +shall achieve results that are the same as if the following were used. +Implementations that do not support the C-Language Development +Utilities option may omit +.BR CC , +.BR CFLAGS , +.BR YACC , +.BR YFLAGS , +.BR LEX , +.BR LFLAGS , +.BR LDFLAGS , +and the +.BR .c , +.BR .y , +and +.BR .l +inference rules. Implementations that do not support FORTRAN may omit +.BR FC , +.BR FFLAGS , +and the +.BR .f +inference rules. Implementations may provide additional macros and +rules. +.sp +.RS 4 +.nf +\fB +\fISPECIAL TARGETS\fP +.P +\&.SCCS_GET: sccs $(SCCSFLAGS) get $(SCCSGETFLAGS) $@ +.P +\&.SUFFIXES: .o .c .y .l .a .sh .f .c~ .y~ .l~ .sh~ .f~ +.P +.IR MACROS +.P +MAKE=make +AR=ar +ARFLAGS=\(mirv +YACC=yacc +YFLAGS= +LEX=lex +LFLAGS= +LDFLAGS= +CC=c99 +CFLAGS=\(miO +FC=fort77 +FFLAGS=\(miO 1 +GET=get +GFLAGS= +SCCSFLAGS= +SCCSGETFLAGS=\(mis +.P +\fISINGLE SUFFIX RULES\fP +.P +\&.c: + $(CC) $(CFLAGS) $(LDFLAGS) \(mio $@ $< +.P +\&.f: + $(FC) $(FFLAGS) $(LDFLAGS) \(mio $@ $< +.P +\&.sh: + cp $< $@ + chmod a+x $@ +.P +\&.c~: + $(GET) $(GFLAGS) \(mip $< > $*.c + $(CC) $(CFLAGS) $(LDFLAGS) \(mio $@ $*.c +.P +\&.f~: + $(GET) $(GFLAGS) \(mip $< > $*.f + $(FC) $(FFLAGS) $(LDFLAGS) \(mio $@ $*.f +.P +\&.sh~: + $(GET) $(GFLAGS) \(mip $< > $*.sh + cp $*.sh $@ + chmod a+x $@ +.P +\fIDOUBLE SUFFIX RULES\fP +.P +\&.c.o: + $(CC) $(CFLAGS) \(mic $< +.P +\&.f.o: + $(FC) $(FFLAGS) \(mic $< +.P +\&.y.o: + $(YACC) $(YFLAGS) $< + $(CC) $(CFLAGS) \(mic y.tab.c + rm \(mif y.tab.c + mv y.tab.o $@ +.P +\&.l.o: + $(LEX) $(LFLAGS) $< + $(CC) $(CFLAGS) \(mic lex.yy.c + rm \(mif lex.yy.c + mv lex.yy.o $@ +.P +\&.y.c: + $(YACC) $(YFLAGS) $< + mv y.tab.c $@ +.P +\&.l.c: + $(LEX) $(LFLAGS) $< + mv lex.yy.c $@ +.P +\&.c~.o: + $(GET) $(GFLAGS) \(mip $< > $*.c + $(CC) $(CFLAGS) \(mic $*.c +.P +\&.f~.o: + $(GET) $(GFLAGS) \(mip $< > $*.f + $(FC) $(FFLAGS) \(mic $*.f +.P +\&.y~.o: + $(GET) $(GFLAGS) \(mip $< > $*.y + $(YACC) $(YFLAGS) $*.y + $(CC) $(CFLAGS) \(mic y.tab.c + rm \(mif y.tab.c + mv y.tab.o $@ +.P +\&.l~.o: + $(GET) $(GFLAGS) \(mip $< > $*.l + $(LEX) $(LFLAGS) $*.l + $(CC) $(CFLAGS) \(mic lex.yy.c + rm \(mif lex.yy.c + mv lex.yy.o $@ +.P +\&.y~.c: + $(GET) $(GFLAGS) \(mip $< > $*.y + $(YACC) $(YFLAGS) $*.y + mv y.tab.c $@ +.P +\&.l~.c: + $(GET) $(GFLAGS) \(mip $< > $*.l + $(LEX) $(LFLAGS) $*.l + mv lex.yy.c $@ +.P +\&.c.a: + $(CC) \(mic $(CFLAGS) $< + $(AR) $(ARFLAGS) $@ $*.o + rm \(mif $*.o +.P +\&.f.a: + $(FC) \(mic $(FFLAGS) $< + $(AR) $(ARFLAGS) $@ $*.o + rm \(mif $*.o +.fi \fR +.P +.RE +.SH "EXIT STATUS" +When the +.BR \(miq +option is specified, the +.IR make +utility shall exit with one of the following values: +.IP "\00" 6 +Successful completion. +.IP "\01" 6 +The target was not up-to-date. +.IP >1 6 +An error occurred. +.P +When the +.BR \(miq +option is not specified, the +.IR make +utility shall exit with one of the following values: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +If there is a source file (such as +.BR ./source.c ) +and there are two SCCS files corresponding to it (\c +.BR ./s.source.c +and +.BR ./SCCS/s.source.c ), +on XSI-conformant systems +.IR make +uses the SCCS file in the current directory. However, users are +advised to use the underlying SCCS utilities (\c +.IR admin , +.IR delta , +.IR get , +and so on) or the +.IR sccs +utility for all source files in a given directory. If both forms are +used for a given source file, future developers are very likely to be +confused. +.P +It is incumbent upon portable makefiles to specify the +.BR .POSIX +special target in order to guarantee that they are not affected by +local extensions. +.P +The +.BR \(mik +and +.BR \(miS +options are both present so that the relationship between the command +line, the +.IR MAKEFLAGS +variable, and the makefile can be controlled precisely. If the +.BR k +flag is passed in +.IR MAKEFLAGS +and a command is of the form: +.sp +.RS 4 +.nf +\fB +$(MAKE) \(miS foo +.fi \fR +.P +.RE +.P +then the default behavior is restored for the child +.IR make . +.P +When the +.BR \(min +option is specified, it is always added to +.IR MAKEFLAGS . +This allows a recursive +.IR make +.BR \(min +.IR target +to be used to see all of the action that would be taken to update +.IR target . +.P +Because of widespread historical practice, interpreting a + +(\c +.BR '#' ) +inside a variable as the start of a comment has the unfortunate +side-effect of making it impossible to place a + +in a variable, thus forbidding something like: +.sp +.RS 4 +.nf +\fB +CFLAGS = "\(miD COMMENT_CHAR='#'" +.fi \fR +.P +.RE +.P +Many historical +.IR make +utilities stop chaining together inference rules when an intermediate +target is nonexistent. For example, it might be possible for a +.IR make +to determine that both +.BR .y.c +and +.BR .c.o +could be used to convert a +.BR .y +to a +.BR .o . +Instead, in this case, +.IR make +requires the use of a +.BR .y.o +rule. +.P +The best way to provide portable makefiles is to include all of the +rules needed in the makefile itself. The rules provided use only +features provided by other parts of this volume of POSIX.1\(hy2008. The default rules include +rules for optional commands in this volume of POSIX.1\(hy2008. Only rules pertaining to commands +that are provided are needed in an implementation's default set. +.P +Macros used within other macros are evaluated when the new macro is +used rather than when the new macro is defined. Therefore: +.sp +.RS 4 +.nf +\fB +MACRO = \fIvalue1\fP +NEW = $(MACRO) +MACRO = \fIvalue2\fP +.P +target: + echo $(NEW) +.fi \fR +.P +.RE +.P +would produce +.IR value2 +and not +.IR value1 +since +.BR NEW +was not expanded until it was needed in the +.IR echo +command line. +.P +Some historical applications have been known to intermix +.IR target_name +and +.IR macro=name +operands on the command line, expecting that all of the macros are +processed before any of the targets are dealt with. Conforming +applications do not do this, although some backwards-compatibility +support may be included in some implementations. +.P +The following characters in filenames may give trouble: +.BR '=' , +.BR ':' , +.BR '`' , +single-quote, and +.BR '@' . +In include filenames, pattern matching characters and +.BR '\&"' +should also be avoided, as they may be treated as special by some +implementations. +.P +For inference rules, the description of $< and $? seem similar. However, +an example shows the minor difference. In a makefile containing: +.sp +.RS 4 +.nf +\fB +foo.o: foo.h +.fi \fR +.P +.RE +.P +if +.BR foo.h +is newer than +.BR foo.o , +yet +.BR foo.c +is older than +.BR foo.o , +the built-in rule to make +.BR foo.o +from +.BR foo.c +is used, with $< equal to +.BR foo.c +and $? equal to +.BR foo.h . +If +.BR foo.c +is also newer than +.BR foo.o , +$< is equal to +.BR foo.c +and $? is equal to +.BR "foo.h foo.c" . +.SH EXAMPLES +.IP " 1." 4 +The following command: +.RS 4 +.sp +.RS 4 +.nf +\fB +make +.fi \fR +.P +.RE +.P +makes the first target found in the makefile. +.RE +.IP " 2." 4 +The following command: +.RS 4 +.sp +.RS 4 +.nf +\fB +make junk +.fi \fR +.P +.RE +.P +makes the target +.BR junk . +.RE +.IP " 3." 4 +The following makefile says that +.BR pgm +depends on two files, +.BR a.o +and +.BR b.o , +and that they in turn depend on their corresponding source files (\c +.BR a.c +and +.BR b.c ), +and a common file +.BR incl.h : +.RS 4 +.sp +.RS 4 +.nf +\fB +pgm: a.o b.o + c99 a.o b.o \(mio pgm +a.o: incl.h a.c + c99 \(mic a.c +b.o: incl.h b.c + c99 \(mic b.c +.fi \fR +.P +.RE +.RE +.IP " 4." 4 +An example for making optimized +.BR .o +files from +.BR .c +files is: +.RS 4 +.sp +.RS 4 +.nf +\fB +\&.c.o: + c99 \(mic \(miO $*.c +.fi \fR +.P +.RE +.P +or: +.sp +.RS 4 +.nf +\fB +\&.c.o: + c99 \(mic \(miO $< +.fi \fR +.P +.RE +.RE +.IP " 5." 4 +The most common use of the archive interface follows. Here, it is +assumed that the source files are all C-language source: +.RS 4 +.sp +.RS 4 +.nf +\fB +lib: lib(file1.o) lib(file2.o) lib(file3.o) + @echo lib is now up-to-date +.fi \fR +.P +.RE +.P +The +.BR .c.a +rule is used to make +.BR file1.o , +.BR file2.o , +and +.BR file3.o +and insert them into +.BR lib . +.P +The treatment of escaped + +characters throughout the makefile is historical practice. For example, +the inference rule: +.sp +.RS 4 +.nf +\fB +\&.c.o\e +: +.fi \fR +.P +.RE +.P +works, and the macro: +.sp +.RS 4 +.nf +\fB +f= bar baz\e + biz +a: + echo ==$f== +.fi \fR +.P +.RE +.P +echoes +.BR \(dq==bar\ baz\ biz==\(dq . +.P +If $? were: +.sp +.RS 4 +.nf +\fB +/usr/include/stdio.h /usr/include/unistd.h foo.h +.fi \fR +.P +.RE +.P +then $(?D) would be: +.sp +.RS 4 +.nf +\fB +/usr/include /usr/include . +.fi \fR +.P +.RE +.P +and $(?F) would be: +.sp +.RS 4 +.nf +\fB +stdio.h unistd.h foo.h +.fi \fR +.P +.RE +.RE +.IP " 6." 4 +The contents of the built-in rules can be viewed by running: +.RS 4 +.sp +.RS 4 +.nf +\fB +make \(mip \(mif /dev/null 2>/dev/null +.fi \fR +.P +.RE +.RE +.SH RATIONALE +The +.IR make +utility described in this volume of POSIX.1\(hy2008 is intended to provide the means for +changing portable source code into executables that can be run on an +POSIX.1\(hy2008-conforming system. It reflects the most common features present +in System V and BSD +.IR make s. +.P +Historically, the +.IR make +utility has been an especially fertile ground for vendor and research +organization-specific syntax modifications and extensions. Examples +include: +.IP " *" 4 +Syntax supporting parallel execution (such as from various +multi-processor vendors, GNU, and others) +.IP " *" 4 +Additional ``operators'' separating targets and their prerequisites +(System V, BSD, and others) +.IP " *" 4 +Specifying that command lines containing the strings +.BR \(dq${MAKE}\(dq +and +.BR \(dq$(MAKE)\(dq +are executed when the +.BR \(min +option is specified (GNU and System V) +.IP " *" 4 +Modifications of the meaning of internal macros when referencing +libraries (BSD and others) +.IP " *" 4 +Using a single instance of the shell for all of the command lines of +the target (BSD and others) +.IP " *" 4 +Allowing + +characters as well as + +characters to delimit command lines (BSD) +.IP " *" 4 +Adding C preprocessor-style ``include'' and ``ifdef'' constructs +(System V, GNU, BSD, and others) +.IP " *" 4 +Remote execution of command lines (Sprite and others) +.IP " *" 4 +Specifying additional special targets (BSD, System V, and most others) +.P +Additionally, many vendors and research organizations have rethought +the basic concepts of +.IR make , +creating vastly extended, as well as completely new, syntaxes. Each of +these versions of +.IR make +fulfills the needs of a different community of users; it is +unreasonable for this volume of POSIX.1\(hy2008 to require behavior that would be incompatible +(and probably inferior) to historical practice for such a community. +.P +In similar circumstances, when the industry has enough sufficiently +incompatible formats as to make them irreconcilable, this volume of POSIX.1\(hy2008 has followed +one or both of two courses of action. Commands have been renamed (\c +.IR cksum , +.IR echo , +and +.IR pax ) +and/or command line options have been provided to select the desired +behavior (\c +.IR grep , +.IR od , +and +.IR pax ). +.P +Because the syntax specified for the +.IR make +utility is, by and large, a subset of the syntaxes accepted by almost +all versions of +.IR make , +it was decided that it would be counter-productive to change the name. +And since the makefile itself is a basic unit of portability, it would +not be completely effective to reserve a new option letter, such as +.IR make +.BR \(miP , +to achieve the portable behavior. Therefore, the special target +.BR .POSIX +was added to the makefile, allowing users to specify ``standard'' +behavior. This special target does not preclude extensions in the +.IR make +utility, nor does it preclude such extensions being used by the +makefile specifying the target; it does, however, preclude any +extensions from being applied that could alter the behavior of +previously valid syntax; such extensions must be controlled via +command line options or new special targets. It is incumbent upon +portable makefiles to specify the +.BR .POSIX +special target in order to guarantee that they are not affected by +local extensions. +.P +The portable version of +.IR make +described in this reference page is not intended to be the +state-of-the-art software generation tool and, as such, some newer and +more leading-edge features have not been included. An attempt has been +made to describe the portable makefile in a manner that does not +preclude such extensions as long as they do not disturb the portable +behavior described here. +.P +When the +.BR \(min +option is specified, it is always added to +.IR MAKEFLAGS . +This allows a recursive +.IR make +.BR \(min +.IR target +to be used to see all of the action that would be taken to update +.IR target . +.P +The definition of +.IR MAKEFLAGS +allows both the System V letter string and the BSD command line +formats. The two formats are sufficiently different to allow +implementations to support both without ambiguity. +.P +Early proposals stated that an ``unquoted'' + +was treated as the start of a comment. The +.IR make +utility does not pay any attention to quotes. A + +starts a comment regardless of its surroundings. +.P +The text about ``other implementation-defined pathnames may also be +tried'' in addition to +.BR ./makefile +and +.BR ./Makefile +is to allow such extensions as +.BR SCCS/s.Makefile +and other variations. It was made an implementation-defined +requirement (as opposed to unspecified behavior) to highlight +surprising implementations that might select something unexpected like +.BR /etc/Makefile . +XSI-conformant systems also try +.BR ./s.makefile , +.BR SCCS/s.makefile , +.BR ./s.Makefile , +and +.BR SCCS/s.Makefile . +.P +Early proposals contained the macro +.BR NPROC +as a means of specifying that +.IR make +should use +.IR n +processes to do the work required. While this feature is a valuable +extension for many systems, it is not common usage and could require +other non-trivial extensions to makefile syntax. This extension is not +required by this volume of POSIX.1\(hy2008, but could be provided as a compatible extension. The +macro +.BR PARALLEL +is used by some historical systems with essentially the same meaning +(but without using a name that is a common system limit value). It is +suggested that implementors recognize the existing use of +.BR NPROC +and/or +.BR PARALLEL +as extensions to +.IR make . +.P +The default rules are based on System V. The default +.BR CC= +value is +.IR c99 +instead of +.IR cc +because this volume of POSIX.1\(hy2008 does not standardize the utility named +.IR cc . +Thus, every conforming application would be required to define +.BR CC= \c +.IR c99 +to expect to run. There is no advantage conferred by the hope that the +makefile might hit the ``preferred'' compiler because this cannot be +guaranteed to work. Also, since the portable makescript can only use +the +.IR c99 +options, no advantage is conferred in terms of what the script can do. +It is a quality-of-implementation issue as to whether +.IR c99 +is as valuable as +.IR cc . +.P +The +.BR \(mid +option to +.IR make +is frequently used to produce debugging information, but is too +implementation-defined to add to this volume of POSIX.1\(hy2008. +.P +The +.BR \(mip +option is not passed in +.IR MAKEFLAGS +on most historical implementations and to change this would cause many +implementations to break without sufficiently increased portability. +.P +Commands that begin with a + +(\c +.BR '\(pl' ) +are executed even if the +.BR \(min +option is present. Based on the GNU version of +.IR make , +the behavior of +.BR \(min +when the + +prefix is encountered has been extended to apply to +.BR \(miq +and +.BR \(mit +as well. However, the System V convention of forcing command execution +with +.BR \(min +when the command line of a target contains either of the strings +.BR \(dq$(MAKE)\(dq +or +.BR \(dq${MAKE}\(dq +has not been adopted. This functionality appeared in early proposals, +but the danger of this approach was pointed out with the following +example of a portion of a makefile: +.sp +.RS 4 +.nf +\fB +subdir: + cd subdir; rm all_the_files; $(MAKE) +.fi \fR +.P +.RE +.P +The loss of the System V behavior in this case is well-balanced by the +safety afforded to other makefiles that were not aware of this +situation. In any event, the command line + +prefix can provide the desired functionality. +.P +The double + +in the target rule format is supported in BSD systems to allow more +than one target line containing the same target name to have commands +associated with it. Since this is not functionality described in the +SVID or XPG3 it has been allowed as an extension, but not mandated. +.P +The default rules are provided with text specifying that the built-in +rules shall be the same as if the listed set were used. The intent is +that implementations should be able to use the rules without change, +but will be allowed to alter them in ways that do not affect the +primary behavior. +.P +The best way to provide portable makefiles is to include all of the +rules needed in the makefile itself. The rules provided use only +features provided by other portions of this volume of POSIX.1\(hy2008. The default rules include +rules for optional commands in this volume of POSIX.1\(hy2008. Only rules pertaining to commands +that are provided are needed in the default set of an implementation. +.P +One point of discussion was whether to drop the default rules list from +\&this volume of POSIX.1\(hy2008. They provide convenience, but do not enhance portability of +applications. The prime benefit is in portability of users who wish to +type +.IR make +.IR command +and have the command build from a +.BR command.c +file. +.P +The historical +.IR MAKESHELL +feature was omitted. In some implementations it is used to let a user +override the shell to be used to run +.IR make +commands. This was confusing; for a portable +.IR make , +the shell should be chosen by the makefile writer or specified on the +.IR make +command line and not by a user running +.IR make . +.P +The +.IR make +utilities in most historical implementations process the prerequisites +of a target in left-to-right order, and the makefile format +requires this. It supports the standard idiom used in many makefiles +that produce +.IR yacc +programs; for example: +.sp +.RS 4 +.nf +\fB +foo: y.tab.o lex.o main.o + $(CC) $(CFLAGS) \(mio $\fR@\fP t.tab.o lex.o main.o +.fi \fR +.P +.RE +.P +In this example, if +.IR make +chose any arbitrary order, the +.BR lex.o +might not be made with the correct +.BR y.tab.h . +Although there may be better ways to express this relationship, it is +widely used historically. Implementations that desire to update +prerequisites in parallel should require an explicit extension to +.IR make +or the makefile format to accomplish it, as described previously. +.P +The algorithm for determining a new entry for target rules is partially +unspecified. Some historical +.IR make s +allow blank, empty, or comment lines within the collection of commands +marked by leading + +characters. A conforming makefile must ensure that each command starts +with a +, +but implementations are free to ignore blank, empty, and comment lines +without triggering the start of a new entry. +.P +The ASYNCHRONOUS EVENTS section includes having SIGTERM and SIGHUP, +along with the more traditional SIGINT and SIGQUIT, remove the current +target unless directed not to do so. SIGTERM and SIGHUP were added to +parallel other utilities that have historically cleaned up their work +as a result of these signals. When +.IR make +receives any signal other than SIGQUIT, it is required to resend itself +the signal it received so that it exits with a status that reflects the +signal. The results from SIGQUIT are partially unspecified because, on +systems that create +.BR core +files upon receipt of SIGQUIT, the +.BR core +from +.IR make +would conflict with a +.BR core +file from the command that was running when the SIGQUIT arrived. The +main concern was to prevent damaged files from appearing up-to-date when +.IR make +is rerun. +.P +The +.BR .PRECIOUS +special target was extended to affect all targets globally (by +specifying no prerequisites). The +.BR .IGNORE +and +.BR .SILENT +special targets were extended to allow prerequisites; it was judged to +be more useful in some cases to be able to turn off errors or echoing +for a list of targets than for the entire makefile. These extensions +to +.IR make +in System V were made to match historical practice from the BSD +.IR make . +.P +Macros are not exported to the environment of commands to be run. This +was never the case in any historical +.IR make +and would have serious consequences. The environment is the same as +the environment to +.IR make +except that +.IR MAKEFLAGS +and macros defined on the +.IR make +command line are added. +.P +Some implementations do not use +\fIsystem\fR() +for all command lines, as required by the portable makefile +format; as a performance enhancement, they select lines without shell +metacharacters for direct execution by +\fIexecve\fR(). +There is no requirement that +\fIsystem\fR() +be used specifically, but merely that the same results be achieved. +The metacharacters typically used to bypass the direct +\fIexecve\fR() +execution have been any of: +.sp +.RS 4 +.nf +\fB += | ^ ( ) ; & < > * ? [ ] : $ ` ' " \e \en +.fi \fR +.P +.RE +.P +The default in some advanced versions of +.IR make +is to group all the command lines for a target and execute them using a +single shell invocation; the System V method is to pass each line +individually to a separate shell. The single-shell method has the +advantages in performance and the lack of a requirement for many +continued lines. However, converting to this newer method has caused +portability problems with many historical makefiles, so the behavior +with the POSIX makefile is specified to be the same as that of System +V. It is suggested that the special target +.BR .ONESHELL +be used as an implementation extension to achieve the single-shell +grouping for a target or group of targets. +.P +Novice users of +.IR make +have had difficulty with the historical need to start commands with a +. +Since it is often difficult to discern differences between + +and + +characters on terminals or printed listings, confusing bugs can arise. In +early proposals, an attempt was made to correct this problem by allowing +leading + +characters instead of + +characters. However, implementors reported many makefiles that failed +in subtle ways following this change, and it is difficult to implement a +.IR make +that unambiguously can differentiate between macro and command lines. +There is extensive historical practice of allowing leading + +characters before macro definitions. Forcing macro lines into column 1 +would be a significant backwards-compatibility problem for some makefiles. +Therefore, historical practice was restored. +.P +There is substantial variation in the handling of include lines by +different implementations. However, there is enough commonality for the +standard to be able to specify a minimum set of requirements that allow +the feature to be used portably. Known variations have been explicitly +called out as unspecified behavior in the description. +.P +The System V dynamic dependency feature was not included. It would +support: +.sp +.RS 4 +.nf +\fB +cat: $$@.c +.fi \fR +.P +.RE +.P +that would expand to; +.sp +.RS 4 +.nf +\fB +cat: cat.c +.fi \fR +.P +.RE +.P +This feature exists only in the new version of System V +.IR make +and, while useful, is not in wide usage. This means that macros are +expanded twice for prerequisites: once at makefile parse time and once +at target update time. +.P +Consideration was given to adding metarules to the POSIX +.IR make . +This would make +.BR "%.o:\ %.c" +the same as +.BR .c.o: . +This is quite useful and available from some vendors, but it would +cause too many changes to this +.IR make +to support. It would have introduced rule chaining and new substitution +rules. However, the rules for target names have been set to reserve the +.BR '%' +and +.BR '\&"' +characters. These are traditionally used to implement metarules and +quoting of target names, respectively. Implementors are strongly +encouraged to use these characters only for these purposes. +.P +A request was made to extend the suffix delimiter character from a + +to any character. The metarules feature in newer +.IR make s +solves this problem in a more general way. This volume of POSIX.1\(hy2008 is staying with the +more conservative historical definition. +.P +The standard output format for the +.BR \(mip +option is not described because it is primarily a debugging option and +because the format is not generally useful to programs. In historical +implementations the output is not suitable for use in generating +makefiles. The +.BR \(mip +format has been variable across historical implementations. Therefore, +the definition of +.BR \(mip +was only to provide a consistently named option for obtaining +.IR make +script debugging information. +.P +Some historical implementations have not cleared the suffix list with +.BR \(mir . +.P +Implementations should be aware that some historical applications have +intermixed +.IR target_name +and +.IR macro =\c +.IR value +operands on the command line, expecting that all of the macros are +processed before any of the targets are dealt with. Conforming +applications do not do this, but some backwards-compatibility support +may be warranted. +.P +Empty inference rules are specified with a + +command rather than omitting all commands, as described in an early +proposal. The latter case has no traditional meaning and is reserved +for implementation extensions, such as in GNU +.IR make . +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIar\fR\^", +.IR "\fIc99\fR\^", +.IR "\fIget\fR\^", +.IR "\fIlex\fR\^", +.IR "\fIsccs\fR\^", +.IR "\fIsh\fR\^", +.IR "\fIyacc\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIexec\fR\^", +.IR "\fIsystem\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/man.1p b/man-pages-posix-2013/man1p/man.1p new file mode 100644 index 0000000..ee4ba2b --- /dev/null +++ b/man-pages-posix-2013/man1p/man.1p @@ -0,0 +1,267 @@ +'\" et +.TH MAN "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +man +\(em display system documentation +.SH SYNOPSIS +.LP +.nf +man \fB[\fR\(mik\fB] \fIname\fR... +.fi +.SH DESCRIPTION +The +.IR man +utility shall write information about each of the +.IR name +operands. If +.IR name +is the name of a standard utility, +.IR man +at a minimum shall write a message describing the syntax used by the +standard utility, its options, and operands. If more information is +available, the +.IR man +utility shall provide it in an implementation-defined manner. +.P +An implementation may provide information for values of +.IR name +other than the standard utilities. Standard utilities that are listed +as optional and that are not supported by the implementation either +shall cause a brief message indicating that fact to be displayed or +shall cause a full display of information as described previously. +.SH OPTIONS +The +.IR man +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(mik\fP" 8 +Interpret +.IR name +operands as keywords to be used in searching a utilities summary +database that contains a brief purpose entry for each standard utility +and write lines from the summary database that match any of the +keywords. The keyword search shall produce results that are the +equivalent of the output of the following command: +.RS 8 +.sp +.RS 4 +.nf +\fB +grep \(miEi ' +\fIname +name\fP +\&... +\&' \fIsummary-database\fR +.fi \fR +.P +.RE +.P +This assumes that the +.IR summary-database +is a text file with a single entry per line; this organization is not +required and the example using +.IR grep +.BR \(miEi +is merely illustrative of the type of search intended. The purpose +entry to be included in the database shall consist of a terse +description of the purpose of the utility. +.RE +.SH OPERANDS +The following operand shall be supported: +.IP "\fIname\fR" 10 +A keyword or the name of a standard utility. When +.BR \(mik +is not specified and +.IR name +does not represent one of the standard utilities, the results are +unspecified. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR man : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and in the summary database). The +value of +.IR LC_CTYPE +need not affect the format of the information written about the +.IR name +operands. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPAGER\fP" 10 +Determine an output filtering command for writing the output to a +terminal. Any string acceptable as a +.IR command_string +operand to the +.IR sh +.BR \(mic +command shall be valid. When standard output is a terminal device, the +reference page output shall be piped through the command. If the +.IR PAGER +variable is null or not set, the command shall be either +.IR more +or another paginator utility documented in the system documentation. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR man +utility shall write text describing the syntax of the utility +.IR name , +its options and its operands, or, when +.BR \(mik +is specified, lines from the summary database. The format of this text +is implementation-defined. +.SH STDERR +The standard error shall be used for diagnostic messages, and may also +be used for informational messages of unspecified format. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +It is recognized that the +.IR man +utility is only of minimal usefulness as specified. The opinion of the +standard developers was strongly divided as to how much or how little +information +.IR man +should be required to provide. They considered, however, that the +provision of some portable way of accessing documentation would aid +user portability. The arguments against a fuller specification were: +.IP " *" 4 +Large quantities of documentation should not be required on a system +that does not have excess disk space. +.IP " *" 4 +The current manual system does not present information in a manner that +greatly aids user portability. +.IP " *" 4 +A ``better help system'' is currently an area in which vendors feel +that they can add value to their POSIX implementations. +.P +The +.BR \(mif +option was considered, but due to implementation differences, it was +not included in this volume of POSIX.1\(hy2008. +.P +The description was changed to be more specific about what has to be +displayed for a utility. The standard developers considered it +insufficient to allow a display of only the synopsis without giving a +short description of what each option and operand does. +.P +The ``purpose'' entry to be included in the database can be similar to +the section title (less the numeric prefix) from this volume of POSIX.1\(hy2008 for each utility. +These titles are similar to those used in historical systems for this +purpose. +.P +See +.IR mailx +for rationale concerning the default paginator. +.P +The caveat in the +.IR LC_CTYPE +description was added because it is not a requirement that an +implementation provide reference pages for all of its supported locales +on each system; changing +.IR LC_CTYPE +does not necessarily translate the reference page into another +language. This is equivalent to the current state of +.IR LC_MESSAGES +in POSIX.1\(hy2008\(emlocale-specific messages are not yet a requirement. +.P +The historical +.IR MANPATH +variable is not included in POSIX because no attempt is made to specify +naming conventions for reference page files, nor even to mandate that +they are files at all. On some implementations they could be a true +database, a hypertext file, or even fixed strings within the +.IR man +executable. The standard developers considered the portability of +reference pages to be outside their scope of work. However, users +should be aware that +.IR MANPATH +is implemented on a number of historical systems and that it can be +used to tailor the search pattern for reference pages from the various +categories (utilities, functions, file formats, and so on) when the +system administrator reveals the location and conventions for reference +pages on the system. +.P +The keyword search can rely on at least the text of the section titles +from these utility descriptions, and the implementation may add more +keywords. The term ``section titles'' refers to the strings such as: +.sp +.RS 4 +.nf +\fB +man \(em Display system documentation +ps \(em Report process status +.fi \fR +.P +.RE +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImore\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/mesg.1p b/man-pages-posix-2013/man1p/mesg.1p new file mode 100644 index 0000000..89ba318 --- /dev/null +++ b/man-pages-posix-2013/man1p/mesg.1p @@ -0,0 +1,167 @@ +'\" et +.TH MESG "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mesg +\(em permit or deny messages +.SH SYNOPSIS +.LP +.nf +mesg \fB[\fRy|n\fB]\fR +.fi +.SH DESCRIPTION +The +.IR mesg +utility shall control whether other users are allowed to send messages +via +.IR write , +.IR talk , +or other utilities to a terminal device. The terminal device affected +shall be determined by searching for the first terminal in the sequence +of devices associated with standard input, standard output, and +standard error, respectively. With no arguments, +.IR mesg +shall report the current state without changing it. Processes with +appropriate privileges may be able to send messages to the terminal +independent of the current state. +.SH OPTIONS +None. +.SH OPERANDS +The following operands shall be supported in the POSIX locale: +.IP "\fIy\fR" 10 +Grant permission to other users to send messages to the terminal +device. +.IP "\fIn\fR" 10 +Deny permission to other users to send messages to the terminal +device. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR mesg : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written (by +.IR mesg ) +to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If no operand is specified, +.IR mesg +shall display the current terminal state in an unspecified format. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Receiving messages is allowed. +.IP "\01" 6 +Receiving messages is not allowed. +.IP >1 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The mechanism by which the message status of the terminal is changed is +unspecified. Therefore, unspecified actions may cause the status of +the terminal to change after +.IR mesg +has successfully completed. These actions may include, but are not +limited to: another invocation of the +.IR mesg +utility, login procedures; invocation of the +.IR stty +utility, invocation of the +.IR chmod +utility or +\fIchmod\fR() +function, and so on. +.SH EXAMPLES +None. +.SH RATIONALE +The terminal changed by +.IR mesg +is that associated with the standard input, output, or error, rather +than the controlling terminal for the session. This is because users +logged in more than once should be able to change any of their login +terminals without having to stop the job running in those sessions. +This is not a security problem involving the terminals of other users +because appropriate privileges would +be required to affect the terminal of another user. +.P +The method of checking each of the first three file descriptors in +sequence until a terminal is found was adopted from System V. +.P +The file +.BR /dev/tty +is not specified for the terminal device because it was thought to be +too restrictive. Typical environment changes for the +.IR n +operand are that write permissions are removed for +.IR others +and +.IR group +from the appropriate device. It was decided to leave the actual +description of what is done as unspecified because of potential +differences between implementations. +.P +The format for standard output is unspecified because of differences +between historical implementations. This output is generally not +useful to shell scripts (they can use the exit status), so exact +parsing of the output is unnecessary. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fItalk\fR\^", +.IR "\fIwrite\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/mkdir.1p b/man-pages-posix-2013/man1p/mkdir.1p new file mode 100644 index 0000000..51a773f --- /dev/null +++ b/man-pages-posix-2013/man1p/mkdir.1p @@ -0,0 +1,261 @@ +'\" et +.TH MKDIR "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\(em make directories +.SH SYNOPSIS +.LP +.nf +mkdir \fB[\fR\(mip\fB] [\fR\(mim \fImode\fB] \fIdir\fR... +.fi +.SH DESCRIPTION +The +.IR mkdir +utility shall create the directories specified by the operands, in the +order specified. +.P +For each +.IR dir +operand, the +.IR mkdir +utility shall perform actions equivalent to the +\fImkdir\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008, called with the following arguments: +.IP " 1." 4 +The +.IR dir +operand is used as the +.IR path +argument. +.IP " 2." 4 +The value of the bitwise-inclusive OR of S_IRWXU, S_IRWXG, and S_IRWXO +is used as the +.IR mode +argument. (If the +.BR \(mim +option is specified, the value of the +\fImkdir\fR() +.IR mode +argument is unspecified, but the directory shall at no time +have permissions less restrictive than the +.BR \(mim +.IR mode +option-argument.) +.SH OPTIONS +The +.IR mkdir +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mim\ \fImode\fR" 10 +Set the file permission bits of the newly-created directory to the +specified +.IR mode +value. The +.IR mode +option-argument shall be the same as the +.IR mode +operand defined for the +.IR chmod +utility. In the +.IR symbolic_mode +strings, the +.IR op +characters +.BR '\(pl' +and +.BR '\(mi' +shall be interpreted relative to an assumed initial mode of +.IR a =\c +.IR rwx ; +.BR '\(pl' +shall add permissions to the default mode, +.BR '\(mi' +shall delete permissions from the default mode. +.IP "\fB\(mip\fP" 10 +Create any missing intermediate pathname components. +.RS 10 +.P +For each +.IR dir +operand that does not name an existing directory, before performing the +actions described in the DESCRIPTION above, the +.IR mkdir +utility shall create any pathname components of the path prefix of +.IR dir +that do not name an existing directory by performing actions equivalent +to first calling the +\fImkdir\fR() +function with the following arguments: +.IP " 1." 4 +A pathname naming the missing pathname component, ending with a trailing + +character, as the +.IR path +argument +.IP " 2." 4 +The value zero as the +.IR mode +argument +.P +and then calling the +\fIchmod\fR() +function with the following arguments: +.IP " 1." 4 +The same +.IR path +argument as in the +\fImkdir\fR() +call +.IP " 2." 4 +The value +.IR "(S_IWUSR|S_IXUSR|~\fIfilemask\fP)&0777" \fR +as the +.IR mode +argument, where +.IR filemask +is the file mode creation mask of the process (see the System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIumask\fR\^(\|)") +.P +Each +.IR dir +operand that names an existing directory shall be ignored without +error. +.RE +.SH OPERANDS +The following operand shall be supported: +.IP "\fIdir\fR" 10 +A pathname of a directory to be created. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR mkdir : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All the specified directories were created successfully or the +.BR \(mip +option was specified and all the specified directories now exist. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The default file mode for directories is +.IR a =\c +.IR rwx +(777 on most systems) with selected permissions removed in accordance +with the file mode creation mask. For intermediate pathname components +created by +.IR mkdir , +the mode is the default modified by +.IR u +\c +.IR wx +so that the subdirectories can always be created regardless of the file +mode creation mask; if different ultimate permissions are desired for +the intermediate directories, they can be changed afterwards with +.IR chmod . +.P +Note that some of the requested directories may have been created even +if an error occurs. +.SH EXAMPLES +None. +.SH RATIONALE +The System V +.BR \(mim +option was included to control the file mode. +.P +The System V +.BR \(mip +option was included to create any needed intermediate directories and +to complement the functionality provided by +.IR rmdir +for removing directories in the path prefix as they become empty. +Because no error is produced if any path component already exists, the +.BR \(mip +option is also useful to ensure that a particular directory exists. +.P +The functionality of +.IR mkdir +is described substantially through a reference to the +\fImkdir\fR() +function in the System Interfaces volume of POSIX.1\(hy2008. For example, by default, the mode of the +directory is affected by the file mode creation mask in accordance with +the specified behavior of the +\fImkdir\fR() +function. In this way, there is less duplication of effort required for +describing details of the directory creation. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^", +.IR "\fIrm\fR\^", +.IR "\fIrmdir\fR\^", +.IR "\fIumask\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fImkdir\fR\^(\|)", +.IR "\fIumask\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/mkfifo.1p b/man-pages-posix-2013/man1p/mkfifo.1p new file mode 100644 index 0000000..c5501a5 --- /dev/null +++ b/man-pages-posix-2013/man1p/mkfifo.1p @@ -0,0 +1,190 @@ +'\" et +.TH MKFIFO "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\(em make FIFO special files +.SH SYNOPSIS +.LP +.nf +mkfifo \fB[\fR\(mim \fImode\fB] \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR mkfifo +utility shall create the FIFO special files specified by the operands, +in the order specified. +.P +For each +.IR file +operand, the +.IR mkfifo +utility shall perform actions equivalent to the +\fImkfifo\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008, called with the following arguments: +.IP " 1." 4 +The +.IR file +operand is used as the +.IR path +argument. +.IP " 2." 4 +The value of the bitwise-inclusive OR of S_IRUSR, S_IWUSR, S_IRGRP, +S_IWGRP, S_IROTH, and S_IWOTH is used as the +.IR mode +argument. (If the +.BR \(mim +option is specified, the value of the +\fImkfifo\fR() +.IR mode +argument is unspecified, but the FIFO shall at no time have permissions +less restrictive than the +.BR \(mim +.IR mode +option-argument.) +.SH OPTIONS +The +.IR mkfifo +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(mim\ \fImode\fR" 10 +Set the file permission bits of the newly-created FIFO to the specified +.IR mode +value. The +.IR mode +option-argument shall be the same as the +.IR mode +operand defined for the +.IR chmod +utility. In the +.IR symbolic_mode +strings, the +.IR op +characters +.BR '\(pl' +and +.BR '\(mi' +shall be interpreted relative to an assumed initial mode of +.IR a =\c +.IR rw . +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of the FIFO special file to be created. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR mkfifo : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All the specified FIFO special files were created successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +This utility was added to permit shell applications to create FIFO +special files. +.P +The +.BR \(mim +option was added to control the file mode, for consistency with the +similar functionality provided by the +.IR mkdir +utility. +.P +Early proposals included a +.BR \(mip +option similar to the +.IR mkdir +.BR \(mip +option that created intermediate directories leading up to the FIFO +specified by the final component. This was removed because it is not +commonly needed and is not common practice with similar utilities. +.P +The functionality of +.IR mkfifo +is described substantially through a reference to the +\fImkfifo\fR() +function in the System Interfaces volume of POSIX.1\(hy2008. For example, by default, the mode of the FIFO +file is affected by the file mode creation mask in accordance with the +specified behavior of the +\fImkfifo\fR() +function. In this way, there is less duplication of effort required for +describing details of the file creation. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^", +.IR "\fIumask\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fImkfifo\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/more.1p b/man-pages-posix-2013/man1p/more.1p new file mode 100644 index 0000000..5e56f88 --- /dev/null +++ b/man-pages-posix-2013/man1p/more.1p @@ -0,0 +1,1382 @@ +'\" et +.TH MORE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +more +\(em display files on a page-by-page basis +.SH SYNOPSIS +.LP +.nf +more \fB[\fR\(miceisu\fB] [\fR\(min \fInumber\fB] [\fR\(mip \fIcommand\fB] [\fR\(mit \fItagstring\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR more +utility shall read files and either write them to the terminal on a +page-by-page basis or filter them to standard output. If standard +output is not a terminal device, all input files shall be copied to +standard output in their entirety, without modification, except as +specified for the +.BR \(mis +option. If standard output is a terminal device, the files shall be +written a number of lines (one screenful) at a time under the control +of user commands. See the EXTENDED DESCRIPTION section. +.P +Certain block-mode terminals do not have all the capabilities necessary +to support the complete +.IR more +definition; they are incapable of accepting commands that are not +terminated with a +. +Implementations that support such terminals shall provide an +operating mode to +.IR more +in which all commands can be terminated with a + +on those terminals. This mode: +.IP " *" 4 +Shall be documented in the system documentation +.IP " *" 4 +Shall, at invocation, inform the user of the terminal deficiency that +requires the + +usage and provide instructions on how this warning can be suppressed in +future invocations +.IP " *" 4 +Shall not be required for implementations supporting only fully capable +terminals +.IP " *" 4 +Shall not affect commands already requiring + +characters +.IP " *" 4 +Shall not affect users on the capable terminals from using +.IR more +as described in this volume of POSIX.1\(hy2008 +.SH OPTIONS +The +.IR more +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that +.BR '\(pl' +may be recognized as an option delimiter as well as +.BR '\(mi' . +.P +The following options shall be supported: +.IP "\fB\(mic\fP" 10 +If a screen is to be written that has no lines in common with the +current screen, or +.IR more +is writing its first screen, +.IR more +shall not scroll the screen, but instead shall redraw each line of the +screen in turn, from the top of the screen to the bottom. In addition, +if +.IR more +is writing its first screen, the screen shall be cleared. This option +may be silently ignored on devices with insufficient terminal +capabilities. +.IP "\fB\(mie\fP" 10 +Exit immediately after writing the last line of the last file in the +argument list; see the EXTENDED DESCRIPTION section. +.IP "\fB\(mii\fP" 10 +Perform pattern matching in searches without regard to case; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.2" ", " "Regular Expression General Requirements". +.IP "\fB\(min\ \fInumber\fR" 10 +Specify the number of lines per screenful. The +.IR number +argument is a positive decimal integer. The +.BR \(min +option shall override any values obtained from any other source. +.IP "\fB\(mip\ \fIcommand\fR" 10 +Each time a screen from a new file is displayed or redisplayed +(including as a result of +.IR more +commands; for example, +.BR :p ), +execute the +.IR more +command(s) in the command arguments in the order specified, as if +entered by the user after the first screen has been displayed. No +intermediate results shall be displayed (that is, if the command is a +movement to a screen different from the normal first screen, only the +screen resulting from the command shall be displayed.) If any of the +commands fail for any reason, an informational message to this effect +shall be written, and no further commands specified using the +.BR \(mip +option shall be executed for this file. +.IP "\fB\(mis\fP" 10 +Behave as if consecutive empty lines were a single empty line. +.IP "\fB\(mit\ \fItagstring\fR" 10 +Write the screenful of the file containing the tag named by the +.IR tagstring +argument. See the +.IR "\fIctags\fR\^" +utility. The tags feature represented by +.BR \(mit +.IR tagstring +and the +.BR :t +command is optional. It shall be provided on any system that also +provides a conforming implementation of +.IR ctags ; +otherwise, the use of +.BR \(mit +produces undefined results. +.RS 10 +.P +The filename resulting from the +.BR \(mit +option shall be logically added as a prefix to the list of command line +files, as if specified by the user. If the tag named by the +.IR tagstring +argument is not found, it shall be an error, and +.IR more +shall take no further action. +.P +If the tag specifies a line number, the first line of the display shall +contain the beginning of that line. If the tag specifies a pattern, the +first line of the display shall contain the beginning of the matching +text from the first line of the file that contains that pattern. If the +line does not exist in the file or matching text is not found, an +informational message to this effect shall be displayed, and +.IR more +shall display the default screen as if +.BR \(mit +had not been specified. +.P +If both the +.BR \(mit +.IR tagstring +and +.BR \(mip +.IR command +options are given, the +.BR \(mit +.IR tagstring +shall be processed first; that is, the file and starting line for the +display shall be as specified by +.BR \(mit , +and then the +.BR \(mip +.IR more +command shall be executed. If the line (matching text) specified by the +.BR \(mit +command does not exist (is not found), no +.BR \(mip +.IR more +command shall be executed for this file at any time. +.RE +.IP "\fB\(miu\fP" 10 +Treat a + +as a printable control character, displayed as an +implementation-defined character sequence (see the EXTENDED DESCRIPTION +section), suppressing backspacing and the special handling that +produces underlined or standout mode text on some terminal types. +Also, do not ignore a + +at the end of a line. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an input file. If no +.IR file +operands are specified, the standard input shall be used. If a +.IR file +is +.BR '\(mi' , +the standard input shall be read at that point in the sequence. +.SH STDIN +The standard input shall be used only if no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' . +.SH "INPUT FILES" +The input files being examined shall be text files. If standard output +is a terminal, standard error shall be used to read commands from the +user. If standard output is a terminal, standard error is not readable, +and command input is needed, +.IR more +may attempt to obtain user commands from the controlling terminal (for +example, +.BR /dev/tty ); +otherwise, +.IR more +shall terminate with an error indicating that it was unable to read +user commands. If standard output is not a terminal, no error shall +result if standard error cannot be opened for reading. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR more : +.IP "\fICOLUMNS\fP" 10 +Override the system-selected horizontal display line size. See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +for valid values and results when it is unset or null. +.IP "\fIEDITOR\fP" 10 +Used by the +.BR v +command to select an editor. See the EXTENDED DESCRIPTION section. +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular expressions. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files) and the behavior of +character classes within regular expressions. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fILINES\fP" 10 +Override the system-selected vertical screen size, used as the number +of lines in a screenful. See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +for valid values and results when it is unset or null. The +.BR \(min +option shall take precedence over the +.IR LINES +variable for determining the number of lines in a screenful. +.IP "\fIMORE\fP" 10 +Determine a string containing options described in the OPTIONS section +preceded with + +characters and +-separated +as on the command line. Any command line options shall be processed +after those in the +.IR MORE +variable, as if the command line were: +.RS 10 +.sp +.RS 4 +.nf +\fB +more $MORE \fIoptions operands\fR +.fi \fR +.P +.RE +.P +The +.IR MORE +variable shall take precedence over the +.IR TERM +and +.IR LINES +variables for determining the number of lines in a screenful. +.RE +.IP "\fITERM\fP" 10 +Determine the name of the terminal type. If this variable is unset or +null, an unspecified default terminal type is used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall be used to write the contents of the input +files. +.SH STDERR +The standard error shall be used for diagnostic messages and user +commands (see the INPUT FILES section), and, if standard output is a +terminal device, to write a prompting string. The prompting string +shall appear on the screen line below the last line of the file +displayed in the current screenful. The prompt shall contain the name +of the file currently being examined and shall contain an end-of-file +indication and the name of the next file, if any, when prompting at the +end-of-file. If an error or informational message is displayed, it is +unspecified whether it is contained in the prompt. If it is not +contained in the prompt, it shall be displayed and then the user shall +be prompted for a continuation character, at which point another +message or the user prompt may be displayed. The prompt is otherwise +unspecified. It is unspecified whether informational messages are +written for other user commands. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +The following section describes the behavior of +.IR more +when the standard output is a terminal device. If the standard output +is not a terminal device, no options other than +.BR \(mis +shall have any effect, and all input files shall be copied to standard +output otherwise unmodified, at which time +.IR more +shall exit without further action. +.P +The number of lines available per screen shall be determined by the +.BR \(min +option, if present, or by examining values in the environment (see the +ENVIRONMENT VARIABLES section). If neither method yields a number, an +unspecified number of lines shall be used. +.P +The maximum number of lines written shall be one less than this number, +because the screen line after the last line written shall be used to +write a user prompt and user input. If the number of lines in the +screen is less than two, the results are undefined. It is unspecified +whether user input is permitted to be longer than the remainder of the +single line where the prompt has been written. +.P +The number of columns available per line shall be determined by +examining values in the environment (see the ENVIRONMENT VARIABLES +section), with a default value as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +.P +Lines that are longer than the display shall be folded; the length at +which folding occurs is unspecified, but should be appropriate for the +output device. Folding may occur between glyphs of single characters +that take up multiple display columns. +.P +When standard output is a terminal and +.BR \(miu +is not specified, +.IR more +shall treat + +and + +characters specially: +.IP " *" 4 +A character, followed first by a sequence of +.IR n + +characters (where +.IR n +is the same as the number of column positions that the character +occupies), then by +.IR n + +characters (\c +.BR '_' ), +shall cause that character to be written as underlined text, if the +terminal type supports that. The +.IR n + +characters, followed first by +.IR n + +characters, then any character with +.IR n +column positions, shall also cause that character to be written as +underlined text, if the terminal type supports that. +.IP " *" 4 +A sequence of +.IR n + +characters (where +.IR n +is the same as the number of column positions that the previous +character occupies) that appears between two identical printable +characters shall cause the first of those two characters to be written +as emboldened text (that is, visually brighter, standout mode, or +inverse-video mode), if the terminal type supports that, and the second +to be discarded. Immediately subsequent occurrences of +/\c +character pairs for that same character shall also be discarded. (For +example, the sequence +.BR \(dqa\eba\eba\eba\(dq +is interpreted as a single emboldened +.BR 'a' .) +.IP " *" 4 +The +.IR more +utility shall logically discard all other + +characters from the line as well as the character which precedes them, +if any. +.IP " *" 4 +A + +at the end of a line shall be ignored, rather than being written as a +non-printable character, as described in the next paragraph. +.P +It is implementation-defined how other non-printable characters are +written. Implementations should use the same format that they use for +the +.IR ex +.BR print +command; see the OPTIONS section within the +.IR ed +utility. It is unspecified whether a multi-column character shall be +separated if it crosses a display line boundary; it shall not be +discarded. The behavior is unspecified if the number of columns on the +display is less than the number of columns any single character in the +line being displayed would occupy. +.P +When each new file is displayed (or redisplayed), +.IR more +shall write the first screen of the file. Once the initial screen has +been written, +.IR more +shall prompt for a user command. If the execution of the user command +results in a screen that has lines in common with the current screen, +and the device has sufficient terminal capabilities, +.IR more +shall scroll the screen; otherwise, it is unspecified whether the +screen is scrolled or redrawn. +.P +For all files but the last (including standard input if no file was +specified, and for the last file as well, if the +.BR \(mie +option was not specified), when +.IR more +has written the last line in the file, +.IR more +shall prompt for a user command. This prompt shall contain the name of +the next file as well as an indication that +.IR more +has reached end-of-file. If the user command is +.BR f , +\(hyF, +, +.BR j , +, +.BR d , +\(hyD, +or +.BR s , +.IR more +shall display the next file. Otherwise, if displaying the last file, +.IR more +shall exit. Otherwise, +.IR more +shall execute the user command specified. +.P +Several of the commands described in this section display a previous +screen from the input stream. In the case that text is being taken from +a non-rewindable stream, such as a pipe, it is implementation-defined +how much backwards motion is supported. If a command cannot be executed +because of a limitation on backwards motion, an error message to this +effect shall be displayed, the current screen shall not change, and the +user shall be prompted for another command. +.P +If a command cannot be performed because there are insufficient lines +to display, +.IR more +shall alert the terminal. If a command cannot be performed because +there are insufficient lines to display or a +.BR / +command fails: if the input is the standard input, the last screen in +the file may be displayed; otherwise, the current file and screen shall +not change, and the user shall be prompted for another command. +.P +The interactive commands in the following sections shall be supported. +Some commands can be preceded by a decimal integer, called +.IR count +in the following descriptions. If not specified with the command, +.IR count +shall default to 1. In the following descriptions, +.IR pattern +is a basic regular expression, as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.3" ", " "Basic Regular Expressions". +The term ``examine'' is historical usage meaning ``open the +file for viewing''; for example, +.IR more +.BR foo +would be expressed as examining file +.BR foo . +.P +In the following descriptions, unless otherwise specified, +.IR line +is a line in the +.IR more +display, not a line from the file being examined. +.P +In the following descriptions, the +.IR "current position" +refers to two things: +.IP " 1." 4 +The position of the current line on the screen +.IP " 2." 4 +The line number (in the file) of the current line on the screen +.P +Usually, the line on the screen corresponding to the current position +is the third line on the screen. If this is not possible (there are +fewer than three lines to display or this is the first page of the +file, or it is the last page of the file), then the current position is +either the first or last line on the screen as described later. +.SS "Help" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +h +.fi \fR +.P +.RE +.RE +.P +Write a summary of these commands and other implementation-defined +commands. The behavior shall be as if the +.IR more +utility were executed with the +.BR \(mie +option on a file that contained the summary information. The user shall +be prompted as described earlier in this section when end-of-file is +reached. If the user command is one of those specified to continue to +the next file, +.IR more +shall return to the file and screen state from which the +.BR h +command was executed. +.SS "Scroll Forward One Screenful" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fRf +\fB[\fIcount\fB]\fR-F +.fi \fR +.P +.RE +.RE +.P +Scroll forward +.IR count +lines, with a default of one screenful. If +.IR count +is more than the screen size, only the final screenful shall be +written. +.SS "Scroll Backward One Screenful" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fRb +\fB[\fIcount\fB]\fR-B +.fi \fR +.P +.RE +.RE +.P +Scroll backward +.IR count +lines, with a default of one screenful (see the +.BR \(min +option). If +.IR count +is more than the screen size, only the final screenful shall be +written. +.SS "Scroll Forward One Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR +\fB[\fIcount\fB]\fRj +\fB[\fIcount\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Scroll forward +.IR count +lines. The default +.IR count +for the + +shall be one screenful; for +.BR j +and +, +one line. The entire +.IR count +lines shall be written, even if +.IR count +is more than the screen size. +.SS "Scroll Backward One Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fRk +.fi \fR +.P +.RE +.RE +.P +Scroll backward +.IR count +lines. The entire +.IR count +lines shall be written, even if +.IR count +is more than the screen size. +.SS "Scroll Forward One Half Screenful" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fRd +\fB[\fIcount\fB]\fR-D +.fi \fR +.P +.RE +.RE +.P +Scroll forward +.IR count +lines, with a default of one half of the screen size. If +.IR count +is specified, it shall become the new default for subsequent +.BR d , +\(hyD, +and +.BR u +commands. +.SS "Skip Forward One Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fRs +.fi \fR +.P +.RE +.RE +.P +Display the screenful beginning with the line +.IR count +lines after the last line on the current screen. If +.IR count +would cause the current position to be such that less than one +screenful would be written, the last screenful in the file shall be +written. +.SS "Scroll Backward One Half Screenful" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fRu +\fB[\fIcount\fB]\fR-U +.fi \fR +.P +.RE +.RE +.P +Scroll backward +.IR count +lines, with a default of one half of the screen size. If +.IR count +is specified, it shall become the new default for subsequent +.BR d , +\(miD, +.BR u , +and +\(miU +commands. The entire +.IR count +lines shall be written, even if +.IR count +is more than the screen size. +.SS "Go to Beginning of File" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fRg +.fi \fR +.P +.RE +.RE +.P +Display the screenful beginning with line +.IR count . +.SS "Go to End-of-File" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fRG +.fi \fR +.P +.RE +.RE +.P +If +.IR count +is specified, display the screenful beginning with the line +.IR count . +Otherwise, display the last screenful of the file. +.SS "Refresh the Screen" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +r +-L +.fi \fR +.P +.RE +.RE +.P +Refresh the screen. +.SS "Discard and Refresh" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +R +.fi \fR +.P +.RE +.RE +.P +Refresh the screen, discarding any buffered input. If the current file +is non-seekable, buffered input shall not be discarded and the +.BR R +command shall be equivalent to the +.BR r +command. +.SS "Mark Position" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +m\fIletter\fR +.fi \fR +.P +.RE +.RE +.P +Mark the current position with the letter named by +.IR letter , +where +.IR letter +represents the name of one of the lowercase letters of the portable +character set. When a new file is examined, all marks may be lost. +.SS "Return to Mark" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\&'\fIletter\fR +.fi \fR +.P +.RE +.RE +.P +Return to the position that was previously marked with the letter named +by +.IR letter , +making that line the current position. +.SS "Return to Previous Position" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\&'' +.fi \fR +.P +.RE +.RE +.P +Return to the position from which the last large movement command was +executed (where a ``large movement'' is defined as any movement of more +than a screenful of lines). If no such movements have been made, return +to the beginning of the file. +.SS "Search Forward for Pattern" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR/\fB[\fR!\fB]\fIpattern\fR +.fi \fR +.P +.RE +.RE +.P +Display the screenful beginning with the +.IR count th +line containing the pattern. The search shall start after the first +line currently displayed. The null regular expression (\c +.BR '/' +followed by a +) +shall repeat the search using the previous regular expression, with a +default +.IR count . +If the character +.BR '!' +is included, the matching lines shall be those that do not contain the +.IR pattern . +If no match is found for the +.IR pattern , +a message to that effect shall be displayed. +.SS "Search Backward for Pattern" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR?\fB[\fR!\fB]\fIpattern\fR +.fi \fR +.P +.RE +.RE +.P +Display the screenful beginning with the +.IR count th +previous line containing the pattern. The search shall start on the +last line before the first line currently displayed. The null regular +expression (\c +.BR '?' +followed by a +) +shall repeat the search using the previous regular expression, with a +default +.IR count . +If the character +.BR '!' +is included, matching lines shall be those that do not contain the +.IR pattern . +If no match is found for the +.IR pattern , +a message to that effect shall be displayed. +.SS "Repeat Search" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fRn +.fi \fR +.P +.RE +.RE +.P +Repeat the previous search for +.IR count th +line containing the last +.IR pattern +(or not containing the last +.IR pattern , +if the previous search was +.BR \(dq/!\(dq +or +.BR \(dq?!\(dq ). +.SS "Repeat Search in Reverse" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fRN +.fi \fR +.P +.RE +.RE +.P +Repeat the search in the opposite direction of the previous search for +the +.IR count th +line containing the last +.IR pattern +(or not containing the last +.IR pattern , +if the previous search was +.BR \(dq/!\(dq +or +.BR \(dq?!\(dq ). +.SS "Examine New File" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +:e \fB[\fIfilename\fB]\fR +.fi \fR +.P +.RE +.RE +.P +Examine a new file. If the +.IR filename +argument is not specified, the current file (see the +.BR :n +and +.BR :p +commands below) shall be re-examined. The +.IR filename +shall be subjected to the process of shell word expansions (see +.IR "Section 2.6" ", " "Word Expansions"); +if more than a single pathname results, the effects are unspecified. +If +.IR filename +is a + +(\c +.BR '#' ), +the previously examined file shall be re-examined. If +.IR filename +is not accessible for any reason (including that it is a non-seekable +file), an error message to this effect shall be displayed and the +current file and screen shall not change. +.SS "Examine Next File" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR:n +.fi \fR +.P +.RE +.RE +.P +Examine the next file. If a number +.IR count +is specified, the +.IR count th +next file shall be examined. If +.IR filename +refers to a non-seekable file, the results are unspecified. +.SS "Examine Previous File" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR:p +.fi \fR +.P +.RE +.RE +.P +Examine the previous file. If a number +.IR count +is specified, the +.IR count th +previous file shall be examined. If +.IR filename +refers to a non-seekable file, the results are unspecified. +.SS "Go to Tag" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +:t \fItagstring\fR +.fi \fR +.P +.RE +.RE +.P +If the file containing the tag named by the +.IR tagstring +argument is not the current file, examine the file, as if the +.BR :e +command was executed with that file as the argument. Otherwise, or in +addition, display the screenful beginning with the tag, as described +for the +.BR \(mit +option (see the OPTIONS section). If the +.IR ctags +utility is not supported by the system, the use of +.BR :t +produces undefined results. +.SS "Invoke Editor" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +v +.fi \fR +.P +.RE +.RE +.P +Invoke an editor to edit the current file being examined. If standard +input is being examined, the results are unspecified. The name of the +editor shall be taken from the environment variable +.IR EDITOR , +or shall default to +.IR vi . +If the last pathname component in +.IR EDITOR +is either +.IR vi +or +.IR ex , +the editor shall be invoked with a +.BR \(mic +.IR linenumber +command line argument, where +.IR linenumber +is the line number of the file line containing the display line +currently displayed as the first line of the screen. It is +implementation-defined whether line-setting options are passed to +editors other than +.IR vi +and +.IR ex . +.P +When the editor exits, +.IR more +shall resume with the same file and screen as when the editor was +invoked. +.SS "Display Position" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB += +-G +.fi \fR +.P +.RE +.RE +.P +Write a message for which the information references the first byte of +the line after the last line of the file on the screen. This message +shall include the name of the file currently being examined, its number +relative to the total number of files there are to examine, the line +number in the file, the byte number and the total bytes in the file, +and what percentage of the file precedes the current position. If +.IR more +is reading from standard input, or the file is shorter than a single +screen, the line number, the byte number, the total bytes, and the +percentage need not be written. +.SS "Quit" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +q +:q +ZZ +.fi \fR +.P +.RE +.RE +.P +Exit +.IR more . +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If an error is encountered accessing a file when using the +.BR :n +command, +.IR more +shall attempt to examine the next file in the argument list, but the +final exit status shall be affected. If an error is encountered +accessing a file via the +.BR :p +command, +.IR more +shall attempt to examine the previous file in the argument list, but +the final exit status shall be affected. If an error is encountered +accessing a file via the +.BR :e +command, +.IR more +shall remain in the current file and the final exit status shall not be +affected. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +When the standard output is not a terminal, only the +.BR \(mis +filter-modification option is effective. This is based on historical +practice. For example, a typical implementation of +.IR man +pipes its output through +.IR more +.BR \(mis +to squeeze excess white space for terminal users. When +.IR man +is piped to +.IR lp , +however, it is undesirable for this squeezing to happen. +.SH EXAMPLES +The +.BR \(mip +allows arbitrary commands to be executed at the start of each file. +Examples are: +.IP "\fImore\ \fB\(mip\ G\ \fIfile1\ file2\fR" 6 +.br +Examine each file starting with its last screenful. +.IP "\fImore\ \fB\(mip\ \fR100\ \fIfile1\ file2\fR" 6 +.br +Examine each file starting with line 100 in the current position +(usually the third line, so line 98 would be the first line written). +.IP "\fImore\ \fB\(mip\ \fR/100\ \fIfile1\ file2\fR" 6 +.br +Examine each file starting with the first line containing the string +.BR \(dq100\(dq +in the current position +.SH RATIONALE +The +.IR more +utility, available in BSD and BSD-derived systems, was chosen as the +prototype for the POSIX file display program since it is more widely +available than either the public-domain program +.IR less +or than +.IR pg , +a pager provided in System V. The 4.4 BSD +.IR more +is the model for the features selected; it is almost fully +upwards-compatible from the 4.3 BSD version in wide use and has become +more amenable for +.IR vi +users. Several features originally derived from various file editors, +found in both +.IR less +and +.IR pg , +have been added to this volume of POSIX.1\(hy2008 as they have proved extremely popular with +users. +.P +There are inconsistencies between +.IR more +and +.IR vi +that result from historical practice. For example, the single-character +commands +.BR h , +.BR f , +.BR b , +and + +are screen movers in +.IR more , +but cursor movers in +.IR vi . +These inconsistencies were maintained because the cursor movements are +not applicable to +.IR more +and the powerful functionality achieved without the use of the control +key justifies the differences. +.P +The tags interface has been included in a program that is not a text +editor because it promotes another degree of consistent operation with +.IR vi . +It is conceivable that the paging environment of +.IR more +would be superior for browsing source code files in some +circumstances. +.P +The operating mode referred to for block-mode terminals effectively +adds a + +to each Synopsis line that currently has none. So, for example, +.BR d \c + +would page one screenful. The mode could be triggered by a command +line option, environment variable, or some other method. The details +are not imposed by this volume of POSIX.1\(hy2008 because there are so few systems known to +support such terminals. Nevertheless, it was considered that all +systems should be able to support +.IR more +given the exception cited for this small community of terminals +because, in comparison to +.IR vi , +the cursor movements are few and the command set relatively amenable to +the optional + +characters. +.P +Some versions of +.IR more +provide a shell escaping mechanism similar to the +.IR ex +.BR ! +command. The standard developers did not consider that this was +necessary in a paginator, particularly given the wide acceptance of +multiple window terminals and job control features. (They chose to +retain such features in the editors and +.IR mailx +because the shell interaction also gives an opportunity to modify the +editing buffer, which is not applicable to +.IR more .) +.P +The +.BR \(mip +(position) option replaces the +.BR + +command because of the Utility Syntax Guidelines. The +.BR \(pl \c +.IR command +option is no longer specified by POSIX.1\(hy2008 but may be present +in some implementations. In early proposals, it took a +.IR pattern +argument, but historical +.IR less +provided the +.IR more +general facility of a command. It would have been desirable to use the +same +.BR \(mic +as +.IR ex +and +.IR vi , +but the letter was already in use. +.P +The text stating ``from a non-rewindable stream .\|.\|. implementations +may limit the amount of backwards motion supported'' would allow an +implementation that permitted no backwards motion beyond text already +on the screen. It was not possible to require a minimum amount of +backwards motion that would be effective for all conceivable device +types. The implementation should allow the user to back up as far as +possible, within device and reasonable memory allocation constraints. +.P +Historically, non-printable characters were displayed using the ARPA +standard mappings, which are as follows: +.IP " 1." 4 +Printable characters are left alone. +.IP " 2." 4 +Control characters less than \e177 are represented as followed by the +character offset from the +.BR '@' +character in the ASCII map; for example, \e007 is represented as +.BR 'G' . +.IP " 3." 4 +\e177 is represented as followed by +.BR '?' . +.P +The display of characters having their eighth bit set was less +standard. Existing implementations use hex (0x00), octal (\e000), and a +meta-bit display. (The latter displayed characters with their eighth +bit set as the two characters +.BR \(dqM\(mi\(dq , +followed by the seven-bit display as described previously.) The latter +probably has the best claim to historical practice because it was used +with the +.BR \(miv +option of 4 BSD and 4 BSD-derived versions of the +.IR cat +utility since 1980. +.P +No specific display format is required by POSIX.1\(hy2008. Implementations are +encouraged to conform to historic practice in the absence of any strong +reason to diverge. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIctags\fR\^", +.IR "\fIed\fR\^", +.IR "\fIex\fR\^", +.IR "\fIvi\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 9.2" ", " "Regular Expression General Requirements", +.IR "Section 9.3" ", " "Basic Regular Expressions", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/mv.1p b/man-pages-posix-2013/man1p/mv.1p new file mode 100644 index 0000000..d8e4dde --- /dev/null +++ b/man-pages-posix-2013/man1p/mv.1p @@ -0,0 +1,529 @@ +'\" et +.TH MV "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +mv +\(em move files +.SH SYNOPSIS +.LP +.nf +mv \fB[\fR\(miif\fB] \fIsource_file target_file\fR +.P +mv \fB[\fR\(miif\fB] \fIsource_file\fR... \fItarget_dir\fR +.fi +.SH DESCRIPTION +In the first synopsis form, the +.IR mv +utility shall move the file named by the +.IR source_file +operand to the destination specified by the +.IR target_file . +This first synopsis form is assumed when the final operand does not +name an existing directory and is not a symbolic link referring to +an existing directory. In this case, if +.IR source_file +names a non-directory file and +.IR target_file +ends with a trailing + +character, +.IR mv +shall treat this as an error and no +.IR source_file +operands will be processed. +.P +In the second synopsis form, +.IR mv +shall move each file named by a +.IR source_file +operand to a destination file in the existing directory named by the +.IR target_dir +operand, or referenced if +.IR target_dir +is a symbolic link referring to an existing directory. The +destination path for each +.IR source_file +shall be the concatenation of the target directory, a single + +character if the target did not end in a +, +and the last pathname component of the +.IR source_file . +This second form is assumed when the final operand names an existing +directory. +.P +If any operand specifies an existing file of a type not +specified by the System Interfaces volume of POSIX.1\(hy2008, the behavior is implementation-defined. +.P +For each +.IR source_file +the following steps shall be taken: +.IP " 1." 4 +If the destination path exists, the +.BR \(mif +option is not specified, and either of the following conditions is +true: +.RS 4 +.IP " a." 4 +The permissions of the destination path do not permit writing and the +standard input is a terminal. +.IP " b." 4 +The +.BR \(mii +option is specified. +.P +the +.IR mv +utility shall write a prompt to standard error and read a line from +standard input. If the response is not affirmative, +.IR mv +shall do nothing more with the current +.IR source_file +and go on to any remaining +.IR source_file s. +.RE +.IP " 2." 4 +If the +.IR source_file +operand and destination path name the same existing file, then the +destination path shall not be removed, and one of the following shall +occur: +.RS 4 +.IP " a." 4 +No change is made to +.IR source_file , +no error occurs, and no diagnostic is issued. +.IP " b." 4 +No change is made to +.IR source_file , +a diagnostic is issued to standard error identifying the two names, +and the exit status is affected. +.IP " c." 4 +If the +.IR source_file +operand and destination path name distinct directory entries, then the +.IR source_file +operand is removed, no error occurs, and no diagnostic is issued. +.P +The +.IR mv +utility shall do nothing more with the current +.IR source_file , +and go on to any remaining +.IR source_file s. +.RE +.IP " 3." 4 +The +.IR mv +utility shall perform actions equivalent to the +\fIrename\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008, called with the following arguments: +.RS 4 +.IP " a." 4 +The +.IR source_file +operand is used as the +.IR old +argument. +.IP " b." 4 +The destination path is used as the +.IR new +argument. +.P +If this succeeds, +.IR mv +shall do nothing more with the current +.IR source_file +and go on to any remaining +.IR source_file s. +If this fails for any reasons other than those described for the +.IR errno +.BR [EXDEV] +in the System Interfaces volume of POSIX.1\(hy2008, +.IR mv +shall write a diagnostic message to standard error, do nothing more +with the current +.IR source_file , +and go on to any remaining +.IR source_file s. +.RE +.IP " 4." 4 +If the destination path exists, and it is a file of type directory and +.IR source_file +is not a file of type directory, or it is a file not of type directory +and +.IR source_file +is a file of type directory, +.IR mv +shall write a diagnostic message to standard error, do nothing more +with the current +.IR source_file , +and go on to any remaining +.IR source_file s. +If the destination path exists and was created by a previous step, it +is unspecified whether this will treated as an error or the destination +path will be overwritten. +.IP " 5." 4 +If the destination path exists, +.IR mv +shall attempt to remove it. If this fails for any reason, +.IR mv +shall write a diagnostic message to standard error, do nothing more +with the current +.IR source_file , +and go on to any remaining +.IR source_file s. +.IP " 6." 4 +The file hierarchy rooted in +.IR source_file +shall be duplicated as a file hierarchy rooted in the destination path. If +.IR source_file +or any of the files below it in the hierarchy are symbolic links, the +links themselves shall be duplicated, including their contents, rather +than any files to which they refer. The following characteristics of +each file in the file hierarchy shall be duplicated: +.RS 4 +.IP " *" 4 +The time of last data modification and time of last access +.IP " *" 4 +The user ID and group ID +.IP " *" 4 +The file mode +.P +If the user ID, group ID, or file mode of a regular file cannot be +duplicated, the file mode bits S_ISUID and S_ISGID shall not be +duplicated. +.P +When files are duplicated to another file system, the implementation +may require that the process invoking +.IR mv +has read access to each file being duplicated. +.P +If files being duplicated to another file system have hard links to +other files, it is unspecified whether the files copied to the new +file system have the hard links preserved or separate copies are created +for the linked files. +.P +If the duplication of the file hierarchy fails for any reason, +.IR mv +shall write a diagnostic message to standard error, do nothing more +with the current +.IR source_file , +and go on to any remaining +.IR source_file s. +.P +If the duplication of the file characteristics fails for any reason, +.IR mv +shall write a diagnostic message to standard error, but this failure +shall not cause +.IR mv +to modify its exit status. +.RE +.IP " 7." 4 +The file hierarchy rooted in +.IR source_file +shall be removed. If this fails for any reason, +.IR mv +shall write a diagnostic message to the standard error, do nothing more +with the current +.IR source_file , +and go on to any remaining +.IR source_file s. +.SH OPTIONS +The +.IR mv +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mif\fP" 10 +Do not prompt for confirmation if the destination path exists. Any +previous occurrence of the +.BR \(mii +option is ignored. +.IP "\fB\(mii\fP" 10 +Prompt for confirmation if the destination path exists. Any previous +occurrence of the +.BR \(mif +option is ignored. +.P +Specifying more than one of the +.BR \(mif +or +.BR \(mii +options shall not be considered an error. The last option specified +shall determine the behavior of +.IR mv . +.SH OPERANDS +The following operands shall be supported: +.IP "\fIsource_file\fR" 10 +A pathname of a file or directory to be moved. +.IP "\fItarget_file\fR" 10 +A new pathname for the file or directory being moved. +.IP "\fItarget_dir\fR" 10 +A pathname of an existing directory into which to move the input +files. +.SH STDIN +The standard input shall be used to read an input line in response to +each prompt specified in the STDERR section. Otherwise, the standard +input shall not be used. +.SH "INPUT FILES" +The input files specified by each +.IR source_file +operand can be of any file type. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR mv : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements used in the extended regular +expression defined for the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files), the behavior of +character classes used in the extended regular expression defined for +the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale used to process affirmative responses, and the +locale used to affect the format and contents of diagnostic messages +and prompts written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +Prompts shall be written to the standard error under the conditions +specified in the DESCRIPTION section. The prompts shall contain the +destination pathname, but their format is otherwise unspecified. +Otherwise, the standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The output files may be of any file type. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All input files were moved successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If the copying or removal of +.IR source_file +is prematurely terminated by a signal or error, +.IR mv +may leave a partial copy of +.IR source_file +at the source or destination. The +.IR mv +utility shall not modify both +.IR source_file +and the destination path simultaneously; termination at any point shall +leave either +.IR source_file +or the destination path complete. +.LP +.IR "The following sections are informative." +.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. +.P +The specification ensures that +.IR mv +.BR a +.BR a +will not alter the contents of file +.BR a , +and allows the implementation to issue an error that a file cannot be +moved onto itself. Likewise, when +.BR a +and +.BR b +are hard links to the same file, +.IR mv +.BR a +.BR b +will not alter +.BR b , +but if a diagnostic is not issued, then it is unspecified whether +.BR a +is left untouched (as it would be by the +\fIrename\fR() +function) or unlinked (reducing the link count of +.BR b ). +.SH EXAMPLES +If the current directory contains only files +.BR a +(of any type defined by the System Interfaces volume of POSIX.1\(hy2008), +.BR b +(also of any type), and a directory +.BR c : +.sp +.RS 4 +.nf +\fB +mv a b c +mv c d +.fi \fR +.P +.RE +.P +results with the original files +.BR a +and +.BR b +residing in the directory +.BR d +in the current directory. +.SH RATIONALE +Early proposals diverged from the SVID and BSD historical practice in +that they required that when the destination path exists, the +.BR \(mif +option is not specified, and input is not a terminal, +.IR mv +fails. This was done for compatibility with +.IR cp . +The current text returns to historical practice. It should be noted +that this is consistent with the +\fIrename\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008, which does not require write permission +on the target. +.P +For absolute clarity, paragraph (1), describing the behavior of +.IR mv +when prompting for confirmation, should be interpreted in the following +manner: +.sp +.RS 4 +.nf +\fB +if (exists AND (NOT f_option) AND + ((not_writable AND input_is_terminal) OR i_option)) +.fi \fR +.P +.RE +.P +The +.BR \(mii +option exists on BSD systems, giving applications and users a way to +avoid accidentally unlinking files when moving others. When the +standard input is not a terminal, the 4.3 BSD +.IR mv +deletes all existing destination paths without prompting, even when +.BR \(mii +is specified; this is inconsistent with the behavior of the 4.3 BSD +.IR cp +utility, which always generates an error when the file is unwritable +and the standard input is not a terminal. The standard developers +decided that use of +.BR \(mii +is a request for interaction, so when the destination +path exists, the utility takes instructions from whatever responds to +standard input. +.P +The +\fIrename\fR() +function is able to move directories within the same file system. Some +historical versions of +.IR mv +have been able to move directories, but not to a different file system. +The standard developers considered that this was an annoying +inconsistency, so this volume of POSIX.1\(hy2008 requires directories to be able to be moved +even across file systems. There is no +.BR \(miR +option to confirm that moving a directory is actually intended, since +such an option was not required for moving directories in historical +practice. Requiring the application to specify it sometimes, depending +on the destination, seemed just as inconsistent. The semantics of the +\fIrename\fR() +function were preserved as much as possible. For example, +.IR mv +is not permitted to ``rename'' files to or from directories, even +though they might be empty and removable. +.P +Historic implementations of +.IR mv +did not exit with a non-zero exit status if they were unable to +duplicate any file characteristics when moving a file across file +systems, nor did they write a diagnostic message for the user. The +former behavior has been preserved to prevent scripts from breaking; a +diagnostic message is now required, however, so that users are alerted +that the file characteristics have changed. +.P +The exact format of the interactive prompts is unspecified. Only the +general nature of the contents of prompts are specified because +implementations may desire more descriptive prompts than those used on +historical implementations. Therefore, an application not using the +.BR \(mif +option or using the +.BR \(mii +option relies on the system to provide the most suitable dialog +directly with the user, based on the behavior specified. +.P +When +.IR mv +is dealing with a single file system and +.IR source_file +is a symbolic link, the link itself is moved as a consequence of the +dependence on the +\fIrename\fR() +functionality, per the DESCRIPTION. Across file systems, this has to be +made explicit. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcp\fR\^", +.IR "\fIln\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIrename\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/newgrp.1p b/man-pages-posix-2013/man1p/newgrp.1p new file mode 100644 index 0000000..c747daf --- /dev/null +++ b/man-pages-posix-2013/man1p/newgrp.1p @@ -0,0 +1,296 @@ +'\" et +.TH NEWGRP "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +newgrp +\(em change to a new group +.SH SYNOPSIS +.LP +.nf +newgrp \fB[\fR\(mil\fB] [\fIgroup\fB]\fR +.fi +.SH DESCRIPTION +The +.IR newgrp +utility shall create a new shell execution environment with a new real +and effective group identification. Of the attributes listed in +.IR "Section 2.12" ", " "Shell Execution Environment", +the new shell execution environment shall retain the working directory, +file creation mask, and exported variables from the previous +environment (that is, open files, traps, unexported variables, alias +definitions, shell functions, and +.IR set +options may be lost). All other aspects of the process environment +that are preserved by the +.IR exec +family of functions defined in the System Interfaces volume of POSIX.1\(hy2008 shall also be preserved by +.IR newgrp ; +whether other aspects are preserved is unspecified. +.P +A failure to assign the new group identifications (for example, for +security or password-related reasons) shall not prevent the new shell +execution environment from being created. +.P +The +.IR newgrp +utility shall affect the supplemental groups for the process as +follows: +.IP " *" 4 +On systems where the effective group ID is normally in the +supplementary group list (or whenever the old effective group ID +actually is in the supplementary group list): +.RS 4 +.IP -- 4 +If the new effective group ID is also in the supplementary group list, +.IR newgrp +shall change the effective group ID. +.IP -- 4 +If the new effective group ID is not in the supplementary group list, +.IR newgrp +shall add the new effective group ID to the list, if there is room to +add it. +.RE +.IP " *" 4 +On systems where the effective group ID is not normally in the +supplementary group list (or whenever the old effective group ID is not +in the supplementary group list): +.RS 4 +.IP -- 4 +If the new effective group ID is in the supplementary group list, +.IR newgrp +shall delete it. +.IP -- 4 +If the old effective group ID is not in the supplementary list, +.IR newgrp +shall add it if there is room. +.RE +.TP 10 +.BR Note: +The System Interfaces volume of POSIX.1\(hy2008 does not specify whether the effective group ID of a process +is included in its supplementary group list. +.P +.P +With no operands, +.IR newgrp +shall change the effective group back to the groups identified in the +user's user entry, and shall set the list of supplementary groups to +that set in the user's group database entries. +.P +If the first argument is +.BR '\(mi' , +the results are unspecified. +.P +If a password is required for the specified group, and the user is not +listed as a member of that group in the group database, the user shall +be prompted to enter the correct password for that group. If the user +is listed as a member of that group, no password shall be requested. +If no password is required for the specified group, it is +implementation-defined whether users not listed as members of that +group can change to that group. Whether or not a password is required, +implementation-defined system accounting or security mechanisms may +impose additional authorization restrictions that may cause +.IR newgrp +to write a diagnostic message and suppress the changing of the group +identification. +.SH OPTIONS +The +.IR newgrp +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except for the unspecified usage of +.BR '\(mi' . +.P +The following option shall be supported: +.IP "\fB\(mil\fP" 10 +(The letter ell.) Change the environment to what would be expected if +the user actually logged in again. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIgroup\fR" 10 +A group name from the group database or a non-negative numeric group +ID. Specifies the group ID to which the real and effective group IDs +shall be set. If +.IR group +is a non-negative numeric string and exists in the group database as a +group name (see +\fIgetgrnam\fR()), +the numeric group ID associated with that group name shall be used as +the group ID. +.SH STDIN +Not used. +.SH "INPUT FILES" +The file +.BR /dev/tty +shall be used to read a single line of text for password checking, when +one is required. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR newgrp : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used for diagnostic messages and a prompt +string for a password, if one is required. Diagnostic messages may be +written in cases where the exit status is not available. See the EXIT +STATUS section. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +If +.IR newgrp +succeeds in creating a new shell execution environment, whether or not +the group identification was changed successfully, the exit status +shall be the exit status of the shell. Otherwise, the following exit +value shall be returned: +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +The invoking shell may terminate. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +There is no convenient way to enter a password into the group +database. Use of group passwords is not encouraged, because by their +very nature they encourage poor security practices. Group passwords +may disappear in the future. +.P +A common implementation of +.IR newgrp +is that the current shell uses +.IR exec +to overlay itself with +.IR newgrp , +which in turn overlays itself with a new shell after changing group. +On some implementations, however, this may not occur and +.IR newgrp +may be invoked as a subprocess. +.P +The +.IR newgrp +command is intended only for use from an interactive terminal. It does +not offer a useful interface for the support of applications. +.P +The exit status of +.IR newgrp +is generally inapplicable. If +.IR newgrp +is used in a script, in most cases it successfully invokes a new shell +and the rest of the original shell script is bypassed when the new +shell exits. Used interactively, +.IR newgrp +displays diagnostic messages to indicate problems. But usage such as: +.sp +.RS 4 +.nf +\fB +newgrp foo +echo $? +.fi \fR +.P +.RE +.P +is not useful because the new shell might not have access to any status +.IR newgrp +may have generated (and most historical systems do not provide this +status). A zero status echoed here does not necessarily indicate that +the user has changed to the new group successfully. Following +.IR newgrp +with the +.IR id +command provides a portable means of determining whether the group +change was successful or not. +.SH EXAMPLES +None. +.SH RATIONALE +Most historical implementations use one of the +.IR exec +functions to implement the behavior of +.IR newgrp . +Errors detected before the +.IR exec +leave the environment unchanged, while errors detected after the +.IR exec +leave the user in a changed environment. While it would be useful to +have +.IR newgrp +issue a diagnostic message to tell the user that the environment +changed, it would be inappropriate to require this change to some +historical implementations. +.P +The password mechanism is allowed in the group database, but how this +would be implemented is not specified. +.P +The +.IR newgrp +utility was retained in this volume of POSIX.1\(hy2008, even given the existence of the multiple +group permissions feature in the System Interfaces volume of POSIX.1\(hy2008, for several reasons. First, in +some implementations, the group ownership of a newly created file is +determined by the group of the directory in which the file is created, +as allowed by the System Interfaces volume of POSIX.1\(hy2008; on other implementations, the group ownership +of a newly created file is determined by the effective group ID. On +implementations of the latter type, +.IR newgrp +allows files to be created with a specific group ownership. Finally, +many implementations use the real group ID in accounting, and on such +systems, +.IR newgrp +allows the accounting identity of the user to be changed. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIsh\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIexec\fR\^", +.IR "\fIgetgrnam\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/nice.1p b/man-pages-posix-2013/man1p/nice.1p new file mode 100644 index 0000000..fa1baaa --- /dev/null +++ b/man-pages-posix-2013/man1p/nice.1p @@ -0,0 +1,287 @@ +'\" et +.TH NICE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 invoke a utility with an altered nice value +.SH SYNOPSIS +.LP +.nf +nice \fB[\fR\(min \fIincrement\fB] \fIutility \fB[\fIargument\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR nice +utility shall invoke a utility, requesting that it be run with a +different nice value (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.240" ", " "Nice Value"). +With no options, the executed utility shall be run with a nice value +that is some implementation-defined quantity greater than or equal to +the nice value of the current process. If the user lacks appropriate +privileges to affect the nice value in the requested manner, the +.IR nice +utility shall not affect the nice value; in this case, a warning +message may be written to standard error, but this shall not prevent +the invocation of +.IR utility +or affect the exit status. +.SH OPTIONS +The +.IR nice +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option is supported: +.IP "\fB\(min\ \fIincrement\fR" 10 +A positive or negative decimal integer which shall have the same +effect on the execution of the utility as if the utility had +called the +\fInice\fR() +function with the numeric value of the +.IR increment +option-argument. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIutility\fR" 10 +The name of a utility that is to be invoked. If the +.IR utility +operand names any of the special built-in utilities in +.IR "Section 2.14" ", " "Special Built-In Utilities", +the results are undefined. +.IP "\fIargument\fR" 10 +Any string to be supplied as an argument when invoking the utility +named by the +.IR utility +operand. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR nice : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPATH\fP" 10 +Determine the search path used to locate the utility to be invoked. +See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +If +.IR utility +is invoked, the exit status of +.IR nice +shall be the exit status of +.IR utility ; +otherwise, the +.IR nice +utility shall exit with one of the following values: +.IP "1\(hy125" 8 +An error occurred in the +.IR nice +utility. +.IP "\0\0126" 8 +The utility specified by +.IR utility +was found but could not be invoked. +.IP "\0\0127" 8 +The utility specified by +.IR utility +could not be found. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The only guaranteed portable uses of this utility are: +.IP "\fInice\ utility\fR" 6 +.br +Run +.IR utility +with the default higher or equal nice value. +.IP "\fInice\ \fB\(min\ \fR<\fIpositive\ integer\fR>\fI\ utility\fR" 6 +.br +Run +.IR utility +with a higher nice value. +.P +On some implementations they have no discernible effect on the invoked +utility and on some others they are exactly equivalent. +.P +Historical systems have frequently supported the <\fIpositive +integer\fP> up to 20. Since there is no error penalty associated with +guessing a number that is too high, users without access to the system +conformance document (to see what limits are actually in place) could +use the historical 1 to 20 range or attempt to use very large numbers +if the job should be truly low priority. +.P +The nice value of a process can be displayed using the command: +.sp +.RS 4 +.nf +\fB +ps \(mio nice +.fi \fR +.P +.RE +.P +The +.IR command , +.IR env , +.IR nice , +.IR nohup , +.IR time , +and +.IR xargs +utilities have been specified to use exit code 127 if an error occurs +so that applications can distinguish ``failure to find a utility'' from +``invoked utility exited with an error indication''. The value 127 was +chosen because it is not commonly used for other meanings; most +utilities use small values for ``normal error conditions'' and the +values above 128 can be confused with termination due to receipt of a +signal. The value 126 was chosen in a similar manner to indicate that +the utility could be found, but not invoked. Some scripts produce +meaningful error messages differentiating the 126 and 127 cases. The +distinction between exit codes 126 and 127 is based on KornShell +practice that uses 127 when all attempts to +.IR exec +the utility fail with +.BR [ENOENT] , +and uses 126 when any attempt to +.IR exec +the utility fails for any other reason. +.SH EXAMPLES +None. +.SH RATIONALE +The 4.3 BSD version of +.IR nice +does not check whether +.IR increment +is a valid decimal integer. The command +.IR nice +.BR \(mix +.IR utility , +for example, would be treated the same as the command +.IR nice +.BR \(mi\|\(mi1 +.IR utility . +If the user does not have appropriate privileges, this results in a +``permission denied'' error. +This is considered a bug. +.P +When a user without appropriate privileges gives a negative +.IR increment , +System V treats it like the command +.IR nice +.BR \(mi0 +.IR utility , +while 4.3 BSD writes a ``permission denied'' message and does not run +the utility. The standard specifies the System V behavior together +with an optional BSD-style ``permission denied'' message. +.P +The C shell has a built-in version of +.IR nice +that has a different interface from the one described in this volume of POSIX.1\(hy2008. +.P +The term ``utility'' is used, rather than ``command'', to highlight the +fact that shell compound commands, pipelines, and so on, cannot be +used. Special built-ins also cannot be used. +However, ``utility'' includes user application programs and shell +scripts, not just utilities defined in this volume of POSIX.1\(hy2008. +.P +Historical implementations of +.IR nice +provide a nice value range of 40 or 41 discrete steps, with the default +nice value being the midpoint of that range. By default, they raise the +nice value of the executed utility by 10. +.P +Some historical documentation states that the +.IR increment +value must be within a fixed range. This is misleading; the valid +.IR increment +values on any invocation are determined by the current process +nice value, which is not always the default. +.P +The definition of nice value is not intended to suggest that all +processes in a system have priorities that are comparable. Scheduling +policy extensions such as the realtime priorities in the System Interfaces volume of POSIX.1\(hy2008 make the +notion of a single underlying priority for all scheduling policies +problematic. Some implementations may implement the +.IR nice -related +features to affect all processes on the system, others to affect just +the general time-sharing activities implied by this volume of POSIX.1\(hy2008, and others may +have no effect at all. Because of the use of +``implementation-defined'' in +.IR nice +and +.IR renice , +a wide range of implementation strategies are possible. +.P +Earlier versions of this standard allowed a +.BR \(mi \c +.IR increment +option. This form is no longer specified by POSIX.1\(hy2008 but may +be present in some implementations. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIrenice\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.240" ", " "Nice Value", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fInice\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/nl.1p b/man-pages-posix-2013/man1p/nl.1p new file mode 100644 index 0000000..b5633e1 --- /dev/null +++ b/man-pages-posix-2013/man1p/nl.1p @@ -0,0 +1,312 @@ +'\" et +.TH NL "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\(em line numbering filter +.SH SYNOPSIS +.LP +.nf +nl \fB[\fR\(mip\fB] [\fR\(mib \fItype\fB] [\fR\(mid \fIdelim\fB] [\fR\(mif \fItype\fB] [\fR\(mih \fItype\fB] [\fR\(mii \fIincr\fB] [\fR\(mil \fInum\fB] + [\fR\(min \fIformat\fB] [\fR\(mis \fIsep\fB] [\fR\(miv \fIstartnum\fB] [\fR\(miw \fIwidth\fB] [\fIfile\fB]\fR +.fi +.SH DESCRIPTION +The +.IR nl +utility shall read lines from the named +.IR file +or the standard input if no +.IR file +is named and shall reproduce the lines to standard output. Lines shall +be numbered on the left. Additional functionality may be provided in +accordance with the command options in effect. +.P +The +.IR nl +utility views the text it reads in terms of logical pages. Line +numbering shall be reset at the start of each logical page. A logical +page consists of a header, a body, and a footer section. Empty sections +are valid. Different line numbering options are independently available +for header, body, and footer (for example, no numbering of header and +footer lines while numbering blank lines only in the body). +.P +The starts of logical page sections shall be signaled by input lines +containing nothing but the following delimiter characters: +.TS +center box tab(@); +cB | cB +lw(1i)f5 | lw(1i). +Line@Start of +_ +\e:\e:\e:@Header +\e:\e:@Body +\e:@Footer +.TE +.P +Unless otherwise specified, +.IR nl +shall assume the text being read is in a single logical page body. +.SH OPTIONS +The +.IR nl +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +Only one file can be named. +.P +The following options shall be supported: +.IP "\fB\(mib\ \fItype\fR" 10 +Specify which logical page body lines shall be numbered. Recognized +.IR types +and their meaning are: +.RS 10 +.IP "\fBa\fP" 8 +Number all lines. +.IP "\fBt\fP" 8 +Number only non-empty lines. +.IP "\fBn\fP" 8 +No line numbering. +.IP "\fBp\fIstring\fR" 8 +Number only lines that contain the basic regular expression +specified in +.IR string . +.P +The default +.IR type +for logical page body shall be +.BR t +(text lines numbered). +.RE +.IP "\fB\(mid\ \fIdelim\fR" 10 +Specify the delimiter characters that indicate the start of a logical +page section. These can be changed from the default characters +.BR \(dq\e:\(dq +to two user-specified characters. If only one character is entered, +the second character shall remain the default character +.BR ':' . +.IP "\fB\(mif\ \fItype\fR" 10 +Specify the same as +.BR b +.IR type +except for footer. The default for logical page footer shall be +.BR n +(no lines numbered). +.IP "\fB\(mih\ \fItype\fR" 10 +Specify the same as +.BR b +.IR type +except for header. The default +.IR type +for logical page header shall be +.BR n +(no lines numbered). +.IP "\fB\(mii\ \fIincr\fR" 10 +Specify the increment value used to number logical page lines. The +default shall be 1. +.IP "\fB\(mil\ \fInum\fR" 10 +Specify the number of blank lines to be considered as one. For +example, +.BR "\(mil\ 2" +results in only the second adjacent blank line being numbered (if the +appropriate +.BR "\(mih\ a" , +.BR "\(mib\ a" , +or +.BR "\(mif\ a" +option is set). The default shall be 1. +.IP "\fB\(min\ \fIformat\fR" 10 +Specify the line numbering format. Recognized values are: +.BR ln , +left justified, leading zeros suppressed; +.BR rn , +right justified, leading zeros suppressed; +.BR rz , +right justified, leading zeros kept. The default +.IR format +shall be +.BR rn +(right justified). +.IP "\fB\(mip\fP" 10 +Specify that numbering should not be restarted at logical page +delimiters. +.IP "\fB\(mis\ \fIsep\fR" 10 +Specify the characters used in separating the line number and the +corresponding text line. The default +.IR sep +shall be a +. +.IP "\fB\(miv\ \fIstartnum\fR" 10 +Specify the initial value used to number logical page lines. The +default shall be 1. +.IP "\fB\(miw\ \fIwidth\fR" 10 +Specify the number of characters to be used for the line number. The +default +.IR width +shall be 6. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a text file to be line-numbered. +.SH STDIN +The standard input shall be used if no +.IR file +operand is specified, and shall be used if the +.IR file +operand is +.BR '\(mi' +and the implementation treats the +.BR '\(mi' +as meaning standard input. +Otherwise, the standard input shall not be used. +See the INPUT FILES section. +.SH "INPUT FILES" +The input file shall be a text file. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR nl : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular expressions. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files), the behavior of +character classes within regular expressions, and for deciding which +characters are in character class +.BR graph +(for the +.BR "\(mib\ t" , +.BR "\(mif\ t" , +and +.BR "\(mih\ t" +options). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall be a text file in the following format: +.sp +.RS 4 +.nf +\fB +"%s%s%s", <\fIline number\fR>, <\fIseparator\fR>, <\fIinput line\fR> +.fi \fR +.P +.RE +.P +where <\fIline\ number\fP> is one of the following numeric formats: +.IP "\fR%6d\fP" 10 +When the +.BR rn +format is used (the default; see +.BR \(min ). +.IP "\fR%06d\fP" 10 +When the +.BR rz +format is used. +.IP "\fR%\(mi6d\fP" 10 +When the +.BR ln +format is used. +.IP 10 +When line numbers are suppressed for a portion of the page; the +<\fIseparator\fP> is also suppressed. +.P +In the preceding list, the number 6 is the default width; the +.BR \(miw +option can change this value. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +In using the +.BR \(mid +.IR delim +option, care should be taken to escape characters that have special +meaning to the command interpreter. +.SH EXAMPLES +The command: +.sp +.RS 4 +.nf +\fB +nl \(miv 10 \(mii 10 \(mid \e!+ file1 +.fi \fR +.P +.RE +.P +numbers +.IR file1 +starting at line number 10 with an increment of 10. The logical page +delimiter is +.BR \(dq!+\(dq . +Note that the +.BR '!' +has to be escaped when using +.IR csh +as a command interpreter because of its history substitution syntax. +For +.IR ksh +and +.IR sh +the escape is not necessary, but does not do any harm. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpr\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/nm.1p b/man-pages-posix-2013/man1p/nm.1p new file mode 100644 index 0000000..149a908 --- /dev/null +++ b/man-pages-posix-2013/man1p/nm.1p @@ -0,0 +1,405 @@ +'\" et +.TH NM "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +nm +\(em write the name list of an object file (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +nm \fB[\fR\(miAPv\fB] [\fR\(mig|\(miu\fB] [\fR\(mit \fIformat\fB] \fIfile\fR... +nm \fB[\fR\(miAPv\fB] [\fR\(miefox\fB] [\fR\(mig|\(miu\fB] [\fR\(mit \fIformat\fB]\fI file\fR... +.fi +.SH DESCRIPTION +The +.IR nm +utility shall display symbolic information appearing in the object +file, executable file, or object-file library named by +.IR file . +If no symbolic information is available for a valid input file, the +.IR nm +utility shall report that fact, but not consider it an error +condition. +.P +The default base used when numeric values are written is unspecified. +On XSI-conformant systems, it shall be decimal. +.SH OPTIONS +The +.IR nm +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(miA\fP" 10 +Write the full pathname or library name of an object on each line. +.IP "\fB\(mie\fP" 10 +Write only external (global) and static symbol information. +.IP "\fB\(mif\fP" 10 +Produce full output. Write redundant symbols (\c +.BR .text , +.BR .data , +and +.BR .bss ), +normally suppressed. +.IP "\fB\(mig\fP" 10 +Write only external (global) symbol information. +.IP "\fB\(mio\fP" 10 +Write numeric values in octal (equivalent to +.BR "\(mit\ o" ). +.IP "\fB\(miP\fP" 10 +Write information in a portable output format, as specified in the +STDOUT section. +.IP "\fB\(mit\ \fIformat\fR" 10 +Write each numeric value in the specified format. The format shall be +dependent on the single character used as the +.IR format +option-argument: +.RS 10 +.IP "\fRd\fR" 6 +The offset is written in decimal +(default). +.IP "\fRo\fR" 6 +The offset is written in octal. +.IP "\fRx\fR" 6 +The offset is written in hexadecimal. +.RE +.IP "\fB\(miu\fP" 10 +Write only undefined symbols. +.IP "\fB\(miv\fP" 10 +Sort output by value instead of by symbol name. +.IP "\fB\(mix\fP" 10 +Write numeric values in hexadecimal (equivalent to +.BR "\(mit\ x" ). +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an object file, executable file, or object-file library. +.SH STDIN +See the INPUT FILES section. +.SH "INPUT FILES" +The input file shall be an object file, an object-file library whose +format is the same as those produced by the +.IR ar +utility for link editing, or an executable file. The +.IR nm +utility may accept additional implementation-defined object library +formats for the input file. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR nm : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for character collation information for the +symbol-name and symbol-value collation sequences. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If symbolic information is present in the input files, then for each +file or for each member of an archive, the +.IR nm +utility shall write the following information to standard output. By +default, the format is unspecified, but the output shall be sorted by +symbol name according to the collation sequence in the current locale. +.IP " *" 4 +Library or object name, if +.BR \(miA +is specified +.IP " *" 4 +Symbol name +.IP " *" 4 +Symbol type, which shall either be one of the following single +characters or an implementation-defined type represented by a single +character: +.RS 4 +.IP "\fRA\fR" 6 +Global absolute symbol. +.IP "\fRa\fR" 6 +Local absolute symbol. +.IP "\fRB\fR" 6 +Global ``bss'' (that is, uninitialized data space) symbol. +.IP "\fRb\fR" 6 +Local bss symbol. +.IP "\fRD\fR" 6 +Global data symbol. +.IP "\fRd\fR" 6 +Local data symbol. +.IP "\fRT\fR" 6 +Global text symbol. +.IP "\fRt\fR" 6 +Local text symbol. +.IP "\fRU\fR" 6 +Undefined symbol. +.RE +.IP " *" 4 +Value of the symbol +.IP " *" 4 +The size associated with the symbol, if applicable +.P +This information may be supplemented by additional information specific +to the implementation. +.P +If the +.BR \(miP +option is specified, the previous information shall be displayed using +the following portable format. The three versions differ depending on +whether +.BR "\(mit\ d" , +.BR "\(mit\ o" , +or +.BR "\(mit\ x" +was specified, respectively: +.sp +.RS 4 +.nf +\fB +"%s%s %s %d %d\en", <\fIlibrary/object name\fR>, <\fIname\fR>, <\fItype\fR>, + <\fIvalue\fR>, <\fIsize\fR> +.P +"%s%s %s %o %o\en", <\fIlibrary/object name\fR>, <\fIname\fR>, <\fItype\fR>, + <\fIvalue\fR>, <\fIsize\fR> +.P +"%s%s %s %x %x\en", <\fIlibrary/object name\fR>, <\fIname\fR>, <\fItype\fR>, + <\fIvalue\fR>, <\fIsize\fR> +.fi \fR +.P +.RE +where <\fIlibrary/object\ name\fP> shall be formatted as follows: +.IP " *" 4 +If +.BR \(miA +is not specified, <\fIlibrary/object\ name\fP> shall be an empty string. +.IP " *" 4 +If +.BR \(miA +is specified and the corresponding +.IR file +operand does not name a library: +.RS 4 +.sp +.RS 4 +.nf +\fB +"%s: ", <\fIfile\fR> +.fi \fR +.P +.RE +.RE +.IP " *" 4 +If +.BR \(miA +is specified and the corresponding +.IR file +operand names a library. In this case, <\fIobject\ file\fP> shall name +the object file in the library containing the symbol being described: +.RS 4 +.sp +.RS 4 +.nf +\fB +"%s[%s]: ", <\fIfile\fR>, <\fIobject file\fR> +.fi \fR +.P +.RE +.RE +.P +If +.BR \(miA +is not specified, then if more than one +.IR file +operand is specified or if only one +.IR file +operand is specified and it names a library, +.IR nm +shall write a line identifying the object containing the following +symbols before the lines containing those symbols, in the form: +.IP " *" 4 +If the corresponding +.IR file +operand does not name a library: +.RS 4 +.sp +.RS 4 +.nf +\fB +"%s:\en", <\fIfile\fR> +.fi \fR +.P +.RE +.RE +.IP " *" 4 +If the corresponding +.IR file +operand names a library; in this case, <\fIobject\ file\fP> shall be +the name of the file in the library containing the following symbols: +.RS 4 +.sp +.RS 4 +.nf +\fB +"%s[%s]:\en", <\fIfile\fR>, <\fIobject file\fR> +.fi \fR +.P +.RE +.RE +.P +If +.BR \(miP +is specified, but +.BR \(mit +is not, the format shall be as if +.BR "\(mit\ x" +had been specified. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Mechanisms for dynamic linking make this utility less meaningful when +applied to an executable file because a dynamically linked executable +may omit numerous library routines that would be found in a statically +linked executable. +.SH EXAMPLES +None. +.SH RATIONALE +Historical implementations of +.IR nm +have used different bases for numeric output and supplied different +default types of symbols that were reported. The +.BR \(mit +.IR format +option, similar to that used in +.IR od +and +.IR strings , +can be used to specify the numeric base; +.BR \(mig +and +.BR \(miu +can be used to restrict the amount of output or the types of symbols +included in the output. +.P +The compromise of using +.BR \(mit +.IR format +\fIversus\fP using +.BR \(mid , +.BR \(mio , +and other similar options was necessary because of differences in the +meaning of +.BR \(mio +between implementations. The +.BR \(mio +option from BSD has been provided here as +.BR \(miA +to avoid confusion with the +.BR \(mio +from System V (which has been provided here as +.BR \(mit +and as +.BR \(mio +on XSI-conformant systems). +.P +The option list was significantly reduced from that provided by +historical implementations. +.P +The +.IR nm +description is a subset of both the System V and BSD +.IR nm +utilities with no specified default output. +.P +It was recognized that mechanisms for dynamic linking make this utility +less meaningful when applied to an executable file (because a +dynamically linked executable file may omit numerous library routines +that would be found in a statically linked executable file), but the +value of +.IR nm +during software development was judged to outweigh other limitations. +.P +The default output format of +.IR nm +is not specified because of differences in historical implementations. +The +.BR \(miP +option was added to allow some type of portable output format. After a +comparison of the different formats used in SunOS, BSD, SVR3, and SVR4, +it was decided to create one that did not match the current format of +any of these four systems. The format devised is easy to parse by +humans, easy to parse in shell scripts, and does not need to vary +depending on locale (because no English descriptions are included). +All of the systems currently have the information available to use this +format. +.P +The format given in +.IR nm +STDOUT uses + +characters between the fields, which may be any number of + +characters required to align the columns. The single-character types +were selected to match historical practice, and the requirement that +implementation additions also be single characters made parsing the +information easier for shell scripts. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIar\fR\^", +.IR "\fIc99\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/nohup.1p b/man-pages-posix-2013/man1p/nohup.1p new file mode 100644 index 0000000..13e18f5 --- /dev/null +++ b/man-pages-posix-2013/man1p/nohup.1p @@ -0,0 +1,311 @@ +'\" et +.TH NOHUP "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +nohup +\(em invoke a utility immune to hangups +.SH SYNOPSIS +.LP +.nf +nohup \fIutility \fB[\fIargument\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR nohup +utility shall invoke the utility named by the +.IR utility +operand with arguments supplied as the +.IR argument +operands. At the time the named +.IR utility +is invoked, the SIGHUP signal shall be set to be ignored. +.P +If standard input is associated with a terminal, the +.IR nohup +utility may redirect standard input from an unspecified file. +.P +If the standard output is a terminal, all output written by the named +.IR utility +to its standard output shall be appended to the end of the file +.BR nohup.out +in the current directory. If +.BR nohup.out +cannot be created or opened for appending, the output shall be appended +to the end of the file +.BR nohup.out +in the directory specified by the +.IR HOME +environment variable. If neither file can be created or opened for +appending, +.IR utility +shall not be invoked. If a file is created, the file's permission bits +shall be set to S_IRUSR | S_IWUSR. +.P +If standard error is a terminal and standard output is open but is not +a terminal, all output written by the named utility to its standard +error shall be redirected to the same open file description as the +standard output. If standard error is a terminal and standard output +either is a terminal or is closed, the same output shall instead be +appended to the end of the +.BR nohup.out +file as described above. +.SH OPTIONS +None. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIutility\fR" 10 +The name of a utility that is to be invoked. If the +.IR utility +operand names any of the special built-in utilities in +.IR "Section 2.14" ", " "Special Built-In Utilities", +the results are undefined. +.IP "\fIargument\fR" 10 +Any string to be supplied as an argument when invoking the utility +named by the +.IR utility +operand. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR nohup : +.IP "\fIHOME\fP" 10 +Determine the pathname of the user's home directory: if the output +file +.BR nohup.out +cannot be created in the current directory, the +.IR nohup +utility shall use the directory named by +.IR HOME +to create the file. +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPATH\fP" 10 +Determine the search path that is used to locate the utility to be +invoked. See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +.SH "ASYNCHRONOUS EVENTS" +The +.IR nohup +utility shall take the standard action for all signals except that +SIGHUP shall be ignored. +.SH STDOUT +If the standard output is not a terminal, the standard output of +.IR nohup +shall be the standard output generated by the execution of the +.IR utility +specified by the operands. Otherwise, nothing shall be written to the +standard output. +.SH STDERR +If the standard output is a terminal, a message shall be written to the +standard error, indicating the name of the file to which the output is +being appended. The name of the file shall be either +.BR nohup.out +or +.BR $HOME/nohup.out . +.SH "OUTPUT FILES" +Output written by the named utility is appended to the file +.BR nohup.out +(or +.BR $HOME/nohup.out ), +if the conditions hold as described in the DESCRIPTION. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP 126 8 +The utility specified by +.IR utility +was found but could not be invoked. +.IP 127 8 +An error occurred in the +.IR nohup +utility or the utility specified by +.IR utility +could not be found. +.P +Otherwise, the exit status of +.IR nohup +shall be that of the utility specified by the +.IR utility +operand. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR command , +.IR env , +.IR nice , +.IR nohup , +.IR time , +and +.IR xargs +utilities have been specified to use exit code 127 if an error occurs +so that applications can distinguish ``failure to find a utility'' from +``invoked utility exited with an error indication''. The value 127 was +chosen because it is not commonly used for other meanings; most +utilities use small values for ``normal error conditions'' and the +values above 128 can be confused with termination due to receipt of a +signal. The value 126 was chosen in a similar manner to indicate that +the utility could be found, but not invoked. Some scripts produce +meaningful error messages differentiating the 126 and 127 cases. The +distinction between exit codes 126 and 127 is based on KornShell +practice that uses 127 when all attempts to +.IR exec +the utility fail with +.BR [ENOENT] , +and uses 126 when any attempt to +.IR exec +the utility fails for any other reason. +.SH EXAMPLES +It is frequently desirable to apply +.IR nohup +to pipelines or lists of commands. This can be done by placing +pipelines and command lists in a single file; this file can then be +invoked as a utility, and the +.IR nohup +applies to everything in the file. +.P +Alternatively, the following command can be used to apply +.IR nohup +to a complex command: +.sp +.RS 4 +.nf +\fB +nohup sh \(mic '\fIcomplex-command-line\fP' +(\c +.BR '*' ). +.IP "\fB\(mix\fP" 10 +Interpret +.IR word s +(two-byte units) in hexadecimal. This shall be equivalent to +.BR "\(mit\ x2" . +.P +Multiple types can be specified by using multiple +.BR \(mibcdostx +options. Output lines are written for each type specified in the order +in which the types are specified. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file to be read. If no +.IR file +operands are specified, the standard input shall be used. +.RS 10 +.P +If there are no more than two operands, none of the +.BR \(miA , +.BR \(mij , +.BR \(miN , +.BR \(mit , +or +.BR \(miv +options is specified, and either of the following is true: the first +character of the last operand is a + +(\c +.BR '\(pl' ), +or there are two operands and the first character of the last operand +is numeric; +the last operand shall be interpreted as an offset operand on +XSI-conformant systems. +Under these conditions, the results are unspecified on systems that are +not XSI-conformant systems. +.RE +.IP "\fB[+]\fIoffset\fB[.][b]\fR" 10 +The +.IR offset +operand specifies the offset in the file where dumping is to commence. +This operand is normally interpreted as octal bytes. If +.BR '.' +is appended, the offset shall be interpreted in decimal. If +.BR 'b' +is appended, the offset shall be interpreted in units of 512 bytes. +.SH STDIN +The standard input shall be used if no +.IR file +operands are specified, and shall be used if a +.IR file +operand is +.BR '\(mi' +and the implementation treats the +.BR '\(mi' +as meaning standard input. +Otherwise, the standard input shall not be used. +See the INPUT FILES section. +.SH "INPUT FILES" +The input files can be any file type. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR od : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILC_NUMERIC\fP" 10 +.br +Determine the locale for selecting the radix character used when +writing floating-point formatted output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +See the EXTENDED DESCRIPTION section. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +The +.IR od +utility shall copy sequentially each input file to standard output, +transforming the input data according to the output types specified by +the +.BR \(mit +option +or the +.BR \(mibcdosx +options. +If no output type is specified, the default output shall be as if +.BR "\(mit\ oS" +had been specified. +.P +The number of bytes transformed by the output type specifier +.BR c +may be variable depending on the +.IR LC_CTYPE +category. +.P +The default number of bytes transformed by output type specifiers +.BR d , +.BR f , +.BR o , +.BR u , +and +.BR x +corresponds to the various C-language types as follows. If the +.IR c99 +compiler is present on the system, these specifiers shall correspond to +the sizes used by default in that compiler. Otherwise, these sizes +may vary among systems that conform to POSIX.1\(hy2008. +.IP " *" 4 +For the type specifier characters +.BR d , +.BR o , +.BR u , +and +.BR x , +the default number of bytes shall correspond to the size of the +underlying implementation's basic integer type. For these specifier +characters, the implementation shall support values of the optional +number of bytes to be converted corresponding to the number of bytes in +the C-language types +.BR char , +.BR short , +.BR int , +and +.BR long . +These numbers can also be specified by an application as the characters +.BR 'C' , +.BR 'S' , +.BR 'I' , +and +.BR 'L' , +respectively. The implementation shall also support the values 1, 2, 4, +and 8, even if it provides no C-Language types of those sizes. The +implementation shall support the decimal value corresponding to the +C-language type +.BR "long long" . +The byte order used when interpreting numeric values is +implementation-defined, but shall correspond to the order in which a +constant of the corresponding type is stored in memory on the system. +.IP " *" 4 +For the type specifier character +.BR f , +the default number of bytes shall correspond to the number of bytes in +the underlying implementation's basic double precision floating-point +data type. The implementation shall support values of the optional +number of bytes to be converted corresponding to the number of bytes in +the C-language types +.BR float, +.BR double , +and +.BR "long double" . +These numbers can also be specified by an application as the characters +.BR 'F' , +.BR 'D' , +and +.BR 'L' , +respectively. +.P +The type specifier character +.BR a +specifies that bytes shall be interpreted as named characters from the +International Reference Version (IRV) of the ISO/IEC\ 646:\|1991 standard. Only the least +significant seven bits of each byte shall be used for this type +specification. Bytes with the values listed in the following table +shall be written using the corresponding names for those characters. +.br +.sp +.ce 1 +\fBTable: Named Characters in \fIod\fP\fR +.TS +center box tab(@); +cB cB | cB cB | cB cB | cB cB +l lb | l lb | l lb | l lb. +Value@Name@Value@Name@Value@Name@Value@Name +_ +\e000@nul@\e001@soh@\e002@stx@\e003@etx +\e004@eot@\e005@enq@\e006@ack@\e007@bel +\e010@bs@\e011@ht@\e012@lf \fRor\fP nl\u\s-3*\s+3\d@\e013@vt +\e014@ff@\e015@cr@\e016@so@\e017@si +\e020@dle@\e021@dc1@\e022@dc2@\e023@dc3 +\e024@dc4@\e025@nak@\e026@syn@\e027@etb +\e030@can@\e031@em@\e032@sub@\e033@esc +\e034@fs@\e035@gs@\e036@rs@\e037@us +\e040@sp@\e177@del +.TE +.TP 10 +.BR Note: +The +.BR \(dq\e012\(dq +value may be written either as +.BR lf +or +.BR nl . +.P +.P +The type specifier character +.BR c +specifies that bytes shall be interpreted as characters specified by +the current setting of the +.IR LC_CTYPE +locale category. Characters listed in the table in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation" +(\c +.BR '\e\e' , +.BR '\ea' , +.BR '\eb' , +.BR '\ef' , +.BR '\en' , +.BR '\er' , +.BR '\et' , +.BR '\ev' ) +shall be written as the corresponding escape sequences, except that + +shall be written as a single + +and a NUL shall be written as +.BR '\e0' . +Other non-printable characters shall be written as one three-digit +octal number for each byte in the character. Printable multi-byte +characters shall be written in the area corresponding to the first byte +of the character; the two-character sequence +.BR \(dq**\(dq +shall be written in the area corresponding to each remaining byte in +the character, as an indication that the character is continued. When +either the +.BR \(mij +.IR skip +or +.BR \(miN +.IR count +option is specified along with the +.BR c +type specifier, and this results in an attempt to start or finish in +the middle of a multi-byte character, the result is +implementation-defined. +.P +The input data shall be manipulated in blocks, where a block is defined +as a multiple of the least common multiple of the number of bytes +transformed by the specified output types. If the least common +multiple is greater than 16, the results are unspecified. Each input +block shall be written as transformed by each output type, one per +written line, in the order that the output types were specified. If +the input block size is larger than the number of bytes transformed by +the output type, the output type shall sequentially transform the parts +of the input block, and the output from each of the transformations +shall be separated by one or more + +characters. +.P +If, as a result of the specification of the +.BR \(miN +option or end-of-file being reached on the last input file, input data +only partially satisfies an output type, the input shall be extended +sufficiently with null bytes to write the last byte of the input. +.P +Unless +.BR "\(miA\ n" +is specified, the first output line produced for each input block shall +be preceded by the input offset, cumulative across input files, of the +next byte to be written. The format of the input offset is unspecified; +however, it shall not contain any + +characters, shall start at the first character of the output line, +and shall be followed by one or more + +characters. In addition, the offset of the byte following the last byte +written shall be written after all the input data has been processed, +but shall not be followed by any + +characters. +.P +If no +.BR \(miA +option is specified, the input offset base is unspecified. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All input files were processed successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +XSI-conformant applications are warned not to use filenames starting +with +.BR '\(pl' +or a first operand starting with a numeric character so that the old +functionality can be maintained by implementations, unless they specify +one of the +.BR \(miA , +.BR \(mij , +or +.BR \(miN +options. To guarantee that one of these filenames is always +interpreted as a filename, an application could always specify the +address base format with the +.BR \(miA +option. +.SH EXAMPLES +If a file containing 128 bytes with decimal values zero to 127, in +increasing order, is supplied as standard input to the command: +.sp +.RS 4 +.nf +\fB +od \(miA d \(mit a +.fi \fR +.P +.RE +.P +on an implementation using an input block size of 16 bytes, the +standard output, independent of the current locale setting, would be +similar to: +.sp +.RS 4 +.nf +\fB +0000000 nul soh stx etx eot enq ack bel bs ht nl vt ff cr so si +0000016 dle dc1 dc2 dc3 dc4 nak syn etb can em sub esc fs gs rs us +0000032 sp ! " # $ % & ' ( ) * + , \(mi . / +0000048 0 1 2 3 4 5 6 7 8 9 : ; < = > ? +0000064 @ A B C D E F G H I J K L M N O +0000080 P Q R S T U V W X Y Z [ \e ] ^ _ +0000096 ` a b c d e f g h i j k l m n o +0000112 p q r s t u v w x y z { | } ~ del +0000128 +.fi \fR +.P +.RE +.P +Note that this volume of POSIX.1\(hy2008 allows +.BR nl +or +.BR lf +to be used as the name for the ISO/IEC\ 646:\|1991 standard IRV character with decimal value +10. The IRV names this character +.BR lf +(line feed), but traditional implementations have referred to this +character as newline +(\c +.BR nl ) +and the POSIX locale character set symbolic name for the corresponding +character is a +. +.P +The command: +.sp +.RS 4 +.nf +\fB +od \(miA o \(mit o2x2x \(miN 18 +.fi \fR +.P +.RE +.P +on a system with 32-bit words and an implementation using an input +block size of 16 bytes could write 18 bytes in approximately the +following format: +.sp +.RS 4 +.nf +\fB +0000000 032056 031440 041123 042040 052516 044530 020043 031464 + 342e 3320 4253 4420 554e 4958 2023 3334 + 342e3320 42534420 554e4958 20233334 +0000020 032472 + 353a + 353a0000 +0000022 +.fi \fR +.P +.RE +.P +The command: +.sp +.RS 4 +.nf +\fB +od \(miA d \(mit f \(mit o4 \(mit x4 \(miN 24 \(mij 0x15 +.fi \fR +.P +.RE +.P +on a system with 64-bit doubles (for example, IEEE\ Std\ 754\(hy1985 double +precision floating-point format) would skip 21 bytes of input data and +then write 24 bytes in approximately the following format: +.sp +.RS 4 +.nf +\fB +0000000 1.00000000000000e+00 1.57350000000000e+01 + 07774000000 00000000000 10013674121 35341217270 + 3ff00000 00000000 402f3851 eb851eb8 +0000016 1.40668230000000e+02 + 10030312542 04370303230 + 40619562 23e18698 +0000024 +.fi \fR +.P +.RE +.SH RATIONALE +The +.IR od +utility went through several names in early proposals, including +.IR hd , +.IR xd , +and most recently +.IR hexdump . +There were several objections to all of these based on the following +reasons: +.IP " *" 4 +The +.IR hd +and +.IR xd +names conflicted with historical utilities that behaved differently. +.IP " *" 4 +The +.IR hexdump +description was much more complex than needed for a simple dump +utility. +.IP " *" 4 +The +.IR od +utility has been available on all historical implementations and there +was no need to create a new name for a utility so similar to the +historical +.IR od +utility. +.P +The original reasons for not standardizing historical +.IR od +were also fairly widespread. Those reasons are given below along with +rationale explaining why the standard developers believe that this +version does not suffer from the indicated problem: +.IP " *" 4 +The BSD and System V versions of +.IR od +have diverged, and the intersection of features provided by both does +not meet the needs of the user community. In fact, the System V +version only provides a mechanism for dumping octal bytes and +.BR short s, +signed and unsigned decimal +.BR short s, +hexadecimal +.BR short s, +and ASCII characters. BSD added the ability to dump +.BR float s, +.BR double s, +named ASCII characters, and octal, signed decimal, unsigned decimal, +and hexadecimal +.BR long s. +The version presented here provides more normalized forms for dumping +bytes, +.BR short s, +.BR int s, +and +.BR long s +in octal, signed decimal, unsigned decimal, and hexadecimal; +.BR float , +.BR double , +and +.BR "long double" ; +and named ASCII as well as current locale characters. +.IP " *" 4 +It would not be possible to come up with a compatible superset of the +BSD and System V flags that met the requirements of the standard +developers. The historical default +.IR od +output is the specified default output of this utility. None of the +option letters chosen for this version of +.IR od +conflict with any of the options to historical versions of +.IR od . +.IP " *" 4 +On systems with different sizes for +.BR short , +.BR int , +and +.BR long , +there was no way to ask for dumps of +.BR int s, +even in the BSD version. Because of the way options are named, the +name space could not be extended to solve these problems. This is why +the +.BR \(mit +option was added (with type specifiers more closely matched to the +\fIprintf\fR() +formats used in the rest of this volume of POSIX.1\(hy2008) and the optional field sizes were +added to the +.BR d , +.BR f , +.BR o , +.BR u , +and +.BR x +type specifiers. It is also one of the reasons why the historical +practice was not mandated as a required obsolescent form of +.IR od . +(Although the old versions of +.IR od +are not listed as an obsolescent form, implementations are urged to +continue to recognize the older forms for several more years.) The +.BR a , +.BR c , +.BR f , +.BR o , +and +.BR x +types match the meaning of the corresponding format characters in the +historical implementations of +.IR od +except for the default sizes of the fields converted. The +.BR d +format is signed in this volume of POSIX.1\(hy2008 to match the +\fIprintf\fR() +notation. (Historical versions of +.IR od +used +.BR d +as a synonym for +.BR u +in this version. The System V implementation uses +.BR s +for signed decimal; BSD uses +.BR i +for signed decimal and +.BR s +for null-terminated strings.) Other than +.BR d +and +.BR u , +all of the type specifiers match format characters in the historical +BSD version of +.BR od . +.RS 4 +.P +The sizes of the C-language types +.BR char , +.BR short , +.BR int , +.BR long , +.BR float , +.BR double , +and +.BR "long double" +are used even though it is recognized that there may be zero or more +than one compiler for the C language on an implementation and that they +may use different sizes for some of these types. (For example, one +compiler might use 2 bytes +.BR short s, +2 bytes +.BR int s, +and 4 bytes +.BR long s, +while another compiler (or an option to the same compiler) uses 2 bytes +.BR short s, +4 bytes +.BR int s, +and 4 bytes +.BR long s.) +Nonetheless, there has to be a basic size known by the implementation +for these types, corresponding to the values reported by invocations of +the +.IR getconf +utility when called with +.IR system_var +operands +{UCHAR_MAX}, +{USHORT_MAX}, +{UINT_MAX}, +and +{ULONG_MAX} +for the types +.BR char , +.BR short , +.BR int , +and +.BR long , +respectively. There are similar constants required by the ISO\ C standard, but +not required by the System Interfaces volume of POSIX.1\(hy2008 or this volume of POSIX.1\(hy2008. They are +{FLT_MANT_DIG}, +{DBL_MANT_DIG}, +and +{LDBL_MANT_DIG} +for the types +.BR float , +.BR double , +and +.BR "long double" , +respectively. If the optional +.IR c99 +utility is provided by the implementation and used as specified by +\&this volume of POSIX.1\(hy2008, these are the sizes that would be provided. If an option is used +that specifies different sizes for these types, there is no guarantee +that the +.IR od +utility is able to interpret binary data output by such a program +correctly. +.P +This volume of POSIX.1\(hy2008 requires that the numeric values of these lengths be recognized +by the +.IR od +utility and that symbolic forms also be recognized. Thus, a conforming +application can always look at an array of +.BR "unsigned long" +data elements using +.IR od +.BR \(mit +.IR uL . +.RE +.IP " *" 4 +The method of specifying the format for the address field based on +specifying a starting offset in a file unnecessarily tied the two +together. The +.BR \(miA +option now specifies the address base and the +.BR \(miS +option specifies a starting offset. +.IP " *" 4 +It would be difficult to break the dependence on US ASCII to achieve +an internationalized utility. It does not seem to be any harder for +.IR od +to dump characters in the current locale than it is for the +.IR ed +or +.IR sed +.BR l +commands. The +.BR c +type specifier does this without difficulty and is completely +compatible with the historical implementations of the +.BR c +format character when the current locale uses a superset of the ISO/IEC\ 646:\|1991 standard +as a codeset. The +.BR a +type specifier (from the BSD +.BR a +format character) was left as a portable means to dump ASCII (or more +correctly ISO/IEC\ 646:\|1991 standard (IRV)) so that headers produced by +.IR pax +could be deciphered even on systems that do not use the ISO/IEC\ 646:\|1991 standard as a +subset of their base codeset. +.P +The use of +.BR \(dq**\(dq +as an indication of continuation of a multi-byte character in +.BR c +specifier output was chosen based on seeing an implementation that uses +this method. The continuation bytes have to be marked in a way that is +not ambiguous with another single-byte or multi-byte character. +.P +An early proposal used +.BR \(miS +and +.BR \(min , +respectively, for the +.BR \(mij +and +.BR \(miN +options eventually selected. These were changed to avoid conflicts with +historical implementations. +.P +The original standard specified +.BR "\(mit o2" +as the default when no output type was given. This was changed to +.BR "\(mit oS" +(the length of a +.BR short ) +to accommodate a supercomputer implementation that historically used 64 +bits as its default (and that defined shorts as 64 bits). This change +should not affect conforming applications. The requirement to support +lengths of 1, 2, and 4 was added at the same time to address an +historical implementation that had no two-byte data types in its C +compiler. +.P +The use of a basic integer data type is intended to allow the +implementation to choose a word size commonly used by applications +on that architecture. +.P +Earlier versions of this standard allowed for implementations with +bytes other than eight bits, but this has been modified in this +version. +.SH "FUTURE DIRECTIONS" +All option and operand interfaces marked XSI may be removed +in a future version. +.SH "SEE ALSO" +.IR "\fIc99\fR\^", +.IR "\fIsed\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/paste.1p b/man-pages-posix-2013/man1p/paste.1p new file mode 100644 index 0000000..10e9e64 --- /dev/null +++ b/man-pages-posix-2013/man1p/paste.1p @@ -0,0 +1,365 @@ +'\" et +.TH PASTE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +paste +\(em merge corresponding or subsequent lines of files +.SH SYNOPSIS +.LP +.nf +paste \fB[\fR\(mis\fB] [\fR\(mid \fIlist\fB] \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR paste +utility shall concatenate the corresponding lines of the given input +files, and write the resulting lines to standard output. +.P +The default operation of +.IR paste +shall concatenate the corresponding lines of the input files. The + +of every line except the line from the last input file shall be +replaced with a +. +.P +If an end-of-file condition is detected on one or more input files, but +not all input files, +.IR paste +shall behave as though empty lines were read from the files on which +end-of-file was detected, unless the +.BR \(mis +option is specified. +.SH OPTIONS +The +.IR paste +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mid\ \fIlist\fR" 10 +Unless a + +character appears in +.IR list , +each character in +.IR list +is an element specifying a delimiter character. If a + +character appears in +.IR list , +the + +character and one or more characters following it are an element +specifying a delimiter character as described below. These elements +specify one or more delimiters to use, instead of the default +, +to replace the + +of the input lines. The elements in +.IR list +shall be used circularly; that is, when the list is exhausted the first +element from the list is reused. When the +.BR \(mis +option is specified: +.RS 10 +.IP " *" 4 +The last + +in a file shall not be modified. +.IP " *" 4 +The delimiter shall be reset to the first element of +.IR list +after each +.IR file +operand is processed. +.P +When the +.BR \(mis +option is not specified: +.IP " *" 4 +The + +characters in the file specified by the last +.IR file +operand shall not be modified. +.IP " *" 4 +The delimiter shall be reset to the first element of list each time a +line is processed from each file. +.P +If a + +character appears in +.IR list , +it and the character following it shall be used to represent the +following delimiter characters: +.IP "\fR\en\fR" 6 +. +.IP "\fR\et\fR" 6 +. +.IP "\fR\e\e\fR" 6 + +character. +.IP "\fR\e0\fR" 6 +Empty string (not a null character). If +.BR '\e0' +is immediately followed by the character +.BR 'x' , +the character +.BR 'X' , +or any character defined by the +.IR LC_CTYPE +.BR digit +keyword (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale"), +the results are unspecified. +.P +If any other characters follow the +, +the results are unspecified. +.RE +.IP "\fB\(mis\fP" 10 +Concatenate all of the lines of each separate input file in command +line order. The + +of every line except the last line in each input file shall be replaced +with the +, +unless otherwise specified by the +.BR \(mid +option. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an input file. If +.BR '\(mi' +is specified for one or more of the +.IR file s, +the standard input shall be used; the standard input shall be read one +line at a time, circularly, for each instance of +.BR '\(mi' . +Implementations shall support pasting of at least 12 +.IR file +operands. +.SH STDIN +The standard input shall be used only if one or more +.IR file +operands is +.BR '\(mi' . +See the INPUT FILES section. +.SH "INPUT FILES" +The input files shall be text files, except that line lengths shall be +unlimited. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR paste : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Concatenated lines of input files shall be separated by the + +(or other characters under the control of the +.BR \(mid +option) and terminated by a +. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If one or more input files cannot be opened when the +.BR \(mis +option is not specified, a diagnostic message shall be written to +standard error, but no output is written to standard output. If the +.BR \(mis +option is specified, the +.IR paste +utility shall provide the default behavior described in +.IR "Section 1.4" ", " "Utility Description Defaults". +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +When the escape sequences of the +.IR list +option-argument are used in a shell script, they must be quoted; +otherwise, the shell treats the + +as a special character. +.P +Conforming applications should only use the specific +-escaped +delimiters presented in this volume of POSIX.1\(hy2008. Historical implementations treat +.BR '\ex' , +where +.BR 'x' +is not in this list, as +.BR 'x' , +but future implementations are free to expand this list to recognize +other common escapes similar to those accepted by +.IR printf +and other standard utilities. +.P +Most of the standard utilities work on text files. The +.IR cut +utility can be used to turn files with arbitrary line lengths into a +set of text files containing the same data. The +.IR paste +utility can be used to create (or recreate) files with arbitrary line +lengths. For example, if +.IR file +contains long lines: +.sp +.RS 4 +.nf +\fB +cut \(mib 1\(mi500 \(min file > file1 +cut \(mib 501\(mi \(min file > file2 +.fi \fR +.P +.RE +.P +creates +.BR file1 +(a text file) with lines no longer than 500 bytes (plus the +) +and +.BR file2 +that contains the remainder of the data from +.IR file . +Note that +.BR file2 +is not a text file if there are lines in +.IR file +that are longer than 500 + +{LINE_MAX} +bytes. The original file can be recreated from +.BR file1 +and +.BR file2 +using the command: +.sp +.RS 4 +.nf +\fB +paste \(mid "\e0" file1 file2 > file +.fi \fR +.P +.RE +.P +The commands: +.sp +.RS 4 +.nf +\fB +paste \(mid "\e0" ... +paste \(mid "" ... +.fi \fR +.P +.RE +.P +are not necessarily equivalent; the latter is not specified by this volume of POSIX.1\(hy2008 +and may result in an error. The construct +.BR '\e0' +is used to mean ``no separator'' because historical versions of +.IR paste +did not follow the syntax guidelines, and the command: +.sp +.RS 4 +.nf +\fB +paste \(mid"" ... +.fi \fR +.P +.RE +.P +could not be handled properly by +\fIgetopt\fR(). +.SH EXAMPLES +.IP " 1." 4 +Write out a directory in four columns: +.RS 4 +.sp +.RS 4 +.nf +\fB +ls | paste \(mi \(mi \(mi \(mi +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +Combine pairs of lines from a file into single lines: +.RS 4 +.sp +.RS 4 +.nf +\fB +paste \(mis \(mid "\et\en" file +.fi \fR +.P +.RE +.RE +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 1.4" ", " "Utility Description Defaults", +.IR "\fIcut\fR\^", +.IR "\fIgrep\fR\^", +.IR "\fIpr\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 7" ", " "Locale", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/patch.1p b/man-pages-posix-2013/man1p/patch.1p new file mode 100644 index 0000000..67243ba --- /dev/null +++ b/man-pages-posix-2013/man1p/patch.1p @@ -0,0 +1,713 @@ +'\" et +.TH PATCH "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +patch +\(em apply changes to files +.SH SYNOPSIS +.LP +.nf +patch \fB[\fR\(miblNR\fB] [\fR\(mic|\(mie|\(min|\(miu\fB] [\fR\(mid \fIdir\fB] [\fR\(miD \fIdefine\fB] [\fR\(mii \fIpatchfile\fB] + [\fR\(mio \fIoutfile\fB] [\fR\(mip \fInum\fB] [\fR\(mir \fIrejectfile\fB] [\fIfile\fB]\fR +.fi +.SH DESCRIPTION +The +.IR patch +utility shall read a source (patch) file containing any of four +forms of difference (diff) listings produced by the +.IR diff +utility (normal, copied context, unified context, or in the style of +.IR ed ) +and apply those differences to a file. By default, +.IR patch +shall read from the standard input. +.P +The +.IR patch +utility shall attempt to determine the type of the +.IR diff +listing, unless overruled by a +.BR \(mic , +.BR \(mie , +.BR \(min , +or +.BR \(miu +option. +.P +If the patch file contains more than one patch, +.IR patch +shall attempt to apply each of them as if they came from separate patch +files. (In this case, the application shall ensure that the name of the +patch file is determinable for each +.IR diff +listing.) +.SH OPTIONS +The +.IR patch +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mib\fP" 10 +Save a copy of the original contents of each modified file, before the +differences are applied, in a file of the same name with the suffix +.BR .orig +appended to it. If the file already exists, it shall be overwritten; +if multiple patches are applied to the same file, the +.BR .orig +file shall be written only for the first patch. When the +.BR \(mio +.IR outfile +option is also specified, +.IR file \c +.BR .orig +shall not be created but, if +.IR outfile +already exists, +.IR outfile \c +.BR .orig +shall be created. +.IP "\fB\(mic\fP" 10 +Interpret the patch file as a copied context difference (the output +of the utility +.IR diff +when the +.BR \(mic +or +.BR \(miC +options are specified). +.IP "\fB\(mid\ \fIdir\fR" 10 +Change the current directory to +.IR dir +before processing as described in the EXTENDED DESCRIPTION section. +.IP "\fB\(miD\ \fIdefine\fR" 10 +Mark changes with one of the following C preprocessor constructs: +.RS 10 +.sp +.RS 4 +.nf +\fB +#ifdef define +\&... +#endif +.P +#ifndef define +\&... +#endif +.fi \fR +.P +.RE +.P +optionally combined with the C preprocessor construct +.BR #else . +If the patched file is processed with the C preprocessor, where the +macro +.IR define +is defined, the output shall contain the changes from the patch file; +otherwise, the output shall not contain the patches specified in the +patch file. +.RE +.IP "\fB\(mie\fP" 10 +Interpret the patch file as an +.IR ed +script, rather than a +.IR diff +script. +.IP "\fB\(mii\ \fIpatchfile\fR" 10 +Read the patch information from the file named by the pathname +.IR patchfile , +rather than the standard input. +.IP "\fB\(mil\fP" 10 +(The letter ell.) Cause any sequence of + +characters in the difference script to match any sequence of + +characters in the input file. Other characters shall be matched exactly. +.IP "\fB\(min\fP" 10 +Interpret the script as a normal difference. +.IP "\fB\(miN\fP" 10 +Ignore patches where the differences have already been applied to the +file; by default, already-applied patches shall be rejected. +.IP "\fB\(mio\ \fIoutfile\fR" 10 +Instead of modifying the files (specified by the +.IR file +operand or the difference listings) directly, write a copy of the file +referenced by each patch, with the appropriate differences applied, to +.IR outfile . +Multiple patches for a single file shall be applied to the intermediate +versions of the file created by any previous patches, and shall result +in multiple, concatenated versions of the file being written to +.IR outfile . +.IP "\fB\(mip\ \fInum\fR" 10 +For all pathnames in the patch file that indicate the names of files to +be patched, delete +.IR num +pathname components from the beginning of each pathname. If the +pathname in the patch file is absolute, any leading + +characters shall be considered the first component (that is, +.BR "\(mip\ 1" +shall remove the leading + +characters). Specifying +.BR "\(mip\ 0" +shall cause the full pathname to be used. If +.BR \(mip +is not specified, only the basename (the final pathname component) +shall be used. +.IP "\fB\(miR\fP" 10 +Reverse the sense of the patch script; that is, assume that the +difference script was created from the new version to the old version. +The +.BR \(miR +option cannot be used with +.IR ed +scripts. The +.IR patch +utility shall attempt to reverse each portion of the script before +applying it. Rejected differences shall be saved in swapped format. If +this option is not specified, and until a portion of the patch file is +successfully applied, +.IR patch +attempts to apply each portion in its reversed sense as well as in its +normal sense. If the attempt is successful, the user shall be prompted +to determine whether the +.BR \(miR +option should be set. +.IP "\fB\(mir\ \fIrejectfile\fR" 10 +Override the default reject filename. In the default case, the reject +file shall have the same name as the output file, with the suffix +.BR .rej +appended to it; see +.IR "Patch Application". +.IP "\fB\(miu\fR" 10 +Interpret the patch file as a unified context difference (the output +of the +.IR diff +utility when the +.BR \(miu +or +.BR \(miU +options are specified). +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file to patch. +.SH STDIN +See the INPUT FILES section. +.SH "INPUT FILES" +Input files shall be text files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR patch : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements used in the extended regular +expression defined for the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of text +data as characters (for example, single-byte as opposed to multi-byte +characters in arguments and input files), and the behavior of character +classes used in the extended regular expression defined for the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale used to process affirmative responses, and the +locale used to affect the format and contents of diagnostic messages +and prompts written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fILC_TIME\fP" 10 +Determine the locale for recognizing the format of file timestamps +written by the +.IR diff +utility in a context-difference input file. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used for diagnostic and informational +messages. +.SH "OUTPUT FILES" +The output of the +.IR patch +utility, the save files (\c +.BR .orig +suffixes), and the reject files (\c +.BR .rej +suffixes) shall be text files. +.SH "EXTENDED DESCRIPTION" +A patch file may contain patching instructions for more than one file; +filenames shall be determined as specified in +.IR "Filename Determination". +When the +.BR \(mib +option is specified, for each patched file, the original shall be saved +in a file of the same name with the suffix +.BR .orig +appended to it. +.P +For each patched file, a reject file may also be created as noted in +.IR "Patch Application". +In the absence of a +.BR \(mir +option, the name of this file shall be formed by appending the suffix +.BR .rej +to the original filename. +.SS "Patch File Format" +.P +The patch file shall contain zero or more lines of header information +followed by one or more patches. Each patch shall contain zero or more +lines of filename identification in the format produced by the +.BR \(mic , +.BR \(miC , +.BR \(miu , +or +.BR \(miU +options of the +.IR diff +utility, and one or more sets of +.IR diff +output, which are customarily called \fIhunks\fP. +.P +The +.IR patch +utility shall recognize the following expression in the header +information: +.IP "\fBIndex:\ \fIpathname\fR" 6 +.br +The file to be patched is named +.IR pathname . +.P +If all lines (including headers) within a patch begin with the same +leading sequence of + +characters, the +.IR patch +utility shall remove this sequence before proceeding. Within each +patch, if the type of difference is common context, the +.IR patch +utility shall recognize the following expressions: +.IP "***\ \fIfilename\ timestamp\fR" 6 +.br +The patches arose from +.IR filename . +.IP "\(mi\|\(mi\|\(mi\ \fIfilename\ timestamp\fR" 6 +.br +The patches should be applied to +.IR filename . +.P +If the type of difference is unified context, the +.IR patch +utility shall recognize the following expressions: +.IP "\(mi\|\(mi\|\(mi\ \fIfilename\ timestamp\fR" 6 +.br +The patches arose from +.IR filename . +.IP "+\|+\|+\ \fIfilename\ timestamp\fR" 6 +.br +The patches should be applied to +.IR filename . +.P +Each hunk within a patch shall be the +.IR diff +output to change a line range within the original file. The line +numbers for successive hunks within a patch shall occur in ascending +order. +.SS "Filename Determination" +.P +If no +.IR file +operand is specified, +.IR patch +shall perform the following steps to determine the filename to use: +.IP " 1." 4 +If the type of +.IR diff +is context, the +.IR patch +utility shall delete pathname components (as specified by the +.BR \(mip +option) from the filename on the line beginning with +.BR \(dq***\(dq +(if copied context) or +.BR \(dq\(mi\|\(mi\|\(mi\(dq +(if unified context), then test for the existence of this file relative +to the current directory (or the directory specified with the +.BR \(mid +option). If the file exists, the +.IR patch +utility shall use this filename. +.IP " 2." 4 +If the type of +.IR diff +is context, the +.IR patch +utility shall delete the pathname components (as specified by the +.BR \(mip +option) from the filename on the line beginning with +.BR \(dq\(mi\|\(mi\|\(mi\(dq +(if copied context) or +.BR \(dq+\|+\|+\(dq +(if unified context), then test for the existence of this file relative +to the current directory (or the directory specified with the +.BR \(mid +option). If the file exists, the +.IR patch +utility shall use this filename. +.IP " 3." 4 +If the header information contains a line beginning with the string +.BR Index: , +the +.IR patch +utility shall delete pathname components (as specified by the +.BR \(mip +option) from this line, then test for the existence of this file +relative to the current directory (or the directory specified with the +.BR \(mid +option). If the file exists, the +.IR patch +utility shall use this filename. +.IP " 4." 4 +If an +.BR SCCS +directory exists in the current directory, +.IR patch +shall attempt to perform a +.IR get +.BR \(mie +.BR SCCS/s. \c +.IR filename +command to retrieve an editable version of the file. If the file +exists, the +.IR patch +utility shall use this filename. +.IP " 5." 4 +The +.IR patch +utility shall write a prompt to standard output and request a filename +interactively from the controlling terminal (for example, +.BR /dev/tty ). +.SS "Patch Application" +.P +If the +.BR \(mic , +.BR \(mie , +.BR \(min , +or +.BR \(miu +option is present, the +.IR patch +utility shall interpret information within each hunk as a copied context +difference, an +.IR ed +difference, a normal difference, or a unified context difference, +respectively. In the absence of any of these options, the +.IR patch +utility shall determine the type of difference based on the format of +information within the hunk. +.P +For each hunk, the +.IR patch +utility shall begin to search for the place to apply the patch at the +line number at the beginning of the hunk, plus or minus any offset used +in applying the previous hunk. If lines matching the hunk context are +not found, +.IR patch +shall scan both forwards and backwards at least 1\|000 bytes for a set +of lines that match the hunk context. +.P +If no such place is found and it is a context difference, then another +scan shall take place, ignoring the first and last line of context. If +that fails, the first two and last two lines of context shall be +ignored and another scan shall be made. Implementations may search +more extensively for installation locations. +.P +If no location can be found, the +.IR patch +utility shall append the hunk to the reject file. A rejected hunk that +is a copied context difference, an +.IR ed +difference, or a normal difference shall be written in +copied-context-difference format regardless of the format of the patch +file. It is implementation-defined whether a rejected hunk that is +a unified context difference is written in copied-context-difference +format or in unified-context-difference format. +If the input was a normal or +.IR ed -style +difference, the reject file may contain differences with zero lines of +context. The line numbers on the hunks in the reject file may be +different from the line numbers in the patch file since they shall +reflect the approximate locations for the failed hunks in the new file +rather than the old one. +.P +If the type of patch is an +.IR ed +diff, the implementation may accomplish the patching by invoking the +.IR ed +utility. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP "\01" 6 +One or more lines were written to a reject file. +.IP >1 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Patches that cannot be correctly placed in the file shall be written to +a reject file. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.BR \(miR +option does not work with +.IR ed +scripts because there is too little information to reconstruct the +reverse operation. +.P +The +.BR \(mip +option makes it possible to customize a patch file to local user +directory structures without manually editing the patch file. For +example, if the filename in the patch file was: +.sp +.RS 4 +.nf +\fB +/curds/whey/src/blurfl/blurfl.c +.fi \fR +.P +.RE +.P +Setting +.BR "\(mip\ 0" +gives the entire pathname unmodified; +.BR "\(mip\ 1" +gives: +.sp +.RS 4 +.nf +\fB +curds/whey/src/blurfl/blurfl.c +.fi \fR +.P +.RE +.P +without the leading +, +.BR "\(mip\ 4" +gives: +.sp +.RS 4 +.nf +\fB +blurfl/blurfl.c +.fi \fR +.P +.RE +.P +and not specifying +.BR \(mip +at all gives: +.sp +.RS 4 +.nf +\fB +blurfl.c . +.fi \fR +.P +.RE +.SH EXAMPLES +None. +.SH RATIONALE +Some of the functionality in historical +.IR patch +implementations was not specified. The following documents those +features present in historical implementations that have not been +specified. +.P +A deleted piece of functionality was the +.BR '\(pl' +pseudo-option allowing an additional set of options and a patch file +operand to be given. This was seen as being insufficiently useful to +standardize. +.P +In historical implementations, if the string +.BR \(dqPrereq:\(dq +appeared in the header, the +.IR patch +utility would search for the corresponding version information (the +string specified in the header, delimited by + +characters or the beginning or end of a line or the file) anywhere in +the original file. This was deleted as too simplistic and insufficiently +trustworthy a mechanism to standardize. For example, if: +.sp +.RS 4 +.nf +\fB +Prereq: 1.2 +.fi \fR +.P +.RE +.P +were in the header, the presence of a delimited 1.2 anywhere in the +file would satisfy the prerequisite. +.P +The following options were dropped from historical implementations of +.IR patch +as insufficiently useful to standardize: +.IP "\fB\(mib\fP" 10 +The +.BR \(mib +option historically provided a method for changing the name extension +of the backup file from the default +.BR .orig . +This option has been modified and retained in this volume of POSIX.1\(hy2008. +.IP "\fB\(miF\fP" 10 +The +.BR \(miF +option specified the number of lines of a context diff to ignore when +searching for a place to install a patch. +.IP "\fB\(mif\fP" 10 +The +.BR \(mif +option historically caused +.IR patch +not to request additional information from the user. +.IP "\fB\(mir\fP" 10 +The +.BR \(mir +option historically provided a method of overriding the extension of +the reject file from the default +.BR .rej . +.IP "\fB\(mis\fP" 10 +The +.BR \(mis +option historically caused +.IR patch +to work silently unless an error occurred. +.IP "\fB\(mix\fP" 10 +The +.BR \(mix +option historically set internal debugging flags. +.P +In some file system implementations, the saving of a +.BR .orig +file may produce unwanted results. In the case of 12, 13, or +14-character filenames (on file systems supporting 14-character +maximum filenames), the +.BR .orig +file overwrites the new file. The reject file may also exceed this +filename limit. It was suggested, due to some historical practice, +that a + +(\c +.BR '~' ) +suffix be used instead of +.BR .orig +and some other character instead of the +.BR .rej +suffix. This was rejected because it is not obvious to the user which +file is which. The suffixes +.BR .orig +and +.BR .rej +are clearer and more understandable. +.P +The +.BR \(mib +option has the opposite sense in some historical implementations\(emdo +not save the +.BR .orig +file. The default case here is not to save the files, making +.IR patch +behave more consistently with the other standard utilities. +.P +The +.BR \(miw +option in early proposals was changed to +.BR \(mil +to match historical practice. +.P +The +.BR \(miN +option was included because without it, a non-interactive application +cannot reject previously applied patches. For example, if a user is +piping the output of +.IR diff +into the +.IR patch +utility, and the user only wants to patch a file to a newer version +non-interactively, the +.BR \(miN +option is required. +.P +Changes to the +.BR \(mil +option description were proposed to allow matching across + +characters in addition to just + +characters. Since this is not historical practice, and since some +ambiguities could result, it is suggested that future developments in +this area utilize another option letter, such as +.BR \(miL . +.P +The +.BR \(miu +option of GNU +.IR patch +has been added, along with support for unified context formats. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdiff\fR\^", +.IR "\fIed\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/pathchk.1p b/man-pages-posix-2013/man1p/pathchk.1p new file mode 100644 index 0000000..ce6862b --- /dev/null +++ b/man-pages-posix-2013/man1p/pathchk.1p @@ -0,0 +1,426 @@ +'\" et +.TH PATHCHK "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pathchk +\(em check pathnames +.SH SYNOPSIS +.LP +.nf +pathchk \fB[\fR\(mip\fB] [\fR\(miP\fB] \fIpathname\fR... +.fi +.SH DESCRIPTION +The +.IR pathchk +utility shall check that one or more pathnames are valid (that is, they +could be used to access or create a file without causing syntax errors) +and portable (that is, no filename truncation results). More +extensive portability checks are provided by the +.BR \(mip +and +.BR \(miP +options. +.P +By default, the +.IR pathchk +utility shall check each component of each +.IR pathname +operand based on the underlying file system. A diagnostic shall be +written for each +.IR pathname +operand that: +.IP " *" 4 +Is longer than +{PATH_MAX} +bytes (see +.BR "Pathname Variable Values" +in the Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP") +.IP " *" 4 +Contains any component longer than +{NAME_MAX} +bytes in its containing directory +.IP " *" 4 +Contains any component in a directory that is not searchable +.IP " *" 4 +Contains any byte sequence that is not valid in its +containing directory +.P +The format of the diagnostic message is not specified, but shall +indicate the error detected and the corresponding +.IR pathname +operand. +.P +It shall not be considered an error if one or more components of a +.IR pathname +operand do not exist as long as a file matching the pathname specified +by the missing components could be created that does not violate any of +the checks specified above. +.SH OPTIONS +The +.IR pathchk +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(mip\fP" 10 +Instead of performing checks based on the underlying file system, write +a diagnostic for each +.IR pathname +operand that: +.RS 10 +.IP " *" 4 +Is longer than +{_POSIX_PATH_MAX} +bytes (see +.BR "Minimum Values" +in the Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP") +.IP " *" 4 +Contains any component longer than +{_POSIX_NAME_MAX} +bytes +.IP " *" 4 +Contains any character in any component that is not in the portable +filename character set +.RE +.IP "\fB\(miP\fP" 10 +Write a diagnostic for each +.IR pathname +operand that: +.RS 10 +.IP " *" 4 +Contains a component whose first character is the + +character +.IP " *" 4 +Is empty +.RE +.SH OPERANDS +The following operand shall be supported: +.IP "\fIpathname\fR" 10 +A pathname to be checked. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR pathchk : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All +.IR pathname +operands passed all of the checks. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR test +utility can be used to determine whether a given pathname names an +existing file; it does not, however, give any indication of whether or +not any component of the pathname was truncated in a directory where +the _POSIX_NO_TRUNC feature is not in effect. The +.IR pathchk +utility does not check for file existence; it performs checks to +determine whether a pathname does exist or could be created with no +pathname component truncation. +.P +The +.IR noclobber +option in the shell (see the +.IR "\fIset\fR\^" +special built-in) can be used to atomically create a file. As with all +file creation semantics in the System Interfaces volume of POSIX.1\(hy2008, it guarantees atomic creation, +but still depends on applications to agree on conventions and cooperate +on the use of files after they have been created. +.P +To verify that a pathname meets the requirements of filename +portability, applications should use both the +.BR \(mip +and +.BR \(miP +options together. +.SH EXAMPLES +To verify that all pathnames in an imported data interchange archive +are legitimate and unambiguous on the current system: +.sp +.RS 4 +.nf +\fB +# This example assumes that no pathnames in the archive +# contain characters. +pax \(mif archive | sed \(mie 's/[^[:alnum:]]/\e\e&/g' | xargs pathchk \(mi\|\(mi +if [ $? \(mieq 0 ] +then + pax \(mir \(mif archive +else + echo Investigate problems before importing files. + exit 1 +fi +.fi \fR +.P +.RE +.P +To verify that all files in the current directory hierarchy could be +moved to any system conforming to the System Interfaces volume of POSIX.1\(hy2008 that also supports the +.IR pax +utility: +.sp +.RS 4 +.nf +\fB +find . \(miexec pathchk \(mip \(miP {} + +if [ $? \(mieq 0 ] +then + pax \(miw \(mif ../archive . +else + echo Portable archive cannot be created. + exit 1 +fi +.fi \fR +.P +.RE +.P +To verify that a user-supplied pathname names a readable file and that +the application can create a file extending the given path without +truncation and without overwriting any existing file: +.sp +.RS 4 +.nf +\fB +case $\(mi in + *C*) reset="";; + *) reset="set +C" + set \(miC;; +esac +test \(mir "$path" && pathchk "$path.out" && + rm "$path.out" > "$path.out" +if [ $? \(mine 0 ]; then + printf "%s: %s not found or %s.out fails \e +creation checks.\en" $0 "$path$path" + $reset # Reset the noclobber option in case a trap + # on EXIT depends on it. + exit 1 +fi +$reset +PROCESSING < "$path" > "$path.out" +.fi \fR +.P +.RE +.P +The following assumptions are made in this example: +.IP " 1." 4 +.BR PROCESSING +represents the code that is used by the application to use +.BR $path +once it is verified that +.BR $path.out +works as intended. +.IP " 2." 4 +The state of the +.IR noclobber +option is unknown when this code is invoked and should be set on exit +to the state it was in when this code was invoked. (The +.BR reset +variable is used in this example to restore the initial state.) +.IP " 3." 4 +Note the usage of: +.RS 4 +.sp +.RS 4 +.nf +\fB +rm "$path.out" > "$path.out" +.fi \fR +.P +.RE +.IP " a." 4 +The +.IR pathchk +command has already verified, at this point, that +.BR $path.out +is not truncated. +.IP " b." 4 +With the +.IR noclobber +option set, the shell verifies that +.BR $path.out +does not already exist before invoking +.IR rm . +.IP " c." 4 +If the shell succeeded in creating +.BR $path.out , +.IR rm +removes it so that the application can create the file again in the +.BR PROCESSING +step. +.IP " d." 4 +If the +.BR PROCESSING +step wants the file to exist already when it is invoked, the: +.RS 4 +.sp +.RS 4 +.nf +\fB +rm "$path.out" > "$path.out" +.fi \fR +.P +.RE +.P +should be replaced with: +.sp +.RS 4 +.nf +\fB +> "$path.out" +.fi \fR +.P +.RE +.P +which verifies that the file did not already exist, but leaves +.BR $path.out +in place for use by +.BR PROCESSING . +.RE +.RE +.SH RATIONALE +The +.IR pathchk +utility was new for the ISO\ POSIX\(hy2:\|1993 standard. It, along with the +.IR set +.BR \(miC (\c +.IR noclobber ) +option added to the shell, replaces the +.IR mktemp , +.IR validfnam , +and +.IR create +utilities that appeared in early proposals. All of these utilities were +attempts to solve several common problems: +.IP " *" 4 +Verify the validity (for several different definitions of ``valid'') of +a pathname supplied by a user, generated by an application, or imported +from an external source. +.IP " *" 4 +Atomically create a file. +.IP " *" 4 +Perform various string handling functions to generate a temporary +filename. +.P +The +.IR create +utility, included in an early proposal, provided checking and atomic +creation in a single invocation of the utility; these are orthogonal +issues and need not be grouped into a single utility. Note that the +.IR noclobber +option also provides a way of creating a lock for process +synchronization; since it provides an atomic +.IR create , +there is no race between a test for existence and the following +creation if it did not exist. +.P +Having a function like +\fItmpnam\fR() +in the ISO\ C standard is important in many high-level languages. The shell +programming language, however, has built-in string manipulation +facilities, making it very easy to construct temporary filenames. The +names needed obviously depend on the application, but are frequently of +a form similar to: +.sp +.RS 4 +.nf +\fB +\fB$TMPDIR/\fIapplication_abbreviation\fB$$.\fIsuffix\fR +.fi \fR +.P +.RE +.P +In cases where there is likely to be contention for a given suffix, a +simple shell +.BR for +or +.BR while +loop can be used with the shell +.IR noclobber +option to create a file without risk of collisions, as long as +applications trying to use the same filename name space are cooperating +on the use of files after they have been created. +.P +For historical purposes, +.BR \(mip +does not check for the use of the + +character as the first character in a component of the pathname, or for +an empty +.IR pathname +operand. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.7" ", " "Redirection", +.IR "\fIset\fR\^", +.IR "\fItest\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/pax.1p b/man-pages-posix-2013/man1p/pax.1p new file mode 100644 index 0000000..788756b --- /dev/null +++ b/man-pages-posix-2013/man1p/pax.1p @@ -0,0 +1,4153 @@ +'\" et +.TH PAX "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pax +\(em portable archive interchange +.SH SYNOPSIS +.LP +.nf +pax \fB[\fR\(midv\fB] [\fR\(mic|\(min\fB] [\fR\(miH|\(miL\fB] [\fR\(mio \fIoptions\fB] [\fR\(mif \fIarchive\fB] [\fR\(mis \fIreplstr\fB]\fR... + \fB[\fIpattern\fR...\fB]\fR +.P +pax \(mir\fB[\fR\(mic|\(min\fB] [\fR\(midikuv\fB] [\fR\(miH|\(miL\fB] [\fR\(mif \fIarchive\fB] [\fR\(mio \fIoptions\fB]\fR... \fB[\fR\(mip \fIstring\fB]\fR... + \fB[\fR\(mis \fIreplstr\fB]\fR... \fB[\fIpattern\fR...\fB]\fR +.P +pax \(miw \fB[\fR\(midituvX\fB] [\fR\(miH|\(miL\fB] [\fR\(mib \fIblocksize\fB] [[\fR\(mia\fB] [\fR\(mif \fIarchive\fB]] [\fR\(mio \fIoptions\fB]\fR... + \fB[\fR\(mis \fIreplstr\fB]\fR... \fB[\fR\(mix \fIformat\fB] [\fIfile\fR...\fB]\fR +.P +pax \(mir \(miw \fB[\fR\(midiklntuvX\fB] [\fR\(miH|\(miL\fB] [\fR\(mio \fIoptions\fB]\fR... \fB[\fR\(mip \fIstring\fB]\fR... + \fB[\fR\(mis \fIreplstr\fB]\fR... \fB[\fIfile\fR...\fB] \fIdirectory\fR +.fi +.SH DESCRIPTION +The +.IR pax +utility shall read, write, and write lists of the members of archive +files and copy directory hierarchies. A variety of archive formats +shall be supported; see the +.BR \(mix +.IR format +option. +.P +The action to be taken depends on the presence of the +.BR \(mir +and +.BR \(miw +options. The four combinations of +.BR \(mir +and +.BR \(miw +are referred to as the four modes of operation: +.BR list , +.BR read , +.BR write , +and +.BR copy +modes, corresponding respectively to the four forms shown in the +SYNOPSIS section. +.IP "\fBlist\fP" 10 +In +.BR list +mode (when neither +.BR \(mir +nor +.BR \(miw +are specified), +.IR pax +shall write the names of the members of the archive file read from the +standard input, with pathnames matching the specified patterns, to +standard output. If a named file is of type directory, the file +hierarchy rooted at that file shall be listed as well. +.IP "\fBread\fP" 10 +In +.BR read +mode (when +.BR \(mir +is specified, but +.BR \(miw +is not), +.IR pax +shall extract the members of the archive file read from the standard +input, with pathnames matching the specified patterns. If an extracted +file is of type directory, the file hierarchy rooted at that file shall +be extracted as well. The extracted files shall be created performing +pathname resolution with the directory in which +.IR pax +was invoked as the current working directory. +.RS 10 +.P +If an attempt is made to extract a directory when the directory +already exists, this shall not be considered an error. If +an attempt is made to extract a FIFO when the FIFO already exists, +this shall not be considered an error. +.P +The ownership, access, and modification times, and file mode of the +restored files are discussed under the +.BR \(mip +option. +.RE +.IP "\fBwrite\fP" 10 +In +.BR write +mode (when +.BR \(miw +is specified, but +.BR \(mir +is not), +.IR pax +shall write the contents of the +.IR file +operands to the standard output in an archive format. If no +.IR file +operands are specified, a list of files to copy, one per line, shall be +read from the standard input and each entry in this list shall be +processed as if it had been a +.IR file +operand on the command line. A file of type directory shall include +all of the files in the file hierarchy rooted at the file. +.IP "\fBcopy\fP" 10 +In +.BR copy +mode (when both +.BR \(mir +and +.BR \(miw +are specified), +.IR pax +shall copy the +.IR file +operands to the destination directory. +.RS 10 +.P +If no +.IR file +operands are specified, a list of files to copy, one per line, shall be +read from the standard input. A file of type directory shall include +all of the files in the file hierarchy rooted at the file. +.P +The effect of the +.BR copy +shall be as if the copied files were written to a +.IR pax +format archive file and then subsequently extracted, except that there +may be hard links between the original and the copied files. If the +destination directory is a subdirectory of one of the files to be +copied, the results are unspecified. If the destination directory is a +file of a type not defined by the System Interfaces volume of POSIX.1\(hy2008, the results are +implementation-defined; otherwise, it shall be an error for the file +named by the +.IR directory +operand not to exist, not be writable by the user, or not be a file of +type directory. +.RE +.P +In +.BR read +or +.BR copy +modes, if intermediate directories are necessary to extract an archive +member, +.IR pax +shall perform actions equivalent to the +\fImkdir\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008, called with the following arguments: +.IP " *" 4 +The intermediate directory used as the +.IR path +argument +.IP " *" 4 +The value of the bitwise-inclusive OR of S_IRWXU, S_IRWXG, and S_IRWXO +as the +.IR mode +argument +.P +If any specified +.IR pattern +or +.IR file +operands are not matched by at least one file or archive member, +.IR pax +shall write a diagnostic message to standard error for each one that +did not match and exit with a non-zero exit status. +.P +The archive formats described in the EXTENDED DESCRIPTION section shall +be automatically detected on input. The default output archive format +shall be implementation-defined. +.P +A single archive can span multiple files. The +.IR pax +utility shall determine, in an implementation-defined manner, what +file to read or write as the next file. +.P +If the selected archive format supports the specification of linked files, +it shall be an error if these files cannot be linked when the archive +is extracted. For archive formats that do not store file contents with +each name that causes a hard link, if the file that contains the data +is not extracted during this +.IR pax +session, either the data shall be restored from the original file, or a +diagnostic message shall be displayed with the name of a file that can +be used to extract the data. In traversing directories, +.IR pax +shall detect infinite loops; that is, entering a previously visited +directory that is an ancestor of the last file visited. When it detects +an infinite loop, +.IR pax +shall write a diagnostic message to standard error and shall +terminate. +.SH OPTIONS +The +.IR pax +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that the order of presentation of the +.BR \(mio , +.BR \(mip , +and +.BR \(mis +options is significant. +.P +The following options shall be supported: +.IP "\fB\(mir\fP" 10 +Read an archive file from standard input. +.IP "\fB\(miw\fP" 10 +Write files to the standard output in the specified archive format. +.IP "\fB\(mia\fP" 10 +Append files to the end of the archive. It is implementation-defined +which devices on the system support appending. Additional file formats +unspecified by this volume of POSIX.1\(hy2008 may impose restrictions on appending. +.IP "\fB\(mib\ \fIblocksize\fR" 10 +Block the output at a positive decimal integer number of bytes per +write to the archive file. Devices and archive formats may impose +restrictions on blocking. Blocking shall be automatically determined on +input. Conforming applications shall not specify a +.IR blocksize +value larger than 32\|256. Default blocking when creating archives +depends on the archive format. (See the +.BR \(mix +option below.) +.IP "\fB\(mic\fP" 10 +Match all file or archive members except those specified by the +.IR pattern +or +.IR file +operands. +.IP "\fB\(mid\fP" 10 +Cause files of type directory being copied or archived or archive +members of type directory being extracted or listed to match only the +file or archive member itself and not the file hierarchy rooted at the +file. +.IP "\fB\(mif\ \fIarchive\fR" 10 +Specify the pathname of the input or output archive, overriding the +default standard input (in +.BR list +or +.BR read +modes) or standard output (\c +.BR write +mode). +.IP "\fB\(miH\fP" 10 +If a symbolic link referencing a file of type directory is specified on +the command line, +.IR pax +shall archive the file hierarchy rooted in the file referenced by the +link, using the name of the link as the root of the file hierarchy. +Otherwise, if a symbolic link referencing a file of any other file type +which +.IR pax +can normally archive is specified on the command line, then +.IR pax +shall archive the file referenced by the link, using the name of the +link. The default behavior, when neither +.BR \(miH +or +.BR \(miL +are specified, shall be to archive the symbolic link itself. +.IP "\fB\(mii\fP" 10 +Interactively rename files or archive members. For each archive member +matching a +.IR pattern +operand or file matching a +.IR file +operand, a prompt shall be written to the file +.BR /dev/tty . +The prompt shall contain the name of the file or archive member, but +the format is otherwise unspecified. A line shall then be read from +.BR /dev/tty . +If this line is blank, the file or archive member shall be skipped. If +this line consists of a single period, the file or archive member shall +be processed with no modification to its name. Otherwise, its name +shall be replaced with the contents of the line. The +.IR pax +utility shall immediately exit with a non-zero exit status if +end-of-file is encountered when reading a response or if +.BR /dev/tty +cannot be opened for reading and writing. +.RS 10 +.P +The results of extracting a hard link to a file that has been renamed +during extraction are unspecified. +.RE +.IP "\fB\(mik\fP" 10 +Prevent the overwriting of existing files. +.IP "\fB\(mil\fP" 10 +(The letter ell.) In +.BR copy +mode, hard links shall be made between the source and destination file +hierarchies whenever possible. If specified in conjunction with +.BR \(miH +or +.BR \(miL , +when a symbolic link is encountered, the hard link created in the +destination file hierarchy shall be to the file referenced by the +symbolic link. If specified when neither +.BR \(miH +nor +.BR \(miL +is specified, when a symbolic link is encountered, the implementation +shall create a hard link to the symbolic link in the source file +hierarchy or copy the symbolic link to the destination. +.IP "\fB\(miL\fP" 10 +If a symbolic link referencing a file of type directory is specified on +the command line or encountered during the traversal of a file +hierarchy, +.IR pax +shall archive the file hierarchy rooted in the file referenced by the +link, using the name of the link as the root of the file hierarchy. +Otherwise, if a symbolic link referencing a file of any other file type +which +.IR pax +can normally archive is specified on the command line or encountered +during the traversal of a file hierarchy, +.IR pax +shall archive the file referenced by the link, using the name of the +link. The default behavior, when neither +.BR \(miH +or +.BR \(miL +are specified, shall be to archive the symbolic link itself. +.IP "\fB\(min\fP" 10 +Select the first archive member that matches each +.IR pattern +operand. No more than one archive member shall be matched for each +pattern (although members of type directory shall still match the file +hierarchy rooted at that file). +.IP "\fB\(mio\ \fIoptions\fR" 10 +Provide information to the implementation to modify the algorithm for +extracting or writing files. The value of +.IR options +shall consist of one or more +-separated +keywords of the form: +.RS 10 +.sp +.RS 4 +.nf +\fB +\fIkeyword\fB[[\fR:\fB]\fR=\fIvalue\fB][\fR,\fIkeyword\fB[[\fR:\fB]\fR=\fIvalue\fB]\fR, ...\fB]\fR +.fi \fR +.P +.RE +.P +Some keywords apply only to certain file formats, as indicated with +each description. Use of keywords that are inapplicable to the file +format being processed produces undefined results. +.P +Keywords in the +.IR options +argument shall be a string that would be a valid portable filename as +described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.278" ", " "Portable Filename Character Set". +.TP 10 +.BR Note: +Keywords are not expected to be filenames, merely to follow the same +character composition rules as portable filenames. +.P +.P +Keywords can be preceded with white space. The +.IR value +field shall consist of zero or more characters; within +.IR value , +the application shall precede any literal + +with a +, +which shall be ignored, but preserves the + +as part of +.IR value . +A + +as the final character, or a + +followed solely by white space as the final characters, in +.IR options +shall be ignored. Multiple +.BR \(mio +options can be specified; if keywords given to these multiple +.BR \(mio +options conflict, the keywords and values appearing later in command +line sequence shall take precedence and the earlier shall be silently +ignored. The following keyword values of +.IR options +shall be supported for the file formats as indicated: +.IP "\fBdelete\fR=\fIpattern\fR" 6 +.br +(Applicable only to the +.BR \(mix +.BR pax +format.) When used in +.BR write +or +.BR copy +mode, +.IR pax +shall omit from extended header records that it produces any keywords +matching the string pattern. When used in +.BR read +or +.BR list +mode, +.IR pax +shall ignore any keywords matching the string pattern in the extended +header records. In both cases, matching shall be performed using the +pattern matching notation described in +.IR "Section 2.13.1" ", " "Patterns Matching a Single Character" +and +.IR "Section 2.13.2" ", " "Patterns Matching Multiple Characters". +For example: +.RS 6 +.sp +.RS 4 +.nf +\fB +\(mio \fBdelete\fR=\fIsecurity\fR.* +.fi \fR +.P +.RE +.P +would suppress security-related information. See +.IR "pax Extended Header" +for extended header record keyword usage. +.P +When multiple +.BR \(mio \c +.BR delete=pattern +options are specified, the patterns shall be additive; all keywords +matching the specified string patterns shall be omitted from extended +header records that +.IR pax +produces. +.RE +.IP "\fBexthdr.name\fR=\fIstring\fR" 6 +.br +(Applicable only to the +.BR \(mix +.BR pax +format.) This keyword allows user control over the name that is written +into the +.BR ustar +header blocks for the extended header produced under the circumstances +described in +.IR "pax Header Block". +The name shall be the contents of +.IR string , +after the following character substitutions have been made: +.TS +center box tab(!); +cB | cB +cB | cB +lf5 | lw(3.8i). +\fIstring\fP +Includes:!Replaced by: +_ +%d!T{ +The directory name of the file, equivalent to the result of the +.IR dirname +utility on the translated pathname. +T} +%f!T{ +The filename of the file, equivalent to the result of the +.IR basename +utility on the translated pathname. +T} +%p!T{ +The process ID of the +.IR pax +process. +T} +%%!T{ +A +.BR '%' +character. +T} +.TE +.RS 6 +.P +Any other +.BR '%' +characters in +.IR string +produce undefined results. +.P +If no +.BR \(mio +.BR exthdr.name=string +is specified, +.IR pax +shall use the following default value: +.sp +.RS 4 +.nf +\fB +%d/PaxHeaders.%p/%f +.fi \fR +.P +.RE +.RE +.IP "\fBglobexthdr.name\fR=\fIstring\fR" 6 +.br +(Applicable only to the +.BR \(mix +.BR pax +format.) When used in +.BR write +or +.BR copy +mode with the appropriate options, +.IR pax +shall create global extended header records with +.BR ustar +header blocks that will be treated as regular files by previous +versions of +.IR pax . +This keyword allows user control over the name that is written into the +.BR ustar +header blocks for global extended header records. The name shall be the +contents of string, after the following character substitutions have +been made: +.TS +center box tab(!); +cB | cB +cB | cB +lf5 | lw(3.8i). +\fIstring\fP +Includes:!Replaced by: +_ +%n!T{ +An integer that represents the sequence number of the global extended +header record in the archive, starting at 1. +T} +%p!T{ +The process ID of the +.IR pax +process. +T} +%%!T{ +A +.BR '%' +character. +T} +.TE +.RS 6 +.P +Any other +.BR '%' +characters in +.IR string +produce undefined results. +.P +If no +.BR \(mio +.BR globexthdr.name=string +is specified, +.IR pax +shall use the following default value: +.sp +.RS 4 +.nf +\fB +$TMPDIR/GlobalHead.%p.%n +.fi \fR +.P +.RE +.P +where $\c +.IR TMPDIR +represents the value of the +.IR TMPDIR +environment variable. If +.IR TMPDIR +is not set, +.IR pax +shall use +.BR /tmp . +.RE +.IP "\fBinvalid\fR=\fIaction\fR" 6 +.br +(Applicable only to the +.BR \(mix +.BR pax +format.) This keyword allows user control over the action +.IR pax +takes upon encountering values in an extended header record that, in +.BR read +or +.BR copy +mode, are invalid in the destination hierarchy or, in +.BR list +mode, cannot be written in the codeset and current locale of the +implementation. The following are invalid values that shall be +recognized by +.IR pax : +.RS 6 +.IP -- 4 +In +.BR read +or +.BR copy +mode, a filename or link name that contains character encodings +invalid in the destination hierarchy. (For example, the name may +contain embedded NULs.) +.IP -- 4 +In +.BR read +or +.BR copy +mode, a filename or link name that is longer than the maximum allowed +in the destination hierarchy (for either a pathname component or the +entire pathname). +.IP -- 4 +In +.BR list +mode, any character string value (filename, link name, user name, and +so on) that cannot be written in the codeset and current locale of the +implementation. +.P +The following mutually-exclusive values of the +.IR action +argument are supported: +.IP "\fBbinary\fR" 10 +In +.BR write +mode, +.IR pax +shall generate a +.BR hdrcharset = BINARY +extended header record for each file with a filename, link name, group +name, owner name, or any other field in an extended header record that +cannot be translated to the UTF\(hy8 codeset, allowing the archive to +contain the files with unencoded extended header record values. In +.BR read +or +.BR copy +mode, +.IR pax +shall use the values specified in the header without translation, +regardless of whether this may overwrite an existing file with a valid +name. In +.BR list +mode, +.IR pax +shall behave identically to the +.BR bypass +action. +.IP "\fBbypass\fR" 10 +In +.BR read +or +.BR copy +mode, +.IR pax +shall bypass the file, causing no change to the destination hierarchy. +In +.BR list +mode, +.IR pax +shall write all requested valid values for the file, but its method for +writing invalid values is unspecified. +.IP "\fBrename\fR" 10 +In +.BR read +or +.BR copy +mode, +.IR pax +shall act as if the +.BR \(mii +option were in effect for each file with invalid filename or link name +values, allowing the user to provide a replacement name interactively. +In +.BR list +mode, +.IR pax +shall behave identically to the +.BR bypass +action. +.IP "\fBUTF\(hy8\fR" 10 +When used in +.BR read , +.BR copy , +or +.BR list +mode and a filename, link name, owner name, or any other field in an +extended header record cannot be translated from the +.BR pax +UTF\(hy8 codeset format to the codeset and current locale of the +implementation, +.IR pax +shall use the actual UTF\(hy8 encoding for the name. If a +.BR hdrcharset +extended header record is in effect for this file, the character set +specified by that record shall be used instead of UTF\(hy8. If a +.BR hdrcharset = BINARY +extended header record is in effect for this file, no translation shall +be performed. +.IP "\fBwrite\fR" 10 +In +.BR read +or +.BR copy +mode, +.IR pax +shall write the file, translating the name, regardless of whether this +may overwrite an existing file with a valid name. In +.BR list +mode, +.IR pax +shall behave identically to the +.BR bypass +action. +.P +If no +.BR \(mio +.BR invalid=option +is specified, +.IR pax +shall act as if +.BR \(mio \c +.BR invalid=bypass +were specified. Any overwriting of existing files that may be allowed +by the +.BR \(mio \c +.BR invalid= +actions shall be subject to permission (\c +.BR \(mip ) +and modification time (\c +.BR \(miu ) +restrictions, and shall be suppressed if the +.BR \(mik +option is also specified. +.RE +.IP "\fBlinkdata\fP" 6 +.br +(Applicable only to the +.BR \(mix +.BR pax +format.) In +.BR write +mode, +.IR pax +shall write the contents of a file to the archive even when that file +is merely a hard link to a file whose contents have already been +written to the archive. +.IP "\fBlistopt\fR=\fIformat\fP" 6 +.br +This keyword specifies the output format of the table of contents +produced when the +.BR \(miv +option is specified in +.BR list +mode. See +.IR "List Mode Format Specifications". +To avoid ambiguity, the +.BR listopt=format +shall be the only or final +.BR keyword=value +pair in a +.BR \(mio +option-argument; all characters in the remainder of the option-argument +shall be considered part of the format string. When multiple +.BR \(mio \c +.BR listopt=format +options are specified, the format strings shall be considered a single, +concatenated string, evaluated in command line order. +.IP "\fBtimes\fR" 6 +.br +(Applicable only to the +.BR \(mix +.IR pax +format.) When used in +.BR write +or +.BR copy +mode, +.IR pax +shall include +.BR atime +and +.BR mtime +extended header records for each file. See +.IR "pax Extended Header File Times". +.P +In addition to these keywords, if the +.BR \(mix +.IR pax +format is specified, any of the keywords and values defined in +.IR "pax Extended Header", +including implementation extensions, can be used in +.BR \(mio +option-arguments, in either of two modes: +.IP "\fBkeyword\fR=\fIvalue\fR" 6 +.br +When used in +.BR write +or +.BR copy +mode, these keyword/value pairs shall be included at the beginning of +the archive as +.BR typeflag +.BR g +global extended header records. When used in +.BR read +or +.BR list +mode, these keyword/value pairs shall act as if they had been at the +beginning of the archive as +.BR typeflag +.BR g +global extended header records. +.IP "\fBkeyword\fR:=\fIvalue\fR" 6 +.br +When used in +.BR write +or +.BR copy +mode, these keyword/value pairs shall be included as records at the +beginning of a +.BR typeflag +.BR x +extended header for each file. (This shall be equivalent to the + +form except that it creates no +.BR typeflag +.BR g +global extended header records.) When used in +.BR read +or +.BR list +mode, these keyword/value pairs shall act as if they were included as +records at the end of each extended header; thus, they shall override +any global or file-specific extended header record keywords of the same +names. For example, in the command: +.RS 6 +.sp +.RS 4 +.nf +\fB +pax \(mir \(mio " +gname:=mygroup, +" , +.BR '\en' +(where +.IR n +is a digit) back-references, or subexpression matching. The +.IR old +string shall also be permitted to contain + +characters. +.P +Any non-null character can be used as a delimiter (\c +.BR '/' +shown here). Multiple +.BR \(mis +expressions can be specified; the expressions shall be applied in the +order specified, terminating with the first successful substitution. +The optional trailing +.BR 'g' +is as defined in the +.IR ed +utility. The optional trailing +.BR 'p' +shall cause successful substitutions to be written to standard error. +File or archive member names that substitute to the empty string shall +be ignored when reading and writing archives. +.RE +.IP "\fB\(mit\fP" 10 +When reading files from the file system, and if the user has the +permissions required by +\fIutime\fR() +to do so, set the access time of each file read to the access time that +it had before being read by +.IR pax . +.IP "\fB\(miu\fP" 10 +Ignore files that are older (having a less recent file modification +time) than a pre-existing file or archive member with the same name. +In +.BR read +mode, an archive member with the same name as a file in the file system +shall be extracted if the archive member is newer than the file. In +.BR write +mode, an archive file member with the same name as a file in the file +system shall be superseded if the file is newer than the archive +member. If +.BR \(mia +is also specified, this is accomplished by appending to the archive; +otherwise, it is unspecified whether this is accomplished by actual +replacement in the archive or by appending to the archive. In +.BR copy +mode, the file in the destination hierarchy shall be replaced by the +file in the source hierarchy or by a link to the file in the source +hierarchy if the file in the source hierarchy is newer. +.IP "\fB\(miv\fP" 10 +In +.BR list +mode, produce a verbose table of contents (see the STDOUT section). +Otherwise, write archive member pathnames to standard error (see the +STDERR section). +.IP "\fB\(mix\ \fIformat\fR" 10 +Specify the output archive format. The +.IR pax +utility shall support the following formats: +.RS 10 +.IP "\fBcpio\fR" 10 +The +.BR cpio +interchange format; see the EXTENDED DESCRIPTION section. The default +.IR blocksize +for this format for character special archive files shall be 5\|120. +Implementations shall support all +.IR blocksize +values less than or equal to 32\|256 that are multiples of 512. +.IP "\fBpax\fR" 10 +The +.BR pax +interchange format; see the EXTENDED DESCRIPTION section. The default +.IR blocksize +for this format for character special archive files shall be 5\|120. +Implementations shall support all +.IR blocksize +values less than or equal to 32\|256 that are multiples of 512. +.IP "\fBustar\fR" 10 +The +.BR tar +interchange format; see the EXTENDED DESCRIPTION section. The default +.IR blocksize +for this format for character special archive files shall be 10\|240. +Implementations shall support all +.IR blocksize +values less than or equal to 32\|256 that are multiples of 512. +.P +Implementation-defined formats shall specify a default block size as +well as any other block sizes supported for character special archive +files. +.P +Any attempt to append to an archive file in a format different from the +existing archive format shall cause +.IR pax +to exit immediately with a non-zero exit status. +.RE +.IP "\fB\(miX\fP" 10 +When traversing the file hierarchy specified by a pathname, +.IR pax +shall not descend into directories that have a different device ID (\c +.IR st_dev ; +see the System Interfaces volume of POSIX.1\(hy2008, +\fIstat\fR()). +.P +Specifying more than one of the mutually-exclusive options +.BR \(miH +and +.BR \(miL +shall not be considered an error and the last option specified shall +determine the behavior of the utility. +.P +The options that operate on the names of files or archive members (\c +.BR \(mic , +.BR \(mii , +.BR \(min , +.BR \(mis , +.BR \(miu , +and +.BR \(miv ) +shall interact as follows. In +.BR read +mode, the archive members shall be selected based on the user-specified +.IR pattern +operands as modified by the +.BR \(mic , +.BR \(min , +and +.BR \(miu +options. Then, any +.BR \(mis +and +.BR \(mii +options shall modify, in that order, the names of the selected files. +The +.BR \(miv +option shall write names resulting from these modifications. +.P +In +.BR write +mode, the files shall be selected based on the user-specified +pathnames as modified by the +.BR \(min +and +.BR \(miu +options. Then, any +.BR \(mis +and +.BR \(mii +options shall modify, in that order, the names of these selected files. +The +.BR \(miv +option shall write names resulting from these modifications. +.P +If both the +.BR \(miu +and +.BR \(min +options are specified, +.IR pax +shall not consider a file selected unless it is newer than the file to +which it is compared. +.SS "List Mode Format Specifications" +.P +In +.BR list +mode with the +.BR \(mio +.BR listopt=format +option, the +.IR format +argument shall be applied for each selected file. The +.IR pax +utility shall append a + +to the +.BR listopt +output for each selected file. The +.IR format +argument shall be used as the +.IR format +string described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation", +with the exceptions 1. through 6. defined in the EXTENDED DESCRIPTION +section of +.IR printf , +plus the following exceptions: +.IP 7. 6 +The sequence (\c +.IR keyword ) +can occur before a format conversion specifier. The conversion +argument is defined by the value of +.IR keyword . +The implementation shall support the following keywords: +.RS 6 +.IP -- 4 +Any of the Field Name entries in +.IR "Table 4-14, ustar Header Block" +and +.IR "Table 4-16, Octet-Oriented cpio Archive Entry". +The implementation may support the +.IR cpio +keywords without the leading +.BR c_ +in addition to the form required by +.IR "Table 4-16, Octet-Oriented cpio Archive Entry". +.IP -- 4 +Any keyword defined for the extended header in +.IR "pax Extended Header". +.IP -- 4 +Any keyword provided as an implementation-defined extension within +the extended header defined in +.IR "pax Extended Header". +.P +For example, the sequence +.BR \(dq%(charset)s\(dq +is the string value of the name of the character set in the extended +header. +.P +The result of the keyword conversion argument shall be the value from +the applicable header field or extended header, without any trailing +NULs. +.P +All keyword values used as conversion arguments shall be translated +from the UTF\(hy8 encoding (or alternative encoding specified by any +.BR hdrcharset +extended header record) to the character set appropriate for the local +file system, user database, and so on, as applicable. +.RE +.IP 8. 6 +An additional conversion specifier character, +.BR T , +shall be used to specify time formats. The +.BR T +conversion specifier character can be preceded by the sequence (\c +.IR keyword= \c +.IR subformat ), +where +.IR subformat +is a date format as defined by +.IR date +operands. The default +.IR keyword +shall be +.BR mtime +and the default subformat shall be: +.RS 6 +.sp +.RS 4 +.nf +\fB +%b %e %H:%M %Y +.fi \fR +.P +.RE +.RE +.IP 9. 6 +An additional conversion specifier character, +.BR M , +shall be used to specify the file mode string as defined in +.IR ls +Standard Output. If (\c +.IR keyword ) +is omitted, the +.BR mode +keyword shall be used. For example, +.BR %.1M +writes the single character corresponding to the <\fIentry\ type\fP> +field of the +.IR ls +.BR \(mil +command. +.IP 10. 6 +An additional conversion specifier character, +.BR D , +shall be used to specify the device for block or special files, if +applicable, in an implementation-defined format. If not applicable, +and (\c +.IR keyword ) +is specified, then this conversion shall be equivalent to +\fR%(\fIkeyword\fR)u\fR. If not applicable, and (\c +.IR keyword ) +is omitted, then this conversion shall be equivalent to +. +.IP 11. 6 +An additional conversion specifier character, +.BR F , +shall be used to specify a pathname. The +.BR F +conversion character can be preceded by a sequence of +-separated +keywords: +.RS 6 +.sp +.RS 4 +.nf +\fB +(\fIkeyword\fB[\fR,\fIkeyword\fB]\fR ... ) +.fi \fR +.P +.RE +.P +The values for all the keywords that are non-null shall be concatenated +together, each separated by a +.BR '/' . +The default shall be (\c +.BR path ) +if the keyword +.BR path +is defined; otherwise, the default shall be (\c +.BR prefix ,\c +.BR name ). +.RE +.IP 12. 6 +An additional conversion specifier character, +.BR L , +shall be used to specify a symbolic link expansion. If the current +file is a symbolic link, then +.BR %L +shall expand to: +.RS 6 +.sp +.RS 4 +.nf +\fB +"%s \(mi> %s", <\fIvalue of keyword\fR>, <\fIcontents of link\fR> +.fi \fR +.P +.RE +.P +Otherwise, the +.BR %L +conversion specification shall be the equivalent of +.BR %F . +.RE +.SH OPERANDS +The following operands shall be supported: +.IP "\fIdirectory\fR" 10 +The destination directory pathname for +.BR copy +mode. +.IP "\fIfile\fR" 10 +A pathname of a file to be copied or archived. +.IP "\fIpattern\fR" 10 +A pattern matching one or more pathnames of archive members. A pattern +must be given in the name-generating notation of the pattern matching +notation in +.IR "Section 2.13" ", " "Pattern Matching Notation", +including the filename expansion rules in +.IR "Section 2.13.3" ", " "Patterns Used for Filename Expansion". +The default, if no +.IR pattern +is specified, is to select all members in the archive. +.SH STDIN +In +.BR write +mode, the standard input shall be used only if no +.IR file +operands are specified. It shall be a file containing a list of +pathnames, each terminated by a + +character. +.P +In +.BR list +and +.BR read +modes, if +.BR \(mif +is not specified, the standard input shall be an archive file. +.P +Otherwise, the standard input shall not be used. +.SH "INPUT FILES" +The input file named by the +.IR archive +option-argument, or standard input when the archive is read from there, +shall be a file formatted according to one of the specifications in the +EXTENDED DESCRIPTION section or some other implementation-defined +format. +.P +The file +.BR /dev/tty +shall be used to write prompts and read responses. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR pax : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements used in the pattern matching +expressions for the +.IR pattern +operand, the basic regular expression for the +.BR \(mis +option, and the extended regular expression defined for the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files), the behavior of +character classes used in the extended regular expression defined for +the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category, and pattern matching. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale used to process affirmative responses, and the +locale used to affect the format and contents of diagnostic messages +and prompts written to standard error. +.IP "\fILC_TIME\fP" 10 +Determine the format and contents of date and time strings when the +.BR \(miv +option is specified. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITMPDIR\fP" 10 +Determine the pathname that provides part of the default global +extended header record file, as described for the +.BR \(mio +.BR globexthdr= +keyword in the OPTIONS section. +.IP "\fITZ\fP" 10 +Determine the timezone used to calculate date and time strings when the +.BR \(miv +option is specified. If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +In +.BR write +mode, if +.BR \(mif +is not specified, the standard output shall be the archive formatted +according to one of the specifications in the EXTENDED DESCRIPTION +section, or some other implementation-defined format (see +.BR \(mix +.IR format ). +.P +In +.BR list +mode, when the +.BR \(mio \c +.BR listopt =\c +.IR format +has been specified, the selected archive members shall be written to +standard output using the format described under +.IR "List Mode Format Specifications". +In +.BR list +mode without the +.BR \(mio \c +.BR listopt =\c +.IR format +option, the table of contents of the selected archive members shall +be written to standard output using the following format: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIpathname\fR> +.fi \fR +.P +.RE +.P +If the +.BR \(miv +option is specified in +.BR list +mode, the table of contents of the selected archive members shall be +written to standard output using the following formats. +.P +For pathnames representing hard links to previous members of the +archive: +.sp +.RS 4 +.nf +\fB +"%s == %s\en", <\fIls\fR \(mil \fIlisting\fR>, <\fIlinkname\fR> +.fi \fR +.P +.RE +.P +For all other pathnames: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIls\fR \(mil \fIlisting\fR> +.fi \fR +.P +.RE +.P +where <\fIls\ \fR\(mil\ \fIlisting\fR> shall be the format specified by +the +.IR ls +utility with the +.BR \(mil +option. When writing pathnames in this format, it is unspecified what +is written for fields for which the underlying archive format does not +have the correct information, although the correct number of +-separated +fields shall be written. +.P +In +.BR list +mode, standard output shall not be buffered more than a pathname +(plus any associated information and a + +terminator) at a time. +.SH STDERR +If +.BR \(miv +is specified in +.BR read , +.BR write , +or +.BR copy +modes, +.IR pax +shall write the pathnames it processes to the standard error output +using the following format: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIpathname\fR> +.fi \fR +.P +.RE +.P +These pathnames shall be written as soon as processing is begun on the +file or archive member, and shall be flushed to standard error. The +trailing +, +which shall not be buffered, is written when the file has been read or +written. +.P +If the +.BR \(mis +option is specified, and the replacement string has a trailing +.BR 'p' , +substitutions shall be written to standard error in the following +format: +.sp +.RS 4 +.nf +\fB +"%s >> %s\en", <\fIoriginal pathname\fR>, <\fInew pathname\fR> +.fi \fR +.P +.RE +.P +In all operating modes of +.IR pax , +optional messages of unspecified format concerning the input archive +format and volume number, the number of files, blocks, volumes, and +media parts as well as other diagnostic messages may be written to +standard error. +.P +In all formats, for both standard output and standard error, it is +unspecified how non-printable characters in pathnames or link names +are written. +.P +When using the +.BR \(mix \c +.BR pax +archive format, if a filename, link name, group name, owner name, or +any other field in an extended header record cannot be translated +between the codeset in use for that extended header record and the +character set of the current locale, +.IR pax +shall write a diagnostic message to standard error, shall process the +file as described for the +.BR \(mio +.BR invalid= +option, and then shall continue processing with the next file. +.SH "OUTPUT FILES" +In +.BR read +mode, the extracted output files shall be of the archived file type. +In +.BR copy +mode, the copied output files shall be the type of the file being +copied. In either mode, existing files in the destination hierarchy +shall be overwritten only when all permission (\c +.BR \(mip ), +modification time (\c +.BR \(miu ), +and invalid-value (\c +.BR \(mio \c +.BR invalid= ) +tests allow it. +.P +In +.BR write +mode, the output file named by the +.BR \(mif +option-argument shall be a file formatted according to one of the +specifications in the EXTENDED DESCRIPTION section, or some other +implementation-defined format. +.SH "EXTENDED DESCRIPTION" +.SS "pax Interchange Format" +.P +A +.IR pax +archive tape or file produced in the +.BR \(mix \c +.BR pax +format shall contain a series of blocks. The physical layout of the +archive shall be identical to the +.BR ustar +format described in +.IR "ustar Interchange Format". +Each file archived shall be represented by the following sequence: +.IP " *" 4 +An optional header block with extended header records. This header +block is of the form described in +.IR "pax Header Block", +with a +.IR typeflag +value of +.BR x +or +.BR g . +The extended header records, described in +.IR "pax Extended Header", +shall be included as the data for this header block. +.IP " *" 4 +A header block that describes the file. Any fields in the preceding +optional extended header shall override the associated fields in +this header block for this file. +.IP " *" 4 +Zero or more blocks that contain the contents of the file. +.P +At the end of the archive file there shall be two 512-byte blocks +filled with binary zeros, interpreted as an end-of-archive indicator. +.P +A schematic of an example archive with global extended header records +and two actual files is shown in +.IR "Figure 4-1, pax Format Archive Example". +In the example, the second file in the archive has no extended header +preceding it, presumably because it has no need for extended +attributes. +.sp +.ce 1 +\fBFigure 4-1: pax Format Archive Example\fR +.SS "pax Header Block" +.P +The +.BR pax +header block shall be identical to the +.BR ustar +header block described in +.IR "ustar Interchange Format", +except that two additional +.IR typeflag +values are defined: +.IP "\fRx\fP" 6 +Represents extended header records for the following file in the +archive (which shall have its own +.BR ustar +header block). The format of these extended header records shall be as +described in +.IR "pax Extended Header". +.IP "\fRg\fR" 6 +Represents global extended header records for the following files in +the archive. The format of these extended header records shall be as +described in +.IR "pax Extended Header". +Each value shall affect all subsequent files that do not override that +value in their own extended header record and until another global +extended header record is reached that provides another value for the +same field. The +.IR typeflag +.BR g +global headers should not be used with interchange media that could +suffer partial data loss in transporting the archive. +.P +For both of these types, the +.IR size +field shall be the size of the extended header records in octets. The +other fields in the header block are not meaningful to this version of +the +.IR pax +utility. However, if this archive is read by a +.IR pax +utility conforming to the ISO\ POSIX\(hy2:\|1993 standard, the header block fields are used to +create a regular file that contains the extended header records as +data. Therefore, header block field values should be selected to +provide reasonable file access to this regular file. +.P +A further difference from the +.BR ustar +header block is that data blocks for files of +.IR typeflag +1 (the digit one) (hard link) may be included, which means that the +size field may be greater than zero. Archives created by +.IR pax +.BR \(mio +.BR linkdata +shall include these data blocks with the hard links. +.SS "pax Extended Header" +.P +A +.BR pax +extended header contains values that are inappropriate for the +.BR ustar +header block because of limitations in that format: fields requiring a +character encoding other than that described in the ISO/IEC\ 646:\|1991 standard, fields +representing file attributes not described in the +.BR ustar +header, and fields whose format or length do not fit the requirements +of the +.BR ustar +header. The values in an extended header add attributes to the +following file (or files; see the description of the +.IR typeflag +.BR g +header block) or override values in the following header block(s), as +indicated in the following list of keywords. +.P +An extended header shall consist of one or more records, each +constructed as follows: +.sp +.RS 4 +.nf +\fB +"%d %s=%s\en", <\fIlength\fR>, <\fIkeyword\fR>, <\fIvalue\fR> +.fi \fR +.P +.RE +.P +The extended header records shall be encoded according to the ISO/IEC\ 10646\(hy1:\|2000 standard +UTF\(hy8 encoding. The <\fIlength\fP> field, +, +, +and + +shown shall be limited to the portable character set, as encoded in +UTF\(hy8. The <\fIkeyword\fP> fields can be any UTF\(hy8 characters. +The <\fIlength\fP> field shall be the decimal length of the extended +header record in octets, including the trailing +. +If there is a +.BR hdrcharset +extended header in effect for a file, the +.IR value +field for any +.BR gname , +.BR linkpath , +.BR path , +and +.BR uname +extended header records shall be encoded using the character set +specified by the +.BR hdrcharset +extended header record; otherwise, the +.IR value +field shall be encoded using UTF\(hy8. The +.IR value +field for all other keywords specified by POSIX.1\(hy2008 shall be +encoded using UTF\(hy8. +.P +The <\fIkeyword\fP> field shall be one of the entries from the +following list or a keyword provided as an implementation extension. +Keywords consisting entirely of lowercase letters, digits, and periods +are reserved for future standardization. A keyword shall not include an +. +(In the following list, the notations ``file(s)'' or ``block(s)'' is used +to acknowledge that a keyword affects the following single file after a +.IR typeflag +.BR x +extended header, but possibly multiple files after +.IR typeflag +.BR g . +Any requirements in the list for +.IR pax +to include a record when in +.BR write +or +.BR copy +mode shall apply only when such a record has not already been provided +through the use of the +.BR \(mio +option. When used in +.BR copy +mode, +.IR pax +shall behave as if an archive had been created with applicable extended +header records and then extracted.) +.IP "\fBatime\fP" 10 +The file access time for the following file(s), equivalent to the value +of the +.IR st_atime +member of the +.BR stat +structure for a file, as described by the +\fIstat\fR() +function. The access time shall be restored if the process has +appropriate privileges required to do so. The format of the +<\fIvalue\fP> shall be as described in +.IR "pax Extended Header File Times". +.IP "\fBcharset\fP" 10 +The name of the character set used to encode the data in the following +file(s). The entries in the following table are defined to refer to +known standards; additional names may be agreed on between the +originator and recipient. +.TS +center box tab(!); +cB | cB +lf5 | l. +!Formal Standard +_ +ISO-IR 646 1990!ISO/IEC 646:\|1990 +ISO-IR 8859 1 1998!ISO/IEC 8859\(hy1:\|1998 +ISO-IR 8859 2 1999!ISO/IEC 8859\(hy2:\|1999 +ISO-IR 8859 3 1999!ISO/IEC 8859\(hy3:\|1999 +ISO-IR 8859 4 1998!ISO/IEC 8859\(hy4:\|1998 +ISO-IR 8859 5 1999!ISO/IEC 8859\(hy5:\|1999 +ISO-IR 8859 6 1999!ISO/IEC 8859\(hy6:\|1999 +ISO-IR 8859 7 1987!ISO/IEC 8859\(hy7:\|1987 +ISO-IR 8859 8 1999!ISO/IEC 8859\(hy8:\|1999 +ISO-IR 8859 9 1999!ISO/IEC 8859\(hy9:\|1999 +ISO-IR 8859 10 1998!ISO/IEC 8859\(hy10:\|1998 +ISO-IR 8859 13 1998!ISO/IEC 8859\(hy13:\|1998 +ISO-IR 8859 14 1998!ISO/IEC 8859\(hy14:\|1998 +ISO-IR 8859 15 1999!ISO/IEC 8859\(hy15:\|1999 +ISO-IR 10646 2000!ISO/IEC 10646:\|2000 +ISO-IR 10646 2000 UTF-8!ISO/IEC 10646, UTF-8 encoding +BINARY!None. +.TE +.RS 10 +.P +The encoding is included in an extended header for information only; +when +.IR pax +is used as described in POSIX.1\(hy2008, it shall not translate the file data +into any other encoding. The +.BR BINARY +entry indicates unencoded binary data. +.P +When used in +.BR write +or +.BR copy +mode, it is implementation-defined whether +.IR pax +includes a +.BR charset +extended header record for a file. +.RE +.IP "\fBcomment\fP" 10 +A series of characters used as a comment. All characters in the +<\fIvalue\fP> field shall be ignored by +.IR pax . +.IP "\fBgid\fP" 10 +The group ID of the group that owns the file, expressed as a decimal +number using digits from the ISO/IEC\ 646:\|1991 standard. This record shall override the +.IR gid +field in the following header block(s). When used in +.BR write +or +.BR copy +mode, +.IR pax +shall include a +.IR gid +extended header record for each file whose group ID is greater than +2\|097\|151 (octal 7\|777\|777). +.IP "\fBgname\fP" 10 +The group of the file(s), formatted as a group name in the group +database. This record shall override the +.IR gid +and +.IR gname +fields in the following header block(s), and any +.IR gid +extended header record. When used in +.BR read , +.BR copy , +or +.BR list +mode, +.IR pax +shall translate the name from the encoding in the header record to +the character set appropriate for the group database on the +receiving system. If any of the characters cannot be +translated, and if neither the +.BR \(mio \c +.BR invalid=UTF\(hy8 +option nor the +.BR \(mio \c +.BR invalid=binary +option is specified, the results are implementation-defined. +When used in +.BR write +or +.BR copy +mode, +.IR pax +shall include a +.BR gname +extended header record for each file whose group name cannot be +represented entirely with the letters and digits of the portable +character set. +.IP "\fBhdrcharset\fR" 10 +The name of the character set used to encode the value field of the +.BR gname , +.BR linkpath , +.BR path , +and +.BR uname +.IR pax +extended header records. The entries in the following table are defined +to refer to known standards; additional names may be agreed between the +originator and the recipient. +.TS +center box tab(!); +cB | cB +lf5 | l. +!Formal Standard +_ +ISO-IR 10646 2000 UTF-8!ISO/IEC 10646, UTF-8 encoding +BINARY!None. +.TE +.RS 10 +.P +If no +.BR hdrcharset +extended header record is specified, the default character set used to +encode all values in extended header records shall be the ISO/IEC\ 10646\(hy1:\|2000 standard +UTF\(hy8 encoding. +.P +The +.BR BINARY +entry indicates that all values recorded in extended headers for +affected files are unencoded binary data from the underlying system. +.RE +.IP "\fBlinkpath\fP" 10 +The pathname of a link being created to another file, of any type, +previously archived. This record shall override the +.IR linkname +field in the following +.BR ustar +header block(s). The following +.BR ustar +header block shall determine the type of link created. If +.IR typeflag +of the following header block is 1, it shall be a hard link. If +.IR typeflag +is 2, it shall be a symbolic link and the +.BR linkpath +value shall be the contents of the symbolic link. The +.IR pax +utility shall translate the name of the link (contents of the symbolic +link) from the encoding in the header to the character set appropriate +for the local file system. When used in +.BR write +or +.BR copy +mode, +.IR pax +shall include a +.BR linkpath +extended header record for each link whose pathname cannot be +represented entirely with the members of the portable character set +other than NUL. +.IP "\fBmtime\fP" 10 +The file modification time of the following file(s), equivalent to the +value of the +.IR st_mtime +member of the +.BR stat +structure for a file, as described in the +\fIstat\fR() +function. This record shall override the +.IR mtime +field in the following header block(s). The modification time shall be +restored if the process has appropriate privileges required to do +so. The format of the <\fIvalue\fP> shall be as described in +.IR "pax Extended Header File Times". +.IP "\fBpath\fP" 10 +The pathname of the following file(s). This record shall override the +.IR name +and +.IR prefix +fields in the following header block(s). The +.IR pax +utility shall translate the pathname of the file from the encoding in +the header to the character set appropriate for the local file system. +.RS 10 +.P +When used in +.BR write +or +.BR copy +mode, +.IR pax +shall include a +.IR path +extended header record for each file whose pathname cannot be +represented entirely with the members of the portable character set +other than NUL. +.RE +.IP "\fBrealtime.\fIany\fR" 10 +The keywords prefixed by ``realtime.'' are reserved for future +standardization. +.IP "\fBsecurity.\fIany\fR" 10 +The keywords prefixed by ``security.'' are reserved for future +standardization. +.IP "\fBsize\fP" 10 +The size of the file in octets, expressed as a decimal number using +digits from the ISO/IEC\ 646:\|1991 standard. This record shall override the +.IR size +field in the following header block(s). When used in +.BR write +or +.BR copy +mode, +.IR pax +shall include a +.IR size +extended header record for each file with a size value greater than +8\|589\|934\|591 (octal 77\|777\|777\|777). +.IP "\fBuid\fP" 10 +The user ID of the file owner, expressed as a decimal number using +digits from the ISO/IEC\ 646:\|1991 standard. This record shall override the +.IR uid +field in the following header block(s). When used in +.BR write +or +.BR copy +mode, +.IR pax +shall include a +.IR uid +extended header record for each file whose owner ID is greater than +2\|097\|151 (octal 7\|777\|777). +.IP "\fBuname\fP" 10 +The owner of the following file(s), formatted as a user name in the +user database. This record shall override the +.IR uid +and +.IR uname +fields in the following header block(s), and any +.IR uid +extended header record. When used in +.BR read , +.BR copy , +or +.BR list +mode, +.IR pax +shall translate the name from the encoding in the header record to the +character set appropriate for the user database on the receiving +system. If any of the characters cannot be translated, and if neither +the +.BR \(mio \c +.BR invalid=UTF\(hy8 +option nor the +.BR \(mio \c +.BR invalid=binary +option is specified, the results are implementation-defined. +When used in +.BR write +or +.BR copy +mode, +.IR pax +shall include a +.BR uname +extended header record for each file whose user name cannot be +represented entirely with the letters and digits of the portable +character set. +.P +If the <\fIvalue\fP> field is zero length, it shall delete any header +block field, previously entered extended header value, or global +extended header value of the same name. +.P +If a keyword in an extended header record (or in a +.BR \(mio +option-argument) overrides or deletes a corresponding field in the +.BR ustar +header block, +.IR pax +shall ignore the contents of that header block field. +.P +Unlike the +.BR ustar +header block fields, NULs shall not delimit <\fIvalue\fP>s; all +characters within the <\fIvalue\fP> field shall be considered data for +the field. None of the length limitations of the +.BR ustar +header block fields in +.IR "Table 4-14, ustar Header Block" +shall apply to the extended header records. +.SS "pax Extended Header Keyword Precedence" +.P +This section describes the precedence in which the various header +records and fields and command line options are selected to apply to a +file in the archive. When +.IR pax +is used in +.BR read +or +.BR list +modes, it shall determine a file attribute in the following sequence: +.IP " 1." 4 +If +.BR \(mio \c +.BR delete=keyword-prefix +is used, the affected attributes shall be determined from step 7., if +applicable, or ignored otherwise. +.IP " 2." 4 +If +.BR \(mio \c +.IR keyword := +is used, the affected attributes shall be ignored. +.IP " 3." 4 +If +.BR \(mio \c +.BR keyword:=value +is used, the affected attribute shall be assigned the value. +.IP " 4." 4 +If there is a +.IR typeflag +.BR x +extended header record, the affected attribute shall be assigned the +<\fIvalue\fP>. When extended header records conflict, the last one +given in the header shall take precedence. +.IP " 5." 4 +If +.BR \(mio \c +.BR keyword=value +is used, the affected attribute shall be assigned the value. +.IP " 6." 4 +If there is a +.IR typeflag +.BR g +global extended header record, the affected attribute shall be assigned +the <\fIvalue\fP>. When global extended header records conflict, the +last one given in the global header shall take precedence. +.IP " 7." 4 +Otherwise, the attribute shall be determined from the +.BR ustar +header block. +.SS "pax Extended Header File Times" +.P +The +.IR pax +utility shall write an +.BR mtime +record for each file in +.BR write +or +.BR copy +modes if the file's modification time cannot be represented exactly in +the +.BR ustar +header logical record described in +.IR "ustar Interchange Format". +This can occur if the time is out of +.BR ustar +range, or if the file system of the underlying implementation supports +non-integer time granularities and the time is not an integer. All of +these time records shall be formatted as a decimal representation of +the time in seconds since the Epoch. If a + +(\c +.BR '.' ) +decimal point character is present, the digits to the right of the +point shall represent the units of a subsecond timing granularity, +where the first digit is tenths of a second and each subsequent digit +is a tenth of the previous digit. In +.BR read +or +.BR copy +mode, the +.IR pax +utility shall truncate the time of a file to the greatest value that is +not greater than the input header file time. In +.BR write +or +.BR copy +mode, the +.IR pax +utility shall output a time exactly if it can be represented exactly as +a decimal number, and otherwise shall generate only enough digits so +that the same time shall be recovered if the file is extracted on a +system whose underlying implementation supports the same time +granularity. +.SS "ustar Interchange Format" +.P +A +.BR ustar +archive tape or file shall contain a series of logical records. Each +logical record shall be a fixed-size logical record of 512 octets (see +below). Although this format may be thought of as being stored on +9-track industry-standard 12.7 mm (0.5 in) magnetic tape, other types of +transportable media are not excluded. Each file archived shall be +represented by a header logical record that describes the file, +followed by zero or more logical records that give the contents of the +file. At the end of the archive file there shall be two 512-octet +logical records filled with binary zeros, interpreted as an +end-of-archive indicator. +.P +The logical records may be grouped for physical I/O operations, as +described under the +.BR \(mib \c +.IR blocksize +and +.BR \(mix +.BR ustar +options. Each group of logical records may be written with a single +operation equivalent to the +\fIwrite\fR() +function. On magnetic tape, the result of this write shall be a single +tape physical block. The last physical block shall always be the full +size, so logical records after the two zero logical records may contain +undefined data. +.P +The header logical record shall be structured as shown in the following +table. All lengths and offsets are in decimal. +.br +.sp +.ce 1 +\fBTable 4-14: ustar Header Block\fR +.TS +center box tab(@); +cB | cB | cB +lI | n | n. +Field Name@Octet Offset@Length (in Octets) +_ +name@0@100 +mode@100@8 +uid@108@8 +gid@116@8 +size@124@12 +mtime@136@12 +chksum@148@8 +typeflag@156@1 +linkname@157@100 +magic@257@6 +version@263@2 +uname@265@32 +gname@297@32 +devmajor@329@8 +devminor@337@8 +prefix@345@155 +.TE +.P +All characters in the header logical record shall be represented in the +coded character set of the ISO/IEC\ 646:\|1991 standard. For maximum portability between +implementations, names should be selected from characters represented +by the portable filename character set as octets with the most +significant bit zero. If an implementation supports the use of +characters outside of + +and the portable filename character set in names for files, users, and +groups, one or more implementation-defined encodings of these characters +shall be provided for interchange purposes. +.P +However, the +.IR pax +utility shall never create filenames on the local system that cannot +be accessed via the procedures described in POSIX.1\(hy2008. If a filename is +found on the medium that would create an invalid filename, it is +implementation-defined whether the data from the file is stored on the +file hierarchy and under what name it is stored. The +.IR pax +utility may choose to ignore these files as long as it produces an +error indicating that the file is being ignored. +.P +Each field within the header logical record is contiguous; that is, +there is no padding used. Each character on the archive medium shall be +stored contiguously. +.P +The fields +.IR magic , +.IR uname , +and +.IR gname +are character strings each terminated by a NUL character. The fields +.IR name , +.IR linkname , +and +.IR prefix +are NUL-terminated character strings except when all characters in the +array contain non-NUL characters including the last character. The +.IR version +field is two octets containing the characters +.BR \(dq00\(dq +(zero-zero). The +.IR typeflag +contains a single character. All other fields are leading zero-filled +octal numbers using digits from the ISO/IEC\ 646:\|1991 standard IRV. Each numeric field is +terminated by one or more + +or NUL characters. +.P +The +.IR name +and the +.IR prefix +fields shall produce the pathname of the file. A new pathname shall +be formed, if +.IR prefix +is not an empty string (its first character is not NUL), by +concatenating +.IR prefix +(up to the first NUL character), a + +character, and +.IR name ; +otherwise, +.IR name +is used alone. In either case, +.IR name +is terminated at the first NUL character. If +.IR prefix +begins with a NUL character, it shall be ignored. In this manner, +pathnames of at most 256 characters can be supported. If a pathname +does not fit in the space provided, +.IR pax +shall notify the user of the error, and shall not store any part of the +file\(emheader or data\(emon the medium. +.P +The +.IR linkname +field, described below, shall not use the +.IR prefix +to produce a pathname. As such, a +.IR linkname +is limited to 100 characters. If the name does not fit in the space +provided, +.IR pax +shall notify the user of the error, and shall not attempt to store the +link on the medium. +.P +The +.IR mode +field provides 12 bits encoded in the ISO/IEC\ 646:\|1991 standard octal digit representation. +The encoded bits shall represent the following values: +.br +.sp +.ce 1 +\fBTable: ustar \fImode\fP Field\fR +.TS +tab(!) center box; +cB | cB | cB +n | l | l. +Bit Value!POSIX.1\(hy2008 Bit!Description +_ +04\|000!S_ISUID!Set UID on execution. +02\|000!S_ISGID!Set GID on execution. +01\|000!!Reserved for future standardization. +00\|400!S_IRUSR!Read permission for file owner class. +00\|200!S_IWUSR!Write permission for file owner class. +00\|100!S_IXUSR!Execute/search permission for file owner class. +00\|040!S_IRGRP!Read permission for file group class. +00\|020!S_IWGRP!Write permission for file group class. +00\|010!S_IXGRP!Execute/search permission for file group class. +00\|004!S_IROTH!Read permission for file other class. +00\|002!S_IWOTH!Write permission for file other class. +00\|001!S_IXOTH!Execute/search permission for file other class. +.TE +.P +When appropriate privileges are required to set one of these mode bits, +and the user restoring the files from the archive does not have +appropriate privileges, the mode bits for which the user does not have +appropriate privileges shall be ignored. Some of the mode bits in the +archive format are not mentioned elsewhere in this volume of POSIX.1\(hy2008. If the +implementation does not support those bits, they may be ignored. +.P +The +.IR uid +and +.IR gid +fields are the user and group ID of the owner and group of the file, +respectively. +.P +The +.IR size +field is the size of the file in octets. If the +.IR typeflag +field is set to specify a file to be of type 1 (a link) or 2 (a +symbolic link), the +.IR size +field shall be specified as zero. If the +.IR typeflag +field is set to specify a file of type 5 (directory), the +.IR size +field shall be interpreted as described under the definition of that +record type. No data logical records are stored for types 1, 2, or 5. +If the +.IR typeflag +field is set to 3 (character special file), 4 (block special file), or +6 (FIFO), the meaning of the +.IR size +field is unspecified by this volume of POSIX.1\(hy2008, and no data logical records shall be +stored on the medium. Additionally, for type 6, the +.IR size +field shall be ignored when reading. If the +.IR typeflag +field is set to any other value, the number of logical records written +following the header shall be (\c +.IR size +511)/512, +ignoring any fraction in the result of the division. +.P +The +.IR mtime +field shall be the modification time of the file at the time it was +archived. It is the ISO/IEC\ 646:\|1991 standard representation of the octal value of the +modification time obtained from the +\fIstat\fR() +function. +.P +The +.IR chksum +field shall be the ISO/IEC\ 646:\|1991 standard IRV representation of the octal value of the +simple sum of all octets in the header logical record. Each octet in +the header shall be treated as an unsigned value. These values shall be +added to an unsigned integer, initialized to zero, the precision of +which is not less than 17 bits. When calculating the checksum, the +.IR chksum +field is treated as if it were all + +characters. +.P +The +.IR typeflag +field specifies the type of file archived. If a particular +implementation does not recognize the type, or the user does not have +appropriate privileges to create that type, the file shall be extracted +as if it were a regular file if the file type is defined to have a +meaning for the +.IR size +field that could cause data logical records to be written on the medium +(see the previous description for +.IR size ). +If conversion to a regular file occurs, the +.IR pax +utility shall produce an error indicating that the conversion took +place. All of the +.IR typeflag +fields shall be coded in the ISO/IEC\ 646:\|1991 standard IRV: +.IP "\fR0\fR" 8 +Represents a regular file. For backwards-compatibility, a +.IR typeflag +value of binary zero (\c +.BR '\e0' ) +should be recognized as meaning a regular file when extracting files +from the archive. Archives written with this version of the archive +file format create regular files with a +.IR typeflag +value of the ISO/IEC\ 646:\|1991 standard IRV +.BR '0' . +.IP "\fR1\fR" 8 +Represents a file linked to another file, of any type, previously +archived. Such files are identified by having the same device +and file serial numbers, and pathnames that refer to different +directory entries. All such files shall be archived as linked files. +The linked-to name is specified in the +.IR linkname +field with a NUL-character terminator if it is less than 100 octets in +length. +.IP "\fR2\fR" 8 +Represents a symbolic link. The contents of the symbolic link shall be +stored in the +.IR linkname +field. +.IP "\fR3,4\fR" 8 +Represent character special files and block special files respectively. +In this case the +.IR devmajor +and +.IR devminor +fields shall contain information defining the device, the format of +which is unspecified by this volume of POSIX.1\(hy2008. Implementations may map the device +specifications to their own local specification or may ignore the +entry. +.IP "\fR5\fR" 8 +Specifies a directory or subdirectory. On systems where disk allocation +is performed on a directory basis, the +.IR size +field shall contain the maximum number of octets (which may be rounded +to the nearest disk block allocation unit) that the directory may hold. +A +.IR size +field of zero indicates no such limiting. Systems that do not support +limiting in this manner should ignore the +.IR size +field. +.IP "\fR6\fR" 8 +Specifies a FIFO special file. Note that the archiving of a FIFO file +archives the existence of this file and not its contents. +.IP "\fR7\fR" 8 +Reserved to represent a file to which an implementation has associated +some high-performance attribute. Implementations without such +extensions should treat this file as a regular file (type 0). +.IP "\fRA\(hyZ\fR" 8 +The letters +.BR 'A' +to +.BR 'Z' , +inclusive, are reserved for custom implementations. All other values +are reserved for future versions of this standard. +.P +It is unspecified whether files with pathnames that refer to the same +directory entry are archived as linked files or as separate files. If +they are archived as linked files, this means that attempting to +extract both pathnames from the resulting archive will always cause an +error (unless the +.BR \(miu +option is used) because the link cannot be created. +.P +It is unspecified whether files with the same device and file serial +numbers being appended to an archive are treated as linked files to +members that were in the archive before the append. +.P +Attempts to archive a socket using +.BR ustar +interchange format shall produce a diagnostic message. Handling of +other file types is implementation-defined. +.P +The +.IR magic +field is the specification that this archive was output in this archive +format. If this field contains +.BR ustar +(the five characters from the ISO/IEC\ 646:\|1991 standard IRV shown followed by NUL), the +.IR uname +and +.IR gname +fields shall contain the ISO/IEC\ 646:\|1991 standard IRV representation of the owner and +group of the file, respectively (truncated to fit, if necessary). When +the file is restored by a privileged, protection-preserving version of +the utility, the user and group databases shall be scanned for these +names. If found, the user and group IDs contained within these files +shall be used rather than the values contained within the +.IR uid +and +.IR gid +fields. +.SS "cpio Interchange Format" +.P +The octet-oriented +.BR cpio +archive format shall be a series of entries, each comprising a header +that describes the file, the name of the file, and then the contents of +the file. +.P +An archive may be recorded as a series of fixed-size blocks of octets. +This blocking shall be used only to make physical I/O more efficient. +The last group of blocks shall always be at the full size. +.P +For the octet-oriented +.BR cpio +archive format, the individual entry information shall be in the order +indicated and described by the following table; see also the +.IR +header. +.br +.sp +.ce 1 +\fBTable 4-16: Octet-Oriented cpio Archive Entry\fR +.TS +center box tab(!); +cB | cB | cB +lI | n | l. +Header Field Name!Length (in Octets)!Interpreted as +_ +c_magic!6!Octal number +c_dev!6!Octal number +c_ino!6!Octal number +c_mode!6!Octal number +c_uid!6!Octal number +c_gid!6!Octal number +c_nlink!6!Octal number +c_rdev!6!Octal number +c_mtime!11!Octal number +c_namesize!6!Octal number +c_filesize!11!Octal number +_ +.T& +cB | cB | cB +lI lI l. +Filename Field Name!Length!Interpreted as +_ +c_name!c_namesize!Pathname string +_ +.T& +cB | cB | cB +lI lI l. +File Data Field Name!Length!Interpreted as +_ +c_filedata!c_filesize!Data +.TE +.SS "cpio Header" +.P +For each file in the archive, a header as defined previously shall be +written. The information in the header fields is written as streams of +the ISO/IEC\ 646:\|1991 standard characters interpreted as octal numbers. The octal numbers +shall be extended to the necessary length by appending the ISO/IEC\ 646:\|1991 standard IRV +zeros at the most-significant-digit end of the number; the result is +written to the most-significant digit of the stream of octets first. +The fields shall be interpreted as follows: +.IP "\fIc_magic\fR" 10 +Identify the archive as being a transportable archive by containing the +identifying value +.BR \(dq070707\(dq . +.IP "\fIc_dev\fR,\ \fIc_ino\fR" 10 +Contains values that uniquely identify the file within the archive +(that is, no files contain the same pair of +.IR c_dev +and +.IR c_ino +values unless they are links to the same file). The values shall be +determined in an unspecified manner. +.IP "\fIc_mode\fR" 10 +Contains the file type and access permissions as defined in the +following table. +.br +.sp +.ce 1 +\fBTable 4-17: Values for cpio c_mode Field\fR +.TS +center box tab(@); +cB | cB | cB +l | n | l. +File Permissions Name@Value@Indicates +_ +C_IRUSR@000\|400@Read by owner +C_IWUSR@000\|200@Write by owner +C_IXUSR@000\|100@Execute by owner +C_IRGRP@000\|040@Read by group +C_IWGRP@000\|020@Write by group +C_IXGRP@000\|010@Execute by group +C_IROTH@000\|004@Read by others +C_IWOTH@000\|002@Write by others +C_IXOTH@000\|001@Execute by others +C_ISUID@004\|000@Set \fIuid\fP +C_ISGID@002\|000@Set \fIgid\fP +C_ISVTX@001\|000@Reserved +_ +.T& +cB | cB | cB +l | n | l. +File Type Name@Value@Indicates +_ +C_ISDIR@040\|000@Directory +C_ISFIFO@010\|000@FIFO +C_ISREG@0100\|000@Regular file +C_ISLNK@0120\|000@Symbolic link +.RS 10 +.P +C_ISBLK@060\|000@Block special file +C_ISCHR@020\|000@Character special file +C_ISSOCK@0140\|000@Socket +.P +C_ISCTG@0110\|000@Reserved +.TE +.P +Directories, FIFOs, symbolic links, and regular files shall be +supported on a system conforming to this volume of POSIX.1\(hy2008; additional values defined +previously are reserved for compatibility with existing systems. +Additional file types may be supported; however, such files should not +be written to archives intended to be transported to other systems. +.RE +.IP "\fIc_uid\fR" 10 +Contains the user ID of the owner. +.IP "\fIc_gid\fR" 10 +Contains the group ID of the group. +.IP "\fIc_nlink\fR" 10 +Contains a number greater than or equal to the number of links in the +archive referencing the file. If the +.BR \(mia +option is used to append to a +.IR cpio +archive, then the +.IR pax +utility need not account for the files in the existing part of the +archive when calculating the +.IR c_nlink +values for the appended part of the archive, and need not alter the +.IR c_nlink +values in the existing part of the archive if additional files with the +same +.IR c_dev +and +.IR c_ino +values are appended to the archive. +.IP "\fIc_rdev\fR" 10 +Contains implementation-defined information for character or block +special files. +.IP "\fIc_mtime\fR" 10 +Contains the latest time of modification of the file at the time the +archive was created. +.IP "\fIc_namesize\fR" 10 +Contains the length of the pathname, including the terminating NUL +character. +.IP "\fIc_filesize\fR" 10 +Contains the length in octets of the data section following the +header structure. +.SS "cpio Filename" +.P +The +.IR c_name +field shall contain the pathname of the file. The length of this field +in octets is the value of +.IR c_namesize . +.P +If a filename is found on the medium that would create an invalid +pathname, it is implementation-defined whether the data from the file +is stored on the file hierarchy and under what name it is stored. +.P +All characters shall be represented in the ISO/IEC\ 646:\|1991 standard IRV. For maximum +portability between implementations, names should be selected from +characters represented by the portable filename character set as +octets with the most significant bit zero. If an implementation +supports the use of characters outside the portable filename character +set in names for files, users, and groups, one or more +implementation-defined encodings of these characters shall be provided +for interchange purposes. However, the +.IR pax +utility shall never create filenames on the local system that cannot +be accessed via the procedures described previously in this volume of POSIX.1\(hy2008. If a +filename is found on the medium that would create an invalid filename, +it is implementation-defined whether the data from the file is stored on +the local file system and under what name it is stored. The +.IR pax +utility may choose to ignore these files as long as it produces an +error indicating that the file is being ignored. +.SS "cpio File Data" +.P +Following +.IR c_name , +there shall be +.IR c_filesize +octets of data. Interpretation of such data occurs in a manner +dependent on the file. For regular files, the data shall consist +of the contents of the file. For symbolic links, the data shall +consist of the contents of the symbolic link. If +.IR c_filesize +is zero, no data shall be contained in +.IR c_filedata . +.P +When restoring from an archive: +.IP " *" 4 +If the user does not have appropriate privileges to create a file of +the specified type, +.IR pax +shall ignore the entry and write an error message to standard error. +.IP " *" 4 +Only regular files and symbolic links have data to be restored. Presuming +a regular file meets any selection criteria that might be imposed on +the format-reading utility by the user, such data shall be restored. +.IP " *" 4 +If a user does not have appropriate privileges to set a particular mode +flag, the flag shall be ignored. Some of the mode flags in the archive +format are not mentioned elsewhere in this volume of POSIX.1\(hy2008. If the implementation does +not support those flags, they may be ignored. +.SS "cpio Special Entries" +.P +FIFO special files, directories, and the trailer shall be recorded with +.IR c_filesize +equal to zero. Symbolic links shall be recorded with +.IR c_filesize +equal to the length of the contents of the symbolic link. +For other special files, +.IR c_filesize +is unspecified by this volume of POSIX.1\(hy2008. The header for the next file entry in the +archive shall be written directly after the last octet of the file +entry preceding it. A header denoting the filename +.BR TRAILER!!! +shall indicate the end of the archive; the contents of octets in the +last block of the archive following such a header are undefined. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All files were processed successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If +.IR pax +cannot create a file or a link when reading an archive or cannot find a +file when writing an archive, or cannot preserve the user ID, group ID, +or file mode when the +.BR \(mip +option is specified, a diagnostic message shall be written to standard +error and a non-zero exit status shall be returned, but processing +shall continue. In the case where +.IR pax +cannot create a link to a file, +.IR pax +shall not, by default, create a second copy of the file. +.P +If the extraction of a file from an archive is prematurely terminated +by a signal or error, +.IR pax +may have only partially extracted the file or (if the +.BR \(min +option was not specified) may have extracted a file of the same name as +that specified by the user, but which is not the file the user wanted. +Additionally, the file modes of extracted directories may have +additional bits from the S_IRWXU mask set as well as incorrect +modification and access times. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Caution is advised when using the +.BR \(mia +option to append to a +.IR cpio +format archive. If any of the files being appended happen to be given +the same +.IR c_dev +and +.IR c_ino +values as a file in the existing part of the archive, then they may be +treated as links to that file on extraction. Thus, it is risky to use +.BR \(mia +with +.IR cpio +format except when it is done on the same system that the original +archive was created on, and with the same +.IR pax +utility, and in the knowledge that there has been little or no file +system activity since the original archive was created that could lead +to any of the files appended being given the same +.IR c_dev +and +.IR c_ino +values as an unrelated file in the existing part of the archive. Also, +when (intentionally) appending additional links to a file in the +existing part of the archive, the +.IR c_nlink +values in the modified archive can be smaller than the number of links +to the file in the archive, which may mean that the links are not +preserved on extraction. +.P +The +.BR \(mip +(privileges) option was invented to reconcile differences between +historical +.IR tar +and +.IR cpio +implementations. In particular, the two utilities use +.BR \(mim +in diametrically opposed ways. The +.BR \(mip +option also provides a consistent means of extending the ways in which +future file attributes can be addressed, such as for enhanced security +systems or high-performance files. Although it may seem complex, there +are really two modes that are most commonly used: +.IP "\fB\(mip\ e\fR" 8 +``Preserve everything''. This would be used by the historical +superuser, someone with all appropriate privileges, to preserve all +aspects of the files as they are recorded in the archive. The +.BR e +flag is the sum of +.BR o +and +.BR p , +and other implementation-defined attributes. +.IP "\fB\(mip\ p\fR" 8 +``Preserve'' the file mode bits. This would be used by the user with +regular privileges who wished to preserve aspects of the file other +than the ownership. The file times are preserved by default, but two +other flags are offered to disable these and use the time of +extraction. +.P +The one pathname per line format of standard input precludes +pathnames containing + +characters. Although such pathnames violate the portable filename +guidelines, they may exist and their presence may inhibit usage of +.IR pax +within shell scripts. This problem is inherited from historical archive +programs. The problem can be avoided by listing filename arguments on +the command line instead of on standard input. +.P +It is almost certain that appropriate privileges are required for +.IR pax +to accomplish parts of this volume of POSIX.1\(hy2008. Specifically, creating files of type +block special or character special, restoring file access times unless +the files are owned by the user (the +.BR \(mit +option), or preserving file owner, group, and mode (the +.BR \(mip +option) all probably require appropriate privileges. +.P +In +.BR read +mode, implementations are permitted to overwrite files when the archive +has multiple members with the same name. This may fail if permissions +on the first version of the file do not permit it to be overwritten. +.P +The +.BR cpio +and +.BR ustar +formats can only support files up to 8\|589\|934\|592 bytes +(8 \(** 2^30) in size. +.P +When archives containing binary header information are listed , the +filenames printed may cause strange behavior on some terminals. +.P +When all of the following are true: +.IP " 1." 4 +A file of type directory is being placed into an archive. +.IP " 2." 4 +The +.BR ustar +archive format is being used. +.IP " 3." 4 +The pathname of the directory is less than or equal to 155 bytes long +(it will fit in the +.IR prefix +field in the +.BR ustar +header block). +.IP " 4." 4 +The last component of the pathname of the directory is longer than 100 +bytes long (it will not fit in the +.IR name +field in the +.BR ustar +header block). +.P +some implementations of the +.IR pax +utility will place the entire directory pathname in the +.IR prefix +field, set the +.IR name +field to an empty string, and place the directory in the archive. +Other implementations of the +.IR pax +utility will give an error under these conditions because the +.IR name +field is not large enough to hold the last component of the directory name. +This standard allows either behavior. However, when extracting a directory +from a +.BR ustar +format archive, this standard requires that all implementations be able +to extract a directory even if the +.IR name +field contains an empty string as long as the +.IR prefix +field does not also contain an empty string. +.SH EXAMPLES +The following command: +.sp +.RS 4 +.nf +\fB +pax \(miw \(mif /dev/rmt/1m . +.fi \fR +.P +.RE +.P +copies the contents of the current directory to tape drive 1, medium +density (assuming historical System V device naming procedures\(emthe +historical BSD device name would be +.BR /dev/rmt9 ). +.P +The following commands: +.sp +.RS 4 +.nf +\fB +mkdir \fInewdir\fR +pax \(mirw \fIolddir newdir\fR +.fi \fR +.P +.RE +.P +copy the +.IR olddir +directory hierarchy to +.IR newdir . +.sp +.RS 4 +.nf +\fB +pax \(mir \(mis ',^//*usr//*,,' \(mif a.pax +.fi \fR +.P +.RE +.P +reads the archive +.BR a.pax , +with all files rooted in +.BR /usr +in the archive extracted relative to the current directory. +.P +Using the option: +.sp +.RS 4 +.nf +\fB +\(mio listopt="%M %(atime)T %(size)D %(name)s" +.fi \fR +.P +.RE +.P +overrides the default output description in Standard Output and instead +writes: +.sp +.RS 4 +.nf +\fB +\(mirw\(mirw\(mi\|\(mi\|\(mi Jan 12 15:53 2003 1492 /usr/foo/bar +.fi \fR +.P +.RE +.P +Using the options: +.sp +.RS 4 +.nf +\fB +\(mio listopt='%L\et%(size)D\en%.7' \e +\(mio listopt='(name)s\en%(atime)T\en%T' +.fi \fR +.P +.RE +.P +overrides the default output description in Standard Output and instead +writes: +.sp +.RS 4 +.nf +\fB +/usr/foo/bar \(mi> /tmp 1492 +/usr/fo +Jan 12 15:53 1991 +Jan 31 15:53 2003 +.fi \fR +.P +.RE +.SH RATIONALE +The +.IR pax +utility was new for the ISO\ POSIX\(hy2:\|1993 standard. It represents a peaceful +compromise between advocates of the historical +.IR tar +and +.IR cpio +utilities. +.P +A fundamental difference between +.IR cpio +and +.IR tar +was in the way directories were treated. The +.IR cpio +utility did not treat directories differently from other files, and to +select a directory and its contents required that each file in the +hierarchy be explicitly specified. For +.IR tar , +a directory matched every file in the file hierarchy it rooted. +.P +The +.IR pax +utility offers both interfaces; by default, directories map into the +file hierarchy they root. The +.BR \(mid +option causes +.IR pax +to skip any file not explicitly referenced, as +.IR cpio +historically did. The +.IR tar +.BR \(mi \c +.IR style +behavior was chosen as the default because it was believed that this +was the more common usage and because +.IR tar +is the more commonly available interface, as it was historically +provided on both System V and BSD implementations. +.P +The data interchange format specification in this volume of POSIX.1\(hy2008 requires that +processes with ``appropriate privileges'' shall always restore the +ownership and permissions of extracted files exactly as archived. If +viewed from the historic equivalence between superuser and +``appropriate privileges'', there are two problems +with this requirement. First, users running as superusers may +unknowingly set dangerous permissions on extracted files. Second, it is +needlessly limiting, in that superusers cannot extract files and own +them as superuser unless the archive was created by the superuser. (It +should be noted that restoration of ownerships and permissions for the +superuser, by default, is historical practice in +.IR cpio , +but not in +.Im tar .) +In order to avoid these two problems, the +.IR pax +specification has an additional ``privilege'' mechanism, the +.BR \(mip +option. Only a +.IR pax +invocation with the privileges needed, and which has the +.BR \(mip +option set using the +.BR e +specification character, has appropriate privileges to restore +full ownership and permission information. +.P +Note also that this volume of POSIX.1\(hy2008 requires that the file ownership and access +permissions shall be set, on extraction, in the same fashion as the +\fIcreat\fR() +function when provided with the mode stored in the archive. This means +that the file creation mask of the user is applied to the file +permissions. +.P +Users should note that directories may be created by +.IR pax +while extracting files with permissions that are different from those +that existed at the time the archive was created. When extracting +sensitive information into a directory hierarchy that no longer exists, +users are encouraged to set their file creation mask appropriately to +protect these files during extraction. +.P +The table of contents output is written to standard output to +facilitate pipeline processing. +.P +An early proposal had hard links displaying for all pathnames. This +was removed because it complicates the output of the case where +.BR \(miv +is not specified and does not match historical +.IR cpio +usage. The hard-link information is available in the +.BR \(miv +display. +.P +The description of the +.BR \(mil +option allows implementations to make hard links to symbolic links. +Earlier versions of this standard did not specify any way to create a +hard link to a symbolic link, but many implementations provided this +capability as an extension. If there are hard links to symbolic links +when an archive is created, the implementation is required to archive +the hard link in the archive (unless +.BR \(miH +or +.BR \(miL +is specified). When in +.BR read +mode and in +.BR copy +mode, implementations supporting hard links to symbolic links should +use them when appropriate. +.P +The archive formats inherited from the POSIX.1\(hy1990 standard have certain restrictions +that have been brought along from historical usage. For example, there +are restrictions on the length of pathnames stored in the archive. +When +.IR pax +is used in +.BR copy (\c +.BR \(mirw ) +mode (copying directory hierarchies), the ability to use extensions +from the +.BR \(mix \c +.BR pax +format overcomes these restrictions. +.P +The default +.IR blocksize +value of 5\|120 bytes for +.IR cpio +was selected because it is one of the standard block-size values for +.IR cpio , +set when the +.BR \(miB +option is specified. (The other default block-size value for +.IR cpio +is 512 bytes, and this was considered to be too small.) The default +block value of 10\|240 bytes for +.IR tar +was selected because that is the standard block-size value for BSD +.IR tar . +The maximum block size of 32\|256 bytes (2\s-3\u15\d\s+3\(mi512 bytes) +is the largest multiple of 512 bytes that fits into a signed 16-bit +tape controller transfer register. There are known limitations in some +historical systems that would prevent larger blocks from being +accepted. Historical values were chosen to improve compatibility with +historical scripts using +.IR dd +or similar utilities to manipulate archives. Also, default block sizes +for any file type other than character special file has been deleted +from this volume of POSIX.1\(hy2008 as unimportant and not likely to affect the structure of the +resulting archive. +.P +Implementations are permitted to modify the block-size value based on +the archive format or the device to which the archive is being +written. This is to provide implementations with the opportunity to +take advantage of special types of devices, and it should not be used +without a great deal of consideration as it almost certainly decreases +archive portability. +.P +The intended use of the +.BR \(min +option was to permit extraction of one or more files from the archive +without processing the entire archive. This was viewed by the standard +developers as offering significant performance advantages over +historical implementations. The +.BR \(min +option in early proposals had three effects; the first was to cause +special characters in patterns to not be treated specially. The second +was to cause only the first file that matched a pattern to be +extracted. The third was to cause +.IR pax +to write a diagnostic message to standard error when no file was found +matching a specified pattern. Only the second behavior is retained by +this volume of POSIX.1\(hy2008, for many reasons. First, it is in general not acceptable for a +single option to have multiple effects. Second, the ability to make +pattern matching characters act as normal characters +is useful for parts of +.IR pax +other than file extraction. Third, a finer degree of control over the +special characters is useful because users may wish to normalize only a +single special character in a single filename. Fourth, given a more +general escape mechanism, the previous behavior of the +.BR \(min +option can be easily obtained using the +.BR \(mis +option or a +.IR sed +script. Finally, writing a diagnostic message when a pattern specified +by the user is unmatched by any file is useful behavior in all cases. +.P +In this version, the +.BR \(min +was removed from the +.BR copy +mode synopsis of +.IR pax ; +it is inapplicable because there are no pattern operands specified in +this mode. +.P +There is another method than +.IR pax +for copying subtrees in POSIX.1\(hy2008 described as part of the +.IR cp +utility. Both methods are historical practice: +.IR cp +provides a simpler, more intuitive interface, while +.IR pax +offers a finer granularity of control. Each provides additional +functionality to the other; in particular, +.IR pax +maintains the hard-link structure of the hierarchy while +.IR cp +does not. It is the intention of the standard developers that the +results be similar (using appropriate option combinations in both +utilities). The results are not required to be identical; there seemed +insufficient gain to applications to balance the difficulty of +implementations having to guarantee that the results would be exactly +identical. +.P +A single archive may span more than one file. It is suggested that +implementations provide informative messages to the user on standard +error whenever the archive file is changed. +.P +The +.BR \(mid +option (do not create intermediate directories not listed in the +archive) found in early proposals was originally provided as a +complement to the historic +.BR \(mid +option of +.IR cpio . +It has been deleted. +.P +The +.BR \(mis +option in early proposals specified a subset of the substitution +command from the +.IR ed +utility. As there was no reason for only a subset to be supported, the +.BR \(mis +option is now compatible with the current +.IR ed +specification. Since the delimiter can be any non-null character, the +following usage with single + +characters is valid: +.sp +.RS 4 +.nf +\fB +pax \(mis " foo bar " ... +.fi \fR +.P +.RE +.P +The +.BR \(mit +description is worded so as to note that this may cause the access time +update caused by some other activity (which occurs while the file is +being read) to be overwritten. +.P +The default behavior of +.IR pax +with regard to file modification times is the same as historical +implementations of +.IR tar . +It is not the historical behavior of +.IR cpio . +.P +Because the +.BR \(mii +option uses +.BR /dev/tty , +utilities without a controlling terminal are not able to use this +option. +.P +The +.BR \(miy +option, found in early proposals, has been deleted because a line +containing a single + +for the +.BR \(mii +option has equivalent functionality. The special lines for the +.BR \(mii +option (a single + +and the empty line) are historical practice in +.IR cpio . +.P +In early drafts, a +.BR \(mie \c +.IR charmap +option was included to increase portability of files between systems +using different coded character sets. This option was omitted because +it was apparent that consensus could not be formed for it. In this +version, the use of UTF\(hy8 should be an adequate substitute. +.P +The ISO\ POSIX\(hy2:\|1993 standard and ISO\ POSIX\(hy1 standard requirements for +.IR pax , +however, made it very difficult to create a single archive containing +files created using extended characters provided by different locales. +This version adds the +.BR hdrcharset +keyword to make it possible to archive files in these cases without +dropping files due to translation errors. +.P +Translating filenames and other attributes from a locale's encoding to +UTF\(hy8 and then back again can lose information, as the resulting +filename might not be byte-for-byte equivalent to the original. To +avoid this problem, users can specify the +.BR \(mio +.BR hdrcharset=binary +option, which will cause the resulting archive to use binary +format for all names and attributes. Such archives are not portable +among hosts that use different native encodings (e.g., EBCDIC +\fIversus\fR ASCII-based encodings), but they will allow interchange +among the vast majority of POSIX file systems in practical use. Also, +the +.BR \(mio +.BR hdrcharset=binary +option will cause +.IR pax +in +.BR copy +mode to behave more like other standard utilities such as +.IR cp . +.P +If the values specified by the +.BR \(mio +.BR exthdr.name=value , +.BR \(mio +.BR globexthdr.name=value , +or by +.BR $TMPDIR +(if +.BR \(mio +.BR globexthdr.name +is not specified) require a character encoding other than that +described in the ISO/IEC\ 646:\|1991 standard, a +.BR path +extended header record will have to be created for the file. If a +.BR hdrcharset +extended header record is active for such headers, it will determine +the codeset used for the value field in these extended +.BR path +header records. These +.BR path +extended header records always need to be created when writing an +archive even if +.BR hdrcharset=binary +has been specified and would contain the same (binary) data that +appears in the +.BR ustar +header record prefix and +.IR name +fields. (In other words, an extended header +.BR path +record is always required to be generated if the +.IR prefix +or +.IR name +fields contain non-ASCII characters even when +.BR hdrcharset=binary +is also in effect for that file.) +.P +The +.BR \(mik +option was added to address international concerns about the dangers +involved in the character set transformations of +.BR \(mie +(if the target character set were different from the source, the +filenames might be transformed into names matching existing files) and +also was made more general to protect files transferred between file +systems with different +{NAME_MAX} +values (truncating a filename on a smaller system might also +inadvertently overwrite existing files). As stated, it prevents any +overwriting, even if the target file is older than the source. This +version adds more granularity of options to solve this problem by +introducing the +.BR \(mio \c +.BR invalid=option \c +\(emspecifically the +.BR UTF\(hy8 +and +.BR binary +actions. (Note that an existing file is still subject to overwriting in +this case. The +.BR \(mik +option closes that loophole.) +.P +Some of the file characteristics referenced in this volume of POSIX.1\(hy2008 might not be +supported by some archive formats. For example, neither the +.BR tar +nor +.BR cpio +formats contain the file access time. For this reason, the +.BR e +specification character has been provided, intended to cause all file +characteristics specified in the archive to be retained. +.P +It is required that extracted directories, by default, have their +access and modification times and permissions set to the values +specified in the archive. This has obvious problems in that the +directories are almost certainly modified after being extracted and +that directory permissions may not permit file creation. One possible +solution is to create directories with the mode specified in the +archive, as modified by the +.IR umask +of the user, with sufficient permissions to allow file creation. After +all files have been extracted, +.IR pax +would then reset the access and modification times and permissions as +necessary. +.P +The list-mode formatting description borrows heavily from the one +defined by the +.IR printf +utility. However, since there is no separate operand list to get +conversion arguments, the format was extended to allow specifying the +name of the conversion argument as part of the conversion +specification. +.P +The +.BR T +conversion specifier allows time fields to be displayed in any of +the date formats. Unlike the +.IR ls +utility, +.IR pax +does not adjust the format when the date is less than six months in the +past. This makes parsing the output more predictable. +.P +The +.BR D +conversion specifier handles the ability to display the major/minor +or file size, as with +.IR ls , +by using \fR%\(mi8(\fIsize\fR)D\fR. +.P +The +.BR L +conversion specifier handles the +.IR ls +display for symbolic links. +.P +Conversion specifiers were added to generate existing known types used +for +.IR ls . +.SS "pax Interchange Format" +.P +The new POSIX data interchange format was developed primarily to +satisfy international concerns that the +.BR ustar +and +.BR cpio +formats did not provide for file, user, and group names encoded in +characters outside a subset of the ISO/IEC\ 646:\|1991 standard. The standard developers +realized that this new POSIX data interchange format should be very +extensible because there were other requirements they foresaw in the +near future: +.IP " *" 4 +Support international character encodings and locale information +.IP " *" 4 +Support security information (ACLs, and so on) +.IP " *" 4 +Support future file types, such as realtime or contiguous files +.IP " *" 4 +Include data areas for implementation use +.IP " *" 4 +Support systems with words larger than 32 bits and timers with +subsecond granularity +.P +The following were not goals for this format because these are better +handled by separate utilities or are inappropriate for a portable +format: +.IP " *" 4 +Encryption +.IP " *" 4 +Compression +.IP " *" 4 +Data translation between locales and codesets +.IP " *" 4 +.IR inode +storage +.P +The format chosen to support the goals is an extension of the +.BR ustar +format. Of the two formats previously available, only the +.BR ustar +format was selected for extensions because: +.IP " *" 4 +It was easier to extend in an upwards-compatible way. It offered version +flags and header block type fields with room for future +standardization. The +.BR cpio +format, while possessing a more flexible file naming methodology, could +not be extended without breaking some theoretical implementation +or using a dummy filename that could be a legitimate filename. +.IP " *" 4 +Industry experience since the original ``\c +.IR tar +wars'' fought in developing the ISO\ POSIX\(hy1 standard has clearly been in favor of the +.BR ustar +format, which is generally the default output format selected for +.IR pax +implementations on new systems. +.P +The new format was designed with one additional goal in mind: +reasonable behavior when an older +.IR tar +or +.IR pax +utility happened to read an archive. Since the POSIX.1\(hy1990 standard mandated that a +``format-reading utility'' had to treat unrecognized +.IR typeflag +values as regular files, this allowed the format to include all the +extended information in a pseudo-regular file that preceded each real +file. An option is given that allows the archive creator to set up +reasonable names for these files on the older systems. Also, the +normative text suggests that reasonable file access values be used for +this +.BR ustar +header block. Making these header files inaccessible for convenient +reading and deleting would not be reasonable. File permissions of 600 +or 700 are suggested. +.P +The +.BR ustar +.IR typeflag +field was used to accommodate the additional functionality of the new +format rather than magic or version because the POSIX.1\(hy1990 standard (and, by +reference, the previous version of +.IR pax ), +mandated the behavior of the format-reading utility when it encountered +an unknown +.IR typeflag , +but was silent about the other two fields. +.P +Early proposals for the first version of this standard contained a proposed +archive format that was based on compatibility with the standard for +tape files (ISO\ 1001, similar to the format used historically on many +mainframes and minicomputers). This format was overly complex and required +considerable overhead in volume and header records. Furthermore, the +standard developers felt that it would not be acceptable to the community +of POSIX developers, so it was later changed to be a format more closely +related to historical practice on POSIX systems. +.P +The prefix and name split of pathnames in +.BR ustar +was replaced by the single path extended header record for simplicity. +.P +The concept of a global extended header (\c +.IR typeflag \c +.BR g ) +was controversial. If this were applied to an archive being recorded on +magnetic tape, a few unreadable blocks at the beginning of the tape +could be a serious problem; a utility attempting to extract as many +files as possible from a damaged archive could lose a large percentage +of file header information in this case. However, if the archive were +on a reliable medium, such as a CD\(hyROM, the global extended header +offers considerable potential size reductions by eliminating redundant +information. Thus, the text warns against using the global method for +unreliable media and provides a method for implanting global +information in the extended header for each file, rather than in the +.IR typeflag +.BR g +records. +.P +No facility for data translation or filtering on a per-file basis is +included because the standard developers could not invent an interface +that would allow this in an efficient manner. If a filter, such as +encryption or compression, is to be applied to all the files, it is +more efficient to apply the filter to the entire archive as a single +file. The standard developers considered interfaces that would invoke a +shell script for each file going into or out of the archive, but the +system overhead in this approach was considered to be too high. +.P +One such approach would be to have +.BR filter= +records that give a pathname for an executable. When the program is +invoked, the file and archive would be open for standard input/output +and all the header fields would be available as environment variables +or command-line arguments. The standard developers did discuss such +schemes, but they were omitted from POSIX.1\(hy2008 due to concerns about +excessive overhead. Also, the program itself would need to be in the +archive if it were to be used portably. +.P +There is currently no portable means of identifying the character +set(s) used for a file in the file system. Therefore, +.IR pax +has not been given a mechanism to generate charset records +automatically. The only portable means of doing this is for the user to +write the archive using the +.BR \(mio \c +.BR charset=string +command line option. This assumes that all of the files in the archive +use the same encoding. The ``implementation-defined'' text is +included to allow for a system that can identify the encodings used for +each of its files. +.P +The table of standards that accompanies the charset record description +is acknowledged to be very limited. Only a limited number of character +set standards is reasonable for maximal interchange. Any character set +is, of course, possible by prior agreement. It was suggested that +EBCDIC be listed, but it was omitted because it is not defined by a +formal standard. Formal standards, and then only those with reasonably +large followings, can be included here, simply as a matter of +practicality. The <\fIvalue\fP>s represent names of officially +registered character sets in the format required by the ISO\ 2375:\|1985 standard. +.P +The normal + +or +-separated +list rules are not followed in the case of keyword options to allow +ease of argument parsing for +.IR getopts . +.P +Further information on character encodings is in +.IR "pax Archive Character Set Encoding/Decoding". +.P +The standard developers have reserved keyword name space for vendor +extensions. It is suggested that the format to be used is: +.sp +.RS 4 +.nf +\fB +\fIVENDOR.keyword\fR +.fi \fR +.P +.RE +.P +where +.IR VENDOR +is the name of the vendor or organization in all uppercase letters. It +is further suggested that the keyword following the + +be named differently than any of the standard keywords so that it could +be used for future standardization, if appropriate, by omitting the +.IR VENDOR +prefix. +.P +The <\fIlength\fP> field in the extended header record was included to +make it simpler to step through the records, even if a record contains +an unknown format (to a particular +.IR pax ) +with complex interactions of special characters. It also provides a +minor integrity checkpoint within the records to aid a program +attempting to recover files from a damaged archive. +.P +There are no extended header versions of the +.IR devmajor +and +.IR devminor +fields because the unspecified format +.BR ustar +header field should be sufficient. If they are not, vendor-specific +extended keywords (such as +.IR VENDOR.devmajor ) +should be used. +.P +Device and +.IR i -number +labeling of files was not adopted from +.IR cpio ; +files are interchanged strictly on a symbolic name basis, as in +.BR ustar . +.P +Just as with the +.BR ustar +format descriptions, the new format makes no special arrangements for +multi-volume archives. Each of the +.IR pax +archive types is assumed to be inside a single POSIX file and splitting +that file over multiple volumes (diskettes, tape cartridges, and so +on), processing their labels, and mounting each in the proper sequence +are considered to be implementation details that cannot be described +portably. +.P +The +.BR pax +format is intended for interchange, not only for backup on a single +(family of) systems. It is not as densely packed as might be possible +for backup: +.IP " *" 4 +It contains information as coded characters that could be coded in +binary. +.IP " *" 4 +It identifies extended records with name fields that could be omitted +in favor of a fixed-field layout. +.IP " *" 4 +It translates names into a portable character set and identifies +locale-related information, both of which are probably unnecessary for +backup. +.P +The requirements on restoring from an archive are slightly different +from the historical wording, allowing for non-monolithic privilege to +bring forward as much as possible. In particular, attributes such as +``high performance file'' might be broadly but not universally granted +while set-user-ID or +\fIchown\fR() +might be much more restricted. There is no implication in POSIX.1\(hy2008 that +the security information be honored after it is restored to the file +hierarchy, in spite of what might be improperly inferred by the silence +on that topic. That is a topic for another standard. +.P +Links are recorded in the fashion described here because a link can be +to any file type. It is desirable in general to be able to restore part +of an archive selectively and restore all of those files completely. If +the data is not associated with each link, it is not possible to do +this. However, the data associated with a file can be large, and when +selective restoration is not needed, this can be a significant burden. +The archive is structured so that files that have no associated data +can always be restored by the name of any link name of any link, and +the user may choose whether data is recorded with each instance of a +file that contains data. The format permits mixing of both types of +links in a single archive; this can be done for special needs, and +.IR pax +is expected to interpret such archives on input properly, despite the +fact that there is no +.IR pax +option that would force this mixed case on output. (When +.BR \(mio +.BR linkdata +is used, the output must contain the duplicate data, but the +implementation is free to include it or omit it when +.BR \(mio +.BR linkdata +is not used.) +.P +The time values are included as extended header records for those +implementations needing more than the eleven octal digits allowed by +the +.BR ustar +format. Portable file timestamps cannot be negative. If +.IR pax +encounters a file with a negative timestamp in +.BR copy +or +.BR write +mode, it can reject the file, substitute a non-negative timestamp, or +generate a non-portable timestamp with a leading +.BR '\(mi' . +Even though some implementations can support finer file-time +granularities than seconds, the normative text requires support only +for seconds since the Epoch because the ISO\ POSIX\(hy1 standard states them that way. The +.BR ustar +format includes only +.IR mtime ; +the new format adds +.IR atime +and +.IR ctime +for symmetry. The +.IR atime +access time restored to the file system will be affected by the +.BR \(mip +.BR a +and +.BR \(mip +.BR e +options. The +.IR ctime +creation time (actually +.IR inode +modification time) is described with appropriate privileges so that +it can be ignored when writing to the file system. POSIX does not +provide a portable means to change file creation time. Nothing is +intended to prevent a non-portable implementation of +.IR pax +from restoring the value. +.P +The +.IR gid , +.IR size , +and +.IR uid +extended header records were included to allow expansion beyond the +sizes specified in the regular +.IR tar +header. New file system architectures are emerging that will exhaust +the 12-digit size field. There are probably not many systems requiring +more than 8 digits for user and group IDs, but the extended header +values were included for completeness, allowing overrides for all of +the decimal values in the +.IR tar +header. +.P +The standard developers intended to describe the effective results of +.IR pax +with regard to file ownerships and permissions; implementations are not +restricted in timing or sequencing the restoration of such, provided +the results are as specified. +.P +Much of the text describing the extended headers refers to use in ``\c +.BR write +or +.BR copy +modes''. The +.BR copy +mode references are due to the normative text: ``The effect of the +copy shall be as if the copied files were written to an archive file +and then subsequently extracted .\|.\|.''. There is certainly no way to +test whether +.IR pax +is actually generating the extended headers in +.BR copy +mode, but the effects must be as if it had. +.SS "pax Archive Character Set Encoding/Decoding" +.P +There is a need to exchange archives of files between systems of +different native codesets. Filenames, group names, and user names must +be preserved to the fullest extent possible when an archive is read on +the receiving platform. Translation of the contents of files is not +within the scope of the +.IR pax +utility. +.P +There will also be the need to represent characters that are not +available on the receiving platform. These unsupported characters +cannot be automatically folded to the local set of characters due to +the chance of collisions. This could result in overwriting previous +extracted files from the archive or pre-existing files on the system. +.P +For these reasons, the codeset used to represent characters within the +extended header records of the +.IR pax +archive must be sufficiently rich to handle all commonly used character +sets. The fields requiring translation include, at a minimum, +filenames, user names, group names, and link pathnames. Implementations +may wish to have localized extended keywords that use non-portable +characters. +.P +The standard developers considered the following options: +.IP " *" 4 +The archive creator specifies the well-defined name of the source +codeset. The receiver must then recognize the codeset name and perform +the appropriate translations to the destination codeset. +.IP " *" 4 +The archive creator includes within the archive the character mapping +table for the source codeset used to encode extended header records. +The receiver must then read the character mapping table and perform the +appropriate translations to the destination codeset. +.IP " *" 4 +The archive creator translates the extended header records in the +source codeset into a canonical form. The receiver must then perform +the appropriate translations to the destination codeset. +.P +The approach that incorporates the name of the source codeset poses the +problem of codeset name registration, and makes the archive useless to +.IR pax +archive decoders that do not recognize that codeset. +.P +Because parts of an archive may be corrupted, the standard developers +felt that including the character map of the source codeset was too +fragile. The loss of this one key component could result in making the +entire archive useless. (The difference between this and the global +extended header decision was that the latter has a +workaround\(emduplicating extended header records on unreliable +media\(embut this would be too burdensome for large character set +maps.) +.P +Both of the above approaches also put an undue burden on the +.IR pax +archive receiver to handle the cross-product of all source and +destination codesets. +.P +To simplify the translation from the source codeset to the canonical +form and from the canonical form to the destination codeset, the +standard developers decided that the internal representation should be +a stateless encoding. A stateless encoding is one where each codepoint +has the same meaning, without regard to the decoder being in a specific +state. An example of a stateful encoding would be the Japanese +Shift-JIS; an example of a stateless encoding would be the ISO/IEC\ 646:\|1991 standard +(equivalent to 7-bit ASCII). +.P +For these reasons, the standard developers decided to adopt a canonical +format for the representation of file information strings. The obvious, +well-endorsed candidate is the ISO/IEC\ 10646\(hy1:\|2000 standard (based in part on Unicode), which +can be used to represent the characters of virtually all standardized +character sets. The standard developers initially agreed upon using +UCS2 (16-bit Unicode) as the internal representation. This repertoire +of characters provides a sufficiently rich set to represent all +commonly-used codesets. +.P +However, the standard developers found that the 16-bit Unicode +representation had some problems. It forced the issue of standardizing +byte ordering. The 2-byte length of each character made the extended +header records twice as long for the case of strings coded entirely +from historical 7-bit ASCII. For these reasons, the standard developers +chose the UTF\(hy8 defined in the ISO/IEC\ 10646\(hy1:\|2000 standard. This multi-byte representation +encodes UCS2 or UCS4 characters reliably and deterministically, +eliminating the need for a canonical byte ordering. In addition, NUL +octets and other characters possibly confusing to POSIX file systems do +not appear, except to represent themselves. It was realized that +certain national codesets take up more space after the encoding, due to +their placement within the UCS range; it was felt that the usefulness +of the encoding of the names outweighs the disadvantage of size +increase for file, user, and group names. +.P +The encoding of UTF\(hy8 is as follows: +.sp +.RS 4 +.nf +\fB +UCS4 Hex Encoding UTF-8 Binary Encoding +.P +00000000-0000007F 0xxxxxxx +00000080-000007FF 110xxxxx 10xxxxxx +00000800-0000FFFF 1110xxxx 10xxxxxx 10xxxxxx +00010000-001FFFFF 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx +00200000-03FFFFFF 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx +04000000-7FFFFFFF 1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx +.fi \fR +.P +.RE +.P +where each +.BR 'x' +represents a bit value from the character being translated. +.SS "ustar Interchange Format" +.P +The description of the +.BR ustar +format reflects numerous enhancements over pre-1988 versions of the +historical +.IR tar +utility. The goal of these changes was not only to provide the +functional enhancements desired, but also to retain compatibility +between new and old versions. This compatibility has been retained. +Archives written using the old archive format are compatible with the +new format. +.P +Implementors should be aware that the previous file format did not +include a mechanism to archive directory type files. For this reason, +the convention of using a filename ending with + +was adopted to specify a directory on the archive. +.P +The total size of the +.IR name +and +.IR prefix +fields have been set to meet the minimum requirements for +{PATH_MAX}. +If a pathname will fit within the +.IR name +field, it is recommended that the pathname be stored there without the +use of the +.IR prefix +field. Although the name field is known to be too small to contain +{PATH_MAX} +characters, the value was not changed in this version of the archive +file format to retain backwards-compatibility, and instead the prefix +was introduced. Also, because of the earlier version of the format, +there is no way to remove the restriction on the +.IR linkname +field being limited in size to just that of the +.IR name +field. +.P +The +.IR size +field is required to be meaningful in all implementation extensions, +although it could be zero. This is required so that the data blocks can +always be properly counted. +.P +It is suggested that if device special files need to be represented +that cannot be represented in the standard format, that one of the +extension types (\c +.BR A \(hy\c +.BR Z ) +be used, and that the additional information for the special file be +represented as data and be reflected in the +.IR size +field. +.P +Attempting to restore a special file type, where it is converted to +ordinary data and conflicts with an existing filename, need not be +specially detected by the utility. If run as an ordinary user, +.IR pax +should not be able to overwrite the entries in, for example, +.BR /dev +in any case (whether the file is converted to another type or not). If +run as a privileged user, it should be able to do so, and it would be +considered a bug if it did not. The same is true of ordinary data files +and similarly named special files; it is impossible to anticipate the +needs of the user (who could really intend to overwrite the file), so +the behavior should be predictable (and thus regular) and rely on the +protection system as required. +.P +The value 7 in the +.IR typeflag +field is intended to define how contiguous files can be stored in a +.BR ustar +archive. POSIX.1\(hy2008 does not require the contiguous file extension, but does +define a standard way of archiving such files so that all conforming +systems can interpret these file types in a meaningful and consistent +manner. On a system that does not support extended file types, the +.IR pax +utility should do the best it can with the file and go on to the next. +.P +The file protection modes are those conventionally used by the +.IR ls +utility. This is extended beyond the usage in the ISO\ POSIX\(hy2 standard to support the +``shared text'' or ``sticky'' bit. It is intended that the conformance +document should not document anything beyond the existence of and +support of such a mode. Further extensions are expected to these bits, +particularly with overloading the set-user-ID and set-group-ID flags. +.SS "cpio Interchange Format" +.P +The reference to appropriate privileges in the +.BR cpio +format refers to an error on standard output; the +.BR ustar +format does not make comparable statements. +.P +The model for this format was the historical System V +.IR cpio \c +.BR \(mic +data interchange format. This model documents the portable version of +the +.BR cpio +format and not the binary version. It has the flexibility to transfer +data of any type described within POSIX.1\(hy2008, yet is extensible to transfer +data types specific to extensions beyond POSIX.1\(hy2008 (for example, contiguous +files). Because it describes existing practice, there is no question of +maintaining upwards-compatibility. +.SS "cpio Header" +.P +There has been some concern that the size of the +.IR c_ino +field of the header is too small to handle those systems that have very +large +.IR inode +numbers. However, the +.IR c_ino +field in the header is used strictly as a hard-link resolution +mechanism for archives. It is not necessarily the same value as the +.IR inode +number of the file in the location from which that file is extracted. +.P +The name +.IR c_magic +is based on historical usage. +.SS "cpio Filename" +.P +For most historical implementations of the +.IR cpio +utility, +{PATH_MAX} +octets can be used to describe the pathname without the addition of +any other header fields (the NUL character would be included in this +count). +{PATH_MAX} +is the minimum value for pathname size, documented as 256 bytes. +However, an implementation may use +.IR c_namesize +to determine the exact length of the pathname. With the current +description of the +.IR +header, this pathname size can be as large as a number that is +described in six octal digits. +.P +Two values are documented under the +.IR c_mode +field values to provide for extensibility for known file types: +.IP "\fB0110\ 000\fP" 10 +Reserved for contiguous files. The implementation may treat the rest of +the information for this archive like a regular file. If this file type +is undefined, the implementation may create the file as a regular +file. +.P +This provides for extensibility of the +.BR cpio +format while allowing for the ability to read old archives. Files of an +unknown type may be read as ``regular files'' on some implementations. +On a system that does not support extended file types, the +.IR pax +utility should do the best it can with the file and go on to the next. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIcp\fR\^", +.IR "\fIed\fR\^", +.IR "\fIgetopts\fR\^", +.IR "\fIls\fR\^", +.IR "\fIprintf\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.169" ", " "File Mode Bits", +.IR "Chapter 5" ", " "File Format Notation", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIchown\fR\^(\|)", +.IR "\fIcreat\fR\^(\|)", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fImkdir\fR\^(\|)", +.IR "\fImkfifo\fR\^(\|)", +.IR "\fIutime\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/pr.1p b/man-pages-posix-2013/man1p/pr.1p new file mode 100644 index 0000000..7280c6d --- /dev/null +++ b/man-pages-posix-2013/man1p/pr.1p @@ -0,0 +1,569 @@ +'\" et +.TH PR "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pr +\(em print files +.SH SYNOPSIS +.LP +.nf +pr \fB[\fR+\fIpage\fB] [\fR\(mi\fIcolumn\fB] [\fR\(miadFmrt\fB] [\fR\(mie\fB[\fIchar\fB][\fIgap\fB]] [\fR\(mih \fIheader\fB] [\fR\(mii\fB[\fIchar\fB][\fIgap\fB]] + [\fR\(mil \fIlines\fB] [\fR\(min\fB[\fIchar\fB][\fIwidth\fB]] [\fR\(mio \fIoffset\fB] [\fR\(mis\fB[\fIchar\fB]] [\fR\(miw \fIwidth\fB] [\fR\(mifp\fB] + [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR pr +utility is a printing and pagination filter. If multiple input files +are specified, each shall be read, formatted, and written to standard +output. By default, the input shall be separated into 66-line pages, +each with: +.IP " *" 4 +A 5-line header that includes the page number, date, time, and +the pathname of the file +.IP " *" 4 +A 5-line trailer consisting of blank lines +.P +If standard output is associated with a terminal, diagnostic messages +shall be deferred until the +.IR pr +utility has completed processing. +.P +When options specifying multi-column output are specified, output text +columns shall be of equal width; input lines that do not fit into a +text column shall be truncated. By default, text columns shall be +separated with at least one +. +.SH OPTIONS +The +.IR pr +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that: the +.IR page +option has a +.BR '\(pl' +delimiter; +.IR page +and +.IR column +can be multi-digit numbers; some of the option-arguments are optional; +and some of the option-arguments cannot be specified as separate +arguments from the preceding option letter. In particular, the +.BR \(mis +option does not allow the option letter to be separated from its +argument, and the options +.BR \(mie , +.BR \(mii , +and +.BR \(min +require that both arguments, if present, not be separated from the +option letter. +.P +The following options shall be supported. In the following option +descriptions, +.IR column , +.IR lines , +.IR offset , +.IR page , +and +.IR width +are positive decimal integers; +.IR gap +is a non-negative decimal integer. +.IP "\fB+\fIpage\fR" 10 +Begin output at page number +.IR page +of the formatted input. +.IP "\fB\(mi\fIcolumn\fR" 10 +Produce multi-column output that is arranged in +.IR column +columns (the default shall be 1) and is written down each column in the +order in which the text is received from the input file. This option +should not be used with +.BR \(mim . +The options +.BR \(mie +and +.BR \(mii +shall be assumed for multiple text-column output. Whether or not text +columns are produced with identical vertical lengths is unspecified, +but a text column shall never exceed the length of the page (see the +.BR \(mil +option). When used with +.BR \(mit , +use the minimum number of lines to write the output. +.IP "\fB\(mia\fP" 10 +Modify the effect of the +.BR \(mi \c +.IR column +option so that the columns are filled across the page in a round-robin +order (for example, when +.IR column +is 2, the first input line heads column 1, the second heads column 2, +the third is the second line in column 1, and so on). +.IP "\fB\(mid\fP" 10 +Produce output that is double-spaced; append an extra + +following every + +found in the input. +.IP "\fB\(mie[\fIchar\fB][\fIgap\fB]\fR" 10 +.br +Expand each input + +to the next greater column position specified by the formula +.IR n *\c +.IR gap +1, +where +.IR n +is an integer > 0. If +.IR gap +is zero or is omitted, it shall default to 8. All + +characters in the input shall be expanded into the appropriate number of + +characters. If any non-digit character, +.IR char , +is specified, it shall be used as the input +. +If the first character of the +.BR \(mie +option-argument is a digit, the entire option-argument shall be assumed +to be +.IR gap . +.IP "\fB\(mif\fP" 10 +Use a + +for new pages, instead of the default behavior that uses a sequence of + +characters. Pause before beginning the first page if the standard output +is associated with a terminal. +.IP "\fB\(miF\fP" 10 +Use a + +for new pages, instead of the default behavior that uses a sequence of + +characters. +.IP "\fB\(mih\ \fIheader\fR" 10 +Use the string +.IR header +to replace the contents of the +.IR file +operand in the page header. +.IP "\fB\(mii[\fIchar\fB][\fIgap\fB]\fR" 10 +In output, replace + +characters with + +characters wherever one or more adjacent + +characters reach column positions +.IR gap +1, +2* +.IR gap +1, +3* +.IR gap +1, +and so on. If +.IR gap +is zero or is omitted, default tab settings at every eighth column +position shall be assumed. If any non-digit character, +.IR char , +is specified, it shall be used as the output +. +If the first character of the +.BR \(mii +option-argument is a digit, the entire option-argument shall be assumed +to be +.IR gap . +.IP "\fB\(mil\ \fIlines\fR" 10 +Override the 66-line default and reset the page length to +.IR lines . +If +.IR lines +is not greater than the sum of both the header and trailer depths (in +lines), the +.IR pr +utility shall suppress both the header and trailer, as if the +.BR \(mit +option were in effect. +.IP "\fB\(mim\fP" 10 +Merge files. Standard output shall be formatted so the +.IR pr +utility writes one line from each file specified by a +.IR file +operand, side by side into text columns of equal fixed widths, in terms +of the number of column positions. Implementations shall support +merging of at least nine +.IR file +operands. +.IP "\fB\(min[\fIchar\fB][\fIwidth\fB]\fR" 10 +.br +Provide +.IR width -digit +line numbering (default for +.IR width +shall be 5). The number shall occupy the first +.IR width +column positions of each text column of default output or each line of +.BR \(mim +output. If +.IR char +(any non-digit character) is given, it shall be appended to the line +number to separate it from whatever follows (default for +.IR char +is a +). +.IP "\fB\(mio\ \fIoffset\fR" 10 +Each line of output shall be preceded by offset + +characters. If the +.BR \(mio +option is not specified, the default offset shall be zero. The space +taken is in addition to the output line width (see the +.BR \(miw +option below). +.IP "\fB\(mip\fP" 10 +Pause before beginning each page if the standard output is directed to +a terminal (\c +.IR pr +shall write an + +to standard error and wait for a + +to be read on +.BR /dev/tty ). +.IP "\fB\(mir\fP" 10 +Write no diagnostic reports on failure to open files. +.IP "\fB\(mis[\fIchar\fB]\fR" 10 +Separate text columns by the single character +.IR char +instead of by the appropriate number of + +characters (default for +.IR char +shall be +). +.IP "\fB\(mit\fP" 10 +Write neither the five-line identifying header nor the five-line +trailer usually supplied for each page. Quit writing after the last +line of each file without spacing to the end of the page. +.IP "\fB\(miw\ \fIwidth\fR" 10 +Set the width of the line to +.IR width +column positions for multiple text-column output only. If the +.BR \(miw +option is not specified and the +.BR \(mis +option is not specified, the default width shall be 72. If the +.BR \(miw +option is not specified and the +.BR \(mis +option is specified, the default width shall be 512. +.RS 10 +.P +For single column output, input lines shall not be truncated. +.RE +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file to be written. If no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' , +the standard input shall be used. +.SH STDIN +The standard input shall be used only if no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' . +See the INPUT FILES section. +.SH "INPUT FILES" +The input files shall be text files. +.P +The file +.BR /dev/tty +shall be used to read responses required by the +.BR \(mip +option. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR pr : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files) and which +characters are defined as printable (character class +.BR print ). +Non-printable characters are still written to standard output, but are +not counted for the purpose for column-width and line-length +calculations. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILC_TIME\fP" 10 +Determine the format of the date and time for use in writing header +lines. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITZ\fP" 10 +Determine the timezone used to calculate date and time strings written +in header lines. If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +If +.IR pr +receives an interrupt while writing to a terminal, it shall flush all +accumulated error messages to the screen before terminating. +.SH STDOUT +The +.IR pr +utility output shall be a paginated version of the original file (or +files). This pagination shall be accomplished using either + +characters or a sequence of + +characters, as controlled by the +.BR \(miF +or +.BR \(mif +option. Page headers shall be generated unless the +.BR \(mit +option is specified. The page headers shall be of the form: +.sp +.RS 4 +.nf +\fB +"\en\en%s %s Page %d\en\en\en", <\fIoutput of date\fP>, <\fIfile\fR>, <\fIpage number\fR> +.fi \fR +.P +.RE +.P +In the POSIX locale, the <\fIoutput\ of\ date\fR> field, representing +the date and time of last modification of the input file (or the +current date and time if the input file is standard input), shall be +equivalent to the output of the following command as it would appear if +executed at the given time: +.sp +.RS 4 +.nf +\fB +date "+%b %e %H:%M %Y" +.fi \fR +.P +.RE +.P +without the trailing +, +if the page being written is from standard input. If the page being +written is not from standard input, in the POSIX locale, the same +format shall be used, but the time used shall be the modification time +of the file corresponding to +.IR file +instead of the current time. When the +.IR LC_TIME +locale category is not set to the POSIX locale, a different format and +order of presentation of this field may be used. +.P +If the standard input is used instead of a +.IR file +operand, the <\fIfile\fP> field shall be replaced by a null string. +.P +If the +.BR \(mih +option is specified, the <\fIfile\fP> field shall be replaced by the +.IR header +argument. +.SH STDERR +The standard error shall be used for diagnostic messages and +for alerting the terminal when +.BR \(mip +is specified. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +A conforming application must protect its first operand, if it starts +with a +, +by preceding it with the +.BR \(dq\(mi\|\(mi\(dq +argument that denotes the end of the options. For example, +.IR pr \(pl\c +.IR x +could be interpreted as an invalid page number or a +.IR file +operand. +.SH EXAMPLES +.IP " 1." 4 +Print a numbered list of all files in the current directory: +.RS 4 +.sp +.RS 4 +.nf +\fB +ls \(mia | pr \(min \(mih "Files in $(pwd)." +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +Print +.BR file1 +and +.BR file2 +as a double-spaced, three-column listing headed by ``file list'': +.RS 4 +.sp +.RS 4 +.nf +\fB +pr \(mi3d \(mih "file list" file1 file2 +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +Write +.BR file1 +on +.BR file2 , +expanding tabs to columns 10, 19, 28, .\|.\|.: +.RS 4 +.sp +.RS 4 +.nf +\fB +pr \(mie9 \(mit file2 +.fi \fR +.P +.RE +.RE +.SH RATIONALE +This utility is one of those that does not follow the Utility Syntax +Guidelines because of its historical origins. The standard developers +could have added new options that obeyed the guidelines (and marked the +old options obsolescent) or devised an entirely new utility; there are +examples of both actions in this volume of POSIX.1\(hy2008. Because of its widespread use by +historical applications, the standard developers decided to exempt this +version of +.IR pr +from many of the guidelines. +.P +Implementations are required to accept option-arguments to the +.BR \(mih , +.BR \(mil , +.BR \(mio , +and +.BR \(miw +options whether presented as part of the same argument or as a separate +argument to +.IR pr , +as suggested by the Utility Syntax Guidelines. The +.BR \(min +and +.BR \(mis +options, however, are specified as in historical practice because they +are frequently specified without their optional arguments. If a + +were allowed before the option-argument in these cases, a +.IR file +operand could mistakenly be interpreted as an option-argument in +historical applications. +.P +The text about the minimum number of lines in multi-column output was +included to ensure that a best effort is made in balancing the length +of the columns. There are known historical implementations in which, +for example, 60-line files are listed by +.IR pr +\(mi2 as one column of 56 lines and a second of 4. Although this is not +a problem when a full page with headers and trailers is produced, it +would be relatively useless when used with +.BR \(mit . +.P +Historical implementations of the +.IR pr +utility have differed in the action taken for the +.BR \(mif +option. BSD uses it as described here for the +.BR \(miF +option; System V uses it to change trailing + +characters on each page to a + +and, if standard output is a TTY device, sends an + +to standard error and reads a line from +.BR /dev/tty +before the first page. There were strong arguments from both sides of +this issue concerning historical practice and as a result the +.BR \(miF +option was added. XSI-conformant systems support the System V +historical actions for the +.BR \(mif +option. +.P +The <\fIoutput\ of\ date\fP> field in the +.BR \(mil +format is specified only for the POSIX locale. As noted, the format can +be different in other locales. No mechanism for defining this is +present in this volume of POSIX.1\(hy2008, as the appropriate vehicle is a message catalog; +that is, the format should be specified as a ``message''. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexpand\fR\^", +.IR "\fIlp\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/printf.1p b/man-pages-posix-2013/man1p/printf.1p new file mode 100644 index 0000000..716fb08 --- /dev/null +++ b/man-pages-posix-2013/man1p/printf.1p @@ -0,0 +1,576 @@ +'\" et +.TH PRINTF "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 write formatted output +.SH SYNOPSIS +.LP +.nf +printf \fIformat\fB [\fIargument\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR printf +utility shall write formatted operands to the standard output. The +.IR argument +operands shall be formatted under control of the +.IR format +operand. +.SH OPTIONS +None. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIformat\fR" 10 +A string describing the format to use to write the remaining operands. +See the EXTENDED DESCRIPTION section. +.IP "\fIargument\fR" 10 +The strings to be written to standard output, under the control of +.IR format . +See the EXTENDED DESCRIPTION section. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR printf : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILC_NUMERIC\fP" 10 +.br +Determine the locale for numeric formatting. It shall affect the +format of numbers written using the +.BR e , +.BR E , +.BR f , +.BR g , +and +.BR G +conversion specifier characters (if supported). +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +See the EXTENDED DESCRIPTION section. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +The +.IR format +operand shall be used as the +.IR format +string described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation" +with the following exceptions: +.IP " 1." 4 +A + +in the format string, in any context other than a flag of a conversion +specification, shall be treated as an ordinary character that is copied +to the output. +.IP " 2." 4 +A +.BR ' ' +character in the format string shall be treated as a +.BR ' ' +character, not as a +. +.IP " 3." 4 +In addition to the escape sequences shown in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation" +(\c +.BR '\e\e' , +.BR '\ea' , +.BR '\eb' , +.BR '\ef' , +.BR '\en' , +.BR '\er' , +.BR '\et' , +.BR '\ev' ), +.BR \(dq\eddd\(dq , +where +.IR ddd +is a one, two, or three-digit octal number, shall be written as a byte +with the numeric value specified by the octal number. +.IP " 4." 4 +The implementation shall not precede or follow output from the +.BR d +or +.BR u +conversion specifiers with + +characters not specified by the +.IR format +operand. +.IP " 5." 4 +The implementation shall not precede output from the +.BR o +conversion specifier with zeros not specified by the +.IR format +operand. +.IP " 6." 4 +The +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +and +.BR G +conversion specifiers need not be supported. +.IP " 7." 4 +An additional conversion specifier character, +.BR b , +shall be supported as follows. The argument shall be taken to be a +string that may contain +-escape +sequences. The following +-escape +sequences shall be supported: +.RS 4 +.IP -- 4 +The escape sequences listed in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation" +(\c +.BR '\e\e' , +.BR '\ea' , +.BR '\eb' , +.BR '\ef' , +.BR '\en' , +.BR '\er' , +.BR '\et' , +.BR '\ev' ), +which shall be converted to the characters they represent +.IP -- 4 +.BR \(dq\e0ddd\(dq , +where +.IR ddd +is a zero, one, two, or three-digit octal number that shall be +converted to a byte with the numeric value specified by the octal +number +.IP -- 4 +.BR '\ec' , +which shall not be written and shall cause +.IR printf +to ignore any remaining characters in the string operand containing it, +any remaining string operands, and any additional characters in the +.IR format +operand +.P +The interpretation of a + +followed by any other sequence of characters is unspecified. +.P +Bytes from the converted string shall be written until the end of the +string or the number of bytes indicated by the precision specification +is reached. If the precision is omitted, it shall be taken to be +infinite, so all bytes up to the end of the converted string shall be +written. +.RE +.IP " 8." 4 +For each conversion specification that consumes an argument, the next +argument operand shall be evaluated and converted to the appropriate +type for the conversion as specified below. +.IP " 9." 4 +The +.IR format +operand shall be reused as often as necessary to satisfy the argument +operands. Any extra +.BR c +or +.BR s +conversion specifiers shall be evaluated as if a null string +argument were supplied; other extra conversion specifications shall be +evaluated as if a zero argument were supplied. If the +.IR format +operand contains no conversion specifications and +.IR argument +operands are present, the results are unspecified. +.IP 10. 4 +If a character sequence in the +.IR format +operand begins with a +.BR '%' +character, but does not form a valid conversion specification, the +behavior is unspecified. +.IP 11. 4 +The argument to the +.BR c +conversion specifier can be a string containing zero or more bytes. If +it contains one or more bytes, the first byte shall be written and any +additional bytes shall be ignored. If the argument is an empty string, +it is unspecified whether nothing is written or a null byte is written. +.P +The +.IR argument +operands shall be treated as strings if the corresponding conversion +specifier is +.BR b , +.BR c , +or +.BR s , +and shall be evaluated as if by the +\fIstrtod\fR() +function if the corresponding conversion specifier is +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +or +.BR G . +Otherwise, they shall be evaluated as unsuffixed C integer constants, +as described by the ISO\ C standard, with the following extensions: +.IP " *" 4 +A leading + +or minus-sign shall be allowed. +.IP " *" 4 +If the leading character is a single-quote or double-quote, the value +shall be the numeric value in the underlying codeset of the character +following the single-quote or double-quote. +.IP " *" 4 +Suffixed integer constants may be allowed. +.P +If an argument operand cannot be completely converted into an internal +value appropriate to the corresponding conversion specification, a +diagnostic message shall be written to standard error and the utility +shall not exit with a zero exit status, but shall continue processing +any remaining operands and shall write the value accumulated at the +time the error was detected to standard output. +.P +It is not considered an error if an argument operand is not completely +used for a +.BR c +or +.BR s +conversion. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The floating-point formatting conversion specifications of +\fIprintf\fR() +are not required because all arithmetic in the shell is integer +arithmetic. The +.IR awk +utility performs floating-point calculations and provides its own +.BR printf +function. The +.IR bc +utility can perform arbitrary-precision floating-point arithmetic, but +does not provide extensive formatting capabilities. (This +.IR printf +utility cannot really be used to format +.IR bc +output; it does not support arbitrary precision.) Implementations are +encouraged to support the floating-point conversions as an extension. +.P +Note that this +.IR printf +utility, like the +\fIprintf\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008 on which it is based, makes no special +provision for dealing with multi-byte characters when using the +.BR %c +conversion specification or when a precision is specified in a +.BR %b +or +.BR %s +conversion specification. Applications should be extremely cautious +using either of these features when there are multi-byte characters in +the character set. +.P +No provision is made in this volume of POSIX.1\(hy2008 which allows field widths and precisions +to be specified as +.BR '*' +since the +.BR '*' +can be replaced directly in the +.IR format +operand using shell variable substitution. Implementations can also +provide this feature as an extension if they so choose. +.P +Hexadecimal character constants as defined in the ISO\ C standard are not +recognized in the +.IR format +operand because there is no consistent way to detect the end of the +constant. Octal character constants are limited to, at most, three +octal digits, but hexadecimal character constants are only terminated +by a non-hex-digit character. In the ISO\ C standard, the +.BR \(dq##\(dq +concatenation operator can be used to terminate a constant and follow +it with a hexadecimal character to be written. In the shell, +concatenation occurs before the +.IR printf +utility has a chance to parse the end of the hexadecimal constant. +.P +The +.BR %b +conversion specification is not part of the ISO\ C standard; it has been added +here as a portable way to process +-escapes +expanded in string operands as provided by the +.IR echo +utility. See also the APPLICATION USAGE section of +.IR "\fIecho\fR\^" +for ways to use +.IR printf +as a replacement for all of the traditional versions of the +.IR echo +utility. +.P +If an argument cannot be parsed correctly for the corresponding +conversion specification, the +.IR printf +utility is required to report an error. Thus, overflow and extraneous +characters at the end of an argument being used for a numeric +conversion shall be reported as errors. +.SH EXAMPLES +To alert the user and then print and read a series of prompts: +.sp +.RS 4 +.nf +\fB +printf "\eaPlease fill in the following: \enName: " +read name +printf "Phone number: " +read phone +.fi \fR +.P +.RE +.P +To read out a list of right and wrong answers from a file, calculate +the percentage correctly, and print them out. The numbers are +right-justified and separated by a single +. +The percentage is written to one decimal place of accuracy: +.sp +.RS 4 +.nf +\fB +while read right wrong ; do + percent=$(echo "scale=1;($right*100)/($right+$wrong)" | bc) + printf "%2d right\et%2d wrong\et(%s%%)\en" \e + $right $wrong $percent +done < database_file +.fi \fR +.P +.RE +The command: +.sp +.RS 4 +.nf +\fB +printf "%5d%4d\en" 1 21 321 4321 54321 +.fi \fR +.P +.RE +.P +produces: +.sp +.RS 4 +.nf +\fB + 1 21 + 3214321 +54321 0 +.fi \fR +.P +.RE +.P +Note that the +.IR format +operand is used three times to print all of the given strings and that +a +.BR '0' +was supplied by +.IR printf +to satisfy the last +.BR %4d +conversion specification. +.P +The +.IR printf +utility is required to notify the user when conversion errors are +detected while producing numeric output; thus, the following results +would be expected on an implementation with 32-bit twos-complement +integers when +.BR %d +is specified as the +.IR format +operand: +.br +.TS +center tab(@) box; +cB | cB | cB +cB | cB | cB +lf5 | lf5 | lf7. +@Standard +Argument@Output@Diagnostic Output +_ +5a@5@printf: "5a" not completely converted +9999999999@2147483647@printf: "9999999999" arithmetic overflow +\(mi9999999999@\(mi2147483648@printf: "\(mi9999999999" arithmetic overflow +ABC@0@printf: "ABC" expected numeric value +.TE +.P +The diagnostic message format is not specified, but these examples +convey the type of information that should be reported. Note that the +value shown on standard output is what would be expected as the return +value from the +\fIstrtol\fR() +function as defined in the System Interfaces volume of POSIX.1\(hy2008. A similar correspondence exists +between +.BR %u +and +\fIstrtoul\fR() +and +.BR %e , +.BR %f , +and +.BR %g +(if the implementation supports floating-point conversions) and +\fIstrtod\fR(). +.P +In a locale using the ISO/IEC\ 646:\|1991 standard as the underlying codeset, the command: +.sp +.RS 4 +.nf +\fB +printf "%d\en" 3 +3 \(mi3 \e'3 \e"+3 "'\(mi3" +.fi \fR +.P +.RE +.P +produces: +.IP 3 6 +Numeric value of constant 3 +.IP 3 6 +Numeric value of constant 3 +.IP "\(mi3" 6 +Numeric value of constant \(mi3 +.IP 51 6 +Numeric value of the character +.BR '3' +in the ISO/IEC\ 646:\|1991 standard codeset +.IP 43 6 +Numeric value of the character +.BR '\(pl' +in the ISO/IEC\ 646:\|1991 standard codeset +.IP 45 6 +Numeric value of the character +.BR '\(mi' +in the ISO/IEC\ 646:\|1991 standard codeset +.P +Note that in a locale with multi-byte characters, the value of a +character is intended to be the value of the equivalent of the +.BR wchar_t +representation of the character as described in the System Interfaces volume of POSIX.1\(hy2008. +.SH RATIONALE +The +.IR printf +utility was added to provide functionality that has historically been +provided by +.IR echo . +However, due to irreconcilable differences in the various versions of +.IR echo +extant, the version has few special features, leaving those to this new +.IR printf +utility, which is based on one in the Ninth Edition system. +.P +The EXTENDED DESCRIPTION section almost exactly matches the +\fIprintf\fR() +function in the ISO\ C standard, although it is described in terms of the file +format notation in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation". +.P +Earlier versions of this standard specified that arguments for all +conversions other than +.BR b , +.BR c , +and +.BR s +were evaluated in the same way (as C constants, but with stated +exceptions). For implementations supporting the floating-point conversions +it was not clear whether integer conversions need only accept integer +constants and floating-point conversions need only accept floating-point +constants, or whether both types of conversions should accept both +types of constants. Also by not distinguishing between them, the +requirement relating to a leading single-quote or double-quote applied +to floating-point conversions even though this provided no useful +functionality to applications that was not already available through +the integer conversions. The current standard clarifies the situation +by specifying that the arguments for floating-point conversions are +evaluated as if by +\fIstrtod\fR(), +and the arguments for integer conversions are evaluated as C integer +constants, with the special treatment of leading single-quote and +double-quote applying only to integer conversions. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIawk\fR\^", +.IR "\fIbc\fR\^", +.IR "\fIecho\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 5" ", " "File Format Notation", +.IR "Chapter 8" ", " "Environment Variables" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIfprintf\fR\^(\|)", +.IR "\fIstrtod\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/prs.1p b/man-pages-posix-2013/man1p/prs.1p new file mode 100644 index 0000000..aa268a6 --- /dev/null +++ b/man-pages-posix-2013/man1p/prs.1p @@ -0,0 +1,445 @@ +'\" et +.TH PRS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +prs +\(em print an SCCS file (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +prs \fB[\fR\(mia\fB] [\fR\(mid \fIdataspec\fB] [\fR\(mir\fB[\fISID\fB]]\fI file\fR... +.P +prs \fB[\fR\(mie|\(mil\fB]\fR \(mic \fIcutoff \fB[\fR\(mid \fIdataspec\fB]\fI file\fR... +.P +prs \fB[\fR\(mie|\(mil\fB]\fR \(mir\fB[\fISID\fB] [\fR\(mid \fIdataspec\fB] \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR prs +utility shall write to standard output parts or all of an SCCS file in +a user-supplied format. +.SH OPTIONS +The +.IR prs +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that the +.BR \(mir +option has an optional option-argument. This optional option-argument +cannot be presented as a separate argument. The following options +shall be supported: +.IP "\fB\(mid\ \fIdataspec\fR" 10 +Specify the output data specification. The +.IR dataspec +shall be a string consisting of SCCS file +.IR data +.IR keywords +(see +.IR "Data Keywords") +interspersed with optional user-supplied text. +.IP "\fB\(mir[\fISID\fB]\fR" 10 +Specify the SCCS identification string (SID) of a delta for which +information is desired. If no +.IR SID +option-argument is specified, the SID of the most recently created +delta shall be assumed. +.IP "\fB\(mie\fP" 10 +Request information for all deltas created earlier than and including +the delta designated via the +.BR \(mir +option or the date-time given by the +.BR \(mic +option. +.IP "\fB\(mil\fP" 10 +Request information for all deltas created later than and including the +delta designated via the +.BR \(mir +option or the date-time given by the +.BR \(mic +option. +.IP "\fB\(mic\ \fIcutoff\fR" 10 +Indicate the +.IR cutoff +date-time, in the form: +.RS 10 +.sp +.RS 4 +.nf +\fB +\fIYY\fB[\fIMM\fB[\fIDD\fB[\fIHH\fB[\fIMM\fB[\fISS\fB]]]]]\fR +.fi \fR +.P +.RE +.P +For the +.IR YY +component, 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. +.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 +.P +No changes (deltas) to the SCCS file that were created after the +specified +.IR cutoff +date-time shall be included in the output. Units omitted from the +date-time default to their maximum possible values; for example, +.BR \(mic\07502 +is equivalent to +.BR \(mic\0750228235959 . +.RE +.IP "\fB\(mia\fP" 10 +Request writing of information for both removed\(emthat is, +.IR delta +.IR type =\c +.IR R +(see +.IR "\fIrmdel\fR\^")\(em\c +and existing\(emthat is, +.IR delta +.IR type =\c +.IR D ,\(em\c +deltas. If the +.BR \(mia +option is not specified, information for existing deltas only shall be +provided. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an existing SCCS file or a directory. If +.IR file +is a directory, the +.IR prs +utility shall behave as though each file in the directory were +specified as a named file, except that non-SCCS files (last component +of the pathname does not begin with +.BR s. ) +and unreadable files shall be silently ignored. +.RS 10 +.P +If exactly one +.IR file +operand appears, and it is +.BR '\(mi' , +the standard input shall be read; each line of the standard input shall +be taken to be the name of an SCCS file to be processed. Non-SCCS +files and unreadable files shall be silently ignored. +.RE +.SH STDIN +The standard input shall be a text file used only when the +.IR file +operand is specified as +.BR '\(mi' . +Each line of the text file shall be interpreted as an SCCS pathname. +.SH "INPUT FILES" +Any SCCS files displayed are files of an unspecified format. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR prs : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall be a text file whose format is dependent on +the data keywords specified with the +.BR \(mid +option. +.SS "Data Keywords" +.P +Data keywords specify which parts of an SCCS file shall be retrieved +and output. All parts of an SCCS file have an associated data +keyword. A data keyword may appear in a +.IR dataspec +multiple times. +.P +The information written by +.IR prs +shall consist of: +.IP " 1." 4 +The user-supplied text +.IP " 2." 4 +Appropriate values (extracted from the SCCS file) substituted for the +recognized data keywords in the order of appearance in the +.IR dataspec +.P +The format of a data keyword value shall either be simple (\c +.BR 'S' ), +in which keyword substitution is direct, or multi-line (\c +.BR 'M' ). +.P +User-supplied text shall be any text other than recognized data +keywords. A + +shall be specified by +.BR '\et' +and + +by +.BR '\en' . +When the +.BR \(mir +option is not specified, the default +.IR dataspec +shall be: +.sp +.RS 4 +.nf +\fB +:PN::\en\en +.fi \fR +.P +.RE +.P +and the following +.IR dataspec +shall be used for each selected delta: +.sp +.RS 4 +.nf +\fB +:Dt:\et:DL:\enMRs:\en:MR:COMMENTS:\en:C: +.fi \fR +.P +.RE +.TS +center box tab(!); +cB s s s s +cB | cB | cB | cB | cB +lB | l | c | lB | c. +SCCS File Data Keywords +_ +Keyword!Data Item!File Section!Value!Format +_ +:Dt:!Delta information!Delta Table!\fRSee below*\fP!S +:DL:!Delta line statistics!"!:Li:/:Ld:/:Lu:!S +:Li:!Lines inserted by Delta!"!\fInnnnn\fR***!S +:Ld:!Lines deleted by Delta!"!\fInnnnn\fR***!S +:Lu:!Lines unchanged by Delta!"!\fInnnnn\fR***!S +:DT:!Delta type!"!D or R!S +:I:!SCCS ID string (SID)!"!\fRSee below**\fP!S +:R:!Release number!"!\fInnnn\fR!S +:L:!Level number!"!\fInnnn\fR!S +:B:!Branch number!"!\fInnnn\fR!S +:S:!Sequence number!"!\fInnnn\fR!S +:D:!Date delta created!"!:Dy:/:Dm:/:Dd:!S +:Dy:!Year delta created!"!\fInn\fR!S +:Dm:!Month delta created!"!\fInn\fR!S +:Dd:!Day delta created!"!\fInn\fR!S +:T:!Time delta created!"!:Th:::Tm:::Ts:!S +:Th:!Hour delta created!"!\fInn\fR!S +:Tm:!Minutes delta created!"!\fInn\fR!S +:Ts:!Seconds delta created!"!\fInn\fR!S +:P:!Programmer who created Delta!"!\fIlogname\fR!S +:DS:!Delta sequence number!"!\fInnnn\fR!S +:DP:!Predecessor Delta sequence!"!\fInnnn\fR!S +!number +:DI:!Sequence number of deltas!"!:Dn:/:Dx:/:Dg:!S +!included, excluded, or ignored +:Dn:!Deltas included (sequence #)!"!:DS: :DS: .\|.\|.!S +:Dx:!Deltas excluded (sequence #)!"!:DS: :DS: .\|.\|.!S +:Dg:!Deltas ignored (sequence #)!"!:DS: :DS: .\|.\|.!S +:MR:!MR numbers for delta!"!\fItext\fR!M +:C:!Comments for delta!"!\fItext\fR!M +:UN:!User names!User Names!\fItext\fR!M +:FL:!Flag list!Flags!\fItext\fP!M +:Y:!Module type flag!"!\fItext\fR!S +:MF:!MR validation flag!"!yes \fRor\fP no!S +:MP:!MR validation program name!"!\fItext\fR!S +:KF:!Keyword error, warning flag!"!yes \fRor\fP no!S +:KV:!Keyword validation string!"!\fItext\fR!S +:BF:!Branch flag!"!yes \fRor\fP no!S +:J:!Joint edit flag!"!yes \fRor\fP no!S +:LK:!Locked releases!"!:R: .\|.\|.!S +:Q:!User-defined keyword!"!\fItext\fR!S +:M:!Module name!"!\fItext\fR!S +:FB:!Floor boundary!"!:R:!S +:CB:!Ceiling boundary!"!:R:!S +:Ds:!Default SID!"!:I:!S +:ND:!Null delta flag!"!yes \fRor\fP no!S +:FD:!File descriptive text!Comments!\fItext\fR!M +:BD:!Body!Body!\fItext\fR!M +:GB:!Gotten body!"!\fItext\fR!M +:W:!A form of \fIwhat\fP string!N/A!:Z::M:\et:I:!S +:A:!A form of \fIwhat\fP string!N/A!:Z::Y: :M: :I::Z:!S +:Z:!\fIwhat\fP string delimiter!N/A!\fR@(#)\fR!S +:F:!SCCS filename!N/A!\fItext\fR!S +:PN:!SCCS file pathname!N/A!\fItext\fR!S +.TE +.IP * 6 +.BR :Dt: =\c +.BR ":DT: :I: :D: :T: :P: :DS: :DP:" +.IP ** 6 +.BR ":R:.:L:.:B:.:S:" +if the delta is a branch delta (\c +.BR :BF: =\|=\c +.BR yes ) +.br +.BR ":R:.:L:" +if the delta is not a branch delta (\c +.BR :BF: =\|=\c +.BR no ) +.IP *** 6 +The line statistics are capped at 99\|999. For example, if 100\|000 +lines were unchanged in a certain revision, +.BR :Lu: +shall produce the value 99\|999. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +.IP " 1." 4 +The following example: +.RS 4 +.sp +.RS 4 +.nf +\fB +prs \(mid "User Names for :F: are:\en:UN:" s.file +.fi \fR +.P +.RE +.P +might write to standard output: +.sp +.RS 4 +.nf +\fB +User Names for s.file are: +xyz +131 +abc +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +The following example: +.RS 4 +.sp +.RS 4 +.nf +\fB +prs \(mid "Delta for pgm :M:: :I: \(mi :D: By :P:" \(mir s.file +.fi \fR +.P +.RE +.P +might write to standard output: +.sp +.RS 4 +.nf +\fB +Delta for pgm main.c: 3.7 \(mi 77/12/01 By cas +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +As a special case: +.RS 4 +.sp +.RS 4 +.nf +\fB +prs s.file +.fi \fR +.P +.RE +.P +might write to standard output: +.sp +.RS 4 +.nf +\fB +s.file: +<\fIblank line\fP> +D 1.1 77/12/01 00:00:00 cas 1 000000/00000/00000 +MRs: +bl78\(mi12345 +bl79\(mi54321 +COMMENTS: +this is the comment line for s.file initial delta +<\fIblank line\fP> +.fi \fR +.P +.RE +.P +for each delta table entry of the +.BR D +type. The only option allowed to be used with this special case is the +.BR \(mia +option. +.RE +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIadmin\fR\^", +.IR "\fIdelta\fR\^", +.IR "\fIget\fR\^", +.IR "\fIwhat\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/ps.1p b/man-pages-posix-2013/man1p/ps.1p new file mode 100644 index 0000000..05757a2 --- /dev/null +++ b/man-pages-posix-2013/man1p/ps.1p @@ -0,0 +1,671 @@ +'\" et +.TH PS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +ps +\(em report process status +.SH SYNOPSIS +.LP +.nf +ps \fB[\fR\(miaA\fB] \*![\fR\(midefl\fB] [\fR\(mig \fIgrouplist\fB]\*? [\fR\(miG \fIgrouplist\fB] + \*![\fR\(min \fInamelist\fB]\*? [\fR\(mio \fIformat\fB]\fR... \fB[\fR\(mip \fIproclist\fB] [\fR\(mit \fItermlist\fB] + \*![\fR\(miu \fIuserlist\fB]\*? [\fR\(miU \fIuserlist\fB] +.fi +.SH DESCRIPTION +The +.IR ps +utility shall write information about processes, subject to having +appropriate privileges to obtain information about those processes. +.P +By default, +.IR ps +shall select all processes with the same effective user ID as the +current user and the same controlling terminal as the invoker. +.SH OPTIONS +The +.IR ps +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mia\fP" 10 +Write information for all processes associated with terminals. +Implementations may omit session leaders from this list. +.IP "\fB\(miA\fP" 10 +Write information for all processes. +.IP "\fB\(mid\fP" 10 +Write information for all processes, except session leaders. +.IP "\fB\(mie\fP" 10 +Write information for all processes. +(Equivalent to +.BR \(miA .) +.IP "\fB\(mif\fP" 10 +Generate a +.BR full +listing. (See the STDOUT section for the contents of a +.BR full +listing.) +.IP "\fB\(mig\ \fIgrouplist\fR" 10 +Write information for processes whose session leaders are given in +.IR grouplist . +The application shall ensure that the +.IR grouplist +is a single argument in the form of a + +or +-separated +list. +.IP "\fB\(miG\ \fIgrouplist\fR" 10 +Write information for processes whose real group ID numbers are given +in +.IR grouplist . +The application shall ensure that the +.IR grouplist +is a single argument in the form of a + +or +-separated +list. +.IP "\fB\(mil\fP" 10 +Generate a +.BR long +listing. (See STDOUT for the contents of a +.BR long +listing.) +.IP "\fB\(min\ \fInamelist\fR" 10 +Specify the name of an alternative system +.IR namelist +file in place of the default. The name of the default file and the +format of a +.IR namelist +file are unspecified. +.IP "\fB\(mio\ \fIformat\fR" 10 +Write information according to the format specification given in +.IR format . +This is fully described in the STDOUT section. Multiple +.BR \(mio +options can be specified; the format specification shall be interpreted +as the +-separated +concatenation of all the +.IR format +option-arguments. +.IP "\fB\(mip\ \fIproclist\fR" 10 +Write information for processes whose process ID numbers are given in +.IR proclist . +The application shall ensure that the +.IR proclist +is a single argument in the form of a + +or +-separated +list. +.IP "\fB\(mit\ \fItermlist\fR" 10 +Write information for processes associated with terminals given in +.IR termlist . +The application shall ensure that the +.IR termlist +is a single argument in the form of a + +or +-separated +list. Terminal identifiers shall be given in an implementation-defined +format. +On XSI-conformant systems, they shall be given in one of two forms: +the device's filename (for example, +.BR tty04 ) +or, if the device's filename starts with +.BR tty , +just the identifier following the characters +.BR tty +(for example, +.BR \(dq04\(dq ). +.IP "\fB\(miu\ \fIuserlist\fR" 10 +Write information for processes whose user ID numbers or login names +are given in +.IR userlist . +The application shall ensure that the +.IR userlist +is a single argument in the form of a + +or +-separated +list. In the listing, the numerical user ID shall be written unless the +.BR \(mif +option is used, in which case the login name shall be written. +.IP "\fB\(miU\ \fIuserlist\fR" 10 +Write information for processes whose real user ID numbers or login +names are given in +.IR userlist . +The application shall ensure that the +.IR userlist +is a single argument in the form of a + +or +-separated +list. +.P +With the exception of +.BR \(mif , +.BR \(mil , +.BR \(min +.IR namelist , +and +.BR \(mio +.IR format , +all of the options shown are used to select processes. If any are +specified, the default list shall be ignored and +.IR ps +shall select the processes represented by the inclusive OR of +all the selection-criteria options. +.SH OPERANDS +None. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR ps : +.IP "\fICOLUMNS\fP" 10 +Override the system-selected horizontal display line size, used to +determine the number of text columns to display. See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +for valid values and results when it is unset or null. +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fILC_TIME\fP" 10 +Determine the format and contents of the date and time strings +displayed. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITZ\fP" 10 +Determine the timezone used to calculate date and time strings +displayed. If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +When the +.BR \(mio +option is not specified, the standard output format is unspecified. +.br +.P +On XSI-conformant systems, the output format shall be as follows. +The column headings and descriptions of the columns in a +.IR ps +listing are given below. The precise meanings of these fields are +implementation-defined. The letters +.BR 'f' +and +.BR 'l' +(below) indicate the option (\c +.BR full +or +.BR long ) +that shall cause the corresponding heading to appear; +.BR all +means that the heading always appears. Note that these two options +determine only what information is provided for a process; they do not +determine which processes are listed. +.TS +tab(@); +lB l lw(11c). +F@(l)@T{ +Flags (octal and additive) associated with the process. +T} +S@(l)@The state of the process. +UID@(f,l)@T{ +The user ID number of the process owner; the login name is printed +under the +.BR \(mif +option. +T} +PID@(all)@T{ +The process ID of the process; it is possible to kill a process if this +datum is known. +T} +PPID@(f,l)@The process ID of the parent process. +C@(f,l)@Processor utilization for scheduling. +PRI@(l)@T{ +The priority of the process; higher numbers mean lower priority. +T} +NI@(l)@T{ +Nice value; used in priority computation. +T} +ADDR@(l)@The address of the process. +SZ@(l)@T{ +The size in blocks of the core image of the process. +T} +WCHAN@(l)@T{ +The event for which the process is waiting or sleeping; if blank, the +process is running. +T} +STIME@(f)@Starting time of the process. +TTY@(all)@The controlling terminal for the process. +TIME@(all)@T{ +The cumulative execution time for the process. +T} +CMD@(all)@T{ +The command name; the full command name and its arguments are written +under the +.BR \(mif +option. +T} +.TE +.P +A process that has exited and has a parent, but has not yet been waited +for by the parent, shall be marked +.BR defunct . +.P +Under the option +.BR \(mif , +.IR ps +tries to determine the command name and arguments given when the +process was created by examining memory or the swap area. Failing +this, the command name, as it would appear without the option +.BR \(mif , +is written in square brackets. +.P +The +.BR \(mio +option allows the output format to be specified under user control. +.P +The application shall ensure that the format specification is a list of +names presented as a single argument, + +or +-separated. +Each variable has a default header. The default header can be overridden +by appending an + +and the new text of the header. The rest of the characters in the +argument shall be used as the header text. The fields specified shall +be written in the order specified on the command line, and should be +arranged in columns in the output. The field widths shall be selected +by the system to be at least as wide as the header text (default or +overridden value). If the header text is null, such as +.BR \(mio +.IR user =, +the field width shall be at least as wide as the default header text. +If all header text fields are null, no header line shall be written. +.P +The following names are recognized in the POSIX locale: +.IP "\fBruser\fR" 8 +The real user ID of the process. This shall be the textual user ID, if +it can be obtained and the field width permits, or a decimal +representation otherwise. +.IP "\fBuser\fR" 8 +The effective user ID of the process. This shall be the textual user +ID, if it can be obtained and the field width permits, or a decimal +representation otherwise. +.IP "\fBrgroup\fR" 8 +The real group ID of the process. This shall be the textual group ID, +if it can be obtained and the field width permits, or a decimal +representation otherwise. +.IP "\fBgroup\fR" 8 +The effective group ID of the process. This shall be the textual group +ID, if it can be obtained and the field width permits, or a decimal +representation otherwise. +.IP "\fBpid\fR" 8 +The decimal value of the process ID. +.IP "\fBppid\fR" 8 +The decimal value of the parent process ID. +.IP "\fBpgid\fR" 8 +The decimal value of the process group ID. +.IP "\fBpcpu\fR" 8 +The ratio of CPU time used recently to CPU time available in the same +period, expressed as a percentage. The meaning of ``recently'' in this +context is unspecified. The CPU time available is determined in an +unspecified manner. +.IP "\fBvsz\fR" 8 +The size of the process in (virtual) memory in 1\|024 byte units as a +decimal integer. +.IP "\fBnice\fR" 8 +The decimal value of the nice value of the process; see +.IR nice . +.IP "\fBetime\fR" 8 +In the POSIX locale, the elapsed time since the process was started, in +the form: +.RS 8 +.sp +.RS 4 +.nf +\fB +\fB[[\fIdd\fR\(mi\fB]\fIhh\fR:\fB]\fImm\fR:\fIss\fR +.fi \fR +.P +.RE +.P +where +.IR dd +shall represent the number of days, +.IR hh +the number of hours, +.IR mm +the number of minutes, and +.IR ss +the number of seconds. The +.IR dd +field shall be a decimal integer. The +.IR hh , +.IR mm , +and +.IR ss +fields shall be two-digit decimal integers padded on the left with +zeros. +.RE +.IP "\fBtime\fR" 8 +In the POSIX locale, the cumulative CPU time of the process in the +form: +.RS 8 +.sp +.RS 4 +.nf +\fB +\fB[\fIdd\fR\(mi\fB]\fIhh\fR:\fImm\fR:\fIss\fR +.fi \fR +.P +.RE +.P +The +.IR dd , +.IR hh , +.IR mm , +and +.IR ss +fields shall be as described in the +.BR etime +specifier. +.RE +.IP "\fBtty\fR" 8 +The name of the controlling terminal of the process (if any) in the +same format used by the +.IR who +utility. +.IP "\fBcomm\fR" 8 +The name of the command being executed (\c +.IR argv [0] +value) as a string. +.IP "\fBargs\fR" 8 +The command with all its arguments as a string. The implementation may +truncate this value to the field width; it is implementation-defined +whether any further truncation occurs. It is unspecified whether the +string represented is a version of the argument list as it was passed +to the command when it started, or is a version of the arguments as +they may have been modified by the application. Applications cannot +depend on being able to modify their argument list and having that +modification be reflected in the output of +.IR ps . +.P +Any field need not be meaningful in all implementations. In such a +case a + +(\c +.BR '\(mi' ) +should be output in place of the field value. +.P +Only +.BR comm +and +.BR args +shall be allowed to contain + +characters; all others shall not. Any implementation-defined variables +shall be specified in the system documentation along with the default +header and indicating whether the field may contain + +characters. +.P +The following table specifies the default header to be used in the +POSIX locale corresponding to each format specifier. +.br +.sp +.ce 1 +\fBTableNames: Variable\fR +.TS +center tab(@) box; +cB cB | cB cB +lB lB | lB lB. +Format Specifier@Default Header@Format Specifier@Default Header +_ +args@COMMAND@ppid@PPID +comm@COMMAND@rgroup@RGROUP +etime@ELAPSED@ruser@RUSER +group@GROUP@time@TIME +nice@NI@tty@TT +pcpu@%CPU@user@USER +pgid@PGID@vsz@VSZ +pid@PID +.TE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Things can change while +.IR ps +is running; the snapshot it gives is only true for an instant, and +might not be accurate by the time it is displayed. +.P +The +.BR args +format specifier is allowed to produce a truncated version of the +command arguments. In some implementations, this information is no +longer available when the +.IR ps +utility is executed. +.P +If the field width is too narrow to display a textual ID, the system +may use a numeric version. Normally, the system would be expected to +choose large enough field widths, but if a large number of fields were +selected to write, it might squeeze fields to their minimum sizes to +fit on one line. One way to ensure adequate width for the textual IDs +is to override the default header for a field to make it larger than +most or all user or group names. +.P +There is no special quoting mechanism for header text. The header text +is the rest of the argument. If multiple header changes are needed, +multiple +.BR \(mio +options can be used, such as: +.sp +.RS 4 +.nf +\fB +ps \(mio "user=User Name" \(mio pid=Process\e ID +.fi \fR +.P +.RE +.P +On some implementations, especially multi-level secure systems, +.IR ps +may be severely restricted and produce information only about child +processes owned by the user. +.SH EXAMPLES +The command: +.sp +.RS 4 +.nf +\fB +ps \(mio user,pid,ppid=MOM \(mio args +.fi \fR +.P +.RE +.P +writes at least the following in the POSIX locale: +.sp +.RS 4 +.nf +\fB + USER PID MOM COMMAND +helene 34 12 ps \(mio uid,pid,ppid=MOM \(mio args +.fi \fR +.P +.RE +.P +The contents of the +.BR COMMAND +field need not be the same in all implementations, due to possible +truncation. +.SH RATIONALE +There is very little commonality between BSD and System V +implementations of +.IR ps . +Many options conflict or have subtly different usages. The standard +developers attempted to select a set of options for the base standard +that were useful on a wide range of systems and selected options that +either can be implemented on both BSD and System V-based systems +without breaking the current implementations or where the options are +sufficiently similar that any changes would not be unduly problematic +for users or implementors. +.P +It is recognized that on some implementations, especially multi-level +secure systems, +.IR ps +may be nearly useless. The default output has therefore been chosen +such that it does not break historical implementations and also is +likely to provide at least some useful information on most systems. +.P +The major change is the addition of the format specification +capability. The motivation for this invention is to provide a mechanism +for users to access a wider range of system information, if the system +permits it, in a portable manner. The fields chosen to appear in this volume of POSIX.1\(hy2008 +were arrived at after considering what concepts were likely to be both +reasonably useful to the ``average'' user and had a reasonable chance +of being implemented on a wide range of systems. Again it is recognized +that not all systems are able to provide all the information and, +conversely, some may wish to provide more. It is hoped that the +approach adopted will be sufficiently flexible and extensible to +accommodate most systems. Implementations may be expected to introduce +new format specifiers. +.P +The default output should consist of a short listing containing the +process ID, terminal name, cumulative execution time, and command name +of each process. +.P +The preference of the standard developers would have been to make the +format specification an operand of the +.IR ps +command. Unfortunately, BSD usage precluded this. +.P +At one time a format was included to display the environment array of +the process. This was deleted because there is no portable way to +display it. +.P +The +.BR \(miA +option is equivalent to the BSD +.BR \(mig +and the SVID +.BR \(mie . +Because the two systems differed, a mnemonic compromise was selected. +.P +The +.BR \(mia +option is described with some optional behavior because the SVID omits +session leaders, but BSD does not. +.P +In an early proposal, format specifiers appeared for priority and start +time. The former was not defined adequately in this volume of POSIX.1\(hy2008 and was removed in +deference to the defined nice value; the latter because elapsed time +was considered to be more useful. +.P +In a new BSD version of +.IR ps , +a +.BR \(miO +option can be used to write all of the default information, followed by +additional format specifiers. This was not adopted because the default +output is implementation-defined. Nevertheless, this is a useful +option that should be reserved for that purpose. In the +.BR \(mio +option for the POSIX Shell and Utilities +.IR ps , +the format is the concatenation of each +.BR \(mio . +Therefore, the user can have an alias or function that defines the +beginning of their desired format and add more fields to the end of the +output in certain cases where that would be useful. +.P +The format of the terminal name is unspecified, but the descriptions of +.IR ps , +.IR talk , +.IR who , +and +.IR write +require that they all use the same format. +.P +The +.BR pcpu +field indicates that the CPU time available is determined in an +unspecified manner. This is because it is difficult to express an +algorithm that is useful across all possible machine architectures. +Historical counterparts to this value have attempted to show percentage +of use in the recent past, such as the preceding minute. Frequently, +these values for all processes did not add up to 100%. Implementations +are encouraged to provide data in this field to users that will help +them identify processes currently affecting the performance of the +system. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIkill\fR\^", +.IR "\fInice\fR\^", +.IR "\fIrenice\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/pwd.1p b/man-pages-posix-2013/man1p/pwd.1p new file mode 100644 index 0000000..6284794 --- /dev/null +++ b/man-pages-posix-2013/man1p/pwd.1p @@ -0,0 +1,210 @@ +'\" et +.TH PWD "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +pwd +\(em return working directory name +.SH SYNOPSIS +.LP +.nf +pwd \fB[\fR\(miL|\(miP\fB]\fR +.fi +.SH DESCRIPTION +The +.IR pwd +utility shall write to standard output an absolute pathname of the +current working directory, which does not contain the filenames dot or +dot-dot. +.SH OPTIONS +The +.IR pwd +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported by the implementation: +.IP "\fB\(miL\fP" 10 +If the +.IR PWD +environment variable contains an absolute pathname of the current +directory that does not contain the filenames dot or dot-dot, +.IR pwd +shall write this pathname to standard output. Otherwise, if the +.IR PWD +environment variable contains a pathname of the current directory +that is longer than +{PATH_MAX} +bytes including the terminating null, and the pathname does not contain +any components that are dot or dot-dot, it is unspecified whether +.IR pwd +writes this pathname to standard output or behaves as if the +.BR \(miP +option had been specified. Otherwise, the +.BR \(miL +option shall behave as the +.BR \(miP +option. +.IP "\fB\(miP\fP" 10 +The pathname written to standard output shall not contain any components +that refer to files of type symbolic link. If there are multiple pathnames +that the +.IR pwd +utility could write to standard output, one beginning with a single + +character and one or more beginning with two + +characters, then it shall write the pathname beginning with a single + +character. The pathname shall not contain any unnecessary + +characters after the leading one or two + +characters. +.P +If both +.BR \(miL +and +.BR \(miP +are specified, the last one shall apply. If neither +.BR \(miL +nor +.BR \(miP +is specified, the +.IR pwd +utility shall behave as if +.BR \(miL +had been specified. +.SH OPERANDS +None. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR pwd : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPWD\fP" 10 +An absolute pathname of the current working directory. If an +application sets or unsets the value of +.IR PWD , +the behavior of +.IR pwd +is unspecified. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR pwd +utility output is an absolute pathname of the current working +directory: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIdirectory pathname\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If an error is detected, output shall not be written to standard +output, a diagnostic message shall be written to standard error, and +the exit status is not zero. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +If the pathname obtained from +.IR pwd +is longer than +{PATH_MAX} +bytes, it could produce an error if passed to +.IR cd . +Therefore, in order to return to that directory it may be necessary to +break the pathname into sections shorter than +{PATH_MAX} +and call +.IR cd +on each section in turn (the first section being an absolute pathname +and subsequent sections being relative pathnames). +.SH EXAMPLES +None. +.SH RATIONALE +Some implementations have historically provided +.IR pwd +as a shell special built-in command. +.P +In most utilities, if an error occurs, partial output may be written to +standard output. This does not happen in historical implementations of +.IR pwd . +Because +.IR pwd +is frequently used in historical shell scripts without checking the +exit status, it is important that the historical behavior is required +here; therefore, the CONSEQUENCES OF ERRORS section specifically +disallows any partial output being written to standard output. +.P +An earlier version of this standard stated that the +.IR PWD +environment variable was affected when the +.BR \(miP +option was in effect. This was incorrect; conforming implementations +do not do this. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcd\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIgetcwd\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/qalter.1p b/man-pages-posix-2013/man1p/qalter.1p new file mode 100644 index 0000000..668d277 --- /dev/null +++ b/man-pages-posix-2013/man1p/qalter.1p @@ -0,0 +1,1093 @@ +'\" et +.TH QALTER "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +qalter +\(em alter batch job +.SH SYNOPSIS +.LP +.nf +qalter \fB[\fR\(mia \fIdate_time\fB] [\fR\(miA \fIaccount_string\fB] [\fR\(mic \fIinterval\fB] [\fR\(mie \fIpath_name\fB] + [\fR\(mih \fIhold_list\fB] [\fR\(mij \fIjoin_list\fB] [\fR\(mik \fIkeep_list\fB] [\fR\(mil \fIresource_list\fB] + [\fR\(mim \fImail_options\fB] [\fR\(miM \fImail_list\fB] [\fR\(miN \fIname\fB] [\fR\(mio \fIpath_name\fB] + [\fR\(mip \fIpriority\fB] [\fR\(mir \fIy\fR|\fIn\fB] [\fR\(miS \fIpath_name_list\fB] [\fR\(miu \fIuser_list\fB] + \fIjob_identifier\fR... +.fi +.SH DESCRIPTION +The attributes of a batch job are altered by a request to the batch +server that manages the batch job. The +.IR qalter +utility is a user-accessible batch client that requests the alteration +of the attributes of one or more batch jobs. +.P +The +.IR qalter +utility shall alter the attributes of those batch jobs, and only those +batch jobs, for which a batch +.IR job_identifier +is presented to the utility. +.P +The +.IR qalter +utility shall alter the attributes of batch jobs in the order in which +the batch +.IR job_identifier s +are presented to the utility. +.P +If the +.IR qalter +utility fails to process a batch +.IR job_identifier +successfully, the utility shall proceed to process the remaining batch +.IR job_identifier s, +if any. +.P +For each batch +.IR job_identifier +for which the +.IR qalter +utility succeeds, each attribute of the identified batch job shall be +altered as indicated by all the options presented to the utility. +.P +For each identified batch job for which the +.IR qalter +utility fails, the utility shall not alter any attribute of the batch +job. +.P +For each batch job that the +.IR qalter +utility processes, the utility shall not modify any attribute other +than those required by the options and option-arguments presented to +the utility. +.P +The +.IR qalter +utility shall alter batch jobs by sending a +.IR "Modify Job Request" +to the batch server that manages each batch job. At the time the +.IR qalter +utility exits, it shall have modified the batch job corresponding to +each successfully processed batch +.IR job_identifier . +An attempt to alter the attributes of a batch job in the RUNNING state +is implementation-defined. +.SH OPTIONS +The +.IR qalter +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported by the implementation: +.IP "\fB\(mia\ \fIdate_time\fR" 10 +Redefine the time at which the batch job becomes eligible for +execution. +.RS 10 +.P +The +.IR date_time +argument shall be in the same form and represent the same time as for +the +.IR touch +utility. The time so represented shall be set into the +.IR Execution_Time +attribute of the batch job. If the time specified is earlier than the +current time, the +.BR \(mia +option shall have no effect. +.RE +.IP "\fB\(miA\ \fIaccount_string\fR" 10 +.br +Redefine the account to which the resource consumption of the batch job +should be charged. +.RS 10 +.P +The syntax of the +.IR account_string +option-argument is unspecified. +.P +The +.IR qalter +utility shall set the +.IR Account_Name +attribute of the batch job to the value of the +.IR account_string +option-argument. +.RE +.IP "\fB\(mic\ \fIinterval\fR" 10 +Redefine whether the batch job should be checkpointed, and if so, how +often. +.RS 10 +.P +The +.IR qalter +utility shall accept a value for the interval option-argument that is +one of the following: +.IP "\fRn\fP" 10 +No checkpointing is to be performed on the batch job +(NO_CHECKPOINT). +.IP "\fRs\fP" 10 +Checkpointing is to be performed only when the batch server is shut +down (CHECKPOINT_AT_SHUTDOWN). +.IP "\fRc\fP" 10 +Automatic periodic checkpointing is to be performed at the +.IR Minimum_Cpu_Interval +attribute of the batch queue, in units of CPU minutes +(CHECKPOINT_AT_MIN_CPU_INTERVAL). +.IP "\fRc\fR=\fIminutes\fR" 10 +Automatic periodic checkpointing is to be performed every +.IR minutes +of CPU time, or every +.IR Minimum_Cpu_Interval +minutes, whichever is greater. The +.IR minutes +argument shall conform to the syntax for unsigned integers and shall be +greater than zero. +.P +An implementation may define other checkpoint intervals. The +conformance document for an implementation shall describe any +alternative checkpoint intervals, how they are specified, their +internal behavior, and how they affect the behavior of the utility. +.P +The +.IR qalter +utility shall set the +.IR Checkpoint +attribute of the batch job to the value of the +.IR interval +option-argument. +.RE +.IP "\fB\(mie\ \fIpath_name\fR" 10 +.br +Redefine the path to be used for the standard error stream of the batch +job. +.RS 10 +.P +The +.IR qalter +utility shall accept a +.IR path_name +option-argument that conforms to the syntax of the +.IR path_name +element defined in the System Interfaces volume of POSIX.1\(hy2008, which can be preceded by a host name +element of the form +.IR hostname :. +.P +If the +.IR path_name +option-argument constitutes an absolute pathname, the +.IR qalter +utility shall set the +.IR Error_Path +attribute of the batch job to the value of the +.IR path_name +option-argument, including the host name element, if present. +.P +If the +.IR path_name +option-argument constitutes a relative pathname and no host name +element is specified, the +.IR qalter +utility shall set the +.IR Error_Path +attribute of the batch job to the value of the absolute pathname +derived by expanding the +.IR path_name +option-argument relative to the current directory of the process that +executes the +.IR qalter +utility. +.P +If the +.IR path_name +option-argument constitutes a relative pathname and a host name +element is specified, the +.IR qalter +utility shall set the +.IR Error_Path +attribute of the batch job to the value of the option-argument without +expansion. +.P +If the +.IR path_name +option-argument does not include a host name element, the +.IR qalter +utility shall prefix the pathname in the +.IR Error_Path +attribute with +.IR hostname :, +where +.IR hostname +is the name of the host upon which the +.IR qalter +utility is being executed. +.RE +.IP "\fB\(mih\ \fIhold_list\fR" 10 +Redefine the types of holds, if any, on the batch job. The +.IR qalter +.BR \(mih +option shall accept a value for the +.IR hold_list +option-argument that is a string of alphanumeric characters in the +portable character set. +.RS 10 +.P +The +.IR qalter +utility shall accept a value for the +.IR hold_list +option-argument that is a string of one or more of the characters +.BR 'u' , +.BR 's' , +or +.BR 'o' , +or the single character +.BR 'n' . +For each unique character in the +.IR hold_list +option-argument, the +.IR qalter +utility shall add a value to the +.IR Hold_Types +attribute of the batch job as follows, each representing a different +hold type: +.IP "\fRu\fP" 6 +USER +.IP "\fRs\fP" 6 +SYSTEM +.IP "\fRo\fP" 6 +OPERATOR +.P +If any of these characters are duplicated in the +.IR hold_list +option-argument, the duplicates shall be ignored. An existing +.IR Hold_Types +attribute can be cleared by the hold type: +.IP "\fRn\fP" 6 +NO_HOLD +.P +The +.IR qalter +utility shall consider it an error if any hold type other than +.BR 'n' +is combined with hold type +.BR 'n' . +Strictly conforming applications shall not repeat any of the characters +.BR 'u' , +.BR 's' , +.BR 'o' , +or +.BR 'n' +within the +.IR hold_list +option-argument. The +.IR qalter +utility shall permit the repetition of characters, but shall not assign +additional meaning to the repeated characters. An implementation may +define other hold types. The conformance document for an implementation +shall describe any additional hold types, how they are specified, their +internal behavior, and how they affect the behavior of the utility. +.RE +.IP "\fB\(mij\ \fIjoin_list\fR" 10 +Redefine which streams of the batch job are to be merged. The +.IR qalter +.BR \(mij +option shall accept a value for the +.IR join_list +option-argument that is a string of alphanumeric characters in the +portable character set. +.RS 10 +.P +The +.IR qalter +utility shall accept a +.IR join_list +option-argument that consists of one or more of the characters +.BR 'e' +and +.BR 'o' , +or the single character +.BR 'n' . +.P +All of the other batch job output streams specified shall be merged +into the output stream represented by the character listed first in the +.IR join_list +option-argument. +.P +For each unique character in the +.IR join_list +option-argument, the +.IR qalter +utility shall add a value to the +.IR Join_Path +attribute of the batch job as follows, each representing a different +batch job stream to join: +.IP "\fRe\fP" 6 +The standard error of the batch job (JOIN_STD_ERROR). +.IP "\fRo\fP" 6 +The standard output of the batch job (JOIN_STD_OUTPUT). +.P +An existing +.IR Join_Path +attribute can be cleared by the join type: +.IP "\fRn\fP" 6 +NO_JOIN +.P +If +.BR 'n' +is specified, then no files are joined. The +.IR qalter +utility shall consider it an error if any join type other than +.BR 'n' +is combined with join type +.BR 'n' . +.P +Strictly conforming applications shall not repeat any of the characters +.BR 'e' , +.BR 'o' , +or +.BR 'n' +within the +.IR join_list +option-argument. The +.IR qalter +utility shall permit the repetition of characters, but shall not assign +additional meaning to the repeated characters. +.P +An implementation may define other join types. The conformance document +for an implementation shall describe any additional batch job streams, +how they are specified, their internal behavior, and how they affect +the behavior of the utility. +.RE +.IP "\fB\(mik\ \fIkeep_list\fR" 10 +Redefine which output of the batch job to retain on the execution host. +.RS 10 +.P +The +.IR qalter +.BR \(mik +option shall accept a value for the +.IR keep_list +option-argument that is a string of alphanumeric characters in the +portable character set. +.P +The +.IR qalter +utility shall accept a +.IR keep_list +option-argument that consists of one or more of the characters +.BR 'e' +and +.BR 'o' , +or the single character +.BR 'n' . +.P +For each unique character in the +.IR keep_list +option-argument, the +.IR qalter +utility shall add a value to the +.IR Keep_Files +attribute of the batch job as follows, each representing a different +batch job stream to keep: +.IP "\fRe\fP" 6 +The standard error of the batch job (KEEP_STD_ERROR). +.IP "\fRo\fP" 6 +The standard output of the batch job (KEEP_STD_OUTPUT). +.P +If both +.BR 'e' +and +.BR 'o' +are specified, then both files are retained. An existing +.IR Keep_Files +attribute can be cleared by the keep type: +.IP "\fRn\fP" 6 +NO_KEEP +.P +If +.BR 'n' +is specified, then no files are retained. The +.IR qalter +utility shall consider it an error if any keep type other than +.BR 'n' +is combined with keep type +.BR 'n' . +.P +Strictly conforming applications shall not repeat any of the characters +.BR 'e' , +.BR 'o' , +or +.BR 'n' +within the +.IR keep_list +option-argument. The +.IR qalter +utility shall permit the repetition of characters, but shall not assign +additional meaning to the repeated characters. An implementation may +define other keep types. The conformance document for an implementation +shall describe any additional keep types, how they are specified, their +internal behavior, and how they affect the behavior of the utility. +.RE +.IP "\fB\(mil\ \fIresource_list\fR" 10 +.br +Redefine the resources that are allowed or required by the batch job. +.RS 10 +.P +The +.IR qalter +utility shall accept a +.IR resource_list +option-argument that conforms to the following syntax: +.sp +.RS 4 +.nf +\fB +resource=value[,,resource=value,,...] +.fi \fR +.P +.RE +.P +The +.IR qalter +utility shall set one entry in the value of the +.IR Resource_List +attribute of the batch job for each resource listed in the +.IR resource_list +option-argument. +.P +Because the list of supported resource names might vary by batch +server, the +.IR qalter +utility shall rely on the batch server to validate the resource names +and associated values. See +.IR "Section 3.3.3" ", " "Multiple Keyword-Value Pairs" +for a means of removing +.IR keyword =\c +.IR value +(and +.IR value @\c +.IR keyword ) +pairs and other general rules for list-oriented batch job attributes. +.RE +.IP "\fB\(mim\ \fImail_options\fR" 10 +.br +Redefine the points in the execution of the batch job at which the +batch server is to send mail about a change in the state of the batch +job. +.RS 10 +.P +The +.IR qalter +.BR \(mim +option shall accept a value for the +.IR mail_options +option-argument that is a string of alphanumeric characters in the +portable character set. +.P +The +.IR qalter +utility shall accept a value for the +.IR mail_options +option-argument that is a string of one or more of the characters +.BR 'e' , +.BR 'b' , +and +.BR 'a' , +or the single character +.BR 'n' . +For each unique character in the +.IR mail_options +option-argument, the +.IR qalter +utility shall add a value to the +.IR Mail_Users +attribute of the batch job as follows, each representing a different +time during the life of a batch job at which to send mail: +.IP "\fRe\fP" 6 +MAIL_AT_EXIT +.IP "\fRb\fP" 6 +MAIL_AT_BEGINNING +.IP "\fRa\fP" 6 +MAIL_AT_ABORT +.P +If any of these characters are duplicated in the +.IR mail_options +option-argument, the duplicates shall be ignored. +.P +An existing +.IR Mail_Points +attribute can be cleared by the mail type: +.IP "\fRn\fP" 6 +NO_MAIL +.P +If +.BR 'n' +is specified, then mail is not sent. The +.IR qalter +utility shall consider it an error if any mail type other than +.BR 'n' +is combined with mail type +.BR 'n' . +Strictly conforming applications shall not repeat any of the characters +.BR 'e' , +.BR 'b' , +.BR 'a' , +or +.BR 'n' +within the +.IR mail_options +option-argument. The +.IR qalter +utility shall permit the repetition of characters but shall not assign +additional meaning to the repeated characters. +.P +An implementation may define other mail types. The conformance document +for an implementation shall describe any additional mail types, how +they are specified, their internal behavior, and how they affect the +behavior of the utility. +.RE +.IP "\fB\(miM\ \fImail_list\fR" 10 +Redefine the list of users to which the batch server that executes the +batch job is to send mail, if the batch server sends mail about the +batch job. +.RS 10 +.P +The syntax of the +.IR mail_list +option-argument is unspecified. If the implementation of the +.IR qalter +utility uses a name service to locate users, the utility shall accept +the syntax used by the name service. +.P +If the implementation of the +.IR qalter +utility does not use a name service to locate users, the implementation +shall accept the following syntax for user names: +.sp +.RS 4 +.nf +\fB +mail_address[,,mail_address,,...] +.fi \fR +.P +.RE +.P +The interpretation of +.IR mail_address +is implementation-defined. +.P +The +.IR qalter +utility shall set the +.IR Mail_Users +attribute of the batch job to the value of the +.IR mail_list +option-argument. +.RE +.IP "\fB\(miN\ \fIname\fR" 10 +Redefine the name of the batch job. +.RS 10 +.P +The +.IR qalter +.BR \(miN +option shall accept a value for the +.IR name +option-argument that is a string of up to 15 alphanumeric characters in +the portable character set where the first character is alphabetic. +.P +The syntax of the +.IR name +option-argument is unspecified. +.P +The +.IR qalter +utility shall set the +.IR Job_Name +attribute of the batch job to the value of the +.IR name +option-argument. +.RE +.IP "\fB\(mio\ \fIpath_name\fR" 10 +.br +Redefine the path for the standard output of the batch job. +.RS 10 +.P +The +.IR qalter +utility shall accept a +.IR path_name +option-argument that conforms to the syntax of the +.IR path_name +element defined in the System Interfaces volume of POSIX.1\(hy2008, which can be preceded by a host name +element of the form +.IR hostname :. +.P +If the +.IR path_name +option-argument constitutes an absolute pathname, the +.IR qalter +utility shall set the +.IR Output_Path +attribute of the batch job to the value of the +.IR path_name +option-argument. +.P +If the +.IR path_name +option-argument constitutes a relative pathname and no host name +element is specified, the +.IR qalter +utility shall set the +.IR Output_Path +attribute of the batch job to the absolute pathname derived by +expanding the +.IR path_name +option-argument relative to the current directory of the process that +executes the +.IR qalter +utility. +.P +If the +.IR path_name +option-argument constitutes a relative pathname and a host name +element is specified, the +.IR qalter +utility shall set the +.IR Output_Path +attribute of the batch job to the value of the +.IR path_name +option-argument without any expansion of the pathname. +.P +If the +.IR path_name +option-argument does not include a host name element, the +.IR qalter +utility shall prefix the pathname in the +.IR Output_Path +attribute with +.IR hostname :, +where +.IR hostname +is the name of the host upon which the +.IR qalter +utility is being executed. +.RE +.IP "\fB\(mip\ \fIpriority\fR" 10 +Redefine the priority of the batch job. +.RS 10 +.P +The +.IR qalter +utility shall accept a value for the priority option-argument that +conforms to the syntax for signed decimal integers, and which is not +less than \(mi1\|024 and not greater than 1\|023. +.P +The +.IR qalter +utility shall set the +.IR Priority +attribute of the batch job to the value of the +.IR priority +option-argument. +.RE +.IP "\fB\(mir\ \fRy\fR|\fRn\fR" 10 +Redefine whether the batch job is rerunnable. +.RS 10 +.P +If the value of the option-argument is +.BR 'y' , +the +.IR qalter +utility shall set the +.IR Rerunable +attribute of the batch job to TRUE. +.P +If the value of the option-argument is +.BR 'n' , +the +.IR qalter +utility shall set the +.IR Rerunable +attribute of the batch job to FALSE. +.P +The +.IR qalter +utility shall consider it an error if any character other than +.BR 'y' +or +.BR 'n' +is specified in the option-argument. +.RE +.IP "\fB\(miS\ \fIpath_name_list\fR" 10 +.br +Redefine the shell that interprets the script at the destination +system. +.RS 10 +.P +The +.IR qalter +utility shall accept a +.IR path_name_list +option-argument that conforms to the following syntax: +.sp +.RS 4 +.nf +\fB +pathname[@host][,pathname[@host],...] +.fi \fR +.P +.RE +.P +The +.IR qalter +utility shall accept only one pathname that is missing a corresponding +host name. The +.IR qalter +utility shall allow only one pathname per named host. +.P +The +.IR qalter +utility shall add a value to the +.IR Shell_Path_List +attribute of the batch job for each entry in the +.IR path_name_list +option-argument. See +.IR "Section 3.3.3" ", " "Multiple Keyword-Value Pairs" +for a means of removing +.IR keyword =\c +.IR value +(and +.IR value @\c +.IR keyword ) +pairs and other general rules for list-oriented batch job attributes. +.RE +.IP "\fB\(miu\ \fIuser_list\fR" 10 +Redefine the user name under which the batch job is to run at the +destination system. +.RS 10 +.P +The +.IR qalter +utility shall accept a +.IR user_list +option-argument that conforms to the following syntax: +.sp +.RS 4 +.nf +\fB +username[@host][,,username[@host],,...] +.fi \fR +.P +.RE +.P +The +.IR qalter +utility shall accept only one user name that is missing a corresponding +host name. The +.IR qalter +utility shall accept only one user name per named host. +.P +The +.IR qalter +utility shall add a value to the +.IR User_List +attribute of the batch job for each entry in the +.IR user_list +option-argument. See +.IR "Section 3.3.3" ", " "Multiple Keyword-Value Pairs" +for a means of removing +.IR keyword =\c +.IR value +(and +.IR value @\c +.IR keyword ) +pairs and other general rules for list-oriented batch job attributes. +.RE +.SH OPERANDS +The +.IR qalter +utility shall accept one or more operands that conform to the syntax +for a batch +.IR job_identifier +(see +.IR "Section 3.3.1" ", " "Batch Job Identifier"). +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR qalter : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILOGNAME\fP" 10 +Determine the login name of the user. +.IP "\fITZ\fP" 10 +Determine the timezone used to interpret the +.IR date-time +option-argument. If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +None. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +In addition to the default behavior, the +.IR qalter +utility shall not be required to write a diagnostic message to standard +error when the error reply received from a batch server indicates that +the batch +.IR job_identifier +does not exist on the server. Whether or not the +.IR qalter +utility attempts to locate the batch job on other batch servers is +implementation-defined. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR qalter +utility allows users to change the attributes of a batch job. +.P +As a means of altering a queued job, the +.IR qalter +utility is superior to deleting and requeuing the batch job insofar as +an altered job retains its place in the queue with some traditional +selection algorithms. In addition, the +.IR qalter +utility is both shorter and simpler than a sequence of +.IR qdel +and +.IR qsub +utilities. +.P +The result of an attempt on the part of a user to alter a batch job in +a RUNNING state is implementation-defined because a batch job in the +RUNNING state will already have opened its output files and otherwise +performed any actions indicated by the options in effect at the time +the batch job began execution. +.P +The options processed by the +.IR qalter +utility are identical to those of the +.IR qsub +utility, with a few exceptions: +.BR \(miV , +.BR \(miv , +and +.BR \(miq . +The +.BR \(miV +and +.BR \(miv +are inappropriate for the +.IR qalter +utility, since they capture potentially transient environment +information from the submitting process. The +.BR \(miq +option would specify a new queue, which would largely negate the +previously stated advantage of using +.IR qalter ; +furthermore, the +.IR qmove +utility provides a superior means of moving jobs. +.P +Each of the following paragraphs provides the rationale for a +.IR qalter +option. +.P +Additional rationale concerning these options can be found in the +rationale for the +.IR qsub +utility. +.P +The +.BR \(mia +option allows users to alter the date and time at which a batch job +becomes eligible to run. +.P +The +.BR \(miA +option allows users to change the account that will be charged for the +resources consumed by the batch job. Support for the +.BR \(miA +option is mandatory for conforming implementations of +.IR qalter , +even though support of accounting is optional for servers. Whether or +not to support accounting is left to the implementor of the server, but +mandatory support of the +.BR \(miA +option assures users of a consistent interface and allows them to +control accounting on servers that support accounting. +.P +The +.BR \(mic +option allows users to alter the checkpointing interval of a batch +job. A checkpointing system, which is not defined by POSIX.1\(hy2008, allows +recovery of a batch job at the most recent checkpoint in the event of a +crash. Checkpointing is typically used for jobs that consume expensive +computing time or must meet a critical schedule. Users should be +allowed to make the tradeoff between the overhead of checkpointing and +the risk to the timely completion of the batch job; therefore, this volume of POSIX.1\(hy2008 +provides the checkpointing interval option. Support for checkpointing +is optional for servers. +.P +The +.BR \(mie +option allows users to alter the name and location of the standard +error stream written by a batch job. However, the path of the standard +error stream is meaningless if the value of the +.IR Join_Path +attribute of the batch job is TRUE. +.P +The +.BR \(mih +option allows users to set the hold type in the +.IR Hold_Types +attribute of a batch job. The +.IR qhold +and +.IR qrls +utilities add or remove hold types to the +.IR Hold_Types +attribute, respectively. The +.BR \(mih +option has been modified to allow for implementation-defined hold +types. +.P +The +.BR \(mij +option allows users to alter the decision to join (merge) the standard +error stream of the batch job with the standard output stream of the +batch job. +.P +The +.BR \(mil +option allows users to change the resource limits imposed on a batch +job. +.P +The +.BR \(mim +option allows users to modify the list of points in the life of a batch +job at which the designated users will receive mail notification. +.P +The +.BR \(miM +option allows users to alter the list of users who will receive +notification about events in the life of a batch job. +.P +The +.BR \(miN +option allows users to change the name of a batch job. +.P +The +.BR \(mio +option allows users to alter the name and path to which the standard +output stream of the batch job will be written. +.P +The +.BR \(miP +option allows users to modify the priority of a batch job. Support for +priority is optional for batch servers. +.P +The +.BR \(mir +option allows users to alter the rerunability status of a batch job. +.P +The +.BR \(miS +option allows users to change the name and location of the shell image +that will be invoked to interpret the script of the batch job. This +option has been modified to allow a list of shell name and locations +associated with different hosts. +.P +The +.BR \(miu +option allows users to change the user identifier under which the batch +job will execute. +.P +The +.IR job_identifier +operand syntax is provided so that the user can differentiate between +the originating and destination (or executing) batch server. These may +or may not be the same. The .\c +.IR server_name +portion identifies the originating batch server, while the @\c +.IR server +portion identifies the destination batch server. +.P +Historically, the +.IR qalter +utility has been a component of the Network Queuing System (NQS), the +existing practice from which this utility has been derived. +.SH "FUTURE DIRECTIONS" +The +.IR qalter +utility may be removed in a future version. +.SH "SEE ALSO" +.IR "Chapter 3" ", " "Batch Environment Services", +.IR "\fIqdel\fR\^", +.IR "\fIqhold\fR\^", +.IR "\fIqmove\fR\^", +.IR "\fIqrls\fR\^", +.IR "\fIqsub\fR\^", +.IR "\fItouch\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/qdel.1p b/man-pages-posix-2013/man1p/qdel.1p new file mode 100644 index 0000000..322db96 --- /dev/null +++ b/man-pages-posix-2013/man1p/qdel.1p @@ -0,0 +1,208 @@ +'\" et +.TH QDEL "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +qdel +\(em delete batch jobs +.SH SYNOPSIS +.LP +.nf +qdel \fIjob_identifier\fP... +.fi +.SH DESCRIPTION +A batch job is deleted by sending a request to the batch server that +manages the batch job. A batch job that has been deleted is no longer +subject to management by batch services. +.P +The +.IR qdel +utility is a user-accessible client of batch services that requests the +deletion of one or more batch jobs. +.P +The +.IR qdel +utility shall request a batch server to delete those batch jobs for +which a batch +.IR job_identifier +is presented to the utility. +.P +The +.IR qdel +utility shall delete batch jobs in the order in which their batch +.IR job_identifier s +are presented to the utility. +.P +If the +.IR qdel +utility fails to process any batch +.IR job_identifier +successfully, the utility shall proceed to process the remaining batch +.IR job_identifier s, +if any. +.P +The +.IR qdel +utility shall delete each batch job by sending a +.IR "Delete Job Request" +to the batch server that manages the batch job. +.P +The +.IR qdel +utility shall not exit until the batch job corresponding to each +successfully processed batch +.IR job_identifier +has been deleted. +.SH OPTIONS +None. +.SH OPERANDS +The +.IR qdel +utility shall accept one or more operands that conform to the syntax +for a batch +.IR job_identifier +(see +.IR "Section 3.3.1" ", " "Batch Job Identifier"). +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR qdel : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILOGNAME\fP" 10 +Determine the login name of the user. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +An implementation of the +.IR qdel +utility may write informative messages to standard output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +In addition to the default behavior, the +.IR qdel +utility shall not be required to write a diagnostic message to standard +error when the error reply received from a batch server indicates that +the batch +.IR job_identifier +does not exist on the server. Whether or not the +.IR qdel +utility waits to output the diagnostic message while attempting to +locate the job on other servers is implementation-defined. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR qdel +utility allows users and administrators to delete jobs. +.P +The +.IR qdel +utility provides functionality that is not otherwise available. For +example, the +.IR kill +utility of the operating system does not suffice. First, to use the +.IR kill +utility, the user might have to log in on a remote node, because the +.IR kill +utility does not operate across the network. Second, unlike +.IR qdel , +.IR kill +cannot remove jobs from queues. Lastly, the arguments of the +.IR qdel +utility are job identifiers rather than process identifiers, and so +this utility can be passed the output of the +.IR qselect +utility, thus providing users with a means of deleting a list of jobs. +.P +Because a set of jobs can be selected using the +.IR qselect +utility, the +.IR qdel +utility has not been complicated with options that provide for +selection of jobs. Instead, the batch jobs to be deleted are identified +individually by their job identifiers. +.P +Historically, the +.IR qdel +utility has been a component of NQS, the existing practice on which it +is based. However, the +.IR qdel +utility defined in this volume of POSIX.1\(hy2008 does not provide an option for specifying a +signal number to send to the batch job prior to the killing of the +process; that capability has been subsumed by the +.IR qsig +utility. +.P +A discussion was held about the delays of networking and the +possibility that the batch server may never respond, due to a down +router, down batch server, or other network mishap. The DESCRIPTION +records this under the words ``fails to process any job identifier''. +In the broad sense, the network problem is also an error, which causes +the failure to process the batch job identifier. +.SH "FUTURE DIRECTIONS" +The +.IR qdel +utility may be removed in a future version. +.SH "SEE ALSO" +.IR "Chapter 3" ", " "Batch Environment Services", +.IR "\fIkill\fR\^", +.IR "\fIqselect\fR\^", +.IR "\fIqsig\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/qhold.1p b/man-pages-posix-2013/man1p/qhold.1p new file mode 100644 index 0000000..c1f0088 --- /dev/null +++ b/man-pages-posix-2013/man1p/qhold.1p @@ -0,0 +1,270 @@ +'\" et +.TH QHOLD "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +qhold +\(em hold batch jobs +.SH SYNOPSIS +.LP +.nf +qhold \fB[\fR\(mih \fIhold_list\fB] \fIjob_identifier\fR... +.fi +.SH DESCRIPTION +A hold is placed on a batch job by a request to the batch server that +manages the batch job. A batch job that has one or more holds is not +eligible for execution. The +.IR qhold +utility is a user-accessible client of batch services that requests one +or more types of hold to be placed on one or more batch jobs. +.P +The +.IR qhold +utility shall place holds on those batch jobs for which a batch +.IR job_identifier +is presented to the utility. +.P +The +.IR qhold +utility shall place holds on batch jobs in the order in which their +batch +.IR job_identifier s +are presented to the utility. If the +.IR qhold +utility fails to process any batch +.IR job_identifier +successfully, the utility shall proceed to process the remaining batch +.IR job_identifier s, +if any. +.P +The +.IR qhold +utility shall place holds on each batch job by sending a +.IR "Hold Job Request" +to the batch server that manages the batch job. +.P +The +.IR qhold +utility shall not exit until holds have been placed on the batch job +corresponding to each successfully processed batch +.IR job_identifier . +.SH OPTIONS +The +.IR qhold +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported by the implementation: +.IP "\fB\(mih\ \fIhold_list\fR" 10 +Define the types of holds to be placed on the batch job. +.RS 10 +.P +The +.IR qhold +.BR \(mih +option shall accept a value for the +.IR hold_list +option-argument that is a string of alphanumeric characters in the +portable character set (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set"). +.P +The +.IR qhold +utility shall accept a value for the +.IR hold_list +option-argument that is a string of one or more of the characters +.BR 'u' , +.BR 's' , +or +.BR 'o' , +or the single character +.BR 'n' . +.P +For each unique character in the +.IR hold_list +option-argument, the +.IR qhold +utility shall add a value to the +.IR Hold_Types +attribute of the batch job as follows, each representing a different +hold type: +.IP "\fRu\fP" 6 +USER +.IP "\fRs\fP" 6 +SYSTEM +.IP "\fRo\fP" 6 +OPERATOR +.P +If any of these characters are duplicated in the +.IR hold_list +option-argument, the duplicates shall be ignored. +.P +An existing +.IR Hold_Types +attribute can be cleared by the following hold type: +.IP "\fRn\fP" 6 +NO_HOLD +.P +The +.IR qhold +utility shall consider it an error if any hold type other than +.BR 'n' +is combined with hold type +.BR 'n' . +.P +Strictly conforming applications shall not repeat any of the characters +.BR 'u' , +.BR 's' , +.BR 'o' , +or +.BR 'n' +within the +.IR hold_list +option-argument. The +.IR qhold +utility shall permit the repetition of characters, but shall not assign +additional meaning to the repeated characters. +.P +An implementation may define other hold types. The conformance document +for an implementation shall describe any additional hold types, how +they are specified, their internal behavior, and how they affect the +behavior of the utility. +.P +If the +.BR \(mih +option is not presented to the +.IR qhold +utility, the implementation shall set the +.IR Hold_Types +attribute to USER. +.RE +.SH OPERANDS +The +.IR qhold +utility shall accept one or more operands that conform to the syntax +for a batch +.IR job_identifier +(see +.IR "Section 3.3.1" ", " "Batch Job Identifier"). +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR qhold : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILOGNAME\fP" 10 +Determine the login name of the user. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +None. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +.br +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +In addition to the default behavior, the +.IR qhold +utility shall not be required to write a diagnostic message to standard +error when the error reply received from a batch server indicates that +the batch +.IR job_identifier +does not exist on the server. Whether or not the +.IR qhold +utility waits to output the diagnostic message while attempting to +locate the job on other servers is implementation-defined. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR qhold +utility allows users to place a hold on one or more jobs. A hold makes +a batch job ineligible for execution. +.P +The +.IR qhold +utility has options that allow the user to specify the type of hold. +Should the user wish to place a hold on a set of jobs that meet a +selection criteria, such a list of jobs can be acquired using the +.IR qselect +utility. +.P +The +.BR \(mih +option allows the user to specify the type of hold that is to be placed +on the job. This option allows for USER, SYSTEM, OPERATOR, and +implementation-defined hold types. The USER and OPERATOR holds are +distinct. The batch server that manages the batch job will verify that +the user is authorized to set the specified hold for the batch job. +.P +Mail is not required on hold because the administrator has the tools +and libraries to build this option if he or she wishes. +.P +Historically, the +.IR qhold +utility has been a part of some existing batch systems, although it has +not traditionally been a part of the NQS. +.SH "FUTURE DIRECTIONS" +The +.IR qhold +utility may be removed in a future version. +.SH "SEE ALSO" +.IR "Chapter 3" ", " "Batch Environment Services", +.IR "\fIqselect\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/qmove.1p b/man-pages-posix-2013/man1p/qmove.1p new file mode 100644 index 0000000..a64e98e --- /dev/null +++ b/man-pages-posix-2013/man1p/qmove.1p @@ -0,0 +1,187 @@ +'\" et +.TH QMOVE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +qmove +\(em move batch jobs +.SH SYNOPSIS +.LP +.nf +qmove \fIdestination job_identifier\fP... +.fi +.SH DESCRIPTION +To move a batch job is to remove the batch job from the batch queue in +which it resides and instantiate the batch job in another batch queue. +A batch job is moved by a request to the batch server that manages the +batch job. The +.IR qmove +utility is a user-accessible batch client that requests the movement of +one or more batch jobs. +.P +The +.IR qmove +utility shall move those batch jobs, and only those batch jobs, for +which a batch +.IR job_identifier +is presented to the utility. +.P +The +.IR qmove +utility shall move batch jobs in the order in which the corresponding +batch +.IR job_identifier s +are presented to the utility. +.P +If the +.IR qmove +utility fails to process a batch +.IR job_identifier +successfully, the utility shall proceed to process the remaining batch +.IR job_identifier s, +if any. +.P +The +.IR qmove +utility shall move batch jobs by sending a +.IR "Move Job Request" +to the batch server that manages each batch job. The +.IR qmove +utility shall not exit before the batch jobs corresponding to all +successfully processed batch +.IR job_identifier s +have been moved. +.SH OPTIONS +None. +.SH OPERANDS +The +.IR qmove +utility shall accept one operand that conforms to the syntax for a +destination (see +.IR "Section 3.3.2" ", " "Destination"). +.P +The +.IR qmove +utility shall accept one or more operands that conform to the syntax +for a batch +.IR job_identifier +(see +.IR "Section 3.3.1" ", " "Batch Job Identifier"). +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR qmove : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILOGNAME\fP" 10 +Determine the login name of the user. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +None. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +In addition to the default behavior, the +.IR qmove +utility shall not be required to write a diagnostic message to standard +error when the error reply received from a batch server indicates that +the batch +.IR job_identifier +does not exist on the server. Whether or not the +.IR qmove +utility waits to output the diagnostic message while attempting to +locate the job on other servers is implementation-defined. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR qmove +utility allows users to move jobs between queues. +.P +The alternative to using the +.IR qmove +utility\(emdeleting the batch job and requeuing it\(ementails +considerably more typing. +.P +Since the means of selecting jobs based on attributes has been +encapsulated in the +.IR qselect +utility, the only option of the +.IR qmove +utility concerns authorization. The +.BR \(miu +option provides the user with the convenience of changing the user +identifier under which the batch job will execute. Minimalism and +consistency have taken precedence over convenience; the +.BR \(miu +option has been deleted because the equivalent capability exists with +the +.BR \(miu +option of the +.IR qalter +utility. +.SH "FUTURE DIRECTIONS" +The +.IR qmove +utility may be removed in a future version. +.SH "SEE ALSO" +.IR "Chapter 3" ", " "Batch Environment Services", +.IR "\fIqalter\fR\^", +.IR "\fIqselect\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/qmsg.1p b/man-pages-posix-2013/man1p/qmsg.1p new file mode 100644 index 0000000..0a8d237 --- /dev/null +++ b/man-pages-posix-2013/man1p/qmsg.1p @@ -0,0 +1,265 @@ +'\" et +.TH QMSG "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +qmsg +\(em send message to batch jobs +.SH SYNOPSIS +.LP +.nf +qmsg \fB[\fR\(miEO\fB] \fImessage_string job_identifier\fR... +.fi +.SH DESCRIPTION +To send a message to a batch job is to request that a server write a +message string into one or more output files of the batch job. A +message is sent to a batch job by a request to the batch server that +manages the batch job. The +.IR qmsg +utility is a user-accessible batch client that requests the sending of +messages to one or more batch jobs. +.P +The +.IR qmsg +utility shall write messages into the files of batch jobs by sending a +.IR "Job Message Request" +to the batch server that manages the batch job. The +.IR qmsg +utility shall not directly write the message into the files of the +batch job. +.P +The +.IR qmsg +utility shall send a +.IR "Job Message Request" +for those batch jobs, and only those batch jobs, for which a batch +.IR job_identifier +is presented to the utility. +.P +The +.IR qmsg +utility shall send +.IR "Job Message Request" s +for batch jobs in the order in which their batch +.IR job_identifier s +are presented to the utility. +.P +If the +.IR qmsg +utility fails to process any batch +.IR job_identifier +successfully, the utility shall proceed to process the remaining batch +.IR job_identifier s, +if any. +.P +The +.IR qmsg +utility shall not exit before a +.IR "Job Message Request" +has been sent to the server that manages the batch job that corresponds +to each successfully processed batch +.IR job_identifier . +.SH OPTIONS +The +.IR qmsg +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported by the implementation: +.IP "\fB\(miE\fP" 10 +Specify that the message is written to the standard error of each batch +job. +.RS 10 +.P +The +.IR qmsg +utility shall write the message into the standard error of the batch +job. +.RE +.IP "\fB\(miO\fP" 10 +Specify that the message is written to the standard output of each +batch job. +.RS 10 +.P +The +.IR qmsg +utility shall write the message into the standard output of the batch +job. +.RE +.P +If neither the +.BR \(miO +nor the +.BR \(miE +option is presented to the +.IR qmsg +utility, the utility shall write the message into an +implementation-defined file. The conformance document for the +implementation shall describe the name and location of the +implementation-defined file. If both the +.BR \(miO +and the +.BR \(miE +options are presented to the +.IR qmsg +utility, then the utility shall write the messages to both standard +output and standard error. +.SH OPERANDS +The +.IR qmsg +utility shall accept a minimum of two operands, +.IR message_string +and one or more batch +.IR job_identifier s. +.P +The +.IR message_string +operand shall be the string to be written to one or more output files +of the batch job followed by a +. +If the string contains + +characters, then the application shall ensure that the string is +quoted. The +.IR message_string +shall be encoded in the portable character set (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set"). +.P +All remaining operands are batch +.IR job_identifier s +that conform to the syntax for a batch +.IR job_identifier +(see +.IR "Section 3.3.1" ", " "Batch Job Identifier"). +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR qmsg : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILOGNAME\fP" 10 +Determine the login name of the user. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +None. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +In addition to the default behavior, the +.IR qmsg +utility shall not be required to write a diagnostic message to standard +error when the error reply received from a batch server indicates that +the batch +.IR job_identifier +does not exist on the server. Whether or not the +.IR qmsg +utility waits to output the diagnostic message while attempting to +locate the job on other servers is implementation-defined. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR qmsg +utility allows users to write messages into the output files of running +jobs. Users, including operators and administrators, have a number of +occasions when they want to place messages in the output files of a +batch job. For example, if a disk that is being used by a batch job is +showing errors, the operator might note this in the standard error +stream of the batch job. +.P +The options of the +.IR qmsg +utility provide users with the means of placing the message in the +output stream of their choice. The default output stream for the +message\(emif the user does not designate an output stream\(emis +implementation-defined, since many implementations will provide, as +an extension to this volume of POSIX.1\(hy2008, a log file that shows the history of utility +execution. +.P +If users wish to send a message to a set of jobs that meet a selection +criteria, the +.IR qselect +utility can be used to acquire the appropriate list of job +identifiers. +.P +The +.BR \(miE +option allows users to place the message in the standard error stream +of the batch job. +.P +The +.BR \(miO +option allows users to place the message in the standard output stream +of the batch job. +.P +Historically, the +.IR qmsg +utility is an existing practice in the offerings of one or more +implementors of an NQS-derived batch system. The utility has been found +to be useful enough that it deserves to be included in this volume of POSIX.1\(hy2008. +.SH "FUTURE DIRECTIONS" +The +.IR qmsg +utility may be removed in a future version. +.SH "SEE ALSO" +.IR "Chapter 3" ", " "Batch Environment Services", +.IR "\fIqselect\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/qrerun.1p b/man-pages-posix-2013/man1p/qrerun.1p new file mode 100644 index 0000000..537bc8e --- /dev/null +++ b/man-pages-posix-2013/man1p/qrerun.1p @@ -0,0 +1,163 @@ +'\" et +.TH QRERUN "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +qrerun +\(em rerun batch jobs +.SH SYNOPSIS +.LP +.nf +qrerun \fIjob_identifier\fR... +.fi +.SH DESCRIPTION +To rerun a batch job is to terminate the session leader of the batch +job, delete any associated checkpoint files, and return the batch job +to the batch queued state. A batch job is rerun by a request to the +batch server that manages the batch job. The +.IR qrerun +utility is a user-accessible batch client that requests the rerunning +of one or more batch jobs. +.P +The +.IR qrerun +utility shall rerun those batch jobs for which a batch +.IR job_identifier +is presented to the utility. +.P +The +.IR qrerun +utility shall rerun batch jobs in the order in which their batch +.IR job_identifier s +are presented to the utility. +.P +If the +.IR qrerun +utility fails to process any batch +.IR job_identifier +successfully, the utility shall proceed to process the remaining batch +.IR job_identifier s, +if any. +.P +The +.IR qrerun +utility shall rerun batch jobs by sending a +.IR "Rerun Job Request" +to the batch server that manages each batch job. +.P +For each successfully processed batch +.IR job_identifier , +the +.IR qrerun +utility shall have rerun the corresponding batch job at the time +the utility exits. +.SH OPTIONS +None. +.SH OPERANDS +The +.IR qrerun +utility shall accept one or more operands that conform to the syntax +for a batch +.IR job_identifier +(see +.IR "Section 3.3.1" ", " "Batch Job Identifier"). +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR qrerun : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILOGNAME\fP" 10 +Determine the login name of the user. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +None. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +In addition to the default behavior, the +.IR qrerun +utility shall not be required to write a diagnostic message to standard +error when the error reply received from a batch server indicates that +the batch +.IR job_identifier +does not exist on the server. Whether or not the +.IR qrerun +utility waits to output the diagnostic message while attempting to +locate the job on other servers is implementation-defined. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR qrerun +utility allows users to cause jobs in the running state to exit and +rerun. +.P +The +.IR qrerun +utility is a new utility, \fIvis-a-vis\fP existing practice, that has +been defined in this volume of POSIX.1\(hy2008 to correct user-perceived deficiencies in the +existing practice. +.SH "FUTURE DIRECTIONS" +The +.IR qrerun +utility may be removed in a future version. +.SH "SEE ALSO" +.IR "Chapter 3" ", " "Batch Environment Services" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/qrls.1p b/man-pages-posix-2013/man1p/qrls.1p new file mode 100644 index 0000000..dfc78df --- /dev/null +++ b/man-pages-posix-2013/man1p/qrls.1p @@ -0,0 +1,279 @@ +'\" et +.TH QRLS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +qrls +\(em release batch jobs +.SH SYNOPSIS +.LP +.nf +qrls \fB[\fR\(mih \fIhold_list\fB] \fIjob_identifier\fR... +.fi +.SH DESCRIPTION +A batch job might have one or more holds, which prevent the batch job +from executing. A batch job from which all the holds have been removed +becomes eligible for execution and is said to have been released. A +batch job hold is removed by sending a request to the batch server that +manages the batch job. The +.IR qrls +utility is a user-accessible client of batch services that requests +holds be removed from one or more batch jobs. +.P +The +.IR qrls +utility shall remove one or more holds from those batch jobs for which +a batch +.IR job_identifier +is presented to the utility. +.P +The +.IR qrls +utility shall remove holds from batch jobs in the order in which their +batch +.IR job_identifier s +are presented to the utility. +.P +If the +.IR qrls +utility fails to process a batch +.IR job_identifier +successfully, the utility shall proceed to process the remaining batch +.IR job_identifier s, +if any. +.P +The +.IR qrls +utility shall remove holds on each batch job by sending a +.IR "Release Job Request" +to the batch server that manages the batch job. +.P +The +.IR qrls +utility shall not exit until the holds have been removed from the batch +job corresponding to each successfully processed batch +.IR job_identifier . +.SH OPTIONS +The +.IR qrls +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported by the implementation: +.IP "\fB\(mih\ \fIhold_list\fR" 10 +Define the types of holds to be removed from the batch job. +.RS 10 +.P +The +.IR qrls +.BR \(mih +option shall accept a value for the +.IR hold_list +option-argument that is a string of alphanumeric characters in the +portable character set (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set"). +.P +The +.IR qrls +utility shall accept a value for the +.IR hold_list +option-argument that is a string of one or more of the characters +.BR 'u' , +.BR 's' , +or +.BR 'o' , +or the single character +.BR 'n' . +.P +For each unique character in the +.IR hold_list +option-argument, the +.IR qrls +utility shall add a value to the +.IR Hold_Types +attribute of the batch job as follows, each representing a different +hold type: +.IP "\fRu\fP" 6 +USER +.IP "\fRs\fP" 6 +SYSTEM +.IP "\fRo\fP" 6 +OPERATOR +.P +If any of these characters are duplicated in the +.IR hold_list +option-argument, the duplicates shall be ignored. +.P +An existing +.IR Hold_Types +attribute can be cleared by the following hold type: +.IP "\fRn\fP" 6 +NO_HOLD +.P +The +.IR qrls +utility shall consider it an error if any hold type other than +.BR 'n' +is combined with hold type +.BR 'n' . +.P +Strictly conforming applications shall not repeat any of the characters +.BR 'u' , +.BR 's' , +.BR 'o' , +or +.BR 'n' +within the +.IR hold_list +option-argument. The +.IR qrls +utility shall permit the repetition of characters, but shall not assign +additional meaning to the repeated characters. +.P +An implementation may define other hold types. The conformance document +for an implementation shall describe any additional hold types, how +they are specified, their internal behavior, and how they affect the +behavior of the utility. +.P +If the +.BR \(mih +option is not presented to the +.IR qrls +utility, the implementation shall remove the USER hold in the +.IR Hold_Types +attribute. +.RE +.SH OPERANDS +The +.IR qrls +utility shall accept one or more operands that conform to the syntax +for a batch +.IR job_identifier +(see +.IR "Section 3.3.1" ", " "Batch Job Identifier"). +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR qrls : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILOGNAME\fP" 10 +Determine the login name of the user. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +None. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +In addition to the default behavior, the +.IR qrls +utility shall not be required to write a diagnostic message to standard +error when the error reply received from a batch server indicates that +the batch +.IR job_identifier +does not exist on the server. Whether or not the +.IR qrls +utility waits to output the diagnostic message while attempting to +locate the job on other servers is implementation-defined. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR qrls +utility allows users, operators, and administrators to remove holds +from jobs. +.P +The +.IR qrls +utility does not support any job selection options or wildcard +arguments. Users may acquire a list of jobs selected by attributes +using the +.IR qselect +utility. For example, a user could select all of their held jobs. +.P +The +.BR \(mih +option allows the user to specify the type of hold that is to be +removed. This option allows for USER, SYSTEM, OPERATOR, and +implementation-defined hold types. The batch server that manages the +batch job will verify whether the user is authorized to remove the +specified hold for the batch job. If more than one type of hold has +been placed on the batch job, a user may wish to remove only some of +them. +.P +Mail is not required on release because the administrator has the tools +and libraries to build this option if required. +.P +The +.IR qrls +utility is a new utility \fIvis-a-vis\fP existing practice; it has been +defined in this volume of POSIX.1\(hy2008 as the natural complement to the +.IR qhold +utility. +.SH "FUTURE DIRECTIONS" +The +.IR qrls +utility may be removed in a future version. +.SH "SEE ALSO" +.IR "Chapter 3" ", " "Batch Environment Services", +.IR "\fIqhold\fR\^", +.IR "\fIqselect\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/qselect.1p b/man-pages-posix-2013/man1p/qselect.1p new file mode 100644 index 0000000..6d9e6bb --- /dev/null +++ b/man-pages-posix-2013/man1p/qselect.1p @@ -0,0 +1,918 @@ +'\" et +.TH QSELECT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +qselect +\(em select batch jobs +.SH SYNOPSIS +.LP +.nf +qselect \fB[\fR\(mia \fB[\fIop\fB]\fIdate_time\fB] [\fR\(miA \fIaccount_string\fB] [\fR\(mic \fB[\fIop\fB]\fIinterval\fB] + [\fR\(mih \fIhold_list\fB] [\fR\(mil \fIresource_list\fB] [\fR\(miN \fIname\fB] [\fR\(mip \fB[\fIop\fB]\fIpriority\fB] + [\fR\(miq \fIdestination\fB] [\fR\(mir \fIy\fR|\fIn\fB] [\fR\(mis \fIstates\fB] [\fR\(miu \fIuser_list\fB]\fR +.fi +.SH DESCRIPTION +To select a set of batch jobs is to return the batch +.IR job_identifier s +for each batch job that meets a list of selection criteria. A set of +batch jobs is selected by a request to a batch server. The +.IR qselect +utility is a user-accessible batch client that requests the selection +of batch jobs. +.P +Upon successful completion, the +.IR qselect +utility shall have returned a list of zero or more batch +.IR job_identifier s +that meet the criteria specified by the options and option-arguments +presented to the utility. +.P +The +.IR qselect +utility shall select batch jobs by sending a +.IR "Select Jobs Request" +to a batch server. The +.IR qselect +utility shall not exit until the server replies to each request +generated. +.P +For each option presented to the +.IR qselect +utility, the utility shall restrict the set of selected batch jobs as +described in the OPTIONS section. +.P +The +.IR qselect +utility shall not restrict selection of batch jobs except by +authorization and as required by the options presented to the utility. +.P +When an option is specified with a mandatory or optional +.IR op +component to the option-argument, then +.IR op +shall specify a relation between the value of a certain batch job +attribute and the +.IR value +component of the option-argument. If an +.IR op +is allowable on an option, then the description of the option letter +indicates the +.IR op +as either mandatory or optional. Acceptable strings for the +.IR op +component, and the relation the string indicates, are shown in the +following list: +.IP "\fR.eq.\fR" 8 +The value represented by the attribute of the batch job is equal to the +value represented by the option-argument. +.IP "\fR.ge.\fR" 8 +The value represented by the attribute of the batch job is greater than +or equal to the value represented by the option-argument. +.IP "\fR.gt.\fR" 8 +The value represented by the attribute of the batch job is greater than +the value represented by the option-argument. +.IP "\fR.lt.\fR" 8 +The value represented by the attribute of the batch job is less than +the value represented by the option-argument. +.IP "\fR.le.\fR" 8 +The value represented by the attribute of the batch job is less than or +equal to the value represented by the option-argument. +.IP "\fR.ne.\fR" 8 +The value represented by the attribute of the batch job is not equal to +the value represented by the option-argument. +.SH OPTIONS +The +.IR qselect +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported by the implementation: +.IP "\fB\(mia\ [\fIop\fB]\fIdate_time\fR" 10 +.br +Restrict selection to a specific time, or a range of times. +.RS 10 +.P +The +.IR qselect +utility shall select only batch jobs for which the value of the +.IR Execution_Time +attribute is related to the Epoch equivalent of the local time +expressed by the value of the +.IR date_time +component of the option-argument in the manner indicated by the value +of the +.IR op +component of the option-argument. +.P +The +.IR qselect +utility shall accept a +.IR date_time +component of the option-argument that conforms to the syntax of the +.IR time +operand of the +.IR touch +utility. +.P +If the +.IR op +component of the option-argument is not presented to the +.IR qselect +utility, the utility shall select batch jobs for which the +.IR Execution_Time +attribute is equal to the +.IR date_time +component of the option-argument. +.P +When comparing times, the +.IR qselect +utility shall use the following definitions for the +.IR op +component of the option-argument: +.IP "\fR.eq.\fR" 8 +The time represented by value of the +.IR Execution_Time +attribute of the batch job is equal to the time represented by the +.IR date_time +component of the option-argument. +.IP "\fR.ge.\fR" 8 +The time represented by value of the +.IR Execution_Time +attribute of the batch job is after or equal to the time represented by +the +.IR date_time +component of the option-argument. +.IP "\fR.gt.\fR" 8 +The time represented by value of the +.IR Execution_Time +attribute of the batch job is after the time represented by the +.IR date_time +component of the option-argument. +.IP "\fR.lt.\fR" 8 +The time represented by value of the +.IR Execution_Time +attribute of the batch job is before the time represented by the +.IR date_time +component of the option-argument. +.IP "\fR.le.\fR" 8 +The time represented by value of the +.IR Execution_Time +attribute of the batch job is before or equal to the time represented +by the +.IR date_time +component of the option-argument. +.IP "\fR.ne.\fR" 8 +The time represented by value of the +.IR Execution_Time +attribute of the batch job is not equal to the time represented by the +.IR date_time +component of the option-argument. +.P +The +.IR qselect +utility shall accept the defined character strings for the +.IR op +component of the option-argument. +.RE +.IP "\fB\(miA\ \fIaccount_string\fR" 10 +.br +Restrict selection to the batch jobs charging a specified account. +.RS 10 +.P +The +.IR qselect +utility shall select only batch jobs for which the value of the +.IR Account_Name +attribute of the batch job matches the value of the +.IR account_string +option-argument. +.P +The syntax of the +.IR account_string +option-argument is unspecified. +.RE +.IP "\fB\(mic\ [\fIop\fB]\fIinterval\fR" 10 +.br +Restrict selection to batch jobs within a range of checkpoint +intervals. +.RS 10 +.P +The +.IR qselect +utility shall select only batch jobs for which the value of the +.IR Checkpoint +attribute relates to the value of the +.IR interval +component of the option-argument in the manner indicated by the value +of the +.IR op +component of the option-argument. +.P +If the +.IR op +component of the option-argument is omitted, the +.IR qselect +utility shall select batch jobs for which the value of the +.IR Checkpoint +attribute is equal to the value of the +.IR interval +component of the option-argument. +.P +When comparing checkpoint intervals, the +.IR qselect +utility shall use the following definitions for the +.IR op +component of the option-argument: +.IP "\fR.eq.\fR" 8 +The value of the +.IR Checkpoint +attribute of the batch job equals the value of the +.IR interval +component of the option-argument. +.IP "\fR.ge.\fR" 8 +The value of the +.IR Checkpoint +attribute of the batch job is greater than or equal to the value of the +.IR interval +component option-argument. +.IP "\fR.gt.\fR" 8 +The value of the +.IR Checkpoint +attribute of the batch job is greater than the value of the +.IR interval +component option-argument. +.IP "\fR.lt.\fR" 8 +The value of the +.IR Checkpoint +attribute of the batch job is less than the value of the +.IR interval +component option-argument. +.IP "\fR.le.\fR" 8 +The value of the +.IR Checkpoint +attribute of the batch job is less than or equal to the value of the +.IR interval +component option-argument. +.IP "\fR.ne.\fR" 8 +The value of the +.IR Checkpoint +attribute of the batch job does not equal the value of the +.IR interval +component option-argument. +.P +The +.IR qselect +utility shall accept the defined character strings for the +.IR op +component of the option-argument. +.P +The ordering relationship for the values of the interval +option-argument is defined to be: +.sp +.RS 4 +.nf +\fB +\&`n' .gt. `s' .gt. `c=\fIminutes\fR' .ge. `c' +.fi \fR +.P +.RE +When comparing +.IR Checkpoint +attributes with an interval having the value of the single character +.BR 'u' , +only equality or inequality are valid comparisons. +.RE +.IP "\fB\(mih\ \fIhold_list\fR" 10 +Restrict selection to batch jobs that have a specific type of hold. +.RS 10 +.P +The +.IR qselect +utility shall select only batch jobs for which the value of the +.IR Hold_Types +attribute matches the value of the +.IR hold_list +option-argument. +.P +The +.IR qselect +.BR \(mih +option shall accept a value for the +.IR hold_list +option-argument that is a string of alphanumeric characters in the +portable character set (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set"). +.P +The +.IR qselect +utility shall accept a value for the +.IR hold_list +option-argument that is a string of one or more of the characters +.BR 'u' , +.BR 's' , +or +.BR 'o' , +or the single character +.BR 'n' . +.P +Each unique character in the +.IR hold_list +option-argument of the +.IR qselect +utility is defined as follows, each representing a different hold type: +.IP "\fRu\fP" 6 +USER +.IP "\fRs\fP" 6 +SYSTEM +.IP "\fRo\fP" 6 +OPERATOR +.P +If any of these characters are duplicated in the +.IR hold_list +option-argument, the duplicates shall be ignored. +.P +The +.IR qselect +utility shall consider it an error if any hold type other than +.BR 'n' +is combined with hold type +.BR 'n' . +.P +Strictly conforming applications shall not repeat any of the characters +.BR 'u' , +.BR 's' , +.BR 'o' , +or +.BR 'n' +within the +.IR hold_list +option-argument. The +.IR qselect +utility shall permit the repetition of characters, but shall not assign +additional meaning to the repeated characters. +.P +An implementation may define other hold types. The conformance document +for an implementation shall describe any additional hold types, how +they are specified, their internal behavior, and how they affect the +behavior of the utility. +.RE +.IP "\fB\(mil\ \fIresource_list\fR" 10 +.br +Restrict selection to batch jobs with specified resource limits and +attributes. +.RS 10 +.P +The +.IR qselect +utility shall accept a +.IR resource_list +option-argument with the following syntax: +.sp +.RS 4 +.nf +\fB +\fIresource_name op value \fB[\fR,,\fIresource_name op value\fR,, ...\fB]\fR +.fi \fR +.P +.RE +.P +When comparing resource values, the +.IR qselect +utility shall use the following definitions for the +.IR op +component of the option-argument: +.IP "\fR.eq.\fR" 8 +The value of the resource of the same name in the +.IR Resource_List +attribute of the batch job equals the value of the value component of +the option-argument. +.IP "\fR.ge.\fR" 8 +The value of the resource of the same name in the +.IR Resource_List +attribute of the batch job is greater than or equal to the value of the +.IR value +component of the option-argument. +.IP "\fR.gt.\fR" 8 +The value of the resource of the same name in the +.IR Resource_List +attribute of the batch job is greater than the value of the value +component of the option-argument. +.IP "\fR.lt.\fR" 8 +The value of the resource of the same name in the +.IR Resource_List +attribute of the batch job is less than the value of the value +component of the option-argument. +.IP "\fR.ne.\fR" 8 +The value of the resource of the same name in the +.IR Resource_List +attribute of the batch job does not equal the value of the value +component of the option-argument. +.IP "\fR.le.\fR" 8 +The value of the resource of the same name in the +.IR Resource_List +attribute of the batch job is less than or equal to the value of the +.IR value +component of the option-argument. +.P +When comparing the limit of a +.IR Resource_List +attribute with the +.IR value +component of the option-argument, if the limit, the value, or both are +non-numeric, only equality or inequality are valid comparisons. +.P +The +.IR qselect +utility shall select only batch jobs for which the values of the +.IR resource_name s +listed in the +.IR resource_list +option-argument match the corresponding limits of the +.IR Resource_List +attribute of the batch job. +.P +Limits of +.IR resource_name s +present in the +.IR Resource_List +attribute of the batch job that have no corresponding values in the +.IR resource_list +option-argument shall not be considered when selecting batch jobs. +.RE +.IP "\fB\(miN\ \fIname\fR" 10 +Restrict selection to batch jobs with a specified name. +.RS 10 +.P +The +.IR qselect +utility shall select only batch jobs for which the value of the +.IR Job_Name +attribute matches the value of the +.IR name +option-argument. The string specified in the +.IR name +option-argument shall be passed, uninterpreted, to the server. This +allows an implementation to match ``wildcard'' patterns against batch +job names. +.P +An implementation shall describe in the conformance document the format +it supports for matching against the +.IR Job_Name +attribute. +.RE +.IP "\fB\(mip\ [\fIop\fB]\fIpriority\fR" 10 +.br +Restrict selection to batch jobs of the specified priority or range of +priorities. +.RS 10 +.P +The +.IR qselect +utility shall select only batch jobs for which the value of the +.IR Priority +attribute of the batch job relates to the value of the +.IR priority +component of the option-argument in the manner indicated by the value +of the +.IR op +component of the option-argument. +.P +If the +.IR op +component of the option-argument is omitted, the +.IR qselect +utility shall select batch jobs for which the value of the +.IR Priority +attribute of the batch job is equal to the value of the +.IR priority +component of the option-argument. +.P +When comparing priority values, the +.IR qselect +utility shall use the following definitions for the +.IR op +component of the option-argument: +.IP "\fR.eq.\fR" 8 +The value of the +.IR Priority +attribute of the batch job equals the value of the +.IR priority +component of the option-argument. +.IP "\fR.ge.\fR" 8 +The value of the +.IR Priority +attribute of the batch job is greater than or equal to the value of the +.IR priority +component option-argument. +.IP "\fR.gt.\fR" 8 +The value of the +.IR Priority +attribute of the batch job is greater than the value of the +.IR priority +component option-argument. +.IP "\fR.lt.\fR" 8 +The value of the +.IR Priority +attribute of the batch job is less than the value of the +.IR priority +component option-argument. +.IP "\fR.lt.\fR" 8 +The value of the +.IR Priority +attribute of the batch job is less than or equal to the value of the +.IR priority +component option-argument. +.IP "\fR.ne.\fR" 8 +The value of the +.IR Priority +attribute of the batch job does not equal the value of the +.IR priority +component option-argument. +.RE +.IP "\fB\(miq\ \fIdestination\fR" 10 +.br +Restrict selection to the specified batch queue or server, or both. +.RS 10 +.P +The +.IR qselect +utility shall select only batch jobs that are located at the +destination indicated by the value of the +.IR destination +option-argument. +.P +The destination defines a batch queue, a server, or a batch queue at a +server. +.P +The +.IR qselect +utility shall accept an option-argument for the +.BR \(miq +option that conforms to the syntax for a destination. If the +.BR \(miq +option is not presented to the +.IR qselect +utility, the utility shall select batch jobs from all batch queues at +the default batch server. +.P +If the option-argument describes only a batch queue, the +.IR qselect +utility shall select only batch jobs from the batch queue of the +specified name at the default batch server. The means by which +.IR qselect +determines the default server is implementation-defined. +.P +If the option-argument describes only a batch server, the +.IR qselect +utility shall select batch jobs from all the batch queues at that batch +server. +.P +If the option-argument describes both a batch queue and a batch server, +the +.IR qselect +utility shall select only batch jobs from the specified batch queue at +the specified server. +.RE +.IP "\fB\(mir\ \fRy\fR|\fRn\fR" 10 +Restrict selection to batch jobs with the specified rerunability +status. +.RS 10 +.P +The +.IR qselect +utility shall select only batch jobs for which the value of the +.IR Rerunable +attribute of the batch job matches the value of the option-argument. +.P +The +.IR qselect +utility shall accept a value for the option-argument that consists of +either the single character +.BR 'y' +or the single character +.BR 'n' . +The character +.BR 'y' +represents the value TRUE, and the character +.BR 'n' +represents the value FALSE. +.RE +.IP "\fB\(mis\ \fIstates\fR" 10 +Restrict selection to batch jobs in the specified states. +.RS 10 +.P +The +.IR qselect +utility shall accept an option-argument that consists of any +combination of the characters +.BR 'e' , +.BR 'q' , +.BR 'r' , +.BR 'w' , +.BR 'h' , +and +.BR 't' . +.P +Conforming applications shall not repeat any character in the +option-argument. The +.IR qselect +utility shall permit the repetition of characters in the +option-argument, but shall not assign additional meaning to repeated +characters. +.P +The +.IR qselect +utility shall interpret the characters in the +.IR states +option-argument as follows: +.IP "\fRe\fR" 6 +Represents the EXITING state. +.IP "\fRq\fR" 6 +Represents the QUEUED state. +.IP "\fRr\fR" 6 +Represents the RUNNING state. +.IP "\fRt\fR" 6 +Represents the TRANSITING state. +.IP "\fRh\fR" 6 +Represents the HELD state. +.IP "\fRw\fR" 6 +Represents the WAITING state. +.P +For each character in the +.IR states +option-argument, the +.IR qselect +utility shall select batch jobs in the corresponding state. +.RE +.IP "\fB\(miu\ \fIuser_list\fR" 10 +Restrict selection to batch jobs owned by the specified user names. +.RS 10 +.P +The +.IR qselect +utility shall select only the batch jobs of those users specified in +the +.IR user_list +option-argument. +.P +The +.IR qselect +utility shall accept a +.IR user_list +option-argument that conforms to the following syntax: +.sp +.RS 4 +.nf +\fB +\fIusername\fB[\fR@\fIhost\fB][\fR,,\fIusername\fB[\fR@\fIhost\fB]\fR,, ...\fB]\fR +.fi \fR +.P +.RE +.P +The +.IR qselect +utility shall accept only one user name that is missing a corresponding +host name. The +.IR qselect +utility shall accept only one user name per named host. +.RE +.SH OPERANDS +None. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR qselect : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILOGNAME\fP" 10 +Determine the login name of the user. +.IP "\fITZ\fP" 10 +Determine the timezone used to interpret the +.IR date-time +option-argument. If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR qselect +utility shall write zero or more batch +.IR job_identifier s +to standard output. +.P +The +.IR qselect +utility shall separate the batch +.IR job_identifier s +written to standard output by white space. +.P +The +.IR qselect +utility shall write batch +.IR job_identifier s +in the following format: +.sp +.RS 4 +.nf +\fB +\fIsequence_number.server_name\fR@\fIserver\fR +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +The following example shows how a user might use the +.IR qselect +utility in conjunction with the +.IR qdel +utility to delete all of his or her jobs in the queued state without +affecting any jobs that are already running: +.sp +.RS 4 +.nf +\fB +qdel $(qselect \(mis q) +.fi \fR +.P +.RE +.P +or: +.sp +.RS 4 +.nf +\fB +qselect \(mis q || xargs qdel +.fi \fR +.P +.RE +.SH RATIONALE +The +.IR qselect +utility allows users to acquire a list of job identifiers that match +user-specified selection criteria. The list of identifiers returned by +the +.IR qselect +utility conforms to the syntax of the batch job identifier list +processed by a utility such as +.IR qmove , +.IR qdel , +and +.IR qrls . +The +.IR qselect +utility is thus a powerful tool for causing another batch system +utility to act upon a set of jobs that match a list of selection +criteria. +.P +The options of the +.IR qselect +utility let the user apply a number of useful filters for selecting +jobs. Each option further restricts the selection of jobs. Many of the +selection options allow the specification of a relational operator. The +FORTRAN-like syntax of the operator\(emthat is, +.BR \(dq.lt.\(dq \(em\c +was chosen rather than the C-like +.BR \(dq<=\(dq +meta-characters. +.P +The +.BR \(mia +option allows users to restrict the selected jobs to those that have +been submitted (or altered) to wait until a particular time. The time +period is determined by the argument of this option, which includes +both a time and an operator\(emit is thus possible to select jobs +waiting until a specific time, jobs waiting until after a certain time, +or those waiting for a time before the specified time. +.P +The +.BR \(miA +option allows users to restrict the selected jobs to those that have +been submitted (or altered) to charge a particular account. +.P +The +.BR \(mic +option allows users to restrict the selected jobs to those whose +checkpointing interval falls within the specified range. +.P +The +.BR \(mil +option allows users to select those jobs whose resource limits fall +within the range indicated by the value of the option. For example, a +user could select those jobs for which the CPU time limit is greater +than two hours. +.P +The +.BR \(miN +option allows users to select jobs by job name. For instance, all the +parts of a task that have been divided in parallel jobs might be given +the same name, and thus manipulated as a group by means of this +option. +.P +The +.BR \(miq +option allows users to select jobs in a specified queue. +.P +The +.BR \(mir +option allows users to select only those jobs with a specified rerun +criteria. For instance, a user might select only those jobs that can be +rerun for use with the +.IR qrerun +utility. +.P +The +.BR \(mis +option allows users to select only those jobs that are in a certain +state. +.P +The +.BR \(miu +option allows users to select jobs that have been submitted to execute +under a particular account. +.P +The selection criteria provided by the options of the +.IR qselect +utility allow users to select jobs based on all the appropriate +attributes that can be assigned to jobs by the +.IR qsub +utility. +.P +Historically, the +.IR qselect +utility has not been a part of existing practice; it is an improvement +that has been introduced in this volume of POSIX.1\(hy2008. +.SH "FUTURE DIRECTIONS" +The +.IR qselect +utility may be removed in a future version. +.SH "SEE ALSO" +.IR "Chapter 3" ", " "Batch Environment Services", +.IR "\fIqdel\fR\^", +.IR "\fIqrerun\fR\^", +.IR "\fIqrls\fR\^", +.IR "\fIqselect\fR\^", +.IR "\fIqsub\fR\^", +.IR "\fItouch\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/qsig.1p b/man-pages-posix-2013/man1p/qsig.1p new file mode 100644 index 0000000..e4e77f0 --- /dev/null +++ b/man-pages-posix-2013/man1p/qsig.1p @@ -0,0 +1,235 @@ +'\" et +.TH QSIG "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +qsig +\(em signal batch jobs +.SH SYNOPSIS +.LP +.nf +qsig \fB[\fR\(mis \fIsignal\fB] \fIjob_identifier\fR... +.fi +.SH DESCRIPTION +To signal a batch job is to send a signal to the session leader of the +batch job. A batch job is signaled by sending a request to the batch +server that manages the batch job. The +.IR qsig +utility is a user-accessible batch client that requests the signaling +of a batch job. +.P +The +.IR qsig +utility shall signal those batch jobs for which a batch +.IR job_identifier +is presented to the utility. The +.IR qsig +utility shall not signal any batch jobs whose batch +.IR job_identifier s +are not presented to the utility. +.P +The +.IR qsig +utility shall signal batch jobs in the order in which the corresponding +batch +.IR job_identifier s +are presented to the utility. If the +.IR qsig +utility fails to process a batch +.IR job_identifier +successfully, the utility shall proceed to process the remaining batch +.IR job_identifier s, +if any. +.P +The +.IR qsig +utility shall signal batch jobs by sending a +.IR "Signal Job Request" +to the batch server that manages the batch job. +.P +For each successfully processed batch +.IR job_identifier , +the +.IR qsig +utility shall have received a completion reply to each +.IR "Signal Job Request" +sent to a batch server at the time the utility exits. +.SH OPTIONS +The +.IR qsig +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported by the implementation: +.IP "\fB\(mis\ \fIsignal\fR" 10 +Define the signal to be sent to the batch job. +.RS 10 +.P +The +.IR qsig +utility shall accept a +.IR signal +option-argument that is either a symbolic signal name or an unsigned +integer signal number (see the POSIX.1\(hy1990 standard, Section 3.3.1.1). The +.IR qsig +utility shall accept signal names for which the SIG prefix has been +omitted. +.P +If the +.IR signal +option-argument is a signal name, the +.IR qsig +utility shall send that name. +.P +If the +.IR signal +option-argument is a number, the +.IR qsig +utility shall send the signal value represented by the number. +.P +If the +.BR \(mis +option is not presented to the +.IR qsig +utility, the utility shall send the signal SIGTERM to each signaled +batch job. +.RE +.SH OPERANDS +The +.IR qsig +utility shall accept one or more operands that conform to the syntax +for a batch +.IR job_identifier +(see +.IR "Section 3.3.1" ", " "Batch Job Identifier"). +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR qsig : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILOGNAME\fP" 10 +Determine the login name of the user. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +An implementation of the +.IR qsig +utility may write informative messages to standard output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +In addition to the default behavior, the +.IR qsig +utility shall not be required to write a diagnostic message to standard +error when the error reply received from a batch server indicates that +the batch +.IR job_identifier +does not exist on the server. Whether or not the +.IR qsig +utility waits to output the diagnostic message while attempting to +locate the batch job on other servers is implementation-defined. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR qsig +utility allows users to signal batch jobs. +.P +A user may be unable to signal a batch job with the +.IR kill +utility of the operating system for a number of reasons. First, the +process ID of the batch job may be unknown to the user. Second, the +processes of the batch job may be on a remote node. However, by virtue +of communication between batch nodes, the +.IR qsig +utility can arrange for the signaling of a process. +.P +Because a batch job that is not running cannot be signaled, and because +the signal may not terminate the batch job, the +.IR qsig +utility is not a substitute for the +.IR qdel +utility. +.P +The options of the +.IR qsig +utility allow the user to specify the signal that is to be sent to the +batch job. +.P +The +.BR \(mis +option allows users to specify a signal by name or by number, and thus +override the default signal. The POSIX.1\(hy1990 standard defines signals by both name and +number. +.P +The +.IR qsig +utility is a new utility, \fIvis-a-vis\fP existing practice; it has +been defined in this volume of POSIX.1\(hy2008 in response to user-perceived shortcomings in +existing practice. +.SH "FUTURE DIRECTIONS" +The +.IR qsig +utility may be removed in a future version. +.SH "SEE ALSO" +.IR "Chapter 3" ", " "Batch Environment Services", +.IR "\fIkill\fR\^", +.IR "\fIqdel\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/qstat.1p b/man-pages-posix-2013/man1p/qstat.1p new file mode 100644 index 0000000..be3a39e --- /dev/null +++ b/man-pages-posix-2013/man1p/qstat.1p @@ -0,0 +1,404 @@ +'\" et +.TH QSTAT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +qstat +\(em show status of batch jobs +.SH SYNOPSIS +.LP +.nf +qstat \fB[\fR\(mif\fB] \fIjob_identifier\fR... +.P +qstat \(miQ \fB[\fR\(mif\fB] \fIdestination\fR... +.P +qstat \(miB \fB[\fR\(mif\fB] \fIserver_name\fR... +.fi +.SH DESCRIPTION +The status of a batch job, batch queue, or batch server is obtained by +a request to the server. The +.IR qstat +utility is a user-accessible batch client that requests the status of +one or more batch jobs, batch queues, or servers, and writes the status +information to standard output. +.P +For each successfully processed batch +.IR job_identifier , +the +.IR qstat +utility shall display information about the corresponding batch job. +.P +For each successfully processed destination, the +.IR qstat +utility shall display information about the corresponding batch queue. +.P +For each successfully processed server name, the +.IR qstat +utility shall display information about the corresponding server. +.P +The +.IR qstat +utility shall acquire batch job status information by sending a +.IR "Job Status Request" +to a batch server. The +.IR qstat +utility shall acquire batch queue status information by sending a +.IR "Queue Status Request" +to a batch server. The +.IR qstat +utility shall acquire server status information by sending a +.IR "Server Status Request" +to a batch server. +.SH OPTIONS +The +.IR qstat +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported by the implementation: +.IP "\fB\(mif\fR" 10 +Specify that a full display is produced. +.RS 10 +.P +The minimum contents of a full display are specified in the STDOUT +section. +.P +Additional contents and format of a full display are +implementation-defined. +.RE +.IP "\fB\(miQ\fR" 10 +Specify that the operand is a destination. +.RS 10 +.P +The +.IR qstat +utility shall display information about each batch queue at each +destination identified as an operand. +.RE +.IP "\fB\(miB\fR" 10 +Specify that the operand is a server name. +.RS 10 +.P +The +.IR qstat +utility shall display information about each server identified as an +operand. +.RE +.SH OPERANDS +If the +.BR \(miQ +option is presented to the +.IR qstat +utility, the utility shall accept one or more operands that conform to +the syntax for a destination (see +.IR "Section 3.3.2" ", " "Destination"). +.P +If the +.BR \(miB +option is presented to the +.IR qstat +utility, the utility shall accept one or more +.IR server_name +operands. +.P +If neither the +.BR \(miB +nor the +.BR \(miQ +option is presented to the +.IR qstat +utility, the utility shall accept one or more operands that conform to +the syntax for a batch +.IR job_identifier +(see +.IR "Section 3.3.1" ", " "Batch Job Identifier"). +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR qstat : +.IP "\fIHOME\fP" 10 +Determine the pathname of the user's home directory. +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular expressions. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILC_NUMERIC\fP" 10 +.br +Determine the locale for selecting the radix character used when +writing floating-point formatted output. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If an operand presented to the +.IR qstat +utility is a batch +.IR job_identifier +and the +.BR \(mif +option is not specified, the +.IR qstat +utility shall display the following items on a single line, in the +stated order, with white space between each item, for each successfully +processed operand: +.IP " *" 4 +The batch +.IR job_identifier +.IP " *" 4 +The batch job name +.IP " *" 4 +The +.IR Job_Owner +attribute +.IP " *" 4 +The CPU time used by the batch job +.IP " *" 4 +The batch job state +.IP " *" 4 +The batch job location +.P +If an operand presented to the +.IR qstat +utility is a batch +.IR job_identifier +and the +.BR \(mif +option is specified, the +.IR qstat +utility shall display the following items for each success fully +processed operand: +.IP " *" 4 +The batch +.IR job_identifier +.IP " *" 4 +The batch job name +.IP " *" 4 +The +.IR Job_Owner +attribute +.IP " *" 4 +The execution user ID +.IP " *" 4 +The CPU time used by the batch job +.IP " *" 4 +The batch job state +.IP " *" 4 +The batch job location +.IP " *" 4 +Additional implementation-defined information, if any, about the +batch job or batch queue +.P +If an operand presented to the +.IR qstat +utility is a destination, the +.BR \(miQ +option is specified, and the +.BR \(mif +option is not specified, the +.IR qstat +utility shall display the following items on a single line, in the +stated order, with white space between each item, for each successfully +processed operand: +.IP " *" 4 +The batch queue name +.IP " *" 4 +The maximum number of batch jobs that shall be run in the batch +queue concurrently +.IP " *" 4 +The total number of batch jobs in the batch queue +.IP " *" 4 +The status of the batch queue +.IP " *" 4 +For each state, the number of batch jobs in that state in the batch +queue and the name of the state +.IP " *" 4 +The type of batch queue (execution or routing) +.P +If the operands presented to the +.IR qstat +utility are destinations, the +.BR \(miQ +option is specified, and the +.BR \(mif +option is specified, the +.IR qstat +utility shall display the following items for each successfully +processed operand: +.IP " *" 4 +The batch queue name +.IP " *" 4 +The maximum number of batch jobs that shall be run in the batch +queue concurrently +.IP " *" 4 +The total number of batch jobs in the batch queue +.IP " *" 4 +The status of the batch queue +.IP " *" 4 +For each state, the number of batch jobs in that state in the batch +queue and the name of the state +.IP " *" 4 +The type of batch queue (execution or routing) +.IP " *" 4 +Additional implementation-defined information, if any, about +the batch queue +.P +If the operands presented to the +.IR qstat +utility are batch server names, the +.BR \(miB +option is specified, and the +.BR \(mif +option is not specified, the +.IR qstat +utility shall display the following items on a single line, in the +stated order, with white space between each item, for each successfully +processed operand: +.IP " *" 4 +The batch server name +.IP " *" 4 +The maximum number of batch jobs that shall be run in the batch +queue concurrently +.IP " *" 4 +The total number of batch jobs managed by the batch server +.IP " *" 4 +The status of the batch server +.IP " *" 4 +For each state, the number of batch jobs in that state and the name of +the state +.P +If the operands presented to the +.IR qstat +utility are server names, the +.BR \(miB +option is specified, and the +.BR \(mif +option is specified, the +.IR qstat +utility shall display the following items for each successfully +processed operand: +.IP " *" 4 +The server name +.IP " *" 4 +The maximum number of batch jobs that shall be run in the batch +queue concurrently +.IP " *" 4 +The total number of batch jobs managed by the server +.IP " *" 4 +The status of the server +.IP " *" 4 +For each state, the number of batch jobs in that state and the name of +the state +.IP " *" 4 +Additional implementation-defined information, if any, about the server +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +In addition to the default behavior, the +.IR qstat +utility shall not be required to write a diagnostic message to standard +error when the error reply received from a batch server indicates that +the batch +.IR job_identifier +does not exist on the server. Whether or not the +.IR qstat +utility waits to output the diagnostic message while attempting to +locate the batch job on other servers is implementation-defined. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR qstat +utility allows users to display the status of jobs and list the +batch jobs in queues. +.P +The operands of the +.IR qstat +utility may be either job identifiers, queues (specified as destination +identifiers), or batch server names. The +.BR \(miQ +and +.BR \(miB +options, or absence thereof, indicate the nature of the operands. +.P +The other options of the +.IR qstat +utility allow the user to control the amount of information displayed +and the format in which it is displayed. Should a user wish to display +the status of a set of jobs that match a selection criteria, the +.IR qselect +utility may be used to acquire such a list. +.P +The +.BR \(mif +option allows users to request a ``full'' display in an +implementation-defined format. +.P +Historically, the +.IR qstat +utility has been a part of the NQS and its derivatives, the existing +practice on which it is based. +.SH "FUTURE DIRECTIONS" +The +.IR qstat +utility may be removed in a future version. +.SH "SEE ALSO" +.IR "Chapter 3" ", " "Batch Environment Services", +.IR "\fIqselect\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/qsub.1p b/man-pages-posix-2013/man1p/qsub.1p new file mode 100644 index 0000000..daa7898 --- /dev/null +++ b/man-pages-posix-2013/man1p/qsub.1p @@ -0,0 +1,1472 @@ +'\" et +.TH QSUB "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +qsub +\(em submit a script +.SH SYNOPSIS +.LP +.nf +qsub \fB[\fR\(mia \fIdate_time\fB] [\fR\(miA \fIaccount_string\fB] [\fR\(mic \fIinterval\fB] + [\fR\(miC \fIdirective_prefix\fB] [\fR\(mie \fIpath_name\fB] [\fR\(mih\fB] [\fR\(mij \fIjoin_list\fB] + [\fR\(mik \fIkeep_list\fB] [\fR\(mim \fImail_options\fB] [\fR\(miM \fImail_list\fB] [\fR\(miN \fIname\fB] + [\fR\(mio \fIpath_name\fB] [\fR\(mip \fIpriority\fB] [\fR\(miq \fIdestination\fB] [\fR\(mir \fIy\fR|\fIn\fB] + [\fR\(miS \fIpath_name_list\fB] [\fR\(miu \fIuser_list\fB] [\fR\(miv \fIvariable_list\fB] [\fR\(miV\fB] + [\fR\(miz\fB] [\fIscript\fB]\fR +.fi +.SH DESCRIPTION +To submit a script is to create a batch job that executes the script. A +script is submitted by a request to a batch server. The +.IR qsub +utility is a user-accessible batch client that submits a script. +.P +Upon successful completion, the +.IR qsub +utility shall have created a batch job that will execute the submitted +script. +.P +The +.IR qsub +utility shall submit a script by sending a +.IR "Queue Job Request" +to a batch server. +.P +The +.IR qsub +utility shall place the value of the following environment variables in +the +.IR Variable_List +attribute of the batch job: +.IR HOME , +.IR LANG , +.IR LOGNAME , +.IR PATH , +.IR MAIL , +.IR SHELL , +and +.IR TZ . +The name of the environment variable shall be the current name prefixed +with the string PBS_O_. +.TP 10 +.BR Note: +If the current value of the +.IR HOME +variable in the environment space of the +.IR qsub +utility is +.BR /aa/bb/cc , +then +.IR qsub +shall place +.IR PBS_O_HOME =\c +.BR /aa/bb/cc +in the +.IR Variable_List +attribute of the batch job. +.P +.P +In addition to the variables described above, the +.IR qsub +utility shall add the following variables with the indicated values to +the variable list: +.IP "\fIPBS_O_WORKDIR\fP" 14 +The absolute path of the current working directory of the +.IR qsub +utility process. +.IP "\fIPBS_O_HOST\fP" 14 +The name of the host on which the +.IR qsub +utility is running. +.SH OPTIONS +The +.IR qsub +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported by the implementation: +.IP "\fB\(mia\ \fIdate_time\fR" 10 +Define the time at which a batch job becomes eligible for execution. +.RS 10 +.P +The +.IR qsub +utility shall accept an option-argument that conforms to the syntax of +the +.IR time +operand of the +.IR touch +utility. +.br +.sp +.ce 1 +\fBTable 4-19: Environment Variable Values (Utilities)\fR +.TS +center box tab(!); +cB | cB +lI | lI. +Variable Name!Value at qsub Time +_ +PBS_O_HOME!HOME +PBS_O_HOST!\fRClient host name\fP +PBS_O_LANG!LANG +PBS_O_LOGNAME!LOGNAME +PBS_O_PATH!PATH +PBS_O_MAIL!MAIL +PBS_O_SHELL!SHELL +PBS_O_TZ!TZ +PBS_O_WORKDIR!\fRCurrent working directory\fP +.TE +.TP 10 +.BR Note: +The server that initiates execution of the batch job will add other +variables to the batch job's environment; see +.IR "Section 3.2.2.1" ", " "Batch Job Execution". +.P +.P +The +.IR qsub +utility shall set the +.IR Execution_Time +attribute of the batch job to the number of seconds since the Epoch +that is equivalent to the local time expressed by the value of the +.IR date_time +option-argument. The Epoch is defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.150" ", " "Epoch". +.P +If the +.BR \(mia +option is not presented to the +.IR qsub +utility, the utility shall set the +.IR Execution_Time +attribute of the batch job to a time (number of seconds since the +Epoch) that is earlier than the time at which the utility exits. +.RE +.IP "\fB\(miA\ \fIaccount_string\fR" 10 +.br +Define the account to which the resource consumption of the batch job +should be charged. +.RS 10 +.P +The syntax of the +.IR account_string +option-argument is unspecified. +.P +The +.IR qsub +utility shall set the +.IR Account_Name +attribute of the batch job to the value of the +.IR account_string +option-argument. +.P +If the +.BR \(miA +option is not presented to the +.IR qsub +utility, the utility shall omit the +.IR Account_Name +attribute from the attributes of the batch job. +.RE +.IP "\fB\(mic\ \fIinterval\fR" 10 +Define whether the batch job should be checkpointed, and if so, how +often. +.RS 10 +.P +The +.IR qsub +utility shall accept a value for the interval option-argument that is +one of the following: +.IP "\fRn\fR" 10 +No checkpointing shall be performed on the batch job +(NO_CHECKPOINT). +.IP "\fRs\fR" 10 +Checkpointing shall be performed only when the batch server is shut +down (CHECKPOINT_AT_SHUTDOWN). +.IP "\fRc\fR" 10 +Automatic periodic checkpointing shall be performed at the +.IR Minimum_Cpu_Interval +attribute of the batch queue, in units of CPU minutes +(CHECKPOINT_AT_MIN_CPU_INTERVAL). +.IP "\fRc\fR=\fIminutes\fR" 10 +Automatic periodic checkpointing shall be performed every +.IR minutes +of CPU time, or every +.IR Minimum_Cpu_Interval +minutes, whichever is greater. The +.IR minutes +argument shall conform to the syntax for unsigned integers and shall be +greater than zero. +.P +The +.IR qsub +utility shall set the +.IR Checkpoint +attribute of the batch job to the value of the +.IR interval +option-argument. +.P +If the +.BR \(mic +option is not presented to the +.IR qsub +utility, the utility shall set the +.IR Checkpoint +attribute of the batch job to the single character +.BR 'u' +(CHECKPOINT_UNSPECIFIED). +.RE +.IP "\fB\(miC\ \fIdirective_prefix\fR" 10 +.br +Define the prefix that declares a directive to the +.IR qsub +utility within the script. +.RS 10 +.P +The +.IR directive_prefix +is not a batch job attribute; it affects the behavior of the +.IR qsub +utility. +.P +If the +.BR \(miC +option is presented to the +.IR qsub +utility, and the value of the +.IR directive_prefix +option-argument is the null string, the utility shall not scan the +script file for directives. If the +.BR \(miC +option is not presented to the +.IR qsub +utility, then the value of the +.IR PBS_DPREFIX +environment variable is used. If the environment variable is not +defined, then #PBS encoded in the portable character set is the +default. +.RE +.IP "\fB\(mie\ \fIpath_name\fR" 10 +.br +Define the path to be used for the standard error stream of the batch +job. +.RS 10 +.P +The +.IR qsub +utility shall accept a +.IR path_name +option-argument which can be preceded by a host name element of the +form +.IR hostname :. +.P +If the +.IR path_name +option-argument constitutes an absolute pathname, the +.IR qsub +utility shall set the +.IR Error_Path +attribute of the batch job to the value of the +.IR path_name +option-argument. +.P +If the +.IR path_name +option-argument constitutes a relative pathname and no host name +element is specified, the +.IR qsub +utility shall set the +.IR Error_Path +attribute of the batch job to the value of the absolute pathname +derived by expanding the +.IR path_name +option-argument relative to the current directory of the process +executing +.IR qsub . +.P +If the +.IR path_name +option-argument constitutes a relative pathname and a host name +element is specified, the +.IR qsub +utility shall set the +.IR Error_Path +attribute of the batch job to the value of the +.IR path_name +option-argument without expansion. The host name element shall be +included. +.P +If the +.IR path_name +option-argument does not include a host name element, the +.IR qsub +utility shall prefix the pathname with +.IR hostname :, +where +.IR hostname +is the name of the host upon which the +.IR qsub +utility is being executed. +.P +If the +.BR \(mie +option is not presented to the +.IR qsub +utility, the utility shall set the +.IR Error_Path +attribute of the batch job to the host name and path of the current +directory of the submitting process and the default filename. +.P +The default filename for standard error has the following format: +.sp +.RS 4 +.nf +\fB +\fIjob_name\fR.e\fIsequence_number\fR +.fi \fR +.P +.RE +.RE +.IP "\fB\(mih\fR" 10 +Specify that a USER hold is applied to the batch job. +.RS 10 +.P +The +.IR qsub +utility shall set the value of the +.IR Hold_Types +attribute of the batch job to the value USER. +.P +If the +.BR \(mih +option is not presented to the +.IR qsub +utility, the utility shall set the +.IR Hold_Types +attribute of the batch job to the value NO_HOLD. +.RE +.IP "\fB\(mij\ \fIjoin_list\fR" 10 +Define which streams of the batch job are to be merged. The +.IR qsub +.BR \(mij +option shall accept a value for the +.IR join_list +option-argument that is a string of alphanumeric characters in the +portable character set (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set"). +.RS 10 +.P +The +.IR qsub +utility shall accept a +.IR join_list +option-argument that consists of one or more of the characters +.BR 'e' +and +.BR 'o' , +or the single character +.BR 'n' . +.P +All of the other batch job output streams specified will be merged into +the output stream represented by the character listed first in the +.IR join_list +option-argument. +.P +For each unique character in the +.IR join_list +option-argument, the +.IR qsub +utility shall add a value to the +.IR Join_Path +attribute of the batch job as follows, each representing a different +batch job stream to join: +.IP "\fRe\fR" 6 +The standard error of the batch job (JOIN_STD_ERROR). +.IP "\fRo\fR" 6 +The standard output of the batch job (JOIN_STD_OUTPUT). +.P +An existing +.IR Join_Path +attribute can be cleared by the following join type: +.IP "\fRn\fR" 6 +NO_JOIN +.P +If +.BR 'n' +is specified, then no files are joined. The +.IR qsub +utility shall consider it an error if any join type other than +.BR 'n' +is combined with join type +.BR 'n' . +.P +Strictly conforming applications shall not repeat any of the characters +.BR 'e' , +.BR 'o' , +or +.BR 'n' +within the +.IR join_list +option-argument. The +.IR qsub +utility shall permit the repetition of characters, but shall not assign +additional meaning to the repeated characters. +.P +An implementation may define other join types. The conformance document +for an implementation shall describe any additional batch job streams, +how they are specified, their internal behavior, and how they affect +the behavior of the utility. +.P +If the +.BR \(mij +option is not presented to the +.IR qsub +utility, the utility shall set the value of the +.IR Join_Path +attribute of the batch job to NO_JOIN. +.RE +.IP "\fB\(mik\ \fIkeep_list\fR" 10 +Define which output of the batch job to retain on the execution host. +.RS 10 +.P +The +.IR qsub +.BR \(mik +option shall accept a value for the +.IR keep_list +option-argument that is a string of alphanumeric characters in the +portable character set (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set"). +.P +The +.IR qsub +utility shall accept a +.IR keep_list +option-argument that consists of one or more of the characters +.BR 'e' +and +.BR 'o' , +or the single character +.BR 'n' . +.P +For each unique character in the +.IR keep_list +option-argument, the +.IR qsub +utility shall add a value to the +.IR Keep_Files +attribute of the batch job as follows, each representing a different +batch job stream to keep: +.IP "\fRe\fR" 6 +The standard error of the batch job (KEEP_STD_ERROR). +.IP "\fRo\fR" 6 +The standard output of the batch job (KEEP_STD_OUTPUT). +.P +If both +.BR 'e' +and +.BR 'o' +are specified, then both files are retained. An existing +.IR Keep_Files +attribute can be cleared by the following keep type: +.IP "\fRn\fR" 6 +NO_KEEP +.P +If +.BR 'n' +is specified, then no files are retained. The +.IR qsub +utility shall consider it an error if any keep type other than +.BR 'n' +is combined with keep type +.BR 'n' . +.P +Strictly conforming applications shall not repeat any of the characters +.BR 'e' , +.BR 'o' , +or +.BR 'n' +within the +.IR keep_list +option-argument. The +.IR qsub +utility shall permit the repetition of characters, but shall not assign +additional meaning to the repeated characters. +.P +An implementation may define other keep types. The conformance document +for an implementation shall describe any additional keep types, how +they are specified, their internal behavior, and how they affect the +behavior of the utility. If the +.BR \(mik +option is not presented to the +.IR qsub +utility, the utility shall set the +.IR Keep_Files +attribute of the batch job to the value NO_KEEP. +.RE +.IP "\fB\(mim\ \fImail_options\fR" 10 +.br +Define the points in the execution of the batch job at which the batch +server that manages the batch job shall send mail about a change in the +state of the batch job. +.RS 10 +.P +The +.IR qsub +.BR \(mim +option shall accept a value for the +.IR mail_options +option-argument that is a string of alphanumeric characters in the +portable character set (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set"). +.P +The +.IR qsub +utility shall accept a value for the +.IR mail_options +option-argument that is a string of one or more of the characters +.BR 'e' , +.BR 'b' , +and +.BR 'a' , +or the single character +.BR 'n' . +.P +For each unique character in the +.IR mail_options +option-argument, the +.IR qsub +utility shall add a value to the +.IR Mail_Users +attribute of the batch job as follows, each representing a different +time during the life of a batch job at which to send mail: +.IP "\fRe\fR" 6 +MAIL_AT_EXIT +.IP "\fRb\fR" 6 +MAIL_AT_BEGINNING +.IP "\fRa\fR" 6 +MAIL_AT_ABORT +.P +If any of these characters are duplicated in the +.IR mail_options +option-argument, the duplicates shall be ignored. +.P +An existing +.IR Mail_Points +attribute can be cleared by the following mail type: +.IP "\fRn\fR" 6 +NO_MAIL +.P +If +.BR 'n' +is specified, then mail is not sent. The +.IR qsub +utility shall consider it an error if any mail type other than +.BR 'n' +is combined with mail type +.BR 'n' . +.P +Strictly conforming applications shall not repeat any of the characters +.BR 'e' , +.BR 'b' , +.BR 'a' , +or +.BR 'n' +within the +.IR mail_options +option-argument. +.P +The +.IR qsub +utility shall permit the repetition of characters, but shall not assign +additional meaning to the repeated characters. An implementation may +define other mail types. The conformance document for an implementation +shall describe any additional mail types, how they are specified, their +internal behavior, and how they affect the behavior of the utility. +.P +If the +.BR \(mim +option is not presented to the +.IR qsub +utility, the utility shall set the +.IR Mail_Points +attribute to the value MAIL_AT_ABORT. +.RE +.IP "\fB\(miM\ \fImail_list\fR" 10 +Define the list of users to which a batch server that executes the +batch job shall send mail, if the server sends mail about the batch +job. +.RS 10 +.P +The syntax of the +.IR mail_list +option-argument is unspecified. +.P +If the implementation of the +.IR qsub +utility uses a name service to locate users, the utility should accept +the syntax used by the name service. +.P +If the implementation of the +.IR qsub +utility does not use a name service to locate users, the implementation +should accept the following syntax for user names: +.sp +.RS 4 +.nf +\fB +\fImail_address\fB[\fR,,\fImail_address\fR,, ...\fB]\fR +.fi \fR +.P +.RE +.P +The interpretation of +.IR mail_address +is implementation-defined. +.P +The +.IR qsub +utility shall set the +.IR Mail_Users +attribute of the batch job to the value of the +.IR mail_list +option-argument. +.P +If the +.BR \(miM +option is not presented to the +.IR qsub +utility, the utility shall place only the user name and host name for +the current process in the +.IR Mail_Users +attribute of the batch job. +.RE +.IP "\fB\(miN\ \fIname\fR" 10 +Define the name of the batch job. +.RS 10 +.P +The +.IR qsub +.BR \(miN +option shall accept a value for the +.IR name +option-argument that is a string of up to 15 alphanumeric characters in +the portable character set (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 6.1" ", " "Portable Character Set") +where the first character is alphabetic. +.P +The +.IR qsub +utility shall set the value of the +.IR Job_Name +attribute of the batch job to the value of the +.IR name +option-argument. +.P +If the +.BR \(miN +option is not presented to the +.IR qsub +utility, the utility shall set the +.IR Job_Name +attribute of the batch job to the name of the +.IR script +argument from which the directory specification if any, has been +removed. +.P +If the +.BR \(miN +option is not presented to the +.IR qsub +utility, and the script is read from standard input, the utility shall +set the +.IR Job_Name +attribute of the batch job to the value STDIN. +.RE +.IP "\fB\(mio\ \fIpath_name\fR" 10 +.br +Define the path for the standard output of the batch job. +.RS 10 +.P +The +.IR qsub +utility shall accept a +.IR path_name +option-argument that conforms to the syntax of the +.IR path_name +element defined in the System Interfaces volume of POSIX.1\(hy2008, which can be preceded by a host name +element of the form +.IR hostname :. +.P +If the +.IR path_name +option-argument constitutes an absolute pathname, the +.IR qsub +utility shall set the +.IR Output_Path +attribute of the batch job to the value of the +.IR path_name +option-argument without expansion. +.P +If the +.IR path_name +option-argument constitutes a relative pathname and no host name +element is specified, the +.IR qsub +utility shall set the +.IR Output_Path +attribute of the batch job to the pathname derived by expanding the +value of the +.IR path_name +option-argument relative to the current directory of the process +executing the +.IR qsub . +.P +If the +.IR path_name +option-argument constitutes a relative pathname and a host name +element is specified, the +.IR qsub +utility shall set the +.IR Output_Path +attribute of the batch job to the value of the +.IR path_name +option-argument without expansion. +.P +If the +.IR path_name +option-argument does not specify a host name element, the +.IR qsub +utility shall prefix the pathname with +.IR hostname :, +where +.IR hostname +is the name of the host upon which the +.IR qsub +utility is executing. +.P +If the +.BR \(mio +option is not presented to the +.IR qsub +utility, the utility shall set the +.IR Output_Path +attribute of the batch job to the host name and path of the current +directory of the submitting process and the default filename. +.P +The default filename for standard output has the following format: +.sp +.RS 4 +.nf +\fB +\fIjob_name\fR.o\fIsequence_number\fR +.fi \fR +.P +.RE +.RE +.IP "\fB\(mip\ \fIpriority\fR" 10 +Define the priority the batch job should have relative to other batch +jobs owned by the batch server. +.RS 10 +.P +The +.IR qsub +utility shall set the +.IR Priority +attribute of the batch job to the value of the +.IR priority +option-argument. +.P +If the +.BR \(mip +option is not presented to the +.IR qsub +utility, the value of the +.IR Priority +attribute is implementation-defined. +.P +The +.IR qsub +utility shall accept a value for the +.IR priority +option-argument that conforms to the syntax for signed decimal +integers, and which is not less than \(mi1\|024 and not greater than +1\|023. +.RE +.IP "\fB\(miq\ \fIdestination\fR" 10 +.br +Define the destination of the batch job. +.RS 10 +.P +The destination is not a batch job attribute; it determines the batch +server, and possibly the batch queue, to which the +.IR qsub +utility batch queues the batch job. +.P +The +.IR qsub +utility shall submit the script to the batch server named by the +.IR destination +option-argument or the server that owns the batch queue named in the +.IR destination +option-argument. +.P +The +.IR qsub +utility shall accept an option-argument for the +.BR \(miq +option that conforms to the syntax for a destination (see +.IR "Section 3.3.2" ", " "Destination"). +.P +If the +.BR \(miq +option is not presented to the +.IR qsub +utility, the +.IR qsub +utility shall submit the batch job to the default destination. The +mechanism for determining the default destination is +implementation-defined. +.RE +.IP "\fB\(mir\ \fIy\fR|\fIn\fR" 10 +Define whether the batch job is rerunnable. +.RS 10 +.P +If the value of the option-argument is +.IR y , +the +.IR qsub +utility shall set the +.IR Rerunable +attribute of the batch job to TRUE. +.P +If the value of the option-argument is +.IR n , +the +.IR qsub +utility shall set the +.IR Rerunable +attribute of the batch job to FALSE. +.P +If the +.BR \(mir +option is not presented to the +.IR qsub +utility, the utility shall set the +.IR Rerunable +attribute of the batch job to TRUE. +.RE +.IP "\fB\(miS\ \fIpath_name_list\fR" 10 +.br +Define the pathname to the shell under which the batch job is to +execute. +.RS 10 +.P +The +.IR qsub +utility shall accept a +.IR path_name_list +option-argument that conforms to the following syntax: +.sp +.RS 4 +.nf +\fB +\fIpathname\fB[\fR@\fIhost\fB][\fR,,\fIpathname\fB[\fR@\fIhost\fB]\fR,, ...\fB]\fR +.fi \fR +.P +.RE +.P +The +.IR qsub +utility shall allow only one pathname for a given host name. The +.IR qsub +utility shall allow only one pathname that is missing a corresponding +host name. +.P +The +.IR qsub +utility shall add a value to the +.IR Shell_Path_List +attribute of the batch job for each entry in the +.IR path_name_list +option-argument. +.P +If the +.BR \(miS +option is not presented to the +.IR qsub +utility, the utility shall set the +.IR Shell_Path_List +attribute of the batch job to the null string. +.P +The conformance document for an implementation shall describe the +mechanism used to set the default shell and determine the current value +of the default shell. An implementation shall provide a means for the +installation to set the default shell to the login shell of the user +under which the batch job is to execute. See +.IR "Section 3.3.3" ", " "Multiple Keyword-Value Pairs" +for a means of removing +.IR keyword =\c +.IR value +(and +.IR value @\c +.IR keyword ) +pairs and other general rules for list-oriented batch job attributes. +.RE +.IP "\fB\(miu\ \fIuser_list\fR" 10 +Define the user name under which the batch job is to execute. +.RS 10 +.P +The +.IR qsub +utility shall accept a +.IR user_list +option-argument that conforms to the following syntax: +.sp +.RS 4 +.nf +\fB +\fIusername\fB[\fR@\fIhost\fB][\fR,,\fIusername\fB[\fR@\fIhost\fB]\fR,, ...\fB]\fR +.fi \fR +.P +.RE +.P +The +.IR qsub +utility shall accept only one user name that is missing a corresponding +host name. The +.IR qsub +utility shall accept only one user name per named host. +.P +The +.IR qsub +utility shall add a value to the +.IR User_List +attribute of the batch job for each entry in the +.IR user_list +option-argument. +.P +If the +.BR \(miu +option is not presented to the +.IR qsub +utility, the utility shall set the +.IR User_List +attribute of the batch job to the user name from which the utility is +executing. See +.IR "Section 3.3.3" ", " "Multiple Keyword-Value Pairs" +for a means of removing +.IR keyword =\c +.IR value +(and +.IR value @\c +.IR keyword ) +pairs and other general rules for list-oriented batch job attributes. +.RE +.IP "\fB\(miv\ \fIvariable_list\fR" 10 +.br +Add to the list of variables that are exported to the session leader of +the batch job. +.RS 10 +.P +A +.IR variable_list +is a set of strings of either the form <\c +.IR variable > +or <\c +.IR variable =\c +.IR value >, +delimited by + +characters. +.P +If the +.BR \(miv +option is presented to the +.IR qsub +utility, the utility shall also add, to the environment +.IR Variable_List +attribute of the batch job, every variable named in the environment +.IR variable_list +option-argument and, optionally, values of specified variables. +.P +If a value is not provided on the command line, the +.IR qsub +utility shall set the value of each variable in the environment +.IR Variable_List +attribute of the batch job to the value of the corresponding +environment variable for the process in which the utility is executing; +see +.IR "Table 4-19, Environment Variable Values (Utilities)". +.P +A conforming application shall not repeat a variable in the environment +.IR variable_list +option-argument. +.P +The +.IR qsub +utility shall not repeat a variable in the environment +.IR Variable_List +attribute of the batch job. See +.IR "Section 3.3.3" ", " "Multiple Keyword-Value Pairs" +for a means of removing +.IR keyword =\c +.IR value +(and +.IR value @\c +.IR keyword ) +pairs and other general rules for list-oriented batch job attributes. +.RE +.IP "\fB\(miV\fR" 10 +Specify that all of the environment variables of the process are +exported to the context of the batch job. +.RS 10 +.P +The +.IR qsub +utility shall place every environment variable in the process in which +the utility is executing in the list and shall set the value of each +variable in the attribute to the value of that variable in the +process. +.RE +.IP "\fB\(miz\fR" 10 +Specify that the utility does not write the batch +.IR job_identifier +of the created batch job to standard output. +.RS 10 +.P +If the +.BR \(miz +option is presented to the +.IR qsub +utility, the utility shall not write the batch +.IR job_identifier +of the created batch job to standard output. +.P +If the +.BR \(miz +option is not presented to the +.IR qsub +utility, the utility shall write the identifier of the created batch +job to standard output. +.RE +.SH OPERANDS +The +.IR qsub +utility shall accept a +.IR script +operand that indicates the path to the script of the batch job. +.P +If the +.IR script +operand is not presented to the +.IR qsub +utility, or if the operand is the single-character string +.BR '\(mi' , +the utility shall read the script from standard input. +.P +If the script represents a partial path, the +.IR qsub +utility shall expand the path relative to the current directory of the +process executing the utility. +.SH STDIN +The +.IR qsub +utility reads the script of the batch job from standard input if the +script operand is omitted or is the single character +.BR '\(mi' . +.SH "INPUT FILES" +In addition to binding the file indicated by the +.IR script +operand to the batch job, the +.IR qsub +utility reads the script file and acts on directives in the script. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR qsub : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +the precedence of internationalization variables used to determine the +values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILOGNAME\fP" 10 +Determine the login name of the user. +.IP "\fIPBS_DPREFIX\fP" 10 +.br +Determine the default prefix for directives within the script. +.IP "\fISHELL\fP" 10 +Determine the pathname of the preferred command language interpreter +of the user. +.IP "\fITZ\fP" 10 +Determine the timezone used to interpret the +.IR date-time +option-argument. If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Once created, a batch job exists until it exits, aborts, or is +deleted. +.P +After a batch job is created by the +.IR qsub +utility, batch servers might route, execute, modify, or delete the +batch job. +.SH STDOUT +The +.IR qsub +utility writes the batch +.IR job_identifier +assigned to the batch job to standard output, unless the +.BR \(miz +option is specified. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +.SS "Script Preservation" +.P +The +.IR qsub +utility shall make the script available to the server executing the +batch job in such a way that the server executes the script as it +exists at the time of submission. +.P +The +.IR qsub +utility can send a copy of the script to the server with the +.IR "Queue Job Request" +or store a temporary copy of the script in a location specified to the +server. +.SS "Option Specification" +.P +A script can contain directives to the +.IR qsub +utility. +.P +The +.IR qsub +utility shall scan the lines of the script for directives, skipping +blank lines, until the first line that begins with a string other than +the directive string; if directives occur on subsequent lines, the +utility shall ignore those directives. +.P +Lines are separated by a +. +If the first line of the script begins with +.BR \(dq#!\(dq +or a + +(\c +.BR ':' ), +then it is skipped. The +.IR qsub +utility shall process a line in the script as a directive if and only +if the string of characters from the first non-white-space character on +the line until the first + +or + +on the line match the directive prefix. If a line in the script +contains a directive and the final characters of the line are + +and +, +then the next line shall be interpreted as a continuation of that +directive. +.P +The +.IR qsub +utility shall process the options and option-arguments contained on the +directive prefix line using the same syntax as if the options were +input on the +.IR qsub +utility. +.P +The +.IR qsub +utility shall continue to process a directive prefix line until after a + +is encountered. An implementation may ignore lines which, according to +the syntax of the shell that will interpret the script, are comments. +An implementation shall describe in the conformance document the format +of any shell comments that it will recognize. +.P +If an option is present in both a directive and the arguments to the +.IR qsub +utility, the utility shall ignore the option and the corresponding +option-argument, if any, in the directive. +.P +If an option that is present in the directive is not present in the +arguments to the +.IR qsub +utility, the utility shall process the option and the option-argument, +if any. +.P +In order of preference, the +.IR qsub +utility shall select the directive prefix from one of the following +sources: +.IP " *" 4 +If the +.BR \(miC +option is presented to the utility, the value of the +.IR directive_prefix +option-argument +.IP " *" 4 +If the environment variable +.IR PBS_DPREFIX +is defined, the value of that variable +.IP " *" 4 +The four-character string +.BR \(dq#PBS\(dq +encoded in the portable character set +.P +If the +.BR \(miC +option is present in the script file it shall be ignored. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR qsub +utility allows users to create a batch job that will process the script +specified as the operand of the utility. +.P +The options of the +.IR qsub +utility allow users to control many aspects of the queuing and +execution of a batch job. +.P +The +.BR \(mia +option allows users to designate the time after which the batch job +will become eligible to run. By specifying an execution time, users can +take advantage of resources at off-peak hours, synchronize jobs with +chronologically predictable events, and perhaps take advantage of +off-peak pricing of computing time. For these reasons and others, a +timing option is existing practice on the part of almost every batch +system, including NQS. +.P +The +.BR \(miA +option allows users to specify the account that will be charged for the +batch job. Support for account is not mandatory for conforming batch +servers. +.P +The +.BR \(miC +option allows users to prescribe the prefix for directives within the +script file. The default prefix +.BR \(dq#PBS\(dq +may be inappropriate if the script will be interpreted with an +alternate shell, as specified by the +.BR \(miS +option. +.P +The +.BR \(mic +option allows users to establish the checkpointing interval for their +jobs. A checkpointing system, which is not defined by this volume of POSIX.1\(hy2008, allows +recovery of a batch job at the most recent checkpoint in the event of a +crash. Checkpointing is typically used for jobs that consume expensive +computing time or must meet a critical schedule. Users should be +allowed to make the tradeoff between the overhead of checkpointing and +the risk to the timely completion of the batch job; therefore, this volume of POSIX.1\(hy2008 +provides the checkpointing interval option. Support for checkpointing +is optional for batch servers. +.P +The +.BR \(mie +option allows users to redirect the standard error streams of their +jobs to a non-default path. For example, if the submitted script +generally produces a great deal of useless error output, a user might +redirect the standard error output to the null device. Or, if the file +system holding the default location (the home directory of the user) +has too little free space, the user might redirect the standard error +stream to a file in another file system. +.P +The +.BR \(mih +option allows users to create a batch job that is held until explicitly +released. The ability to create a held job is useful when some external +event must complete before the batch job can execute. For example, the +user might submit a held job and release it when the system load has +dropped. +.P +The +.BR \(mij +option allows users to merge the standard error of a batch job into its +standard output stream, which has the advantage of showing the +sequential relationship between output and error messages. +.P +The +.BR \(mim +option allows users to designate those points in the execution of a +batch job at which mail will be sent to the submitting user, or to the +account(s) indicated by the +.BR \(miM +option. By requesting mail notification at points of interest in the +life of a job, the submitting user, or other designated users, can +track the progress of a batch job. +.P +The +.BR \(miN +option allows users to associate a name with the batch job. The job +name in no way affects the processing of the batch job, but rather +serves as a mnemonic handle for users. For example, the batch job name +can help the user distinguish between multiple jobs listed by the +.IR qstat +utility. +.P +The +.BR \(mio +option allows users to redirect the standard output stream. A user +might, for example, wish to redirect to the null device the standard +output stream of a job that produces copious yet superfluous output. +.P +The +.BR \(miP +option allows users to designate the relative priority of a batch job +for selection from a queue. +.P +The +.BR \(miq +option allows users to specify an initial queue for the batch job. If +the user specifies a routing queue, the batch server routes the +batch job to another queue for execution or further routing. If the +user specifies a non-routing queue, the batch server of the queue +eventually executes the batch job. +.P +The +.BR \(mir +option allows users to control whether the submitted job will be rerun +if the controlling batch node fails during execution of the batch job. +The +.BR \(mir +option likewise allows users to indicate whether or not the batch job +is eligible to be rerun by the +.IR qrerun +utility. Some jobs cannot be correctly rerun because of changes they +make in the state of databases or other aspects of their environment. +This volume of POSIX.1\(hy2008 specifies that the default, if the +.BR \(mir +option is not presented to the utility, will be that the batch job +cannot be rerun, since the result of rerunning a non-rerunnable job +might be catastrophic. +.P +The +.BR \(miS +option allows users to specify the program (usually a shell) that will +be invoked to process the script of the batch job. This option has been +modified to allow a list of shell names and locations associated with +different hosts. +.P +The +.BR \(miu +option is useful when the submitting user is authorized to use more +than one account on a given host, in which case the +.BR \(miu +option allows the user to select from among those accounts. The +option-argument is a list of user-host pairs, so that the submitting +user can provide different user identifiers for different nodes in the +event the batch job is routed. The +.BR \(miu +option provides a lot of flexibility to accommodate sites with complex +account structures. Users that have the same user identifier on all the +hosts they are authorized to use will not need to use the +.BR \(miu +option. +.P +The +.BR \(miV +option allows users to export all their current environment variables, +as of the time the batch job is submitted, to the context of the +processes of the batch job. +.P +The +.BR \(miv +option allows users to export specific environment variables from their +current process to the processes of the batch job. +.P +The +.BR \(miz +option allows users to suppress the writing of the batch job identifier +to standard output. The +.BR \(miz +option is an existing NQS practice that has been standardized. +.P +Historically, the +.IR qsub +utility has served the batch job-submission function in the NQS system, +the existing practice on which it is based. Some changes and additions +have been made to the +.IR qsub +utility in this volume of POSIX.1\(hy2008, \fIvis-a-vis\fP NQS, as a result of the growing pool +of experience with distributed batch systems. +.P +The set of features of the +.IR qsub +utility as defined in this volume of POSIX.1\(hy2008 appears to incorporate all the common +existing practice on potentially conforming platforms. +.SH "FUTURE DIRECTIONS" +The +.IR qsub +utility may be removed in a future version. +.SH "SEE ALSO" +.IR "Chapter 3" ", " "Batch Environment Services", +.IR "\fIqrerun\fR\^", +.IR "\fIqstat\fR\^", +.IR "\fItouch\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.150" ", " "Epoch", +.IR "Section 6.1" ", " "Portable Character Set", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/read.1p b/man-pages-posix-2013/man1p/read.1p new file mode 100644 index 0000000..9896542 --- /dev/null +++ b/man-pages-posix-2013/man1p/read.1p @@ -0,0 +1,272 @@ +'\" et +.TH READ "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +read +\(em read a line from standard input +.SH SYNOPSIS +.LP +.nf +read \fB[\fR\(mir\fB] \fIvar\fR... +.fi +.SH DESCRIPTION +The +.IR read +utility shall read a single line from standard input. +.P +By default, unless the +.BR \(mir +option is specified, + +shall act as an escape character. An unescaped + +shall preserve the literal value of the following character, with the +exception of a +. +If a + +follows the +, +the +.IR read +utility shall interpret this as line continuation. The + +and + +shall be removed before splitting the input into fields. All other +unescaped + +characters shall be removed after splitting the input into fields. +.P +If standard input is a terminal device and the invoking shell is +interactive, +.IR read +shall prompt for a continuation line when it reads an input line ending +with a + +, +unless the +.BR \(mir +option is specified. +.P +The terminating + +(if any) shall be removed from the input and the results shall be split +into fields as in the shell for the results of parameter expansion (see +.IR "Section 2.6.5" ", " "Field Splitting"); +the first field shall be assigned to the first variable +.IR var , +the second field to the second variable +.IR var , +and so on. If there are fewer fields than there are +.IR var +operands, the remaining +.IR var s +shall be set to empty strings. If there are fewer +.IR var s +than fields, the last +.IR var +shall be set to a value comprising the following elements: +.IP " *" 4 +The field that corresponds to the last +.IR var +in the normal assignment sequence described above +.IP " *" 4 +The delimiter(s) that follow the field corresponding to the last +.IR var +.IP " *" 4 +The remaining fields and their delimiters, with trailing +.IR IFS +white space ignored +.P +The setting of variables specified by the +.IR var +operands shall affect the current shell execution environment; see +.IR "Section 2.12" ", " "Shell Execution Environment". +If it is called in a subshell or separate utility execution +environment, such as one of the following: +.sp +.RS 4 +.nf +\fB +(read foo) +nohup read ... +find . \(miexec read ... \e; +.fi \fR +.P +.RE +.P +it shall not affect the shell variables in the caller's environment. +.SH OPTIONS +The +.IR read +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option is supported: +.IP "\fB\(mir\fP" 10 +Do not treat a + +character in any special way. Consider each + +to be part of the input line. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIvar\fR" 10 +The name of an existing or nonexisting shell variable. +.SH STDIN +The standard input shall be a text file. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR read : +.IP "\fIIFS\fP" 10 +Determine the internal field separators used to delimit fields; see +.IR "Section 2.5.3" ", " "Shell Variables". +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPS2\fP" 10 +Provide the prompt string that an interactive shell shall write to +standard error when a line ending with a + + +is read and the +.BR \(mir +option was not specified. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used for diagnostic messages and +prompts for continued input. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +End-of-file was detected or an error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.BR \(mir +option is included to enable +.IR read +to subsume the purpose of the +.IR line +utility, which is not included in POSIX.1\(hy2008. +.SH EXAMPLES +The following command: +.sp +.RS 4 +.nf +\fB +while read \(mir xx yy +do + printf "%s %s\en$yy$xx" +done < \fIinput_file\fR +.fi \fR +.P +.RE +.P +prints a file with the first field of each line moved to the end of the +line. +.SH RATIONALE +The +.IR read +utility historically has been a shell built-in. It was separated off +into its own utility to take advantage of the richer description of +functionality introduced by this volume of POSIX.1\(hy2008. +.P +Since +.IR read +affects the current shell execution environment, +it is generally provided as a shell regular built-in. If it is called +in a subshell or separate utility execution environment, such as one of +the following: +.sp +.RS 4 +.nf +\fB +(read foo) +nohup read ... +find . \(miexec read ... \e; +.fi \fR +.P +.RE +.P +it does not affect the shell variables in the environment of the +caller. +.P +Although the standard input is required to be a text file, and +therefore will always end with a + +(unless it is an empty file), the processing of continuation lines +when the +.BR \(mir +option is not used can result in the input not ending with a +. +This occurs if the last line of the input file ends with a + +. +It is for this reason that ``if any'' is used in ``The terminating + +(if any) shall be removed from the input'' in the description. +It is not a relaxation of the requirement for standard input to +be a text file. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/readonly.1p b/man-pages-posix-2013/man1p/readonly.1p new file mode 100644 index 0000000..f00a71a --- /dev/null +++ b/man-pages-posix-2013/man1p/readonly.1p @@ -0,0 +1,164 @@ +'\" et +.TH READONLY "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +readonly +\(em set the readonly attribute for variables +.SH SYNOPSIS +.LP +.nf +readonly name\fB[\fR=\fIword\fB]\fR... +.P +readonly\fR \(mip +.fi +.SH DESCRIPTION +The variables whose +.IR name s +are specified shall be given the +.IR readonly +attribute. The values of variables with the +.IR readonly +attribute cannot be changed by subsequent assignment, nor can those +variables be unset by the +.IR unset +utility. If the name of a variable is followed by =\c +.IR word , +then the value of that variable shall be set to +.IR word . +.P +The +.IR readonly +special built-in shall support the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +When +.BR \(mip +is specified, +.IR readonly +writes to the standard output the names and values of all read-only +variables, in the following format: +.sp +.RS 4 +.nf +\fB +"readonly %s=%s\en", <\fIname\fR>, <\fIvalue\fR> +.fi \fR +.P +.RE +.P +if +.IR name +is set, and +.sp +.RS 4 +.nf +\fB +"readonly %s\en", <\fIname\fR> +.fi \fR +.P +.RE +.P +if +.IR name +is unset. +.P +The shell shall format the output, including the proper use of quoting, +so that it is suitable for reinput to the shell as commands that +achieve the same value and +.IR readonly +attribute-setting results in a shell execution environment in which: +.IP " 1." 4 +Variables with values at the time they were output do not have the +.IR readonly +attribute set. +.IP " 2." 4 +Variables that were unset at the time they were output do not have a +value at the time at which the saved output is reinput to the shell. +.P +When no arguments are given, the results are unspecified. +.SH OPTIONS +See the DESCRIPTION. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +See the DESCRIPTION. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +Zero. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +.LP +.nf +readonly HOME PWD +.fi +.SH "RATIONALE" +Some historical shells preserve the +.IR readonly +attribute across separate invocations. This volume of POSIX.1\(hy2008 allows this behavior, +but does not require it. +.P +The +.BR \(mip +option allows portable access to the values that can be saved and then +later restored using, for example, a +.IR dot +script. Also see the RATIONALE for +.IR "\fIexport\fR\^" +for a description of the no-argument and +.BR \(mip +output cases and a related example. +.P +Read-only functions were considered, but they were omitted as not being +historical practice or particularly useful. Furthermore, functions must +not be read-only across invocations to preclude ``spoofing'' +(spoofing is the term for the practice of creating a program that acts +like a well-known utility with the intent of subverting the real intent +of the user) of administrative or security-relevant (or +security-conscious) shell scripts. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/renice.1p b/man-pages-posix-2013/man1p/renice.1p new file mode 100644 index 0000000..993773f --- /dev/null +++ b/man-pages-posix-2013/man1p/renice.1p @@ -0,0 +1,280 @@ +'\" et +.TH RENICE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +renice +\(em set nice values of running processes +.SH SYNOPSIS +.LP +.nf +renice \fB[\fR\(mig|\(mip|\(miu\fB] \fR\(min \fIincrement ID\fR... +.fi +.SH DESCRIPTION +The +.IR renice +utility shall request that the nice values (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.240" ", " "Nice Value") +of one or more running processes be changed. By default, the applicable +processes are specified by their process IDs. When a process group is +specified (see +.BR \(mig ), +the request shall apply to all processes in the process group. +.P +The nice value shall be bounded in an implementation-defined manner. +If the requested +.IR increment +would raise or lower the nice value of the executed utility beyond +implementation-defined limits, then the limit whose value was +exceeded shall be used. +.P +When a user is +.IR renice d, +the request applies to all processes whose saved set-user-ID matches +the user ID corresponding to the user. +.P +Regardless of which options are supplied or any other factor, +.IR renice +shall not alter the nice values of any process unless the user +requesting such a change has appropriate privileges to do so for the +specified process. If the user lacks appropriate privileges to perform +the requested action, the utility shall return an error status. +.P +The saved set-user-ID of the user's process shall be checked instead of +its effective user ID when +.IR renice +attempts to determine the user ID of the process in order to determine +whether the user has appropriate privileges. +.SH OPTIONS +The +.IR renice +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except for Guideline 9. +.P +The following options shall be supported: +.IP "\fB\(mig\fP" 10 +Interpret the following operands as unsigned decimal integer process +group IDs. +.IP "\fB\(min\ \fIincrement\fR" 10 +Specify how the nice value of the specified process or processes is to +be adjusted. The +.IR increment +option-argument is a positive or negative decimal integer that shall be +used to modify the nice value of the specified process or processes. +.RS 10 +.P +Positive +.IR increment +values shall cause a lower nice value. Negative +.IR increment +values may require appropriate privileges and shall cause a higher +nice value. +.RE +.IP "\fB\(mip\fP" 10 +Interpret the following operands as unsigned decimal integer process +IDs. The +.BR \(mip +option is the default if no options are specified. +.IP "\fB\(miu\fP" 10 +Interpret the following operands as users. If a user exists with a user +name equal to the operand, then the user ID of that user is used in +further processing. Otherwise, if the operand represents an unsigned +decimal integer, it shall be used as the numeric user ID of the user. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIID\fR" 10 +A process ID, process group ID, or user name/user ID, depending on the +option selected. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR renice : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +.IP " 1." 4 +Adjust the nice value so that process IDs 987 and 32 would have a lower +nice value: +.RS 4 +.sp +.RS 4 +.nf +\fB +renice \(min 5 \(mip 987 32 +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +Adjust the nice value so that group IDs 324 and 76 would have a higher +nice value, if the user has appropriate privileges to do so: +.RS 4 +.sp +.RS 4 +.nf +\fB +renice \(min \(mi4 \(mig 324 76 +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +Adjust the nice value so that numeric user ID 8 and user +.BR sas +would have a lower nice value: +.RS 4 +.sp +.RS 4 +.nf +\fB +renice \(min 4 \(miu 8 sas +.fi \fR +.P +.RE +.RE +.P +Useful nice value increments on historical systems include 19 or 20 +(the affected processes run only when nothing else in the system +attempts to run) and any negative number (to make processes run +faster). +.SH RATIONALE +The +.IR gid , +.IR pid , +and +.IR user +specifications do not fit either the definition of operand or +option-argument. However, for clarity, they have been included in the +OPTIONS section, rather than the OPERANDS section. +.P +The definition of nice value is not intended to suggest that all +processes in a system have priorities that are comparable. Scheduling +policy extensions such as the realtime priorities in the System Interfaces volume of POSIX.1\(hy2008 make the +notion of a single underlying priority for all scheduling policies +problematic. Some implementations may implement the +.IR nice -related +features to affect all processes on the system, others to affect just +the general time-sharing activities implied by this volume of POSIX.1\(hy2008, and others may +have no effect at all. Because of the use of +``implementation-defined'' in +.IR nice +and +.IR renice , +a wide range of implementation strategies are possible. +.P +Originally, this utility was written in the historical manner, using +the term ``nice value''. This was always a point of concern with users +because it was never intuitively obvious what this meant. With a newer +version of +.IR renice , +which used the term ``system scheduling priority'', it was hoped that +novice users could better understand what this utility was meant to +do. Also, it would be easier to document what the utility was meant to +do. Unfortunately, the addition of the POSIX realtime scheduling +capabilities introduced the concepts of process and thread scheduling +priorities that were totally unaffected by the +.IR nice /\c +.IR renice +utilities or the +\fInice\fR()/\c +\fIsetpriority\fR() +functions. Continuing to use the term ``system scheduling priority'' +would have incorrectly suggested that these utilities and functions +were indeed affecting these realtime priorities. It was decided to +revert to the historical term ``nice value'' to reference this +unrelated process attribute. +.P +Although this utility has use by system administrators (and in fact +appears in the system administration portion of the BSD documentation), +the standard developers considered that it was very useful for +individual end users to control their own processes. +.P +Earlier versions of this standard allowed the following forms in the +SYNOPSIS: +.sp +.RS 4 +.nf +\fB +renice \fInice_value\fB[\fR\(mip\fB] \fIpid\fR...\fB[\fR\(mig \fIgid\fR...\fB][\fR\(mip \fIpid\fR...\fB][\fR\(miu \fIuser\fR...\fB]\fR +renice \fInice_value \(mig \fIgid\fR...\fB[\fR\(mig \fIgid\fR...\fB]\fR\(mip \fIpid\fR...\fB][\fR\(miu \fIuser\fR...\fB]\fR +renice \fInice_value \(miu \fIuser\fR...\fB[\fR\(mig \fIgid\fR...\fB]\fR\(mip \fIpid\fR...\fB][\fR\(miu \fIuser\fR...\fB]\fR +.fi \fR +.P +.RE +.P +These forms are no longer specified by POSIX.1\(hy2008 but may be +present in some implementations. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fInice\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.240" ", " "Nice Value", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/return.1p b/man-pages-posix-2013/man1p/return.1p new file mode 100644 index 0000000..ba20275 --- /dev/null +++ b/man-pages-posix-2013/man1p/return.1p @@ -0,0 +1,110 @@ +'\" et +.TH RETURN "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +return +\(em return from a function or dot script +.SH SYNOPSIS +.LP +.nf +return \fB[\fIn\fB]\fR +.fi +.SH DESCRIPTION +The +.IR return +utility shall cause the shell to stop executing the current function or +.IR dot +script. If the shell is not currently executing a function or +.IR dot +script, the results are unspecified. +.SH OPTIONS +None. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The value of the special parameter +.BR '?' +shall be set to +.IR n , +an unsigned decimal integer, or to the exit status of the last command +executed if +.IR n +is not specified. If the value of +.IR n +is greater than 255, the results are undefined. When +.IR return +is executed in a +.IR trap +action, the last command is considered to be the command that +executed immediately preceding the +.IR trap +action. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH "EXAMPLES" +None. +.SH "RATIONALE" +The behavior of +.IR return +when not in a function or +.IR dot +script differs between the System V shell and the KornShell. In the +System V shell this is an error, whereas in the KornShell, the effect +is the same as +.IR exit . +.P +The results of returning a number greater than 255 are undefined +because of differing practices in the various historical +implementations. Some shells AND out all but the low-order 8 bits; +others allow larger values, but not of unlimited size. +.P +See the discussion of appropriate exit status values under +.IR "\fIexit\fR\^". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.9.5" ", " "Function Definition Command", +.IR "Section 2.14" ", " "Special Built-In Utilities", +.IR "\fIdot\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/rm.1p b/man-pages-posix-2013/man1p/rm.1p new file mode 100644 index 0000000..2a8c94d --- /dev/null +++ b/man-pages-posix-2013/man1p/rm.1p @@ -0,0 +1,447 @@ +'\" et +.TH RM "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +rm +\(em remove directory entries +.SH SYNOPSIS +.LP +.nf +rm \fB[\fR\(mifiRr\fB]\fI file\fR... +.fi +.SH DESCRIPTION +The +.IR rm +utility shall remove the directory entry specified by each +.IR file +argument. +.P +If either of the files dot or dot-dot are specified as the basename +portion of an operand (that is, the final pathname component) or if an +operand resolves to the root directory, +.IR rm +shall write a diagnostic message to standard error and do nothing more +with such operands. +.P +For each +.IR file +the following steps shall be taken: +.IP " 1." 4 +If the +.IR file +does not exist: +.RS 4 +.IP " a." 4 +If the +.BR \(mif +option is not specified, +.IR rm +shall write a diagnostic message to standard error. +.IP " b." 4 +Go on to any remaining +.IR files . +.RE +.IP " 2." 4 +If +.IR file +is of type directory, the following steps shall be taken: +.RS 4 +.IP " a." 4 +If neither the +.BR \(miR +option nor the +.BR \(mir +option is specified, +.IR rm +shall write a diagnostic message to standard error, do nothing more +with +.IR file , +and go on to any remaining files. +.IP " b." 4 +If the +.BR \(mif +option is not specified, and either the permissions of +.IR file +do not permit writing and the standard input is a terminal or the +.BR \(mii +option is specified, +.IR rm +shall write a prompt to standard error and read a line from the +standard input. If the response is not affirmative, +.IR rm +shall do nothing more with the current file and go on to any remaining +files. +.IP " c." 4 +For each entry contained in +.IR file , +other than dot or dot-dot, the four steps listed here (1 to 4) shall be +taken with the entry as if it were a +.IR file +operand. The +.IR rm +utility shall not traverse directories by following symbolic links into +other parts of the hierarchy, but shall remove the links themselves. +.IP " d." 4 +If the +.BR \(mii +option is specified, +.IR rm +shall write a prompt to standard error and read a line from the +standard input. If the response is not affirmative, +.IR rm +shall do nothing more with the current file, and go on to any remaining +files. +.RE +.IP " 3." 4 +If +.IR file +is not of type directory, the +.BR \(mif +option is not specified, and either the permissions of +.IR file +do not permit writing and the standard input is a terminal or the +.BR \(mii +option is specified, +.IR rm +shall write a prompt to the standard error and read a line from the +standard input. If the response is not affirmative, +.IR rm +shall do nothing more with the current file and go on to any remaining +files. +.IP " 4." 4 +If the current file is a directory, +.IR rm +shall perform actions equivalent to the +\fIrmdir\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008 called with a pathname of the current +file used as the +.IR path +argument. If the current file is not a directory, +.IR rm +shall perform actions equivalent to the +\fIunlink\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008 called with a pathname of the current +file used as the +.IR path +argument. +.RS 4 +.P +If this fails for any reason, +.IR rm +shall write a diagnostic message to standard error, do nothing more +with the current file, and go on to any remaining files. +.RE +.P +The +.IR rm +utility shall be able to descend to arbitrary depths in a file +hierarchy, and shall not fail due to path length limitations (unless an +operand specified by the user exceeds system limitations). +.SH OPTIONS +The +.IR rm +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mif\fP" 10 +Do not prompt for confirmation. Do not write diagnostic messages or +modify the exit status in the case of nonexistent operands. Any +previous occurrences of the +.BR \(mii +option shall be ignored. +.IP "\fB\(mii\fP" 10 +Prompt for confirmation as described previously. Any previous +occurrences of the +.BR \(mif +option shall be ignored. +.IP "\fB\(miR\fP" 10 +Remove file hierarchies. See the DESCRIPTION. +.IP "\fB\(mir\fP" 10 +Equivalent to +.BR \(miR . +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a directory entry to be removed. +.SH STDIN +The standard input shall be used to read an input line in response to +each prompt specified in the STDOUT section. Otherwise, the standard +input shall not be used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR rm : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements used in the extended regular +expression defined for the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments) and the behavior of character +classes within regular expressions used in the extended regular +expression defined for the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale used to process affirmative responses, and the +locale used to affect the format and contents of diagnostic messages +and prompts written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +Prompts shall be written to standard error under the conditions +specified in the DESCRIPTION and OPTIONS sections. The prompts shall +contain the +.IR file +pathname, but their format is otherwise unspecified. The standard +error also shall be used for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Each directory entry was successfully removed, unless its removal was +canceled by a non-affirmative response to a prompt for confirmation. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR rm +utility is forbidden to remove the names dot and dot-dot in order to +avoid the consequences of inadvertently doing something like: +.sp +.RS 4 +.nf +\fB +rm \(mir .* +.fi \fR +.P +.RE +.P +Some implementations do not permit the removal of the last link to an +executable binary file that is being executed; see the +.BR [EBUSY] +error in the +\fIunlink\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008. Thus, the +.IR rm +utility can fail to remove such files. +.P +The +.BR \(mii +option causes +.IR rm +to prompt and read the standard input even if the standard input is not +a terminal, but in the absence of +.BR \(mii +the mode prompting is not done when the standard input is not a +terminal. +.SH EXAMPLES +.IP " 1." 4 +The following command: +.RS 4 +.sp +.RS 4 +.nf +\fB +rm a.out core +.fi \fR +.P +.RE +.P +removes the directory entries: +.BR a.out +and +.BR core . +.RE +.IP " 2." 4 +The following command: +.RS 4 +.sp +.RS 4 +.nf +\fB +rm \(miRf junk +.fi \fR +.P +.RE +.P +removes the directory +.BR junk +and all its contents, without prompting. +.RE +.SH RATIONALE +For absolute clarity, paragraphs (2b) and (3) in the DESCRIPTION of +.IR rm +describing the behavior when prompting for confirmation, should be +interpreted in the following manner: +.sp +.RS 4 +.nf +\fB +if ((NOT f_option) AND + ((not_writable AND input_is_terminal) OR i_option)) +.fi \fR +.P +.RE +.P +The exact format of the interactive prompts is unspecified. Only the +general nature of the contents of prompts are specified because +implementations may desire more descriptive prompts than those used on +historical implementations. Therefore, an application not using the +.BR \(mif +option, or using the +.BR \(mii +option, relies on the system to provide the most suitable dialog +directly with the user, based on the behavior specified. +.P +The +.BR \(mir +option is historical practice on all known systems. The synonym +.BR \(miR +option is provided for consistency with the other utilities in this volume of POSIX.1\(hy2008 +that provide options requesting recursive descent through the file +hierarchy. +.P +The behavior of the +.BR \(mif +option in historical versions of +.IR rm +is inconsistent. In general, along with ``forcing'' the unlink without +prompting for permission, it always causes diagnostic messages to be +suppressed and the exit status to be unmodified for nonexistent +operands and files that cannot be unlinked. In some versions, however, +the +.BR \(mif +option suppresses usage messages and system errors as well. +Suppressing such messages is not a service to either shell scripts or +users. +.P +It is less clear that error messages regarding files that cannot be +unlinked (removed) should be suppressed. Although this is historical +practice, this volume of POSIX.1\(hy2008 does not permit the +.BR \(mif +option to suppress such messages. +.P +When given the +.BR \(mir +and +.BR \(mii +options, historical versions of +.IR rm +prompt the user twice for each directory, once before removing its +contents and once before actually attempting to delete the directory +entry that names it. This allows the user to ``prune'' the file +hierarchy walk. Historical versions of +.IR rm +were inconsistent in that some did not do the former prompt for +directories named on the command line and others had obscure prompting +behavior when the +.BR \(mii +option was specified and the permissions of the file did not permit +writing. The POSIX Shell and Utilities +.IR rm +differs little from historic practice, but does require that prompts be +consistent. Historical versions of +.IR rm +were also inconsistent in that prompts were done to both standard +output and standard error. This volume of POSIX.1\(hy2008 requires that prompts be done to +standard error, for consistency with +.IR cp +and +.IR mv , +and to allow historical extensions to +.IR rm +that provide an option to list deleted files on standard output. +.P +The +.IR rm +utility is required to descend to arbitrary depths so that any file +hierarchy may be deleted. This means, for example, that the +.IR rm +utility cannot run out of file descriptors during its descent (that is, +if the number of file descriptors is limited, +.IR rm +cannot be implemented in the historical fashion where one file +descriptor is used per directory level). Also, +.IR rm +is not permitted to fail because of path length restrictions, unless an +operand specified by the user is longer than +{PATH_MAX}. +.P +The +.IR rm +utility removes symbolic links themselves, not the files they refer to, +as a consequence of the dependence on the +\fIunlink\fR() +functionality, per the DESCRIPTION. When removing hierarchies with +.BR \(mir +or +.BR \(miR , +the prohibition on following symbolic links has to be made explicit. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIrmdir\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIremove\fR\^(\|)", +.IR "\fIrmdir\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/rmdel.1p b/man-pages-posix-2013/man1p/rmdel.1p new file mode 100644 index 0000000..08d0578 --- /dev/null +++ b/man-pages-posix-2013/man1p/rmdel.1p @@ -0,0 +1,167 @@ +'\" et +.TH RMDEL "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +rmdel +\(em remove a delta from an SCCS file (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +rmdel \(mir \fISID file\fR... +.fi +.SH DESCRIPTION +The +.IR rmdel +utility shall remove the delta specified by the SID from each named +SCCS file. The delta to be removed shall be the most recent delta in +its branch in the delta chain of each named SCCS file. In addition, the +application shall ensure that the SID specified is not that of a +version being edited for the purpose of making a delta; that is, if a +.IR p-file +(see +.IR "\fIget\fR\^") +exists for the named SCCS file, the SID specified shall not appear in +any entry of the +.IR p-file . +.P +Removal of a delta shall be restricted to: +.IP " 1." 4 +The user who made the delta +.IP " 2." 4 +The owner of the SCCS file +.IP " 3." 4 +The owner of the directory containing the SCCS file +.SH OPTIONS +The +.IR rmdel +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(mir\ \fISID\fR" 10 +Specify the SCCS identification string (\c +.IR SID ) +of the delta to be deleted. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an existing SCCS file or a directory. If +.IR file +is a directory, the +.IR rmdel +utility shall behave as though each file in the directory were +specified as a named file, except that non-SCCS files (last component +of the pathname does not begin with +.BR s. ) +and unreadable files shall be silently ignored. +.RS 10 +.P +If exactly one +.IR file +operand appears, and it is +.BR '\(mi' , +the standard input shall be read; each line of the standard input is +taken to be the name of an SCCS file to be processed. Non-SCCS files +and unreadable files shall be silently ignored. +.RE +.SH STDIN +The standard input shall be a text file used only when the +.IR file +operand is specified as +.BR '\(mi' . +Each line of the text file shall be interpreted as an SCCS pathname. +.SH "INPUT FILES" +The SCCS files shall be files of unspecified format. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR rmdel : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The SCCS files shall be files of unspecified format. During processing +of a +.IR file , +a temporary +.IR x-file , +as described in +.IR "\fIadmin\fR\^", +may be created and deleted; a locking +.IR z-file , +as described in +.IR "\fIget\fR\^", +may be created and deleted. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIadmin\fR\^", +.IR "\fIdelta\fR\^", +.IR "\fIget\fR\^", +.IR "\fIprs\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/rmdir.1p b/man-pages-posix-2013/man1p/rmdir.1p new file mode 100644 index 0000000..753d854 --- /dev/null +++ b/man-pages-posix-2013/man1p/rmdir.1p @@ -0,0 +1,195 @@ +'\" et +.TH RMDIR "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 directories +.SH SYNOPSIS +.LP +.nf +rmdir \fB[\fR\(mip\fB]\fI dir\fR... +.fi +.SH DESCRIPTION +The +.IR rmdir +utility shall remove the directory entry specified by each +.IR dir +operand. +.P +For each +.IR dir +operand, the +.IR rmdir +utility shall perform actions equivalent to the +\fIrmdir\fR() +function called with the +.IR dir +operand as its only argument. +.P +Directories shall be processed in the order specified. If a directory +and a subdirectory of that directory are specified in a single +invocation of the +.IR rmdir +utility, the application shall specify the subdirectory before the +parent directory so that the parent directory will be empty when the +.IR rmdir +utility tries to remove it. +.SH OPTIONS +The +.IR rmdir +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(mip\fP" 10 +Remove all directories in a pathname. For each +.IR dir +operand: +.RS 10 +.IP " 1." 4 +The directory entry it names shall be removed. +.IP " 2." 4 +If the +.IR dir +operand includes more than one pathname component, effects equivalent +to the following command shall occur: +.RS 4 +.sp +.RS 4 +.nf +\fB +rmdir \(mip $(dirname \fIdir\fP) +.fi \fR +.P +.RE +.RE +.RE +.SH OPERANDS +The following operand shall be supported: +.IP "\fIdir\fR" 10 +A pathname of an empty directory to be removed. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR rmdir : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Each directory entry specified by a +.IR dir +operand was removed successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The definition of an empty directory is one that contains, at most, +directory entries for dot and dot-dot. +.SH EXAMPLES +If a directory +.BR a +in the current directory is empty except it contains a directory +.BR b +and +.BR a/b +is empty except it contains a directory +.BR c : +.sp +.RS 4 +.nf +\fB +rmdir \(mip a/b/c +.fi \fR +.P +.RE +.P +removes all three directories. +.SH RATIONALE +On historical System V systems, the +.BR \(mip +option also caused a message to be written to the standard output. The +message indicated whether the whole path was removed or whether part of +the path remained for some reason. The STDERR section requires this +diagnostic when the entire path specified by a +.IR dir +operand is not removed, but does not allow the status message reporting +success to be written as a diagnostic. +.P +The +.IR rmdir +utility on System V also included a +.BR \(mis +option that suppressed the informational message output by the +.BR \(mip +option. This option has been omitted because the informational message +is not specified by this volume of POSIX.1\(hy2008. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIrm\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIremove\fR\^(\|)", +.IR "\fIrmdir\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/sact.1p b/man-pages-posix-2013/man1p/sact.1p new file mode 100644 index 0000000..fe3e7b1 --- /dev/null +++ b/man-pages-posix-2013/man1p/sact.1p @@ -0,0 +1,186 @@ +'\" et +.TH SACT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sact +\(em print current SCCS file-editing activity (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +sact \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR sact +utility shall inform the user of any impending deltas to a named SCCS +file by writing a list to standard output. This situation occurs when +.IR get +.BR \(mie +has been executed previously without a subsequent execution of +.IR delta , +.IR unget , +or +.IR sccs +.BR unedit . +.SH OPTIONS +None. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an existing SCCS file or a directory. If +.IR file +is a directory, the +.IR sact +utility shall behave as though each file in the directory were +specified as a named file, except that non-SCCS files (last component +of the pathname does not begin with +.BR s. ) +and unreadable files shall be silently ignored. +.RS 10 +.P +If exactly one +.IR file +operand appears, and it is +.BR '\(mi' , +the standard input shall be read; each line of the standard input shall +be taken to be the name of an SCCS file to be processed. Non-SCCS files +and unreadable files shall be silently ignored. +.RE +.SH STDIN +The standard input shall be a text file used only when the +.IR file +operand is specified as +.BR '\(mi' . +Each line of the text file shall be interpreted as an SCCS pathname. +.SH "INPUT FILES" +Any SCCS files interrogated are files of an unspecified format. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR sact : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The output for each named file shall consist of a line in the following +format: +.sp +.RS 4 +.nf +\fB +"%s %s %s %s %s\en", <\fISID\fR>, <\fInew SID\fR>, <\fIlogin\fR>, <\fIdate\fR>, <\fItime\fR> +.fi \fR +.P +.RE +.IP "<\fISID\fR>" 10 +Specifies the SID of a delta that currently exists in the SCCS file to +which changes are made to make the new delta. +.IP "<\fInew\ SID\fR>" 10 +Specifies the SID for the new delta to be created. +.IP "<\fIlogin\fR>" 10 +Contains the login name of the user who makes the delta (that is, who +executed a +.IR get +for editing). +.IP "<\fIdate\fR>" 10 +Contains the date that +.IR get +.BR \(mie +was executed, in the format used by the +.IR prs +.BR :D: +data keyword. +.IP "<\fItime\fR>" 10 +Contains the time that +.IR get +.BR \(mie +was executed, in the format used by the +.IR prs +.BR :T: +data keyword. +.P +If there is more than one named file or if a directory or standard +input is named, each pathname shall be written before each of the +preceding lines: +.sp +.RS 4 +.nf +\fB +"\en%s:\en", <\fIpathname\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for optional informative +messages concerning SCCS files with no impending deltas, and for +diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdelta\fR\^", +.IR "\fIget\fR\^", +.IR "\fIsccs\fR\^", +.IR "\fIunget\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/sccs.1p b/man-pages-posix-2013/man1p/sccs.1p new file mode 100644 index 0000000..765bf08 --- /dev/null +++ b/man-pages-posix-2013/man1p/sccs.1p @@ -0,0 +1,542 @@ +'\" et +.TH SCCS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sccs +\(em front end for the SCCS subsystem (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +sccs \fB[\fR\(mir\fB] [\fR\(mid \fIpath\fB] [\fR\(mip \fIpath\fB] \fIcommand \fB[\fIoptions\fR...\fB] [\fIoperands\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR sccs +utility is a front end to the SCCS programs. It also includes the +capability to run set-user-id to another user to provide additional +protection. +.P +The +.IR sccs +utility shall invoke the specified +.IR command +with the specified +.IR options +and +.IR operands . +By default, each of the +.IR operands +shall be modified by prefixing it with the string +.BR \(dqSCCS/s.\(dq . +.P +The +.IR command +can be the name of one of the SCCS utilities in this volume of POSIX.1\(hy2008 (\c +.IR admin , +.IR delta , +.IR get , +.IR prs , +.IR rmdel , +.IR sact , +.IR unget , +.IR val , +or +.IR what ) +or one of the pseudo-utilities listed in the EXTENDED DESCRIPTION +section. +.SH OPTIONS +The +.IR sccs +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that +.IR options +operands are actually options to be passed to the utility named by +.IR command . +When the portion of the command: +.sp +.RS 4 +.nf +\fB +\fIcommand \fB[\fIoptions\fR ... \fB] [\fIoperands\fR ... \fB]\fR +.fi \fR +.P +.RE +.P +is considered, all of the pseudo-utilities used as +.IR command +shall support the Utility Syntax Guidelines. Any of the other SCCS +utilities that can be invoked in this manner support the Guidelines to +the extent indicated by their individual OPTIONS sections. +.P +The following options shall be supported preceding the +.IR command +operand: +.IP "\fB\(mid\ \fIpath\fR" 10 +A pathname of a directory to be used as a root directory for the SCCS +files. The default shall be the current directory. The +.BR \(mid +option shall take precedence over the +.IR PROJECTDIR +variable. See +.BR \(mip . +.IP "\fB\(mip\ \fIpath\fR" 10 +A pathname of a directory in which the SCCS files are located. The +default shall be the +.BR SCCS +directory. +.RS 10 +.P +The +.BR \(mip +option differs from the +.BR \(mid +option in that the +.BR \(mid +option-argument shall be prefixed to the entire pathname and the +.BR \(mip +option-argument shall be inserted before the final component of the +pathname. For example: +.sp +.RS 4 +.nf +\fB +sccs \(mid /x \(mip y get a/b +.fi \fR +.P +.RE +.P +converts to: +.sp +.RS 4 +.nf +\fB +get /x/a/y/s.b +.fi \fR +.P +.RE +.P +This allows the creation of aliases such as: +.sp +.RS 4 +.nf +\fB +alias syssccs="sccs \(mid /usr/src" +.fi \fR +.P +.RE +.P +which is used as: +.sp +.RS 4 +.nf +\fB +syssccs get cmd/who.c +.fi \fR +.P +.RE +.RE +.IP "\fB\(mir\fP" 10 +Invoke +.IR command +with the real user ID of the process, not any effective user ID that +the +.IR sccs +utility is set to. Certain commands (\c +.IR admin , +.BR check , +.BR clean , +.BR diffs , +.BR info , +.IR rmdel , +and +.BR tell ) +cannot be run set-user-ID by all users, since this would allow anyone +to change the authorizations. These commands are always run as the +real user. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIcommand\fR" 10 +An SCCS utility name or the name of one of the pseudo-utilities listed +in the EXTENDED DESCRIPTION section. +.IP "\fIoptions\fR" 10 +An option or option-argument to be passed to +.IR command . +.IP "\fIoperands\fR" 10 +An operand to be passed to +.IR command . +.SH STDIN +See the utility description for the specified +.IR command . +.SH "INPUT FILES" +See the utility description for the specified +.IR command . +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR sccs : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPROJECTDIR\fP" 10 +.br +Provide a default value for the +.BR \(mid +.IR path +option. If the value of +.IR PROJECTDIR +begins with a +, +it shall be considered an absolute pathname; otherwise, the value of +.IR PROJECTDIR +is treated as a user name and that user's initial working directory +shall be examined for a subdirectory +.BR src +or +.BR source . +If such a directory is found, it shall be used. Otherwise, the value +shall be used as a relative pathname. +.P +Additional environment variable effects may be found in the utility +description for the specified +.IR command . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +See the utility description for the specified +.IR command . +.SH STDERR +See the utility description for the specified +.IR command . +.SH "OUTPUT FILES" +See the utility description for the specified +.IR command . +.SH "EXTENDED DESCRIPTION" +The following pseudo-utilities shall be supported as +.IR command +operands. All options referred to in the following list are values +given in the +.IR options +operands following +.IR command . +.IP "\fBcheck\fR" 8 +Equivalent to +.BR info , +except that nothing shall be printed if nothing is being edited, and a +non-zero exit status shall be returned if anything is being edited. The +intent is to have this included in an ``install'' entry in a makefile +to ensure that everything is included into the SCCS file before a +version is installed. +.IP "\fBclean\fR" 8 +Remove everything from the current directory that can be recreated from +SCCS files, but do not remove any files being edited. If the +.BR \(mib +option is given, branches shall be ignored in the determination of +whether they are being edited; this is dangerous if branches are kept +in the same directory. +.IP "\fBcreate\fR" 8 +Create an SCCS file, taking the initial contents from the file of the +same name. Any options to +.IR admin +are accepted. If the creation is successful, the original files shall +be renamed by prefixing the basenames with a comma. These renamed files +should be removed after it has been verified that the SCCS files have +been created successfully. +.IP "\fBdelget\fR" 8 +Perform a +.IR delta +on the named files and then +.IR get +new versions. The new versions shall have ID keywords expanded and +shall not be editable. Any +.BR \(mim , +.BR \(mip , +.BR \(mir , +.BR \(mis , +and +.BR \(miy +options shall be passed to +.IR delta , +and any +.BR \(mib , +.BR \(mic , +.BR \(mie , +.BR \(mii , +.BR \(mik , +.BR \(mil , +.BR \(mis , +and +.BR \(mix +options shall be passed to +.IR get . +.IP "\fBdeledit\fR" 8 +Equivalent to +.BR delget , +except that the +.IR get +phase shall include the +.BR \(mie +option. This option is useful for making a checkpoint of the current +editing phase. The same options shall be passed to +.IR delta +as described above, and all the options listed for +.IR get +above except +.BR \(mie +shall be passed to +.BR edit . +.IP "\fBdiffs\fR" 8 +Write a difference listing between the current version of the files +checked out for editing and the versions in SCCS format. Any +.BR \(mir , +.BR \(mic , +.BR \(mii , +.BR \(mix , +and +.BR \(mit +options shall be passed to +.IR get ; +any +.BR \(mil , +.BR \(mis , +.BR \(mie , +.BR \(mif , +.BR \(mih , +and +.BR \(mib +options shall be passed to +.IR diff . +A +.BR \(miC +option shall be passed to +.IR diff +as +.BR \(mic . +.IP "\fBedit\fR" 8 +Equivalent to +.IR get +.BR \(mie . +.IP "\fBfix\fR" 8 +Remove the named delta, but leave a copy of the delta with the changes +that were in it. It is useful for fixing small compiler bugs, and so +on. The application shall ensure that it is followed by a +.BR \(mir +.IR SID +option. Since +.BR fix +does not leave audit trails, it should be used carefully. +.IP "\fBinfo\fR" 8 +Write a listing of all files being edited. If the +.BR \(mib +option is given, branches (that is, SIDs with two or fewer components) +shall be ignored. If a +.BR \(miu +.IR user +option is given, then only files being edited by the named user shall +be listed. A +.BR \(miU +option shall be equivalent to +.BR \(miu <\c +.IR "current\ user" >. +.IP "\fBprint\fR" 8 +Write out verbose information about the named files, equivalent to +.IR sccs +.IR prs . +.IP "\fBtell\fR" 8 +Write a +-separated +list of the files being edited to standard output. Takes the +.BR \(mib , +.BR \(miu , +and +.BR \(miU +options like +.BR info +and +.BR check . +.IP "\fBunedit\fR" 8 +This is the opposite of an +.BR edit +or a +.IR get +.BR \(mie . +It should be used with caution, since any changes made since the +.IR get +are lost. +.br +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Many of the SCCS utilities take directory names as operands as well as +specific filenames. The pseudo-utilities supported by +.IR sccs +are not described as having this capability, but are not prohibited +from doing so. +.SH EXAMPLES +.IP " 1." 4 +To get a file for editing, edit it and produce a new delta: +.RS 4 +.sp +.RS 4 +.nf +\fB +sccs get \(mie file.c +ex file.c +sccs delta file.c +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +To get a file from another directory: +.RS 4 +.sp +.RS 4 +.nf +\fB +sccs \(mip /usr/src/sccs/s. get cc.c +.fi \fR +.P +.RE +.P +or: +.sp +.RS 4 +.nf +\fB +sccs get /usr/src/sccs/s.cc.c +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +To make a delta of a large number of files in the current directory: +.RS 4 +.sp +.RS 4 +.nf +\fB +sccs delta *.c +.fi \fR +.P +.RE +.RE +.IP " 4." 4 +To get a list of files being edited that are not on branches: +.RS 4 +.sp +.RS 4 +.nf +\fB +sccs info \(mib +.fi \fR +.P +.RE +.RE +.IP " 5." 4 +To delta everything being edited by the current user: +.RS 4 +.sp +.RS 4 +.nf +\fB +sccs delta $(sccs tell \(miU) +.fi \fR +.P +.RE +.RE +.IP " 6." 4 +In a makefile, to get source files from an SCCS file if it does not +already exist: +.RS 4 +.sp +.RS 4 +.nf +\fB +SRCS = <\fIlist of source files\fP> +$(SRCS): + sccs get $(REL) $@ +.fi \fR +.P +.RE +.RE +.SH RATIONALE +.IR sccs +and its associated utilities are part of the XSI Development +Utilities option within the XSI option. +.P +SCCS is an abbreviation for Source Code Control System. It is a +maintenance and enhancement tracking tool. When a file is put under +SCCS, the source code control system maintains the file and, when +changes are made, identifies and stores them in the file with the +original source code and/or documentation. As other changes are made, +they too are identified and retained in the file. +.P +Retrieval of the original and any set of changes is possible. Any +version of the file as it develops can be reconstructed for inspection +or additional modification. History data can be stored with each +version, documenting why the changes were made, who made them, and when +they were made. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIadmin\fR\^", +.IR "\fIdelta\fR\^", +.IR "\fIget\fR\^", +.IR "\fImake\fR\^", +.IR "\fIprs\fR\^", +.IR "\fIrmdel\fR\^", +.IR "\fIsact\fR\^", +.IR "\fIunget\fR\^", +.IR "\fIval\fR\^", +.IR "\fIwhat\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/sed.1p b/man-pages-posix-2013/man1p/sed.1p new file mode 100644 index 0000000..90428f4 --- /dev/null +++ b/man-pages-posix-2013/man1p/sed.1p @@ -0,0 +1,1067 @@ +'\" et +.TH SED "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sed +\(em stream editor +.SH SYNOPSIS +.LP +.nf +sed \fB[\fR\(min\fB] \fIscript \fB[\fIfile\fR...\fB]\fR +.P +sed \fB[\fR\(min\fB] \fR\(mie \fIscript \fB[\fR\(mie \fIscript\fB]\fR... \fB[\fR\(mif \fIscript_file\fB]\fR... \fB[\fIfile\fR...\fB]\fR +.P +sed \fB[\fR\(min\fB] [\fR\(mie \fIscript\fB]\fR... \(mif \fIscript_file\fR \fB[\fR\(mif \fIscript_file\fB]\fR... \fB[\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR sed +utility is a stream editor that shall read one or more text files, make +editing changes according to a script of editing commands, and write +the results to standard output. The script shall be obtained from +either the +.IR script +operand string or a combination of the option-arguments from the +.BR \(mie +.IR script +and +.BR \(mif +.IR script_file +options. +.SH OPTIONS +The +.IR sed +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that the order of presentation of the +.BR \(mie +and +.BR \(mif +options is significant. +.P +The following options shall be supported: +.IP "\fB\(mie\ \fIscript\fR" 10 +Add the editing commands specified by the +.IR script +option-argument to the end of the script of editing commands. +.IP "\fB\(mif\ \fIscript_file\fR" 10 +Add the editing commands in the file +.IR script_file +to the end of the script of editing commands. +.IP "\fB\(min\fP" 10 +Suppress the default output (in which each line, after it is examined +for editing, is written to standard output). Only lines explicitly +selected for output are written. +.P +If any +.BR \(mie +or +.BR \(mif +options are specified, the script of editing commands shall initially +be empty. The commands specified by each +.BR \(mie +or +.BR \(mif +option shall be added to the script in the order specified. When each +addition is made, if the previous addition (if any) was from a +.BR \(mie +option, a + +shall be inserted before the new addition. The resulting script shall +have the same properties as the +.IR script +operand, described in the OPERANDS section. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file whose contents are read and edited. If multiple +.IR file +operands are specified, the named files shall be read in the order +specified and the concatenation shall be edited. If no +.IR file +operands are specified, the standard input shall be used. +.IP "\fIscript\fR" 10 +A string to be used as the script of editing commands. The application +shall not present a +.IR script +that violates the restrictions of a text file except that the final +character need not be a +. +.SH STDIN +The standard input shall be used if no +.IR file +operands are specified, and shall be used if a +.IR file +operand is +.BR '\(mi' +and the implementation treats the +.BR '\(mi' +as meaning standard input. +Otherwise, the standard input shall not be used. +See the INPUT FILES section. +.SH "INPUT FILES" +The input files shall be text files. The +.IR script_file s +named by the +.BR \(mif +option shall consist of editing commands. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR sed : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular expressions. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files), and the behavior +of character classes within regular expressions. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The input files shall be written to standard output, with the editing +commands specified in the script applied. If the +.BR \(min +option is specified, only those input lines selected by the script +shall be written to standard output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The output files shall be text files whose formats are dependent on the +editing commands given. +.SH "EXTENDED DESCRIPTION" +The +.IR script +shall consist of editing commands of the following form: +.sp +.RS 4 +.nf +\fB +\fB[\fIaddress\fB[\fR,\fIaddress\fB]]\fIfunction\fR +.fi \fR +.P +.RE +.P +where +.IR function +represents a single-character command verb from the list in +.IR "Editing Commands in sed", +followed by any applicable arguments. +.P +The command can be preceded by + +characters and/or + +characters. The function can be preceded by + +characters. These optional characters shall have no effect. +.P +In default operation, +.IR sed +cyclically shall append a line of input, less its terminating + +character, into the pattern space. Reading from input shall be skipped +if a + +was in the pattern space prior to a +.BR D +command ending the previous cycle. The +.IR sed +utility shall then apply in sequence all commands whose addresses select +that pattern space, until a command starts the next cycle or quits. If +no commands explicitly started a new cycle, then at the end of the script +the pattern space shall be copied to standard output (except when +.BR \(min +is specified) and the pattern space shall be deleted. Whenever the +pattern space is written to standard output or a named file, +.IR sed +shall immediately follow it with a +. +.P +Some of the editing commands use a hold space to save all or part of +the pattern space for subsequent retrieval. The pattern and hold spaces +shall each be able to hold at least 8\|192 bytes. +.SS "Addresses in sed" +.P +An address is either a decimal number that counts input lines +cumulatively across files, a +.BR '$' +character that addresses the last line of input, or a context address +(which consists of a BRE, as described in +.IR "Regular Expressions in sed", +preceded and followed by a delimiter, usually a +). +.P +An editing command with no addresses shall select every pattern space. +.P +An editing command with one address shall select each pattern space +that matches the address. +.P +An editing command with two addresses shall select the inclusive range +from the first pattern space that matches the first address through the +next pattern space that matches the second. (If the second address is a +number less than or equal to the line number first selected, only one +line shall be selected.) Starting at the first line following the +selected range, +.IR sed +shall look again for the first address. Thereafter, the process shall +be repeated. Omitting either or both of the address components in the +following form produces undefined results: +.sp +.RS 4 +.nf +\fB +\fB[\fIaddress\fB[\fR,\fIaddress\fB]]\fR +.fi \fR +.P +.RE +.SS "Regular Expressions in sed" +.P +The +.IR sed +utility shall support the BREs described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 9.3" ", " "Basic Regular Expressions", +with the following additions: +.IP " *" 4 +In a context address, the construction +.BR \(dq\ecBREc\(dq , +where +.IR c +is any character other than + +or +, +shall be identical to +.BR \(dq/BRE/\(dq . +If the character designated by +.IR c +appears following a +, +then it shall be considered to be that literal character, which shall +not terminate the BRE. For example, in the context address +.BR \(dq\exabc\exdefx\(dq , +the second +.IR x +stands for itself, so that the BRE is +.BR \(dqabcxdef\(dq . +.IP " *" 4 +The escape sequence +.BR '\en' +shall match a + +embedded in the pattern space. A literal + +shall not be used in the BRE of a context address or in the substitute +function. +.IP " *" 4 +If an RE is empty (that is, no pattern is specified) +.IR sed +shall behave as if the last RE used in the last command applied (either +as an address or as part of a substitute command) was specified. +.SS "Editing Commands in sed" +.P +In the following list of editing commands, the maximum number of +permissible addresses for each function is indicated by [\c +.IR 0addr ], +[\c +.IR 1addr ], +or [\c +.IR 2addr ], +representing zero, one, or two addresses. +.P +The argument +.IR text +shall consist of one or more lines. Each embedded + +in the text shall be preceded by a +. +Other + +characters in text shall be removed, and the following character shall +be treated literally. +.P +The +.BR r +and +.BR w +command verbs, and the +.IR w +flag to the +.BR s +command, take an +.IR rfile +(or +.IR wfile ) +parameter, separated from the command verb letter or flag by one or +more + +characters; implementations may allow zero separation as an extension. +.P +The argument +.IR rfile +or the argument +.IR wfile +shall terminate the editing command. Each +.IR wfile +shall be created before processing begins. Implementations shall +support at least ten +.IR wfile +arguments in the script; the actual number (greater than or equal to +10) that is supported by the implementation is unspecified. The +use of the +.IR wfile +parameter shall cause that file to be initially created, if it does not +exist, or shall replace the contents of an existing file. +.P +The +.BR b , +.BR r , +.BR s , +.BR t , +.BR w , +.BR y , +and +.BR : +command verbs shall accept additional arguments. The following synopses +indicate which arguments shall be separated from the command verbs by a +single +. +.P +The +.BR a +and +.BR r +commands schedule text for later output. The text specified for the +.BR a +command, and the contents of the file specified for the +.BR r +command, shall be written to standard output just before the next +attempt to fetch a line of input when executing the +.BR N +or +.BR n +commands, or when reaching the end of the script. If written when +reaching the end of the script, and the +.BR \(min +option was not specified, the text shall be written after copying the +pattern space to standard output. The contents of the file specified +for the +.BR r +command shall be as of the time the output is written, not the time the +.BR r +command is applied. The text shall be output in the order in which the +.BR a +and +.BR r +commands were applied to the input. +.P +Command verbs other than +.BR { , +.BR a , +.BR b , +.BR c , +.BR i , +.BR r , +.BR t , +.BR w , +.BR : , +and +.BR # +can be followed by a +, +optional + +characters, and another command verb. However, when the +.BR s +command verb is used with the +.IR w +flag, following it with another command in this manner produces +undefined results. +.P +A function can be preceded by one or more +.BR '!' +characters, in which case the function shall be applied if the +addresses do not select the pattern space. Zero or more + +characters shall be accepted before the first +.BR '!' +character. It is unspecified whether + +characters can follow a +.BR '!' +character, and conforming applications shall not follow a +.BR '!' +character with + +characters. +.IP "\fB[\fI2addr\fB]\ {\fIediting command\fR" 10 +.IP "\fIediting command\fR" 10 +.IP ".\|.\|." 10 +.IP "\fB}\fR" 10 +Execute a list of +.IR sed +editing commands only when the pattern space is selected. The list of +.IR sed +editing commands shall be surrounded by braces and separated by + +characters, and conform to the following rules. The braces can be preceded +or followed by + +characters. The editing commands can be preceded by + +characters, but shall not be followed by + +characters. The + +shall be preceded by a + +and can be preceded or followed by + +characters. +.IP "\fB[\fI1addr\fB]a\e\fR" 10 +.IP "\fItext\fR" 10 +Write text to standard output as described previously. +.IP "\fB[\fI2addr\fB]b\ [\fIlabel\fB]\fR" 10 +.br +Branch to the +.BR : +function bearing the +.IR label . +If +.IR label +is not specified, branch to the end of the script. The implementation +shall support +.IR label s +recognized as unique up to at least 8 characters; the actual length +(greater than or equal to 8) that shall be supported by the +implementation is unspecified. It is unspecified whether exceeding a +label length causes an error or a silent truncation. +.IP "\fB[\fI2addr\fB]c\e\fR" 10 +.IP "\fItext\fR" 10 +Delete the pattern space. With a 0 or 1 address or at the end of a +2-address range, place +.IR text +on the output and start the next cycle. +.IP "\fB[\fI2addr\fB]d\fR" 10 +Delete the pattern space and start the next cycle. +.IP "\fB[\fI2addr\fB]D\fR" 10 +If the pattern space contains no +, +delete the pattern space and start a normal new cycle as if the +.BR d +command was issued. Otherwise, delete the initial segment of the +pattern space through the first +, +and start the next cycle with the resultant pattern space and without +reading any new input. +.IP "\fB[\fI2addr\fB]g\fR" 10 +Replace the contents of the pattern space by the contents of the hold +space. +.IP "\fB[\fI2addr\fB]G\fR" 10 +Append to the pattern space a + +followed by the contents of the hold space. +.IP "\fB[\fI2addr\fB]h\fR" 10 +Replace the contents of the hold space with the contents of the pattern +space. +.IP "\fB[\fI2addr\fB]H\fR" 10 +Append to the hold space a + +followed by the contents of the pattern space. +.IP "\fB[\fI1addr\fB]i\e\fR" 10 +.IP "\fItext\fR" 10 +Write +.IR text +to standard output. +.IP "\fB[\fI2addr\fB]l\fR" 10 +(The letter ell.) Write the pattern space to standard output in a +visually unambiguous form. The characters listed in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Table 5-1" ", " "Escape Sequences and Associated Actions" +(\c +.BR '\e\e' , +.BR '\ea' , +.BR '\eb' , +.BR '\ef' , +.BR '\er' , +.BR '\et' , +.BR '\ev' ) +shall be written as the corresponding escape sequence; the +.BR '\en' +in that table is not applicable. Non-printable characters not in that +table shall be written as one three-digit octal number (with a +preceding +) +for each byte in the character (most significant byte first). +.RS 10 +.P +Long lines shall be folded, with the point of folding indicated by +writing a + +followed by a +; +the length at which folding occurs is unspecified, but should be +appropriate for the output device. The end of each line shall be marked +with a +.BR '$' . +.RE +.IP "\fB[\fI2addr\fB]n\fR" 10 +Write the pattern space to standard output if the default output has +not been suppressed, and replace the pattern space with the next line +of input, less its terminating +. +.RS 10 +.P +If no next line of input is available, the +.BR n +command verb shall branch to the end of the script and quit without +starting a new cycle. +.RE +.IP "\fB[\fI2addr\fB]N\fR" 10 +Append the next line of input, less its terminating +, +to the pattern space, using an embedded + +to separate the appended material from the original material. Note that +the current line number changes. +.RS 10 +.P +If no next line of input is available, the +.BR N +command verb shall branch to the end of the script and quit without +starting a new cycle or copying the pattern space to standard output. +.RE +.IP "\fB[\fI2addr\fB]p\fR" 10 +Write the pattern space to standard output. +.IP "\fB[\fI2addr\fB]P\fR" 10 +Write the pattern space, up to the first +, +to standard output. +.IP "\fB[\fI1addr\fB]q\fR" 10 +Branch to the end of the script and quit without starting a new cycle. +.IP "\fB[\fI1addr\fB]r\ \fIrfile\fR" 10 +Copy the contents of +.IR rfile +to standard output as described previously. If +.IR rfile +does not exist or cannot be read, it shall be treated as if it were an +empty file, causing no error condition. +.IP "\fB[\fI2addr\fB]s/\fIBRE\fB/\fIreplacement\fB/\fIflags\fR" 10 +.br +Substitute the replacement string for instances of the BRE in the +pattern space. Any character other than + +or + +can be used instead of a + +to delimit the BRE and the replacement. Within the BRE and the +replacement, the BRE delimiter itself can be used as a literal character +if it is preceded by a +. +.RS 10 +.P +The replacement string shall be scanned from beginning to end. An + +(\c +.BR '&' ) +appearing in the replacement shall be replaced by the string matching +the BRE. The special meaning of +.BR '&' +in this context can be suppressed by preceding it by a +. +The characters \fR"\e\fIn"\fR, where +.IR n +is a digit, shall be replaced by the text matched by the corresponding +back-reference expression. If the corresponding back-reference expression +does not match, then the characters \fR"\e\fIn"\fR shall be replaced +by the empty string. The special meaning of \fR"\e\fIn"\fR where +.IR n +is a digit in this context, can be suppressed by preceding it by a +. +For each other + +encountered, the following character shall lose its special meaning (if +any). The meaning of a + +immediately followed by any character other than +.BR '&' , +, +a digit, or the delimiter character used for this command, is +unspecified. +.P +A line can be split by substituting a + +into it. The application shall escape the + +in the replacement by preceding it by a +. +A substitution shall be considered to have been performed even if the +replacement string is identical to the string that it replaces. Any + +used to alter the default meaning of a subsequent character shall be +discarded from the BRE or the replacement before evaluating the BRE or +using the replacement. +.P +The value of +.IR flags +shall be zero or more of: +.IP "\fIn\fR" 10 +Substitute for the +.IR n th +occurrence only of the BRE found within the pattern space. +.IP "\fBg\fR" 10 +Globally substitute for all non-overlapping instances of the BRE rather +than just the first one. If both +.BR g +and +.IR n +are specified, the results are unspecified. +.IP "\fBp\fR" 10 +Write the pattern space to standard output if a replacement was made. +.IP "\fBw\ \fIwfile\fR" 10 +Write. Append the pattern space to +.IR wfile +if a replacement was made. A conforming application shall precede the +.IR wfile +argument with one or more + +characters. If the +.BR w +flag is not the last flag value given in a concatenation of multiple +flag values, the results are undefined. +.RE +.IP "\fB[\fI2addr\fB]t\ [\fIlabel\fB]\fR" 10 +.br +Test. Branch to the +.BR : +command verb bearing the +.IR label +if any substitutions have been made since the most recent reading of an +input line or execution of a +.BR t . +If +.IR label +is not specified, branch to the end of the script. +.IP "\fB[\fI2addr\fB]w\ \fIwfile\fR" 10 +.br +Append (write) the pattern space to +.IR wfile . +.IP "\fB[\fI2addr\fB]x\fR" 10 +Exchange the contents of the pattern and hold spaces. +.IP "\fB[\fI2addr\fB]y/\fIstring1\fB/\fIstring2\fB/\fR" 10 +.br +Replace all occurrences of characters in +.IR string1 +with the corresponding characters in +.IR string2 . +If a + +followed by an +.BR 'n' +appear in +.IR string1 +or +.IR string2 , +the two characters shall be handled as a single +. +If the number of characters in +.IR string1 +and +.IR string2 +are not equal, or if any of the characters in +.IR string1 +appear more than once, the results are undefined. Any character other +than + +or + +can be used instead of + +to delimit the strings. If the delimiter is not +.BR 'n' , +within +.IR string1 +and +.IR string2 , +the delimiter itself can be used as a literal character if it is +preceded by a +. +If a + +character is immediately followed by a + +character in +.IR string1 +or +.IR string2 , +the two + +characters shall be counted as a single literal + +character. The meaning of a + +followed by any character that is not +.BR 'n' , +a +, +or the delimiter character is undefined. +.IP "\fB[\fI0addr\fB]:\fIlabel\fR" 10 +Do nothing. This command bears a +.IR label +to which the +.BR b +and +.BR t +commands branch. +.IP "\fB[\fI1addr\fB]=\fR" 10 +Write the following to standard output: +.RS 10 +.sp +.RS 4 +.nf +\fB +"%d\en", <\fIcurrent line number\fR> +.fi \fR +.P +.RE +.RE +.IP "\fB[\fI0addr\fB]\fR" 10 +Ignore this empty command. +.IP "\fB[\fI0addr\fB]#\fR" 10 +Ignore the +.BR '#' +and the remainder of the line (treat them as a comment), with the +single exception that if the first two characters in the script are +.BR \(dq#n\(dq , +the default output shall be suppressed; this shall be the equivalent of +specifying +.BR \(min +on the command line. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Regular expressions match entire strings, not just individual lines, +but a + +is matched by +.BR '\en' +in a +.IR sed +RE; a + +is not allowed by the general definition of regular expression in +POSIX.1\(hy2008. Also note that +.BR '\en' +cannot be used to match a + +at the end of an arbitrary input line; + +characters appear in the pattern space as a result of the +.BR N +editing command. +.SH EXAMPLES +This +.IR sed +script simulates the BSD +.IR cat +.BR \(mis +command, squeezing excess empty lines from standard input. +.sp +.RS 4 +.nf +\fB +sed \(min ' +# Write non-empty lines. +/./ { + p + d + } +# Write a single empty line, then look for more empty lines. +/^$/ p +# Get next line, discard the held (empty line), +# and look for more empty lines. +:Empty +/^$/ { + N + s/.// + b Empty + } +# Write the non-empty line before going back to search +# for the first in a set of empty lines. + p +\&' +.fi \fR +.P +.RE +.P +The following +.IR sed +command is a much simpler method of squeezing empty lines, although +it is not quite the same as +.IR cat +.BR \(mis +since it removes any initial empty lines: +.sp +.RS 4 +.nf +\fB +sed \(min '/./,/^$/p' +.fi \fR +.P +.RE +.SH RATIONALE +This volume of POSIX.1\(hy2008 requires implementations to support at least ten distinct +.IR wfile s, +matching historical practice on many implementations. Implementations +are encouraged to support more, but conforming applications should not +exceed this limit. +.P +The exit status codes specified here are different from those in System +V. System V returns 2 for garbled +.IR sed +commands, but returns zero with its usage message or if the input file +could not be opened. The standard developers considered this to be a +bug. +.P +The manner in which the +.BR l +command writes non-printable characters was changed to avoid +the historical backspace-overstrike method, and other requirements to +achieve unambiguous output were added. See the RATIONALE for +.IR "\fIed\fR\^" +for details of the format chosen, which is the same as that chosen for +.IR sed . +.P +This volume of POSIX.1\(hy2008 requires implementations to provide pattern and hold spaces of at +least 8\|192 bytes, larger than the 4\|000 bytes spaces used by some +historical implementations, but less than the 20\|480 bytes limit used +in an early proposal. Implementations are encouraged to allocate +dynamically larger pattern and hold spaces as needed. +.P +The requirements for acceptance of + +and + +characters in command lines has been made more explicit than in early +proposals to describe clearly the historical practice and to remove +confusion about the phrase ``protect initial blanks [\fIsic\fP] and tabs +from the stripping that is done on every script line'' that appears in +much of the historical documentation of the +.IR sed +utility description of text. (Not all implementations are known to have +stripped + +characters from text lines, although they all have allowed leading + +characters preceding the address on a command line.) +.P +The treatment of +.BR '#' +comments differs from the SVID which only allows a comment as the first +line of the script, but matches BSD-derived implementations. The +comment character is treated as a command, and it has the same +properties in terms of being accepted with leading + +characters; the BSD implementation has historically supported this. +.P +Early proposals required that a +.IR script_file +have at least one non-comment line. Some historical implementations +have behaved in unexpected ways if this were not the case. The standard +developers considered that this was incorrect behavior and that +application developers should not have to avoid this feature. A correct +implementation of this volume of POSIX.1\(hy2008 shall permit +.IR script_file s +that consist only of comment lines. +.P +Early proposals indicated that if +.BR \(mie +and +.BR \(mif +options were intermixed, all +.BR \(mie +options were processed before any +.BR \(mif +options. This has been changed to process them in the order presented +because it matches historical practice and is more intuitive. +.P +The treatment of the +.BR p +flag to the +.BR s +command differs between System V and BSD-based systems when the default +output is suppressed. In the two examples: +.sp +.RS 4 +.nf +\fB +echo a | sed 's/a/A/p' +echo a | sed \(min 's/a/A/p' +.fi \fR +.P +.RE +.P +this volume of POSIX.1\(hy2008, BSD, System V documentation, and the SVID indicate that the +first example should write two lines with +.BR A , +whereas the second should write one. Some System V systems write the +.BR A +only once in both examples because the +.BR p +flag is ignored if the +.BR \(min +option is not specified. +.P +This is a case of a diametrical difference between systems that could +not be reconciled through the compromise of declaring the behavior to +be unspecified. The SVID/BSD/System V documentation behavior was +adopted for this volume of POSIX.1\(hy2008 because: +.IP " *" 4 +No known documentation for any historic system describes the +interaction between the +.BR p +flag and the +.BR \(min +option. +.IP " *" 4 +The selected behavior is more correct as there is no technical +justification for any interaction between the +.BR p +flag and the +.BR \(min +option. A relationship between +.BR \(min +and the +.BR p +flag might imply that they are only used together, but this ignores +valid scripts that interrupt the cyclical nature of the processing +through the use of the +.BR D , +.BR d , +.BR q , +or branching commands. Such scripts rely on the +.BR p +suffix to write the pattern space because they do not make use of the +default output at the ``bottom'' of the script. +.IP " *" 4 +Because the +.BR \(min +option makes the +.BR p +flag unnecessary, any interaction would only be useful if +.IR sed +scripts were written to run both with and without the +.BR \(min +option. This is believed to be unlikely. It is even more unlikely that +programmers have coded the +.BR p +flag expecting it to be unnecessary. Because the interaction was not +documented, the likelihood of a programmer discovering the interaction +and depending on it is further decreased. +.IP " *" 4 +Finally, scripts that break under the specified behavior produce too +much output instead of too little, which is easier to diagnose and +correct. +.P +The form of the substitute command that uses the +.BR n +suffix was limited to the first 512 matches in an early proposal. This +limit has been removed because there is no reason an editor processing +lines of +{LINE_MAX} +length should have this restriction. The command +.BR "s/a/A/2047" +should be able to substitute the 2\|047th occurrence of +.BR a +on a line. +.P +The +.BR b , +.BR t , +and +.BR : +commands are documented to ignore leading white space, but no mention +is made of trailing white space. Historical implementations of +.IR sed +assigned different locations to the labels +.BR 'x' +and +.BR \(dqx\ \(dq . +This is not useful, and leads to subtle programming errors, but it is +historical practice, and changing it could theoretically break working +scripts. Implementors are encouraged to provide warning messages about +labels that are never used or jumps to labels that do not exist. +.P +Historically, the +.IR sed +.BR ! +and +.BR } +editing commands did not permit multiple commands on a single line +using a + +as a command delimiter. Implementations are permitted, but not required, +to support this extension. +.P +Earlier versions of this standard allowed for implementations with +bytes other than eight bits, but this has been modified in this +version. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIawk\fR\^", +.IR "\fIed\fR\^", +.IR "\fIgrep\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Table 5-1" ", " "Escape Sequences and Associated Actions", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 9.3" ", " "Basic Regular Expressions", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/set.1p b/man-pages-posix-2013/man1p/set.1p new file mode 100644 index 0000000..8db4db1 --- /dev/null +++ b/man-pages-posix-2013/man1p/set.1p @@ -0,0 +1,806 @@ +'\" et +.TH SET "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +set +\(em set or unset options and positional parameters +.SH SYNOPSIS +.LP +.nf +set \fB[\fR\(miabCefhmnuvx\fB] [\fR\(mio \fIoption\fB] [\fIargument\fR...\fB]\fR +.P +set \fB[\fR+abCefhmnuvx\fB] [\fR+o \fIoption\fB] [\fIargument\fR...\fB]\fR +.P +set \(mi\|\(mi\fB [\fIargument\fR...\fB]\fR +.P +set \(mio +.P +set +o +.fi +.SH DESCRIPTION +If no +.IR option s +or +.IR argument s +are specified, +.IR set +shall write the names and values of all shell variables in the collation +sequence of the current locale. Each +.IR name +shall start on a separate line, using the format: +.sp +.RS 4 +.nf +\fB +"%s=%s\en", <\fIname\fR>, <\fIvalue\fR> +.fi \fR +.P +.RE +.P +The +.IR value +string shall be written with appropriate quoting; see the description +of shell quoting in +.IR "Section 2.2" ", " "Quoting". +The output shall be suitable for reinput to the shell, setting or +resetting, as far as possible, the variables that are currently set; +read-only variables cannot be reset. +.P +When options are specified, they shall set or unset attributes of the +shell, as described below. When +.IR argument s +are specified, they cause positional parameters to be set or unset, as +described below. Setting or unsetting attributes and positional +parameters are not necessarily related actions, but they can be +combined in a single invocation of +.IR set . +.P +The +.IR set +special built-in shall support the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +except that options can be specified with either a leading + +(meaning enable the option) or + +(meaning disable it) unless otherwise specified. +.P +Implementations shall support the options in the following list in both +their + +and + +forms. These options can also be specified as options to +.IR sh . +.IP "\fB\(mia\fP" 6 +When this option is on, the +.IR export +attribute shall be set for each variable to which an assignment is +performed; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.22" ", " "Variable Assignment". +If the assignment precedes a utility name in a command, the +.IR export +attribute shall not persist in the current execution environment after +the utility completes, with the exception that preceding one of the +special built-in utilities causes the +.IR export +attribute to persist after the built-in has completed. If the +assignment does not precede a utility name in the command, or if the +assignment is a result of the operation of the +.IR getopts +or +.IR read +utilities, the +.IR export +attribute shall persist until the variable is unset. +.IP "\fB\(mib\fP" 6 +This option shall be supported if the implementation supports the User +Portability Utilities option. It shall cause the shell to notify the +user asynchronously of background job completions. The following +message is written to standard error: +.RS 6 +.sp +.RS 4 +.nf +\fB +"[%d]%c %s%s\en", <\fIjob-number\fR>, <\fIcurrent\fR>, <\fRstatus\fR>, <\fRjob-name\fR> +.fi \fR +.P +.RE +.P +where the fields shall be as follows: +.IP "<\fIcurrent\fR>" 12 +The character +.BR '+' +identifies the job that would be used as a default for the +.IR fg +or +.IR bg +utilities; this job can also be specified using the +.IR job_id +.BR \(dq%+\(dq +or +.BR \(dq%%\(dq . +The character +.BR '\(mi' +identifies the job that would become the +default if the current default job were to exit; this job can also be +specified using the +.IR job_id +.BR \(dq%\(mi\(dq . +For other jobs, this field is a +. +At most one job can be identified with +.BR '+' +and at most one job can be identified with +.BR '\(mi' . +If there is any suspended job, then the current job shall be a +suspended job. If there are at least two suspended jobs, then the +previous job also shall be a suspended job. +.IP "<\fIjob-number\fR>" 12 +A number that can be used to identify the process group to the +.IR wait , +.IR fg , +.IR bg , +and +.IR kill +utilities. Using these utilities, the job can be identified by +prefixing the job number with +.BR '%' . +.IP "<\fIstatus\fR>" 12 +Unspecified. +.IP "<\fIjob-name\fR>" 12 +Unspecified. +.P +When the shell notifies the user a job has been completed, it may +remove the job's process ID from the list of those known in the current +shell execution environment; see +.IR "Section 2.9.3.1" ", " "Examples". +Asynchronous notification shall not be enabled by default. +.RE +.IP "\fB\(miC\fP" 6 +(Uppercase C.) Prevent existing files from being overwritten by the +shell's +.BR '>' +redirection operator (see +.IR "Section 2.7.2" ", " "Redirecting Output"); +the +.BR \(dq>|\(dq +redirection operator shall override this +.IR noclobber +option for an individual file. +.IP "\fB\(mie\fP" 6 +When this option is on, when any command fails (for any of the reasons +listed in +.IR "Section 2.8.1" ", " "Consequences of Shell Errors" +or by returning an exit status greater than zero), the shell immediately +shall exit with the following exceptions: +.RS 6 +.IP " 1." 4 +The failure of any individual command in a multi-command pipeline shall +not cause the shell to exit. Only the failure of the pipeline itself +shall be considered. +.IP " 2." 4 +The +.BR \(mie +setting shall be ignored when executing the compound list following the +.BR while , +.BR until , +.BR if , +or +.BR elif +reserved word, a pipeline beginning with the +.BR ! +reserved word, or any command of an AND-OR list other than the last. +.IP " 3." 4 +If the exit status of a compound command other than a subshell command +was the result of a failure while +.BR \(mie +was being ignored, then +.BR \(mie +shall not apply to this command. +.P +This requirement applies to the shell environment and each subshell +environment separately. For example, in: +.sp +.RS 4 +.nf +\fB +set -e; (false; echo one) | cat; echo two +.fi \fR +.P +.RE +.P +the +.IR false +command causes the subshell to exit without executing +.IR "echo one" ; +however, +.IR "echo two" +is executed because the exit status of the pipeline +.IR "(false; echo one) | cat" +is zero. +.RE +.IP "\fB\(mif\fP" 6 +The shell shall disable pathname expansion. +.IP "\fB\(mih\fP" 6 +Locate and remember utilities invoked by functions as those functions +are defined (the utilities are normally located when the function is +executed). +.IP "\fB\(mim\fP" 6 +This option shall be supported if the implementation supports the User +Portability Utilities option. All jobs shall be run in their own +process groups. Immediately before the shell issues a prompt after +completion of the background job, a message reporting the exit status +of the background job shall be written to standard error. If a +foreground job stops, the shell shall write a message to standard error +to that effect, formatted as described by the +.IR jobs +utility. In addition, if a job changes status other than exiting (for +example, if it stops for input or output or is stopped by a SIGSTOP +signal), the shell shall write a similar message immediately prior to +writing the next prompt. This option is enabled by default for +interactive shells. +.IP "\fB\(min\fP" 6 +The shell shall read commands but does not execute them; this can be +used to check for shell script syntax errors. An interactive shell may +ignore this option. +.IP "\fB\(mio\fP" 6 +Write the current settings of the options to standard output in an +unspecified format. +.IP "\fB+o\fP" 6 +Write the current option settings to standard output in a format that +is suitable for reinput to the shell as commands that achieve the same +options settings. +.IP "\fB\(mio\ \fIoption\fR" 6 +.br +This option is supported if the system supports the User Portability +Utilities option. It shall set various options, many of which shall be +equivalent to the single option letters. The following values of +.IR option +shall be supported: +.RS 6 +.IP "\fIallexport\fR" 10 +Equivalent to +.BR \(mia . +.IP "\fIerrexit\fR" 10 +Equivalent to +.BR \(mie . +.IP "\fIignoreeof\fR" 10 +Prevent an interactive shell from exiting on end-of-file. This setting +prevents accidental logouts when +\(hyD +is entered. A user shall explicitly +.IR exit +to leave the interactive shell. +.IP "\fImonitor\fR" 10 +Equivalent to +.BR \(mim . +This option is supported if the system supports the User Portability +Utilities option. +.IP "\fInoclobber\fR" 10 +Equivalent to +.BR \(miC +(uppercase C). +.IP "\fInoglob\fR" 10 +Equivalent to +.BR \(mif . +.IP "\fInoexec\fR" 10 +Equivalent to +.BR \(min . +.IP "\fInolog\fR" 10 +Prevent the entry of function definitions into the command history; see +.IR "Command History List". +.IP "\fInotify\fR" 10 +Equivalent to +.BR \(mib . +.IP "\fInounset\fR" 10 +Equivalent to +.BR \(miu . +.IP "\fIverbose\fR" 10 +Equivalent to +.BR \(miv . +.IP "\fIvi\fR" 10 +Allow shell command line editing using the built-in +.IR vi +editor. Enabling +.IR vi +mode shall disable any other command line editing mode provided as an +implementation extension. +.RS 10 +.P +It need not be possible to set +.IR vi +mode on for certain block-mode terminals. +.RE +.IP "\fIxtrace\fR" 10 +Equivalent to +.BR \(mix . +.RE +.IP "\fB\(miu\fP" 6 +When the shell tries to expand an unset parameter other than the +.BR '@' +and +.BR '*' +special parameters, it shall write a message to standard error and shall +not execute the command containing the expansion, but for the purposes +of setting the +.BR '?' +special parameter and the exit status of the shell the command shall be +treated as having been executed and returned an exit status of between +1 and 125 inclusive. A non-interactive shell shall immediately exit. An +interactive shell shall not exit. +.IP "\fB\(miv\fP" 6 +The shell shall write its input to standard error as it is read. +.IP "\fB\(mix\fP" 6 +The shell shall write to standard error a trace for each command after +it expands the command and before it executes it. It is unspecified +whether the command that turns tracing off is traced. +.P +The default for all these options shall be off (unset) unless stated +otherwise in the description of the option or unless the shell was +invoked with them on; see +.IR sh . +.P +The remaining arguments shall be assigned in order to the positional +parameters. The special parameter +.BR '#' +shall be set to reflect the number of positional parameters. All +positional parameters shall be unset before any new values are +assigned. +.P +If the first argument is +.BR '\(mi' , +the results are unspecified. +.P +The special argument +.BR \(dq\(mi\|\(mi\(dq +immediately following the +.IR set +command name can be used to delimit the arguments if the first argument +begins with +.BR '+' +or +.BR '\(mi' , +or to prevent inadvertent listing of all shell variables when there are +no arguments. The command +.IR set +.BR \(mi\|\(mi +without +.IR argument +shall unset all positional parameters and set the special parameter +.BR '#' +to zero. +.SH OPTIONS +See the DESCRIPTION. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +See the DESCRIPTION. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +Zero. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Application writers should avoid relying on +.IR set +.BR \(mie +within functions. For example, in the following script: +.sp +.RS 4 +.nf +\fB +set -e +start() { + some_server + echo some_server started successfully +} +start || echo >&2 some_server failed +.fi \fR +.P +.RE +.P +the +.BR \(mie +setting is ignored within the function body (because the function is a +command in an AND-OR list other than the last). Therefore, if +.IR some_server +fails, the function carries on to echo +.BR \(dqsome_server started successfully\(dq , +and the exit status of the function is zero (which means +.BR \(dqsome_server failed\(dq +is not output). +.SH EXAMPLES +Write out all variables and their values: +.sp +.RS 4 +.nf +\fB +set +.fi \fR +.P +.RE +.P +Set $1, $2, and $3 and set +.BR \(dq$#\(dq +to 3: +.sp +.RS 4 +.nf +\fB +set c a b +.fi \fR +.P +.RE +.P +Turn on the +.BR \(mix +and +.BR \(miv +options: +.sp +.RS 4 +.nf +\fB +set \(mixv +.fi \fR +.P +.RE +.P +Unset all positional parameters: +.sp +.RS 4 +.nf +\fB +set \(mi\|\(mi +.fi \fR +.P +.RE +.P +Set $1 to the value of +.IR x , +even if it begins with +.BR '\(mi' +or +.BR '+' : +.sp +.RS 4 +.nf +\fB +set \(mi\|\(mi "$x" +.fi \fR +.P +.RE +.P +Set the positional parameters to the expansion of +.IR x , +even if +.IR x +expands with a leading +.BR '\(mi' +or +.BR '+' : +.sp +.RS 4 +.nf +\fB +set \(mi\|\(mi $x +.fi \fR +.P +.RE +.SH "RATIONALE" +The +.IR set +\(mi\|\(mi form is listed specifically in the SYNOPSIS even though this +usage is implied by the Utility Syntax Guidelines. The explanation of +this feature removes any ambiguity about whether the +.IR set +\(mi\|\(mi form might be misinterpreted as being equivalent to +.IR set +without any options or arguments. The functionality of this form has +been adopted from the KornShell. In System V, +.IR set +\(mi\|\(mi only unsets parameters if there is at least one argument; +the only way to unset all parameters is to use +.IR shift . +Using the KornShell version should not affect System V scripts because +there should be no reason to issue it without arguments deliberately; +if it were issued as, for example: +.sp +.RS 4 +.nf +\fB +set \(mi\|\(mi "$@" +.fi \fR +.P +.RE +.P +and there were in fact no arguments resulting from +.BR \(dq$@\(dq , +unsetting the parameters would have no result. +.P +The +.IR set ++ form in early proposals was omitted as being an unnecessary +duplication of +.IR set +alone and not widespread historical practice. +.P +The +.IR noclobber +option was changed to allow +.IR set +.BR \(miC +as well as the +.IR set +.BR \(mio +.IR noclobber +option. The single-letter version was added so that the historical +.BR \(dq$\(mi\(dq +paradigm would not be broken; see +.IR "Section 2.5.2" ", " "Special Parameters". +.P +The description of the +.BR \(mie +option is intended to match the behavior of the 1988 version of the +KornShell. +.P +The +.BR \(mih +flag is related to command name hashing. See +.IR "\fIhash\fR\^". +.P +The following +.IR set +flags were omitted intentionally with the following rationale: +.IP "\fB\(mik\fP" 6 +The +.BR \(mik +flag was originally added by the author of the Bourne shell to make it +easier for users of pre-release versions of the shell. In early +versions of the Bourne shell the construct +.IR set +.IR name =\c +.IR value +had to be used to assign values to shell variables. The problem with +.BR \(mik +is that the behavior affects parsing, virtually precluding writing any +compilers. To explain the behavior of +.BR \(mik , +it is necessary to describe the parsing algorithm, which is +implementation-defined. For example: +.RS 6 +.sp +.RS 4 +.nf +\fB +set \(mik; echo \fIname\fR=\fIvalue\fR +.fi \fR +.P +.RE +.P +and: +.sp +.RS 4 +.nf +\fB +set \(mik +echo \fIname\fP=\fIvalue\fR +.fi \fR +.P +.RE +.P +behave differently. The interaction with functions is even more +complex. What is more, the +.BR \(mik +flag is never needed, since the command line could have been +reordered. +.RE +.IP "\fB\(mit\fP" 6 +The +.BR \(mit +flag is hard to specify and almost never used. The only known use could +be done with here-documents. Moreover, the behavior with +.IR ksh +and +.IR sh +differs. The reference page says that it exits after reading and +executing one command. What is one command? If the input is +.IR date ;\c +.IR date , +.IR sh +executes both +.IR date +commands while +.IR ksh +does only the first. +.P +Consideration was given to rewriting +.IR set +to simplify its confusing syntax. A specific suggestion was that the +.IR unset +utility should be used to unset options instead of using the non-\c +\fIgetopt\fR()\c +-able +\c +.IR option +syntax. However, the conclusion was reached that the historical +practice of using +\c +.IR option +was satisfactory and that there was no compelling reason to modify such +widespread historical practice. +.P +The +.BR \(mio +option was adopted from the KornShell to address user needs. In +addition to its generally friendly interface, +.BR \(mio +is needed to provide the +.IR vi +command line editing mode, for which historical practice yields no +single-letter option name. (Although it might have been possible to +invent such a letter, it was recognized that other editing modes would +be developed and +.BR \(mio +provides ample name space for describing such extensions.) +.P +Historical implementations are inconsistent in the format used for +.BR \(mio +option status reporting. The +.BR +o +format without an option-argument was added to allow portable access to +the options that can be saved and then later restored using, for +instance, a dot script. +.P +Historically, +.IR sh +did trace the command +.IR set +.BR +x , +but +.IR ksh +did not. +.P +The +.IR ignoreeof +setting prevents accidental logouts when the end-of-file character +(typically +\(hyD) +is entered. A user shall explicitly +.IR exit +to leave the interactive shell. +.P +The +.IR set +.BR \(mim +option was added to apply only to the UPE because it applies primarily +to interactive use, not shell script applications. +.P +The ability to do asynchronous notification became available in the +1988 version of the KornShell. To have it occur, the user had to issue +the command: +.sp +.RS 4 +.nf +\fB +trap "jobs \(min" CLD +.fi \fR +.P +.RE +.P +The C shell provides two different levels of an asynchronous +notification capability. The environment variable +.IR notify +is analogous to what is done in +.IR set +.BR \(mib +or +.IR set +.BR \(mio +.IR notify . +When set, it notifies the user immediately of background job +completions. When unset, this capability is turned off. +.P +The other notification ability comes through the built-in utility +.IR notify . +The syntax is: +.sp +.RS 4 +.nf +\fB +notify \fB[\fR%job ... \fB]\fR +.fi \fR +.P +.RE +.P +By issuing +.IR notify +with no operands, it causes the C shell to notify the user +asynchronously when the state of the current job changes. If given +operands, +.IR notify +asynchronously informs the user of changes in the states of the +specified jobs. +.P +To add asynchronous notification to the POSIX shell, neither the +KornShell extensions to +.IR trap , +nor the C shell +.IR notify +environment variable seemed appropriate (\c +.IR notify +is not a proper POSIX environment variable name). +.P +The +.IR set +.BR \(mib +option was selected as a compromise. +.P +The +.IR notify +built-in was considered to have more functionality than was required +for simple asynchronous notification. +.P +Historically, some shells applied the +.BR \(miu +option to all parameters including +.IR $@ +and +.IR $* . +The standard developers felt that this was a misfeature since it is +normal and common for +.IR $@ +and +.IR $* +to be used in shell scripts regardless of whether they were passed any +arguments. Treating these uses as an error when no arguments are passed +reduces the value of +.BR \(miu +for its intended purpose of finding spelling mistakes in variable names +and uses of unset positional parameters. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities", +.IR "\fIhash\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.22" ", " "Variable Assignment", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/sh.1p b/man-pages-posix-2013/man1p/sh.1p new file mode 100644 index 0000000..d280223 --- /dev/null +++ b/man-pages-posix-2013/man1p/sh.1p @@ -0,0 +1,1729 @@ +'\" et +.TH SH "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sh +\(em shell, the standard command language interpreter +.SH SYNOPSIS +.LP +.nf +sh \fB[\fR\(miabCefhimnuvx\fB] [\fR\(mio \fIoption\fB]\fR... \fB[\fR+abCefhimnuvx\fB] [\fR+o \fIoption\fB]\fR... + \fB[\fIcommand_file \fB[\fIargument\fR...\fB]]\fR +.P +sh \(mic \fB[\fR\(miabCefhimnuvx\fB] [\fR\(mio \fIoption\fB]\fR... \fB[\fR+abCefhimnuvx\fB] [\fR+o \fIoption\fB]\fR... + \fIcommand_string \fB[\fIcommand_name \fB[\fIargument\fR...\fB]]\fR +.P +sh \(mis \fB[\fR\(miabCefhimnuvx\fB] [\fR\(mio \fIoption\fB]\fR... \fB[\fR+abCefhimnuvx\fB] [\fR+o \fIoption\fB]\fR... + \fB[\fIargument\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR sh +utility is a command language interpreter that shall execute commands +read from a command line string, the standard input, or a specified +file. The application shall ensure that the commands to be executed are +expressed in the language described in +.IR "Chapter 2" ", " "Shell Command Language". +.P +Pathname expansion shall not fail due to the size of a file. +.P +Shell input and output redirections have an implementation-defined +offset maximum that is established in the open file description. +.SH OPTIONS +The +.IR sh +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +with an extension for support of a leading + +(\c +.BR '\(pl' ) +as noted below. +.P +The +.BR \(mia , +.BR \(mib , +.BR \(miC , +.BR \(mie , +.BR \(mif , +.BR \(mim , +.BR \(min , +.BR \(mio +.IR option , +.BR \(miu , +.BR \(miv , +and +.BR \(mix +options are described as part of the +.IR set +utility in +.IR "Section 2.14" ", " "Special Built-In Utilities". +The option letters derived from the +.IR set +special built-in shall also be accepted with a leading + +(\c +.BR '\(pl' ) +instead of a leading + +(meaning the reverse case of the option as described in this volume of POSIX.1\(hy2008). +.P +The following additional options shall be supported: +.IP "\fB\(mic\fP" 10 +Read commands from the +.IR command_string +operand. Set the value of special parameter 0 (see +.IR "Section 2.5.2" ", " "Special Parameters") +from the value of the +.IR command_name +operand and the positional parameters ($1, $2, and so on) in sequence +from the remaining +.IR argument +operands. No commands shall be read from the standard input. +.IP "\fB\(mii\fP" 10 +Specify that the shell is +.IR interactive ; +see below. An implementation may treat specifying the +.BR \(mii +option as an error if the real user ID of the calling process does not +equal the effective user ID or if the real group ID does not equal the +effective group ID. +.IP "\fB\(mis\fP" 10 +Read commands from the standard input. +.P +If there are no operands and the +.BR \(mic +option is not specified, the +.BR \(mis +option shall be assumed. +.P +If the +.BR \(mii +option is present, or if there are no operands and the shell's standard +input and standard error are attached to a terminal, the shell is +considered to be +.IR interactive . +.SH OPERANDS +The following operands shall be supported: +.IP "\fR\(mi\fR" 10 +A single + +shall be treated as the first operand and then ignored. If both +.BR '\(mi' +and +.BR \(dq\(mi\|\(mi\(dq +are given as arguments, or if other operands precede the single +, +the results are undefined. +.IP "\fIargument\fR" 10 +The positional parameters ($1, $2, and so on) shall be set to +.IR arguments , +if any. +.IP "\fIcommand_file\fR" 10 +The pathname of a file containing commands. If the pathname contains +one or more + +characters, the implementation attempts to read that file; the file need +not be executable. If the pathname does not contain a + +character: +.RS 10 +.IP " *" 4 +The implementation shall attempt to read that file from the current +working directory; the file need not be executable. +.IP " *" 4 +If the file is not in the current working directory, the implementation +may perform a search for an executable file using the value of +.IR PATH , +as described in +.IR "Section 2.9.1.1" ", " "Command Search and Execution". +.P +Special parameter 0 (see +.IR "Section 2.5.2" ", " "Special Parameters") +shall be set to the value of +.IR command_file . +If +.IR sh +is called using a synopsis form that omits +.IR command_file , +special parameter 0 shall be set to the value of the first argument +passed to +.IR sh +from its parent (for example, +.IR argv [0] +for a C program), which is normally a pathname used to execute the +.IR sh +utility. +.RE +.IP "\fIcommand_name\fR" 10 +.br +A string assigned to special parameter 0 when executing the commands in +.IR command_string . +If +.IR command_name +is not specified, special parameter 0 shall be set to the value of the +first argument passed to +.IR sh +from its parent (for example, +.IR argv [0] +for a C program), which is normally a pathname used to execute the +.IR sh +utility. +.IP "\fIcommand_string\fR" 10 +.br +A string that shall be interpreted by the shell as one or more +commands, as if the string were the argument to the +\fIsystem\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008. If the +.IR command_string +operand is an empty string, +.IR sh +shall exit with a zero exit status. +.SH STDIN +The standard input shall be used only if one of the following is true: +.IP " *" 4 +The +.BR \(mis +option is specified. +.IP " *" 4 +The +.BR \(mic +option is not specified and no operands are specified. +.IP " *" 4 +The script executes one or more commands that require input from +standard input (such as a +.IR read +command that does not redirect its input). +.P +See the INPUT FILES section. +.P +When the shell is using standard input and it invokes a command that +also uses standard input, the shell shall ensure that the standard +input file pointer points directly after the command it has read when +the command begins execution. It shall not read ahead in such a manner +that any characters intended to be read by the invoked command are +consumed by the shell (whether interpreted by the shell or not) or that +characters that are not read by the invoked command are not seen by the +shell. When the command expecting to read standard input is started +asynchronously by an interactive shell, it is unspecified whether +characters are read by the command or interpreted by the shell. +.P +If the standard input to +.IR sh +is a FIFO or terminal device and is set to non-blocking reads, then +.IR sh +shall enable blocking reads on standard input. This shall remain in +effect when the command completes. +.SH "INPUT FILES" +The input file shall be a text file, except that line lengths shall be +unlimited. If the input file is empty or consists solely of blank +lines or comments, or both, +.IR sh +shall exit with a zero exit status. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR sh : +.IP "\fIENV\fP" 10 +This variable, when and only when an interactive shell is invoked, +shall be subjected to parameter expansion (see +.IR "Section 2.6.2" ", " "Parameter Expansion") +by the shell, and the resulting value shall be used as a pathname of a +file containing shell commands to execute in the current environment. +The file need not be executable. If the expanded value of +.IR ENV +is not an absolute pathname, the results are unspecified. +.IR ENV +shall be ignored if the real and effective user IDs or real and +effective group IDs of the process are different. +.IP "\fIFCEDIT\fP" 10 +This variable, when expanded by the shell, shall determine the default +value for the +.BR \(mie +.IR editor +option's +.IR editor +option-argument. If +.IR FCEDIT +is null or unset, +.IR ed +shall be used as the editor. +.IP "\fIHISTFILE\fP" 10 +Determine a pathname naming a command history file. If the +.IR HISTFILE +variable is not set, the shell may attempt to access or create a file +.BR .sh_history +in the directory referred to by the +.IR HOME +environment variable. If the shell cannot obtain both read and +write access to, or create, the history file, it shall use an +unspecified mechanism that allows the history to operate properly. +(References to history ``file'' in this section shall be understood to +mean this unspecified mechanism in such cases.) An implementation may +choose to access this variable only when initializing the history file; +this initialization shall occur when +.IR fc +or +.IR sh +first attempt to retrieve entries from, or add entries to, the file, as +the result of commands issued by the user, the file named by the +.IR ENV +variable, or implementation-defined system start-up files. +Implementations may choose to disable the history list mechanism for +users with appropriate privileges who do not set +.IR HISTFILE ; +the specific circumstances under which this occurs are +implementation-defined. If more than one instance of the shell is +using the same history file, it is unspecified how updates to the +history file from those shells interact. As entries are deleted from +the history file, they shall be deleted oldest first. It is +unspecified when history file entries are physically removed from the +history file. +.IP "\fIHISTSIZE\fP" 10 +Determine a decimal number representing the limit to the number of +previous commands that are accessible. If this variable is unset, an +unspecified default greater than or equal to 128 shall be used. The +maximum number of commands in the history list is unspecified, but +shall be at least 128. An implementation may choose to access this +variable only when initializing the history file, as described under +.IR HISTFILE . +Therefore, it is unspecified whether changes made to +.IR HISTSIZE +after the history file has been initialized are effective. +.IP "\fIHOME\fP" 10 +Determine the pathname of the user's home directory. The contents of +.IR HOME +are used in tilde expansion as described in +.IR "Section 2.6.1" ", " "Tilde Expansion". +.IP "\fIIFS\fP" 10 +A string treated as a list of characters that is used for field +splitting and to split lines into fields with the +.IR read +command. +.RS 10 +.P +If +.IR IFS +is not set, it shall behave as normal for an unset variable, except +that field splitting by the shell and line splitting by the +.IR read +command shall be performed as if the value of +.IR IFS +is +\c +\c +; +see +.IR "Section 2.6.5" ", " "Field Splitting". +.P +Implementations may ignore the value of +.IR IFS +in the environment, or the absence of +.IR IFS +from the environment, at the time the shell is invoked, in which case +the shell shall set +.IR IFS +to +\c +\c + +when it is invoked. +.RE +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the behavior of range expressions, equivalence classes, and +multi-character collating elements within pattern matching. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files), which characters +are defined as letters (character class +.BR alpha ), +and the behavior of character classes within pattern matching. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fIMAIL\fP" 10 +Determine a pathname of the user's mailbox file for purposes of +incoming mail notification. If this variable is set, the shell shall +inform the user if the file named by the variable is created or if its +modification time has changed. Informing the user shall be accomplished +by writing a string of unspecified format to standard error prior to +the writing of the next primary prompt string. Such check shall be +performed only after the completion of the interval defined by the +.IR MAILCHECK +variable after the last such check. The user shall be informed only if +.IR MAIL +is set and +.IR MAILPATH +is not set. +.IP "\fIMAILCHECK\fP" 10 +.br +Establish a decimal integer value that specifies how often (in seconds) +the shell shall check for the arrival of mail in the files specified by +the +.IR MAILPATH +or +.IR MAIL +variables. The default value shall be 600 seconds. If set to zero, +the shell shall check before issuing each primary prompt. +.IP "\fIMAILPATH\fP" 10 +Provide a list of pathnames and optional messages separated by + +characters. If this variable is set, the shell shall inform the user if +any of the files named by the variable are created or if any of their +modification times change. (See the preceding entry for +.IR MAIL +for descriptions of mail arrival and user informing.) Each pathname can +be followed by +.BR '%' +and a string that shall be subjected to parameter expansion and written +to standard error when the modification time changes. If a +.BR '%' +character in the pathname is preceded by a +, +it shall be treated as a literal +.BR '%' +in the pathname. The default message is unspecified. +.RS 10 +.P +The +.IR MAILPATH +environment variable takes precedence over the +.IR MAIL +variable. +.RE +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPATH\fP" 10 +Establish a string formatted as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +used to effect command interpretation; see +.IR "Section 2.9.1.1" ", " "Command Search and Execution". +.IP "\fIPWD\fP" 10 +This variable shall represent an absolute pathname of the current +working directory. Assignments to this variable may be ignored. +.SH "ASYNCHRONOUS EVENTS" +The +.IR sh +utility shall take the standard action for all signals (see +.IR "Section 1.4" ", " "Utility Description Defaults") +with the following exceptions. +.P +If the shell is interactive, SIGINT signals received during command +line editing shall be handled as described in the EXTENDED DESCRIPTION, +and SIGINT signals received at other times shall be caught but no action +performed. +.P +If the shell is interactive: +.IP " *" 4 +SIGQUIT and SIGTERM signals shall be ignored. +.IP " *" 4 +If the +.BR \(mim +option is in effect, SIGTTIN, SIGTTOU, and SIGTSTP signals shall be +ignored. +.IP " *" 4 +If the +.BR \(mim +option is not in effect, it is unspecified whether SIGTTIN, SIGTTOU, +and SIGTSTP signals are ignored, set to the default action, or caught. +If they are caught, the shell shall, in the signal-catching function, +set the signal to the default action and raise the signal (after taking +any appropriate steps, such as restoring terminal settings). +.P +The standard actions, and the actions described above for interactive +shells, can be overridden by use of the +.IR trap +special built-in utility (see +.IR "\fItrap\fR\^" +and +.IR "Section 2.11" ", " "Signals and Error Handling"). +.SH STDOUT +See the STDERR section. +.SH STDERR +Except as otherwise stated (by the descriptions of any invoked +utilities or in interactive mode), standard error shall be used +only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +See +.IR "Chapter 2" ", " "Shell Command Language". +The functionality described in the rest of the EXTENDED DESCRIPTION +section shall be provided on implementations that support the User +Portability Utilities option +(and the rest of this section is not further shaded for this option). +.SS "Command History List" +.P +When the +.IR sh +utility is being used interactively, it shall maintain a list of +commands previously entered from the terminal in the file named by the +.IR HISTFILE +environment variable. The type, size, and internal format of this file +are unspecified. Multiple +.IR sh +processes can share access to the file for a user, if file access +permissions allow this; see the description of the +.IR HISTFILE +environment variable. +.SS "Command Line Editing" +.P +When +.IR sh +is being used interactively from a terminal, the current command and +the command history (see +.IR "\fIfc\fR\^") +can be edited using +.IR vi -mode +command line editing. This mode uses commands, described below, +similar to a subset of those described in the +.IR vi +utility. Implementations may offer other command line editing modes +corresponding to other editing utilities. +.P +The command +.IR set +.BR \(mio +.IR vi +shall enable +.IR vi -mode +editing and place +.IR sh +into +.IR vi +insert mode (see +.IR "Command Line Editing (vi-mode)"). +This command also shall disable any other editing mode that the +implementation may provide. The command +.IR set +.BR +o +.IR vi +disables +.IR vi -mode +editing. +.P +Certain block-mode terminals may be unable to support shell command +line editing. If a terminal is unable to provide either edit mode, it +need not be possible to +.IR set +.BR \(mio +.IR vi +when using the shell on this terminal. +.P +In the following sections, the characters +.IR erase , +.IR interrupt , +.IR kill , +and +.IR end-of-file +are those set by the +.IR stty +utility. +.SS "Command Line Editing (vi-mode)" +.P +In +.IR vi +editing mode, there shall be a distinguished line, the edit line. All +the editing operations which modify a line affect the edit line. The +edit line is always the newest line in the command history buffer. +.P +With +.IR vi -mode +enabled, +.IR sh +can be switched between insert mode and command mode. +.P +When in insert mode, an entered character shall be inserted into the +command line, except as noted in +.IR "vi Line Editing Insert Mode". +Upon entering +.IR sh +and after termination of the previous command, +.IR sh +shall be in insert mode. +.P +Typing an escape character shall switch +.IR sh +into command mode (see +.IR "vi Line Editing Command Mode"). +In command mode, an entered character shall either invoke a defined +operation, be used as part of a multi-character operation, or be +treated as an error. A character that is not recognized as part of an +editing command shall terminate any specific editing command and shall +alert the terminal. If +.IR sh +receives a SIGINT signal in command mode (whether generated by typing the +.IR interrupt +character or by other means), it shall terminate command line editing +on the current command line, reissue the prompt on the next line of the +terminal, and reset the command history (see +.IR "\fIfc\fR\^") +so that the most recently executed command is the previous command +(that is, the command that was being edited when it was interrupted is +not re-entered into the history). +.P +In the following sections, the phrase ``move the cursor to the +beginning of the word'' shall mean ``move the cursor to the first +character of the current word'' and the phrase ``move the cursor to the +end of the word'' shall mean ``move the cursor to the last character of +the current word''. The phrase ``beginning of the command line'' +indicates the point between the end of the prompt string issued by the +shell (or the beginning of the terminal line, if there is no prompt +string) and the first character of the command text. +.SS "vi Line Editing Insert Mode" +.P +While in insert mode, any character typed shall be inserted in the +current command line, unless it is from the following set. +.IP 10 +Execute the current command line. If the current command line is not +empty, this line shall be entered into the command history (see +.IR "\fIfc\fR\^"). +.IP "\fIerase\fR" 10 +Delete the character previous to the current cursor position and move +the current cursor position back one character. In insert mode, +characters shall be erased from both the screen and the buffer when +backspacing. +.IP "\fIinterrupt\fR" 10 +If +.IR sh +receives a SIGINT signal in insert mode (whether generated by typing +the +.IR interrupt +character or by other means), it shall terminate command line editing +with the same effects as described for interrupting command mode; see +.IR "Command Line Editing (vi-mode)". +.IP "\fIkill\fR" 10 +Clear all the characters from the input line. +.IP "\(hyV" 10 +Insert the next character input, even if the character is otherwise a +special insert mode character. +.IP "\(hyW" 10 +Delete the characters from the one preceding the cursor to the +preceding word boundary. The word boundary in this case is the closer +to the cursor of either the beginning of the line or a character that +is in neither the +.BR blank +nor +.BR punct +character classification of the current locale. +.IP "\fIend-of-file\fR" 10 +Interpreted as the end of input in +.IR sh . +This interpretation shall occur only at the beginning of an input +line. If +.IR end-of-file +is entered other than at the beginning of the line, the results are +unspecified. +.IP 10 +Place +.IR sh +into command mode. +.SS "vi Line Editing Command Mode" +.P +In command mode for the command line editing feature, decimal digits +not beginning with 0 that precede a command letter shall be +remembered. Some commands use these decimal digits as a count number +that affects the operation. +.P +The term +.IR "motion command" +represents one of the commands: +.sp +.RS 4 +.nf +\fB + 0 b F l W ^ $ ; E f T w | , B e h t +.fi \fR +.P +.RE +.P +If the current line is not the edit line, any command that modifies the +current line shall cause the content of the current line to replace the +content of the edit line, and the current line shall become the edit +line. This replacement cannot be undone (see the +.BR u +and +.BR U +commands below). The modification requested shall then be performed to +the edit line. When the current line is the edit line, the modification +shall be done directly to the edit line. +.P +Any command that is preceded by +.IR count +shall take a count (the numeric value of any preceding decimal +digits). Unless otherwise noted, this count shall cause the specified +operation to repeat by the number of times specified by the count. +Also unless otherwise noted, a +.IR count +that is out of range is considered an error condition and shall alert +the terminal, but neither the cursor position, nor the command line, +shall change. +.P +The terms +.IR word +and +.IR bigword +are used as defined in the +.IR vi +description. The term +.IR "save buffer" +corresponds to the term +.IR "unnamed buffer" +in +.IR vi . +.P +The following commands shall be recognized in command mode: +.IP 10 +Execute the current command line. If the current command line is not +empty, this line shall be entered into the command history (see +.IR "\fIfc\fR\^"). +.IP "\(hyL" 10 +Redraw the current command line. Position the cursor at the same +location on the redrawn line. +.IP "\fB#\fP" 10 +Insert the character +.BR '#' +at the beginning of the current command line and treat the resulting +edit line as a comment. This line shall be entered into the command +history; see +.IR "\fIfc\fR\^". +.IP "\fB=\fP" 10 +Display the possible shell word expansions (see +.IR "Section 2.6" ", " "Word Expansions") +of the bigword at the current command line position. +.RS 10 +.TP 10 +.BR Note: +This does not modify the content of the current line, and therefore +does not cause the current line to become the edit line. +.P +.P +These expansions shall be displayed on subsequent terminal lines. If +the bigword contains none of the characters +.BR '?' , +.BR '*' , +or +.BR '[' , +an + +(\c +.BR '*' ) +shall be implicitly assumed at the end. If any directories are +matched, these expansions shall have a +.BR '/' +character appended. After the expansion, the line shall be redrawn, +the cursor repositioned at the current cursor position, and +.IR sh +shall be placed in command mode. +.RE +.IP "\fB\e\fR" 10 +Perform pathname expansion (see +.IR "Section 2.6.6" ", " "Pathname Expansion") +on the current bigword, up to the largest set of characters that can be +matched uniquely. If the bigword contains none of the characters +.BR '?' , +.BR '*' , +or +.BR '[' , +an + +(\c +.BR '*' ) +shall be implicitly assumed at the end. This maximal expansion then +shall replace the original bigword in the command line, and the cursor +shall be placed after this expansion. If the resulting bigword +completely and uniquely matches a directory, a +.BR '/' +character shall be inserted directly after the bigword. If some other +file is completely matched, a single + +shall be inserted after the bigword. After this operation, +.IR sh +shall be placed in insert mode. +.IP "\fB*\fR" 10 +Perform pathname expansion on the current bigword and insert all +expansions into the command to replace the current bigword, with each +expansion separated by a single +. +If at the end of the line, the current cursor position shall be moved +to the first column position following the expansions and +.IR sh +shall be placed in insert mode. Otherwise, the current cursor position +shall be the last column position of the first character after the +expansions and +.IR sh +shall be placed in insert mode. If the current bigword contains none +of the characters +.BR '?' , +.BR '*' , +or +.BR '[' , +before the operation, an + +(\c +.BR '*' ) +shall be implicitly assumed at the end. +.IP "\fB@\fIletter\fR" 10 +Insert the value of the alias named +.IR _letter . +The symbol +.IR letter +represents a single alphabetic character from the portable character +set; implementations may support additional characters as an +extension. If the alias +.IR _letter +contains other editing commands, these commands shall be performed as +part of the insertion. If no alias +.IR _letter +is enabled, this command shall have no effect. +.IP "\fB[\fIcount\fB]~\fR" 10 +Convert, if the current character is a lowercase letter, to the +equivalent uppercase letter and +.IR "vice versa" , +as prescribed by the current locale. The current cursor position then +shall be advanced by one character. If the cursor was positioned on +the last character of the line, the case conversion shall occur, but +the cursor shall not advance. If the +.BR '~' +command is preceded by a +.IR count , +that number of characters shall be converted, and the cursor shall be +advanced to the character position after the last character converted. +If the +.IR count +is larger than the number of characters after the cursor, this shall +not be considered an error; the cursor shall advance to the last +character on the line. +.IP "\fB[\fIcount\fB].\fR" 10 +Repeat the most recent non-motion command, even if it was executed on +an earlier command line. If the previous command was preceded by a +.IR count , +and no count is given on the +.BR '.' +command, the count from the previous command shall be included as part +of the repeated command. If the +.BR '.' +command is preceded by a +.IR count , +this shall override any +.IR count +argument to the previous command. The +.IR count +specified in the +.BR '.' +command shall become the count for subsequent +.BR '.' +commands issued without a count. +.IP "\fB[\fInumber\fB]v\fR" 10 +Invoke the +.IR vi +editor to edit the current command line in a temporary file. When the +editor exits, the commands in the temporary file shall be executed and +placed in the command history. If a +.IR number +is included, it specifies the command number in the command history to +be edited, rather than the current command line. +.IP "\fB[\fIcount\fB]l\fR\0\0\0(ell)" 10 +.sp -0.5v +.IP "\fB[\fIcount\fB]\fR" 10 +.br +Move the current cursor position to the next character position. If +the cursor was positioned on the last character of the line, the +terminal shall be alerted and the cursor shall not be advanced. If the +.IR count +is larger than the number of characters after the cursor, this shall +not be considered an error; the cursor shall advance to the last +character on the line. +.IP "\fB[\fIcount\fB]h\fR" 10 +Move the current cursor position to the +.IR count th +(default 1) previous character position. If the cursor was positioned +on the first character of the line, the terminal shall be alerted and +the cursor shall not be moved. If the count is larger than the number +of characters before the cursor, this shall not be considered an error; +the cursor shall move to the first character on the line. +.IP "\fB[\fIcount\fB]w\fR" 10 +Move to the start of the next word. If the cursor was positioned on +the last character of the line, the terminal shall be alerted and the +cursor shall not be advanced. If the +.IR count +is larger than the number of words after the cursor, this shall not be +considered an error; the cursor shall advance to the last character on +the line. +.IP "\fB[\fIcount\fB]W\fR" 10 +Move to the start of the next bigword. If the cursor was positioned on +the last character of the line, the terminal shall be alerted and the +cursor shall not be advanced. If the +.IR count +is larger than the number of bigwords after the cursor, this shall not +be considered an error; the cursor shall advance to the last character +on the line. +.IP "\fB[\fIcount\fB]e\fR" 10 +Move to the end of the current word. If at the end of a word, move to +the end of the next word. If the cursor was positioned on the last +character of the line, the terminal shall be alerted and the cursor +shall not be advanced. If the +.IR count +is larger than the number of words after the cursor, this shall not be +considered an error; the cursor shall advance to the last character on +the line. +.IP "\fB[\fIcount\fB]E\fR" 10 +Move to the end of the current bigword. If at the end of a bigword, +move to the end of the next bigword. If the cursor was positioned on +the last character of the line, the terminal shall be alerted and the +cursor shall not be advanced. If the +.IR count +is larger than the number of bigwords after the cursor, this shall not +be considered an error; the cursor shall advance to the last character +on the line. +.IP "\fB[\fIcount\fB]b\fR" 10 +Move to the beginning of the current word. If at the beginning of a +word, move to the beginning of the previous word. If the cursor was +positioned on the first character of the line, the terminal shall be +alerted and the cursor shall not be moved. If the +.IR count +is larger than the number of words preceding the cursor, this shall not +be considered an error; the cursor shall return to the first character +on the line. +.IP "\fB[\fIcount\fB]B\fR" 10 +Move to the beginning of the current bigword. If at the beginning of a +bigword, move to the beginning of the previous bigword. If the cursor +was positioned on the first character of the line, the terminal shall +be alerted and the cursor shall not be moved. If the +.IR count +is larger than the number of bigwords preceding the cursor, this shall +not be considered an error; the cursor shall return to the first +character on the line. +.IP "\fB^\fR" 10 +Move the current cursor position to the first character on the input +line that is not a +. +.IP "\fB$\fR" 10 +Move to the last character position on the current command line. +.IP "\fB0\fR" 10 +(Zero.) Move to the first character position on the current command +line. +.IP "\fB[\fIcount\fB]\||\fR" 10 +Move to the +.IR count th +character position on the current command line. If no number is +specified, move to the first position. The first character position +shall be numbered 1. If the count is larger than the number of +characters on the line, this shall not be considered an error; the +cursor shall be placed on the last character on the line. +.IP "\fB[\fIcount\fB]f\fIc\fR" 10 +Move to the first occurrence of the character +.BR 'c' +that occurs after the current cursor position. If the cursor was +positioned on the last character of the line, the terminal shall be +alerted and the cursor shall not be advanced. If the character +.BR 'c' +does not occur in the line after the current cursor position, the +terminal shall be alerted and the cursor shall not be moved. +.IP "\fB[\fIcount\fB]F\fIc\fR" 10 +Move to the first occurrence of the character +.BR 'c' +that occurs before the current cursor position. If the cursor was +positioned on the first character of the line, the terminal shall be +alerted and the cursor shall not be moved. If the character +.BR 'c' +does not occur in the line before the current cursor position, the +terminal shall be alerted and the cursor shall not be moved. +.IP "\fB[\fIcount\fB]t\fIc\fR" 10 +Move to the character before the first occurrence of the character +.BR 'c' +that occurs after the current cursor position. If the cursor was +positioned on the last character of the line, the terminal shall be +alerted and the cursor shall not be advanced. If the character +.BR 'c' +does not occur in the line after the current cursor position, the +terminal shall be alerted and the cursor shall not be moved. +.IP "\fB[\fIcount\fB]T\fIc\fR" 10 +Move to the character after the first occurrence of the character +.BR 'c' +that occurs before the current cursor position. If the cursor was +positioned on the first character of the line, the terminal shall be +alerted and the cursor shall not be moved. If the character +.BR 'c' +does not occur in the line before the current cursor position, the +terminal shall be alerted and the cursor shall not be moved. +.IP "\fB[\fIcount\fB];\fR" 10 +Repeat the most recent +.BR f , +.BR F , +.BR t , +or +.BR T +command. Any number argument on that previous command shall be +ignored. Errors are those described for the repeated command. +.IP "\fB[\fIcount\fB],\fR" 10 +Repeat the most recent +.BR f , +.BR F , +.BR t , +or +.BR T +command. Any number argument on that previous command shall be +ignored. However, reverse the direction of that command. +.IP "\fBa\fR" 10 +Enter insert mode after the current cursor position. Characters that +are entered shall be inserted before the next character. +.IP "\fBA\fR" 10 +Enter insert mode after the end of the current command line. +.IP "\fBi\fR" 10 +Enter insert mode at the current cursor position. Characters that are +entered shall be inserted before the current character. +.IP "\fBI\fR" 10 +Enter insert mode at the beginning of the current command line. +.IP "\fBR\fR" 10 +Enter insert mode, replacing characters from the command line beginning +at the current cursor position. +.IP "\fB[\fIcount\fB]c\fImotion\fR" 10 +.br +Delete the characters between the current cursor position and the +cursor position that would result from the specified motion +command. Then enter insert mode before the first character following +any deleted characters. If +.IR count +is specified, it shall be applied to the motion command. A +.IR count +shall be ignored for the following motion commands: +.RS 10 +.sp +.RS 4 +.nf +\fB +0 ^ $ c +.fi \fR +.P +.RE +.P +If the motion command is the character +.BR 'c' , +the current command line shall be cleared and insert mode shall be +entered. If the motion command would move the current cursor position +toward the beginning of the command line, the character under the +current cursor position shall not be deleted. If the motion command +would move the current cursor position toward the end of the command +line, the character under the current cursor position shall be deleted. +If the +.IR count +is larger than the number of characters between the current cursor +position and the end of the command line toward which the motion +command would move the cursor, this shall not be considered an error; +all of the remaining characters in the aforementioned range shall be +deleted and insert mode shall be entered. If the motion command is +invalid, the terminal shall be alerted, the cursor shall not be moved, +and no text shall be deleted. +.RE +.IP "\fBC\fR" 10 +Delete from the current character to the end of the line and enter +insert mode at the new end-of-line. +.IP "\fBS\fR" 10 +Clear the entire edit line and enter insert mode. +.IP "\fB[\fIcount\fB]r\fIc\fR" 10 +Replace the current character with the character +.BR 'c' . +With a number +.IR count , +replace the current and the following +.IR count \(mi1 +characters. After this command, the current cursor position shall be +on the last character that was changed. If the +.IR count +is larger than the number of characters after the cursor, this shall +not be considered an error; all of the remaining characters shall be +changed. +.IP "\fB[\fIcount\fB]_\fR" 10 +Append a + +after the current character position and then append the last bigword +in the previous input line after the +. +Then enter insert mode after the last character just appended. With a +number +.IR count , +append the +.IR count th +bigword in the previous line. +.IP "\fB[\fIcount\fB]x\fR" 10 +Delete the character at the current cursor position and place the +deleted characters in the save buffer. If the cursor was positioned on +the last character of the line, the character shall be deleted and the +cursor position shall be moved to the previous character (the new last +character). If the +.IR count +is larger than the number of characters after the cursor, this shall +not be considered an error; all the characters from the cursor to the +end of the line shall be deleted. +.IP "\fB[\fIcount\fB]X\fR" 10 +Delete the character before the current cursor position and place the +deleted characters in the save buffer. The character under the current +cursor position shall not change. If the cursor was positioned on the +first character of the line, the terminal shall be alerted, and the +.BR X +command shall have no effect. If the line contained a single +character, the +.BR X +command shall have no effect. If the line contained no characters, the +terminal shall be alerted and the cursor shall not be moved. If the +.IR count +is larger than the number of characters before the cursor, this shall +not be considered an error; all the characters from before the cursor +to the beginning of the line shall be deleted. +.IP "\fB[\fIcount\fB]d\fImotion\fR" 10 +.br +Delete the characters between the current cursor position and the +character position that would result from the motion command. A number +.IR count +repeats the motion command +.IR count +times. If the motion command would move toward the beginning of the +command line, the character under the current cursor position shall not +be deleted. If the motion command is +.BR d , +the entire current command line shall be cleared. If the +.IR count +is larger than the number of characters between the current cursor +position and the end of the command line toward which the motion +command would move the cursor, this shall not be considered an error; +all of the remaining characters in the aforementioned range shall be +deleted. The deleted characters shall be placed in the save buffer. +.IP "\fBD\fR" 10 +Delete all characters from the current cursor position to the end of +the line. The deleted characters shall be placed in the save buffer. +.IP "\fB[\fIcount\fB]y\fImotion\fR" 10 +.br +Yank (that is, copy) the characters from the current cursor position to +the position resulting from the motion command into the save buffer. A +number +.IR count +shall be applied to the motion command. If the motion command would +move toward the beginning of the command line, the character under the +current cursor position shall not be included in the set of yanked +characters. If the motion command is +.BR y , +the entire current command line shall be yanked into the save buffer. +The current cursor position shall be unchanged. If the +.IR count +is larger than the number of characters between the current cursor +position and the end of the command line toward which the motion +command would move the cursor, this shall not be considered an error; +all of the remaining characters in the aforementioned range shall be +yanked. +.IP "\fBY\fR" 10 +Yank the characters from the current cursor position to the end of the +line into the save buffer. The current character position shall be +unchanged. +.IP "\fB[\fIcount\fB]p\fR" 10 +Put a copy of the current contents of the save buffer after the current +cursor position. The current cursor position shall be advanced to the +last character put from the save buffer. A +.IR count +shall indicate how many copies of the save buffer shall be put. +.IP "\fB[\fIcount\fB]P\fR" 10 +Put a copy of the current contents of the save buffer before the +current cursor position. The current cursor position shall be moved to +the last character put from the save buffer. A +.IR count +shall indicate how many copies of the save buffer shall be put. +.IP "\fBu\fR" 10 +Undo the last command that changed the edit line. This operation shall +not undo the copy of any command line to the edit line. +.IP "\fBU\fR" 10 +Undo all changes made to the edit line. This operation shall not undo +the copy of any command line to the edit line. +.IP "\fB[\fIcount\fB]k\fR" 10 +.sp -0.5v +.IP "\fB[\fIcount\fB]\(mi\fR" 10 +Set the current command line to be the +.IR count th +previous command line in the shell command history. If +.IR count +is not specified, it shall default to 1. The cursor shall be positioned +on the first character of the new command. If a +.BR k +or +.BR \(mi +command would retreat past the maximum number of commands in effect for +this shell (affected by the +.IR HISTSIZE +environment variable), the terminal shall be alerted, and the command +shall have no effect. +.IP "\fB[\fIcount\fB]j\fR" 10 +.sp -0.5v +.IP "\fB[\fIcount\fB]+\fR" 10 +Set the current command line to be the +.IR count th +next command line in the shell command history. If +.IR count +is not specified, it shall default to 1. The cursor shall be positioned +on the first character of the new command. If a +.BR j +or +.BR + +command advances past the edit line, the current command line shall be +restored to the edit line and the terminal shall be alerted. +.IP "\fB[\fInumber\fB]G\fR" 10 +Set the current command line to be the oldest command line stored in +the shell command history. With a number +.IR number , +set the current command line to be the command line +.IR number +in the history. If command line +.IR number +does not exist, the terminal shall be alerted and the command line +shall not be changed. +.IP "\fB/\fIpattern\fR" 10 +.br +Move backwards through the command history, searching for the specified +pattern, beginning with the previous command line. Patterns use the +pattern matching notation described in +.IR "Section 2.13" ", " "Pattern Matching Notation", +except that the +.BR '^' +character shall have special meaning when it appears as the first +character of +.IR pattern . +In this case, the +.BR '^' +is discarded and the characters after the +.BR '^' +shall be matched only at the beginning of a line. Commands in the +command history shall be treated as strings, not as filenames. If the +pattern is not found, the current command line shall be unchanged and +the terminal is alerted. If it is found in a previous line, the current +command line shall be set to that line and the cursor shall be set to +the first character of the new command line. +.RS 10 +.P +If +.IR pattern +is empty, the last non-empty pattern provided to +.BR / +or +.BR ? +shall be used. If there is no previous non-empty pattern, the terminal +shall be alerted and the current command line shall remain unchanged. +.RE +.IP "\fB?\fIpattern\fR" 10 +.br +Move forwards through the command history, searching for the specified +pattern, beginning with the next command line. Patterns use the pattern +matching notation described in +.IR "Section 2.13" ", " "Pattern Matching Notation", +except that the +.BR '^' +character shall have special meaning when it appears as the first +character of +.IR pattern . +In this case, the +.BR '^' +is discarded and the characters after the +.BR '^' +shall be matched only at the beginning of a line. Commands in the +command history shall be treated as strings, not as filenames. If the +pattern is not found, the current command line shall be unchanged and +the terminal alerted. If it is found in a following line, the current +command line shall be set to that line and the cursor shall be set to +the fist character of the new command line. +.RS 10 +.P +If +.IR pattern +is empty, the last non-empty pattern provided to +.BR / +or +.BR ? +shall be used. If there is no previous non-empty pattern, the terminal +shall be alerted and the current command line shall remain unchanged. +.RE +.IP "\fBn\fR" 10 +Repeat the most recent +.BR / +or +.BR ? +command. If there is no previous +.BR / +or +.BR ? , +the terminal shall be alerted and the current command line shall remain +unchanged. +.IP "\fBN\fR" 10 +Repeat the most recent +.BR / +or +.BR ? +command, reversing the direction of the search. If there is no previous +.BR / +or +.BR ? , +the terminal shall be alerted and the current command line shall remain +unchanged. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\0\0\0\00" 8 +The script to be executed consisted solely of zero or more blank lines +or comments, or both. +.IP "1\(hy125" 8 +A non-interactive shell detected an error other than +.IR command_file +not found, including but not limited to syntax, redirection, or variable +assignment errors. +.IP "\0\0127" 8 +A specified +.IR command_file +could not be found by a non-interactive shell. +.P +Otherwise, the shell shall return the exit status of the last command +it invoked or attempted to invoke (see also the +.IR exit +utility in +.IR "Section 2.14" ", " "Special Built-In Utilities"). +.SH "CONSEQUENCES OF ERRORS" +See +.IR "Section 2.8.1" ", " "Consequences of Shell Errors". +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Standard input and standard error are the files that +determine whether a shell is interactive when +.BR \(mii +is not specified. For example: +.sp +.RS 4 +.nf +\fB +sh > file +.fi \fR +.P +.RE +.P +and: +.sp +.RS 4 +.nf +\fB +sh 2> file +.fi \fR +.P +.RE +.P +create interactive and non-interactive shells, respectively. Although +both accept terminal input, the results of error conditions are +different, as described in +.IR "Section 2.8.1" ", " "Consequences of Shell Errors"; +in the second example a redirection error encountered by a special +built-in utility aborts the shell. +.P +A conforming application must protect its first operand, if it starts +with a +, +by preceding it with the +.BR \(dq\(mi\|\(mi\(dq +argument that denotes the end of the options. +.P +Applications should note that the standard +.IR PATH +to the shell cannot be assumed to be either +.BR /bin/sh +or +.BR /usr/bin/sh , +and should be determined by interrogation of the +.IR PATH +returned by +.IR getconf +.IR PATH , +ensuring that the returned pathname is an absolute pathname and not a +shell built-in. +.P +For example, to determine the location of the standard +.IR sh +utility: +.sp +.RS 4 +.nf +\fB +command \(miv sh +.fi \fR +.P +.RE +.P +On some implementations this might return: +.sp +.RS 4 +.nf +\fB +/usr/xpg4/bin/sh +.fi \fR +.P +.RE +.P +Furthermore, on systems that support executable scripts (the +.BR \(dq#!\(dq +construct), it is recommended that applications using executable +scripts install them using +.IR getconf +.IR PATH +to determine the shell pathname and update the +.BR \(dq#!\(dq +script appropriately as it is being installed (for example, with +.IR sed ). +For example: +.sp +.RS 4 +.nf +\fB +# +# Installation time script to install correct POSIX shell pathname +# +# Get list of paths to check +# +Sifs=$IFS +Sifs_set=${IFS+y} +IFS=: +set \(mi\|\(mi $(getconf PATH) +if [ "$Sifs_set" = y ] +then + IFS=$Sifs +else + unset IFS +fi +# +# Check each path for 'sh' +# +for i +do + if [ \(mix "${i}"/sh ] + then + Pshell=${i}/sh + fi +done +# +# This is the list of scripts to update. They should be of the +# form '${name}.source' and will be transformed to '${name}'. +# Each script should begin: +# +# #!INSTALLSHELLPATH +# +scripts="a b c" +# +# Transform each script +# +for i in ${scripts} +do + sed \(mie "s|INSTALLSHELLPATH|${Pshell}|" < ${i}.source > ${i} +done +.fi \fR +.P +.RE +.SH EXAMPLES +.IP " 1." 4 +Execute a shell command from a string: +.RS 4 +.sp +.RS 4 +.nf +\fB +sh \(mic "cat myfile" +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +Execute a shell script from a file in the current directory: +.RS 4 +.sp +.RS 4 +.nf +\fB +sh my_shell_cmds +.fi \fR +.P +.RE +.RE +.SH RATIONALE +The +.IR sh +utility and the +.IR set +special built-in utility share a common set of options. +.P +The name +.IR IFS +was originally an abbreviation of ``Input Field Separators''; however, +this name is misleading as the +.IR IFS +characters are actually used as field terminators. The KornShell +ignores the contents of +.IR IFS +upon entry to the script. A conforming application cannot rely on +importing +.IR IFS . +One justification for this, beyond security considerations, is to +assist possible future shell compilers. Allowing +.IR IFS +to be imported from the environment prevents many optimizations that +might otherwise be performed via dataflow analysis of the script +itself. +.P +The text in the STDIN section about non-blocking reads concerns an +instance of +.IR sh +that has been invoked, probably by a C-language program, with standard +input that has been opened using the O_NONBLOCK flag; see +\fIopen\fR() +in the System Interfaces volume of POSIX.1\(hy2008. If the shell did not reset this flag, it would +immediately terminate because no input data would be available yet and +that would be considered the same as end-of-file. +.P +The options associated with a +.IR "restricted shell" +(command name +.IR rsh +and the +.BR \(mir +option) were excluded because the standard developers considered that +the implied level of security could not be achieved and they did not +want to raise false expectations. +.P +On systems that support set-user-ID scripts, +a historical trapdoor has been to link a script to the name +.BR \(mii . +When it is called by a sequence such as: +.sp +.RS 4 +.nf +\fB +sh \(mi +.fi \fR +.P +.RE +.P +or by: +.sp +.RS 4 +.nf +\fB +#!\ usr/bin/sh\ \(mi +.fi \fR +.P +.RE +.P +the historical systems have assumed that no option letters follow. +Thus, this volume of POSIX.1\(hy2008 allows the single + +to mark the end of the options, in addition to the use of the regular +.BR \(dq\(mi\|\(mi\(dq +argument, because it was considered that the older practice was so +pervasive. An alternative approach is taken by the KornShell, where +real and effective user/group IDs must match for an interactive shell; +this behavior is specifically allowed by this volume of POSIX.1\(hy2008. +.TP 10 +.BR Note: +There are other problems with set-user-ID scripts that the two +approaches described here do not resolve. +.P +.P +The initialization process for the history file can be dependent on the +system start-up files, in that they may contain commands that +effectively preempt the user's settings of +.IR HISTFILE +and +.IR HISTSIZE . +For example, function definition commands are recorded in the history +file, unless the +.IR set +.BR \(mio +.IR nolog +option is set. If the system administrator includes function +definitions in some system start-up file called before the +.IR ENV +file, the history file is initialized before the user gets a chance to +influence its characteristics. In some historical shells, the history +file is initialized just after the +.IR ENV +file has been processed. Therefore, it is implementation-defined +whether changes made to +.IR HISTFILE +after the history file has been initialized are effective. +.P +The default messages for the various +.IR MAIL -related +messages are unspecified because they vary across implementations. +Typical messages are: +.sp +.RS 4 +.nf +\fB +"you have mail\en" +.fi \fR +.P +.RE +.P +or: +.sp +.RS 4 +.nf +\fB +"you have new mail\en" +.fi \fR +.P +.RE +.P +It is important that the descriptions of command line editing refer to +the same shell as that in POSIX.1\(hy2008 so that interactive users can also be +application programmers without having to deal with programmatic +differences in their two environments. It is also essential that the +utility name +.IR sh +be specified because this explicit utility name is too firmly rooted in +historical practice of application programs for it to change. +.P +Consideration was given to mandating a diagnostic message when +attempting to set +.IR vi -mode +on terminals that do not support command line editing. However, it is +not historical practice for the shell to be cognizant of all terminal +types and thus be able to detect inappropriate terminals in all cases. +Implementations are encouraged to supply diagnostics in this case +whenever possible, rather than leaving the user in a state where +editing commands work incorrectly. +.P +In early proposals, the KornShell-derived +.IR emacs +mode of command line editing was included, even though the +.IR emacs +editor itself was not. The community of +.IR emacs +proponents was adamant that the full +.IR emacs +editor not be standardized because they were concerned that an attempt +to standardize this very powerful environment would encourage vendors +to ship strictly conforming versions lacking the extensibility required +by the community. The author of the original +.IR emacs +program also expressed his desire to omit the program. Furthermore, +there were a number of historical systems that did not include +.IR emacs , +or included it without supporting it, but there were very few that did +not include and support +.IR vi . +The shell +.IR emacs +command line editing mode was finally omitted because it became +apparent that the KornShell version and the editor being distributed +with the GNU system had diverged in some respects. The author of +.IR emacs +requested that the POSIX +.IR emacs +mode either be deleted or have a significant number of unspecified +conditions. Although the KornShell author agreed to consider changes to +bring the shell into alignment, the standard developers decided to +defer specification at that time. At the time, it was assumed that +convergence on an acceptable definition would occur for a subsequent +draft, but that has not happened, and there appears to be no impetus to +do so. In any case, implementations are free to offer additional +command line editing modes based on the exact models of editors their +users are most comfortable with. +.P +Early proposals had the following list entry in +.IR "vi Line Editing Insert Mode": +.IP "\fR\e\fR" 6 +If followed by the +.IR erase +or +.IR kill +character, that character shall be inserted into the input line. +Otherwise, the + +itself shall be inserted into the input line. +.P +However, this is not actually a feature of +.IR sh +command line editing insert mode, but one of some historical terminal +line drivers. Some conforming implementations continue to do this when +the +.IR stty +.BR iexten +flag is set. +.P +In interactive shells, SIGTERM is ignored so that +.IR "kill 0" +does not kill the shell, and SIGINT is caught so that +.IR wait +is interruptible. If the shell does not ignore SIGTTIN, SIGTTOU, and +SIGTSTP signals when it is interactive and the +.BR \(mim +option is not in effect, these signals suspend the shell if it is not +a session leader. If it is a session leader, the signals are discarded +if they would stop the process, as required by the System Interfaces volume of POSIX.1\(hy2008, +.IR "Section 2.4.3" ", " "Signal Actions" +for orphaned process groups. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIcd\fR\^", +.IR "\fIecho\fR\^", +.IR "\fIexit\fR\^", +.IR "\fIfc\fR\^", +.IR "\fIpwd\fR\^", +.IR "invalid", +.IR "\fIset\fR\^", +.IR "\fIstty\fR\^", +.IR "\fItest\fR\^", +.IR "\fItrap\fR\^", +.IR "\fIumask\fR\^", +.IR "\fIvi\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIdup\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIpipe\fR\^(\|)", +.IR "\fIsignal\fR\^(\|)", +.IR "\fIsystem\fR\^(\|)", +.IR "\fIulimit\fR\^(\|)", +.IR "\fIumask\fR\^(\|)", +.IR "\fIwait\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/shift.1p b/man-pages-posix-2013/man1p/shift.1p new file mode 100644 index 0000000..0194fa0 --- /dev/null +++ b/man-pages-posix-2013/man1p/shift.1p @@ -0,0 +1,103 @@ +'\" et +.TH SHIFT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +shift +\(em shift positional parameters +.SH SYNOPSIS +.LP +.nf +shift \fB[\fIn\fB]\fR +.fi +.SH DESCRIPTION +The positional parameters shall be shifted. Positional parameter 1 +shall be assigned the value of parameter (1+\fIn\fP), parameter 2 shall +be assigned the value of parameter (2+\fIn\fP), and so on. The +parameters represented by the numbers +.BR \(dq$#\(dq +down to +.BR \(dq$#\(min+1\(dq +shall be unset, and the parameter +.BR '#' +is updated to reflect the new number of positional parameters. +.P +The value +.IR n +shall be an unsigned decimal integer less than or equal to the value of +the special parameter +.BR '#' . +If +.IR n +is not given, it shall be assumed to be 1. If +.IR n +is 0, the positional and special parameters are not changed. +.SH OPTIONS +None. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +If the +.IR n +operand is invalid or is greater than +.BR \(dq$#\(dq , +this may be considered a syntax error and a non-interactive shell may +exit; if the shell does not exit in this case, a non-zero exit status +shall be returned. Otherwise, zero shall be returned. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +.LP +.nf +\fB$\fR set a b c d e +\fB$\fR shift 2 +\fB$\fR echo $* +\fBc d e\fR +.fi +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/sleep.1p b/man-pages-posix-2013/man1p/sleep.1p new file mode 100644 index 0000000..a86781f --- /dev/null +++ b/man-pages-posix-2013/man1p/sleep.1p @@ -0,0 +1,173 @@ +'\" et +.TH SLEEP "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +.SH SYNOPSIS +.LP +.nf +sleep \fItime\fR +.fi +.SH DESCRIPTION +The +.IR sleep +utility shall suspend execution for at least the integral number of +seconds specified by the +.IR time +operand. +.SH OPTIONS +None. +.SH OPERANDS +The following operand shall be supported: +.IP "\fItime\fR" 10 +A non-negative decimal integer specifying the number of seconds for +which to suspend execution. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR sleep : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +If the +.IR sleep +utility receives a SIGALRM signal, one of the following actions shall +be taken: +.IP " 1." 4 +Terminate normally with a zero exit status. +.IP " 2." 4 +Effectively ignore the signal. +.IP " 3." 4 +Provide the default behavior for signals described in the ASYNCHRONOUS +EVENTS section of +.IR "Section 1.4" ", " "Utility Description Defaults". +This could include terminating with a non-zero exit status. +.P +The +.IR sleep +utility shall take the standard action for all other signals. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The execution was successfully suspended for at least +.IR time +seconds, or a SIGALRM signal was received. See the ASYNCHRONOUS EVENTS +section. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +The +.IR sleep +utility can be used to execute a command after a certain amount of +time, as in: +.sp +.RS 4 +.nf +\fB +(sleep 105; \fIcommand\fP) & +.fi \fR +.P +.RE +.P +or to execute a command every so often, as in: +.sp +.RS 4 +.nf +\fB +while true +do + \fIcommand\fP + sleep 37 +done +.fi \fR +.P +.RE +.SH RATIONALE +The exit status is allowed to be zero when +.IR sleep +is interrupted by the SIGALRM signal because most implementations of +this utility rely on the arrival of that signal to notify them that the +requested finishing time has been successfully attained. Such +implementations thus do not distinguish this situation from the +successful completion case. Other implementations are allowed to catch +the signal and go back to sleep until the requested time expires or to +provide the normal signal termination procedures. +.P +As with all other utilities that take integral operands and do not +specify subranges of allowed values, +.IR sleep +is required by this volume of POSIX.1\(hy2008 to deal with +.IR time +requests of up to 2\|147\|483\|647 seconds. This may mean that some +implementations have to make multiple calls to the delay mechanism of +the underlying operating system if its argument range is less than +this. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwait\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIalarm\fR\^(\|)", +.IR "\fIsleep\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/sort.1p b/man-pages-posix-2013/man1p/sort.1p new file mode 100644 index 0000000..a8cde07 --- /dev/null +++ b/man-pages-posix-2013/man1p/sort.1p @@ -0,0 +1,776 @@ +'\" et +.TH SORT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +sort +\(em sort, merge, or sequence check text files +.SH SYNOPSIS +.LP +.nf +sort \fB[\fR\(mim\fB] [\fR\(mio \fIoutput\fB] [\fR\(mibdfinru\fB] [\fR\(mit \fIchar\fB] [\fR\(mik \fIkeydef\fB]\fR... \fB[\fIfile\fR...\fB]\fR +.P +sort \fB[\fR\(mic|\(miC\fB] [\fR\(mibdfinru\fB] [\fR\(mit \fIchar\fB] [\fR\(mik \fIkeydef\fB] [\fIfile\fB]\fR +.fi +.SH DESCRIPTION +The +.IR sort +utility shall perform one of the following functions: +.IP " 1." 4 +Sort lines of all the named files together and write the result to +the specified output. +.IP " 2." 4 +Merge lines of all the named (presorted) files together and write the +result to the specified output. +.IP " 3." 4 +Check that a single input file is correctly presorted. +.P +Comparisons shall be based on one or more sort keys extracted from each +line of input (or, if no sort keys are specified, the entire line up +to, but not including, the terminating +), +and shall be performed using the collating sequence of the current +locale. +.SH OPTIONS +The +.IR sort +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except for Guideline 9, and the +.BR \(mik +.IR keydef +option should follow the +.BR \(mib , +.BR \(mid , +.BR \(mif , +.BR \(mii , +.BR \(min , +and +.BR \(mir +options. In addition, +.BR '\(pl' +may be recognized as an option delimiter as well as +.BR '\(mi' . +.P +The following options shall be supported: +.IP "\fB\(mic\fP" 10 +Check that the single input file is ordered as specified by the +arguments and the collating sequence of the current locale. Output +shall not be sent to standard output. The exit code shall indicate +whether or not disorder was detected or an error occurred. If +disorder (or, with +.BR \(miu , +a duplicate key) is detected, a warning message shall be sent to +standard error indicating where the disorder or duplicate key +was found. +.IP "\fB\(miC\fP" 10 +Same as +.BR \(mic , +except that a warning message shall not be sent to standard error +if disorder or, with +.BR \(miu , +a duplicate key is detected. +.IP "\fB\(mim\fP" 10 +Merge only; the input file shall be assumed to be already sorted. +.IP "\fB\(mio\ \fIoutput\fR" 10 +Specify the name of an output file to be used instead of the standard +output. This file can be the same as one of the input +.IR file s. +.IP "\fB\(miu\fP" 10 +Unique: suppress all but one in each set of lines having equal keys. +If used with the +.BR \(mic +option, check that there are no lines with duplicate keys, in addition +to checking that the input file is sorted. +.P +The following options shall override the default ordering rules. When +ordering options appear independent of any key field specifications, +the requested field ordering rules shall be applied globally to all +sort keys. When attached to a specific key (see +.BR \(mik ), +the specified ordering options shall override all global ordering +options for that key. +.IP "\fB\(mid\fP" 10 +Specify that only + +characters and alphanumeric characters, according to the current +setting of +.IR LC_CTYPE , +shall be significant in comparisons. The behavior is undefined for a +sort key to which +.BR \(mii +or +.BR \(min +also applies. +.IP "\fB\(mif\fP" 10 +Consider all lowercase characters that have uppercase equivalents, +according to the current setting of +.IR LC_CTYPE , +to be the uppercase equivalent for the purposes of comparison. +.IP "\fB\(mii\fP" 10 +Ignore all characters that are non-printable, according to the current +setting of +.IR LC_CTYPE . +The behavior is undefined for a sort key for which +.BR \(min +also applies. +.IP "\fB\(min\fP" 10 +Restrict the sort key to an initial numeric string, consisting of +optional + +characters, optional minus-sign, and zero or more digits with an +optional radix character and thousands separators (as defined in the +current locale), which shall be sorted by arithmetic value. An empty +digit string shall be treated as zero. Leading zeros and signs on zeros +shall not affect ordering. +.IP "\fB\(mir\fP" 10 +Reverse the sense of comparisons. +.P +The treatment of field separators can be altered using the options: +.IP "\fB\(mib\fP" 10 +Ignore leading + +characters when determining the starting and ending positions of a +restricted sort key. If the +.BR \(mib +option is specified before the first +.BR \(mik +option, it shall be applied to all +.BR \(mik +options. Otherwise, the +.BR \(mib +option can be attached independently to each +.BR \(mik +.IR field_start +or +.IR field_end +option-argument (see below). +.IP "\fB\(mit\ \fIchar\fR" 10 +Use +.IR char +as the field separator character; +.IR char +shall not be considered to be part of a field (although it can be +included in a sort key). Each occurrence of +.IR char +shall be significant (for example, <\fIchar\fR><\fIchar\fR> delimits an +empty field). If +.BR \(mit +is not specified, + +characters shall be used as default field separators; each maximal +non-empty sequence of + +characters that follows a non-\c + +shall be a field separator. +.P +Sort keys can be specified using the options: +.IP "\fB\(mik\ \fIkeydef\fR" 10 +The +.IR keydef +argument is a restricted sort key field definition. The format of this +definition is: +.RS 10 +.sp +.RS 4 +.nf +\fB +\fIfield_start\fB[\fItype\fB][\fR,\fIfield_end\fB[\fItype\fB]]\fR +.fi \fR +.P +.RE +.P +where +.IR field_start +and +.IR field_end +define a key field restricted to a portion of the line (see the +EXTENDED DESCRIPTION section), and +.IR type +is a modifier from the list of characters +.BR 'b' , +.BR 'd' , +.BR 'f' , +.BR 'i' , +.BR 'n' , +.BR 'r' . +The +.BR 'b' +modifier shall behave like the +.BR \(mib +option, but shall apply only to the +.IR field_start +or +.IR field_end +to which it is attached. The other modifiers shall behave like the +corresponding options, but shall apply only to the key field to which +they are attached; they shall have this effect if specified with +.IR field_start , +.IR field_end , +or both. If any modifier is attached to a +.IR field_start +or to a +.IR field_end , +no option shall apply to either. Implementations shall support at +least nine occurrences of the +.BR \(mik +option, which shall be significant in command line order. If no +.BR \(mik +option is specified, a default sort key of the entire line shall be +used. +.P +When there are multiple key fields, later keys shall be compared only +after all earlier keys compare equal. Except when the +.BR \(miu +option is specified, lines that otherwise compare equal shall be +ordered as if none of the options +.BR \(mid , +.BR \(mif , +.BR \(mii , +.BR \(min , +or +.BR \(mik +were present (but with +.BR \(mir +still in effect, if it was specified) and with all bytes in the lines +significant to the comparison. The order in which lines that still +compare equal are written is unspecified. +.RE +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file to be sorted, merged, or checked. If no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' , +the standard input shall be used. +.SH STDIN +The standard input shall be used only if no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' . +See the INPUT FILES section. +.SH "INPUT FILES" +The input files shall be text files, except that the +.IR sort +utility shall add a + +to the end of a file ending with an incomplete last line. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR sort : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for ordering rules. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files) and the behavior of +character classification for the +.BR \(mib , +.BR \(mid , +.BR \(mif , +.BR \(mii , +and +.BR \(min +options. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILC_NUMERIC\fP" 10 +.br +Determine the locale for the definition of the radix character and +thousands separator for the +.BR \(min +option. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Unless the +.BR \(mio +or +.BR \(mic +options are in effect, the standard output shall contain the sorted +input. +.SH STDERR +The standard error shall be used for diagnostic messages. When +.BR \(mic +is specified, if disorder is detected (or if +.BR \(miu +is also specified and a duplicate key is detected), a message shall +be written to the standard error which identifies the input line at +which disorder (or a duplicate key) was detected. A warning +message about correcting an incomplete last line of an input file +may be generated, but need not affect the final exit status. +.SH "OUTPUT FILES" +If the +.BR \(mio +option is in effect, the sorted input shall be written to the file +.IR output . +.SH "EXTENDED DESCRIPTION" +The notation: +.sp +.RS 4 +.nf +\fB +\(mik \fIfield_start\fB[\fItype\fB][\fR,\fIfield_end\fB[\fItype\fB]]\fR +.fi \fR +.P +.RE +.P +shall define a key field that begins at +.IR field_start +and ends at +.IR field_end +inclusive, unless +.IR field_start +falls beyond the end of the line or after +.IR field_end , +in which case the key field is empty. A missing +.IR field_end +shall mean the last character of the line. +.P +A field comprises a maximal sequence of non-separating characters and, +in the absence of option +.BR \(mit , +any preceding field separator. +.P +The +.IR field_start +portion of the +.IR keydef +option-argument shall have the form: +.sp +.RS 4 +.nf +\fB +\fIfield_number\fB[\fR.\fIfirst_character\fB]\fR +.fi \fR +.P +.RE +.P +Fields and characters within fields shall be numbered starting with 1. +The +.IR field_number +and +.IR first_character +pieces, interpreted as positive decimal integers, shall specify the +first character to be used as part of a sort key. If +.IR .first_character +is omitted, it shall refer to the first character of the field. +.P +The +.IR field_end +portion of the +.IR keydef +option-argument shall have the form: +.sp +.RS 4 +.nf +\fB +\fIfield_number\fB[\fR.\fIlast_character\fB]\fR +.fi \fR +.P +.RE +.P +The +.IR field_number +shall be as described above for +.IR field_start. +The +.IR last_character +piece, interpreted as a non-negative decimal integer, shall specify the +last character to be used as part of the sort key. If +.IR last_character +evaluates to zero or +.IR .last_character +is omitted, it shall refer to the last character of the field specified +by +.IR field_number . +.P +If the +.BR \(mib +option or +.BR b +type modifier is in effect, characters within a field shall be counted +from the first non-\c + +in the field. (This shall apply separately to +.IR first_character +and +.IR last_character .) +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All input files were output successfully, or +.BR \(mic +was specified and the input file was correctly sorted. +.IP "\01" 6 +Under the +.BR \(mic +option, the file was not ordered as specified, or if the +.BR \(mic +and +.BR \(miu +options were both specified, two input lines were found with equal +keys. +.IP >1 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The default value for +.BR \(mit , +, +has different properties from, for example, +.BR \(mit \c +"". If a line contains: +.sp +.RS 4 +.nf +\fB +foo +.fi \fR +.P +.RE +.P +the following treatment would occur with default separation as opposed +to specifically selecting a +: +.TS +center box tab(@); +cB | cB | cB +n | l | l. +Field@Default@\(mit "" +_ +1@foo@\fIempty\fP +2@\fIempty\fP@\fIempty\fP +3@\fIempty\fP@foo +.TE +.P +The leading field separator itself is included in a field when +.BR \(mit +is not used. For example, this command returns an exit status of zero, +meaning the input was already sorted: +.sp +.RS 4 +.nf +\fB +sort \(mic \(mik 2 <b +xa +eof +.fi \fR +.P +.RE +.P +(assuming that a + +precedes the + +in the current collating sequence). The field separator is not included +in a field when it is explicitly set via +.BR \(mit . +This is historical practice and allows usage such as: +.sp +.RS 4 +.nf +\fB +sort \(mit "|" \(mik 2n < +of the second field as the sort key: +.RS 4 +.sp +.RS 4 +.nf +\fB +sort \(mik 2.2b,2.2b infile1 infile2 +.fi \fR +.P +.RE +.RE +.IP " 4." 4 +The following command prints the System\ V password file (user +database) sorted by the numeric user ID (the third +-separated +field): +.RS 4 +.sp +.RS 4 +.nf +\fB +sort \(mit : \(mik 3,3n /etc/passwd +.fi \fR +.P +.RE +.RE +.IP " 5." 4 +The following command prints the lines of the already sorted file +.BR infile , +suppressing all but one occurrence of lines having the same third +field: +.RS 4 +.sp +.RS 4 +.nf +\fB +sort \(mium \(mik 3.1,3.0 infile +.fi \fR +.P +.RE +.RE +.SH RATIONALE +Examples in some historical documentation state that options +.BR \(mium +with one input file keep the first in each set of lines with equal +keys. This behavior was deemed to be an implementation artifact and +was not standardized. +.P +The +.BR \(miz +option was omitted; it is not standard practice on most systems and is +inconsistent with using +.IR sort +to sort several files individually and then merge them together. The +text concerning +.BR \(miz +in historical documentation appeared to require implementations to +determine the proper buffer length during the sort phase of operation, +but not during the merge. +.P +The +.BR \(miy +option was omitted because of non-portability. The +.BR \(miM +option, present in System V, was omitted because of non-portability in +international usage. +.P +An undocumented +.BR \(miT +option exists in some implementations. It is used to specify a +directory for intermediate files. Implementations are encouraged to +support the use of the +.IR TMPDIR +environment variable instead of adding an option to support this +functionality. +.P +The +.BR \(mik +option was added to satisfy two objections. First, the zero-based +counting used by +.IR sort +is not consistent with other utility conventions. Second, it did not +meet syntax guideline requirements. +.P +Historical documentation indicates that ``setting +.BR \(min +implies +.BR \(mib ''. +The description of +.BR \(min +already states that optional leading s are tolerated in doing +the comparison. If +.BR \(mib +is enabled, rather than implied, by +.BR \(min , +this has unusual side-effects. When a character offset is used in a +column of numbers (for example, to sort modulo 100), that offset is +measured relative to the most significant digit, not to the column. +Based upon a recommendation from the author of the original +.IR sort +utility, the +.BR \(mib +implication has been omitted from this volume of POSIX.1\(hy2008, and an application wishing to +achieve the previously mentioned side-effects has to code the +.BR \(mib +flag explicitly. +.P +Earlier versions of this standard allowed the +.BR \(mio +option to appear after operands. Historical practice allowed all +options to be interspersed with operands. This version of the +standard allows implementations to accept options after operands +but conforming applications should not use this form. +.P +Earlier versions of this standard also allowed the +.BR \(mi \c +.IR number +and +.BR \(pl \c +.IR number +options. These options are no longer specified by POSIX.1\(hy2008 but may +be present in some implementations. +.P +Historical implementations produced a message on standard error when +.BR \(mic +was specified and disorder was detected, and when +.BR \(mic +and +.BR \(miu +were specified and a duplicate key was detected. An earlier version of +this standard contained wording that did not make it clear that this +message was allowed and some implementations removed this message to +be sure that they conformed to the standard's requirements. Confronted +with this difference in behavior, interactive users that wanted to be +sure that they got visual feedback instead of just exit code 1 could +have used a command like: +.sp +.RS 4 +.nf +\fB +sort \(mic file || echo disorder +.fi \fR +.P +.RE +.P +whether or not the +.IR sort +utility provided a message in this case. But, it was not easy for a user +to find where the disorder or duplicate key occurred on implementations +that do not produce a message, especially when some parts of the input +line were not part of the key and when one or more of the +.BR \(mib , +.BR \(mid , +.BR \(mif , +.BR \(mii , +.BR \(min , +or +.BR \(mi r +options or +.IR keydef +type modifiers were in use. POSIX.1\(hy2008 requires a message to be +produced in this case. POSIX.1\(hy2008 also contains the +.BR \(miC +option giving users the ability to choose either behavior. +.P +When a disorder or duplicate is found when the +.BR \(mic +option is specified, some implementations print a message containing +the first line that is out of order or contains a duplicate key; others +print a message specifying the line number of the offending line. This +standard allows either type of message. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcomm\fR\^", +.IR "\fIjoin\fR\^", +.IR "\fIuniq\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fItoupper\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/split.1p b/man-pages-posix-2013/man1p/split.1p new file mode 100644 index 0000000..a8269f0 --- /dev/null +++ b/man-pages-posix-2013/man1p/split.1p @@ -0,0 +1,318 @@ +'\" et +.TH SPLIT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +split +\(em split files into pieces +.SH SYNOPSIS +.LP +.nf +split \fB[\fR\(mil \fIline_count\fB] [\fR\(mia \fIsuffix_length\fB] [\fIfile\fB[\fIname\fB]]\fR +.P +split \(mib \fIn\fB[\fRk|m\fB] [\fR\(mia \fIsuffix_length\fB] [\fIfile\fB[\fIname\fB]]\fR +.fi +.SH DESCRIPTION +The +.IR split +utility shall read an input file and write one or more output files. +The default size of each output file shall be 1\|000 lines. The size +of the output files can be modified by specification of the +.BR \(mib +or +.BR \(mil +options. Each output file shall be created with a unique suffix. The +suffix shall consist of exactly +.IR suffix_length +lowercase letters from the POSIX locale. The letters of the suffix +shall be used as if they were a base-26 digit system, with the first +suffix to be created consisting of all +.BR 'a' +characters, the second with a +.BR 'b' +replacing the last +.BR 'a' , +and so on, until a name of all +.BR 'z' +characters is created. By default, the names of the output files shall +be +.BR 'x' , +followed by a two-character suffix from the character set as described +above, starting with +.BR \(dqaa\(dq , +.BR \(dqab\(dq , +.BR \(dqac\(dq , +and so on, and continuing until the suffix +.BR \(dqzz\(dq , +for a maximum of 676 files. +.P +If the number of files required exceeds the maximum allowed by the +suffix length provided, such that the last allowable file would be +larger than the requested size, the +.IR split +utility shall fail after creating the last file with a valid suffix; +.IR split +shall not delete the files it created with valid suffixes. If the file +limit is not exceeded, the last file created shall contain the +remainder of the input file, and may be smaller than the requested +size. +.SH OPTIONS +The +.IR split +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mia\ \fIsuffix_length\fR" 10 +.br +Use +.IR suffix_length +letters to form the suffix portion of the filenames of the split +file. If +.BR \(mia +is not specified, the default suffix length shall be two. If the sum +of the +.IR name +operand and the +.IR suffix_length +option-argument would create a filename exceeding +{NAME_MAX} +bytes, an error shall result; +.IR split +shall exit with a diagnostic message and no files shall be created. +.IP "\fB\(mib\ \fIn\fR" 10 +Split a file into pieces +.IR n +bytes in size. +.IP "\fB\(mib\ \fIn\fBk\fR" 10 +Split a file into pieces +.IR n *1\|024 +bytes in size. +.IP "\fB\(mib\ \fIn\fBm\fR" 10 +Split a file into pieces +.IR n *1\|048\|576 +bytes in size. +.IP "\fB\(mil\ \fIline_count\fR" 10 +Specify the number of lines in each resulting file piece. The +.IR line_count +argument is an unsigned decimal integer. The default is 1\|000. If +the input does not end with a +, +the partial line shall be included in the last output file. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile\fR" 10 +The pathname of the ordinary file to be split. If no input file is +given or +.IR file +is +.BR '\(mi' , +the standard input shall be used. +.IP "\fIname\fR" 10 +The prefix to be used for each of the files resulting from the split +operation. If no +.IR name +argument is given, +.BR 'x' +shall be used as the prefix of the output files. The combined length +of the basename of +.IR prefix +and +.IR suffix_length +cannot exceed +{NAME_MAX} +bytes. See the OPTIONS section. +.SH STDIN +See the INPUT FILES section. +.SH "INPUT FILES" +Any file can be used as input. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR split : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The output files contain portions of the original input file; otherwise, +unchanged. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +In the following examples +.BR foo +is a text file that contains 5\|000 lines. +.IP " 1." 4 +Create five files, +.BR xaa , +.BR xab , +.BR xac , +.BR xad , +and +.BR xae : +.RS 4 +.sp +.RS 4 +.nf +\fB +split foo +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +Create five files, but the suffixed portion of the created +files consists of three letters, +.BR xaaa , +.BR xaab , +.BR xaac , +.BR xaad , +and +.BR xaae : +.RS 4 +.sp +.RS 4 +.nf +\fB +split \(mia 3 foo +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +Create three files with four-letter suffixes and a supplied prefix, +.BR bar_aaaa , +.BR bar_aaab , +and +.BR bar_aaac : +.RS 4 +.sp +.RS 4 +.nf +\fB +split \(mia 4 \(mil 2000 foo bar_ +.fi \fR +.P +.RE +.RE +.IP " 4." 4 +Create as many files as are necessary to contain at most 20*1\|024 +bytes, each with the default prefix of +.BR x +and a five-letter suffix: +.RS 4 +.sp +.RS 4 +.nf +\fB +split \(mia 5 \(mib 20k foo +.fi \fR +.P +.RE +.RE +.SH RATIONALE +The +.BR \(mib +option was added to provide a mechanism for splitting files other than +by lines. While most uses of the +.BR \(mib +option are for transmitting files over networks, some believed it would +have additional uses. +.P +The +.BR \(mia +option was added to overcome the limitation of being able to create +only 676 files. +.P +Consideration was given to deleting this utility, using the rationale +that the functionality provided by this utility is available via the +.IR csplit +utility (see +.IR "\fIcsplit\fR\^"). +Upon reconsideration of the purpose of the User Portability Utilities +option, it was decided to retain both this utility and the +.IR csplit +utility because users use both utilities and have historical +expectations of their behavior. Furthermore, the splitting on byte +boundaries in +.IR split +cannot be duplicated with the historical +.IR csplit . +.P +The text ``\c +.IR split +shall not delete the files it created with valid suffixes'' would +normally be assumed, but since the related utility, +.IR csplit , +does delete files under some circumstances, the historical behavior of +.IR split +is made explicit to avoid misinterpretation. +.P +Earlier versions of this standard allowed a +.BR \(mi \c +.IR line_count +option. This form is no longer specified by POSIX.1\(hy2008 but may be +present in some implementations. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcsplit\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/strings.1p b/man-pages-posix-2013/man1p/strings.1p new file mode 100644 index 0000000..eaaaf0b --- /dev/null +++ b/man-pages-posix-2013/man1p/strings.1p @@ -0,0 +1,244 @@ +'\" et +.TH STRINGS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strings +\(em find printable strings in files +.SH SYNOPSIS +.LP +.nf +strings \fB[\fR\(mia\fB] [\fR\(mit \fIformat\fB] [\fR\(min \fInumber\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR strings +utility shall look for printable strings in regular files and shall +write those strings to standard output. A printable string is any +sequence of four (by default) or more printable characters terminated +by a + +or NUL character. Additional implementation-defined strings may be +written; see +.IR localedef . +.P +If the first argument is +.BR '\(mi' , +the results are unspecified. +.SH OPTIONS +The +.IR strings +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except for the unspecified usage of +.BR '\(mi' . +.P +The following options shall be supported: +.IP "\fB\(mia\fP" 10 +Scan files in their entirety. If +.BR \(mia +is not specified, it is implementation-defined what portion of each +file is scanned for strings. +.IP "\fB\(min\ \fInumber\fR" 10 +Specify the minimum string length, where the +.IR number +argument is a positive decimal integer. The default shall be 4. +.IP "\fB\(mit\ \fIformat\fR" 10 +Write each string preceded by its byte offset from the start of the +file. The format shall be dependent on the single character used as +the +.IR format +option-argument: +.RS 10 +.IP "\fRd\fR" 6 +The offset shall be written in decimal. +.IP "\fRo\fR" 6 +The offset shall be written in octal. +.IP "\fRx\fR" 6 +The offset shall be written in hexadecimal. +.RE +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a regular file to be used as input. If no +.IR file +operand is specified, the +.IR strings +utility shall read from the standard input. +.SH STDIN +See the INPUT FILES section. +.SH "INPUT FILES" +The input files named by the utility arguments or the standard input +shall be regular files of any format. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR strings : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files) and to identify +printable strings. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Strings found shall be written to the standard output, one per line. +.P +When the +.BR \(mit +option is not specified, the format of the output shall be: +.sp +.RS 4 +.nf +\fB +"%s", <\fIstring\fR> +.fi \fR +.P +.RE +.P +With the +.BR "\(mit\ o" +option, the format of the output shall be: +.sp +.RS 4 +.nf +\fB +"%o %s", <\fIbyte offset\fR>, <\fIstring\fR> +.fi \fR +.P +.RE +.P +With the +.BR "\(mit\ x" +option, the format of the output shall be: +.sp +.RS 4 +.nf +\fB +"%x %s", <\fIbyte offset\fR>, <\fIstring\fR> +.fi \fR +.P +.RE +.P +With the +.BR "\(mit\ d" +option, the format of the output shall be: +.sp +.RS 4 +.nf +\fB +"%d %s", <\fIbyte offset\fR>, <\fIstring\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +By default the data area (as opposed to the text, ``bss'', or header +areas) of a binary executable file is scanned. Implementations +document which areas are scanned. +.P +Some historical implementations do not require NUL or + +terminators for strings to permit those languages that do not use NUL +as a string terminator to have their strings written. +.SH EXAMPLES +None. +.SH RATIONALE +Apart from rationalizing the option syntax and slight difficulties with +object and executable binary files, +.IR strings +is specified to match historical practice closely. The +.BR \(mia +and +.BR \(min +options were introduced to replace the non-conforming +.BR \(mi +and +.BR \(mi \c +.IR number +options. These options are no longer specified by POSIX.1\(hy2008 but +may be present in some implementations. +.P +The +.BR \(mio +option historically means different things on different +implementations. Some use it to mean ``\c +.IR offset +in decimal'', while others use it as ``\c +.IR offset +in octal''. Instead of trying to decide which way would be least +objectionable, the +.BR \(mit +option was added. It was originally named +.BR \(miO +to mean ``offset'', but was changed to +.BR \(mit +to be consistent with +.IR od . +.P +The ISO\ C standard function +\fIisprint\fR() +is restricted to a domain of +.BR "unsigned char" . +This volume of POSIX.1\(hy2008 requires implementations to write strings as defined by the +current locale. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIlocaledef\fR\^", +.IR "\fInm\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/strip.1p b/man-pages-posix-2013/man1p/strip.1p new file mode 100644 index 0000000..1b9eea9 --- /dev/null +++ b/man-pages-posix-2013/man1p/strip.1p @@ -0,0 +1,153 @@ +'\" et +.TH STRIP "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +strip +\(em remove unnecessary information from strippable files +(\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +strip \fIfile\fR... +.fi +.SH DESCRIPTION +A strippable file is defined as a relocatable, object, or executable +file. +On XSI-conformant systems, a strippable file can also be an archive +of object or relocatable files. +.P +The +.IR strip +utility shall remove from strippable files named by the +.IR file +operands any information the implementor deems unnecessary for +execution of those files. The nature of that information is +unspecified. The effect of +.IR strip +on object and executable files shall be similar to the use of the +.BR \(mis +option to +.IR c99 +or +.IR fort77 . +The effect of +.IR strip +on an archive of object files shall be similar to the use of the +.BR \(mis +option to +.IR c99 +or +.IR fort77 +for each object file in the archive. +.SH OPTIONS +None. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname referring to a strippable file. +.SH STDIN +Not used. +.SH "INPUT FILES" +The input files shall be in the form of strippable files successfully +produced by any compiler defined by this volume of POSIX.1\(hy2008 +or produced by creating or updating an archive of such files +using the +.IR ar +utility. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR strip : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The +.IR strip +utility shall produce strippable files of unspecified format. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +Historically, this utility has been used to remove the symbol table +from a strippable file. It was included since it is known that the +amount of symbolic information can amount to several megabytes; the +ability to remove it in a portable manner was deemed important, +especially for smaller systems. +.P +The behavior of +.IR strip +on object and executable files is said to be the same as the +.BR \(mis +option to a compiler. While the end result is essentially the same, +it is not required to be identical. +.P +XSI-conformant systems support use of +.IR strip +on archive files containing object files or relocatable files. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIar\fR\^", +.IR "\fIc99\fR\^", +.IR "\fIfort77\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/stty.1p b/man-pages-posix-2013/man1p/stty.1p new file mode 100644 index 0000000..bd707d1 --- /dev/null +++ b/man-pages-posix-2013/man1p/stty.1p @@ -0,0 +1,807 @@ +'\" et +.TH STTY "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +stty +\(em set the options for a terminal +.SH SYNOPSIS +.LP +.nf +stty \fB[\fR\(mia|\(mig\fB]\fR +.P +stty \fIoperand\fR... +.fi +.SH DESCRIPTION +The +.IR stty +utility shall set or report on terminal I/O characteristics for the +device that is its standard input. Without options or operands +specified, it shall report the settings of certain characteristics, +usually those that differ from implementation-defined defaults. +Otherwise, it shall modify the terminal state according to the +specified operands. Detailed information about the modes listed in the +first five groups below are described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +Operands in the Combination Modes group (see +.IR "Combination Modes") +are implemented using operands in the previous groups. Some +combinations of operands are mutually-exclusive on some terminal types; +the results of using such combinations are unspecified. +.P +Typical implementations of this utility require a communications line +configured to use the +.BR termios +interface defined in the System Interfaces volume of POSIX.1\(hy2008. On systems where none of these lines +are available, and on lines not currently configured to support the +.BR termios +interface, some of the operands need not affect terminal +characteristics. +.SH OPTIONS +The +.IR stty +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mia\fP" 10 +Write to standard output all the current settings for the terminal. +.IP "\fB\(mig\fP" 10 +Write to standard output all the current settings in an unspecified +form that can be used as arguments to another invocation of the +.IR stty +utility on the same system. The form used shall not contain any +characters that would require quoting to avoid word expansion by the +shell; see +.IR "Section 2.6" ", " "Word Expansions". +.SH OPERANDS +The following operands shall be supported to set the terminal +characteristics. +.SS "Control Modes" +.IP "\fBparenb\ \fR(\fB\(miparenb\fR)" 12 +Enable (disable) parity generation and detection. This shall have +the effect of setting (not setting) PARENB in the +.BR termios +.IR c_cflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBparodd\ \fR(\fB\(miparodd\fR)" 12 +.br +Select odd (even) parity. This shall have the effect of setting (not +setting) PARODD in the +.BR termios +.IR c_cflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBcs5\ cs6\ cs7\ cs8\fR" 12 +Select character size, if possible. This shall have the effect of +setting CS5, CS6, CS7, and CS8, respectively, in the +.BR termios +.IR c_cflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fInumber\fR" 12 +Set terminal baud rate to the number given, if possible. If the baud +rate is set to zero, the modem control lines shall no longer be +asserted. This shall have the effect of setting the input and output +.BR termios +baud rate values as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBispeed\ \fInumber\fR" 12 +Set terminal input baud rate to the number given, if possible. If the +input baud rate is set to zero, the input baud rate shall be specified +by the value of the output baud rate. This shall have the effect of +setting the input +.BR termios +baud rate values as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBospeed\ \fInumber\fR" 12 +Set terminal output baud rate to the number given, if possible. If the +output baud rate is set to zero, the modem control lines shall no +longer be asserted. This shall have the effect of setting the output +.BR termios +baud rate values as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBhupcl\ \fR(\fB\(mihupcl\fR)" 12 +Stop asserting modem control lines (do not stop asserting modem control +lines) on last close. This shall have the effect of setting (not +setting) HUPCL in the +.BR termios +.IR c_cflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBhup\ \fR(\fB\(mihup\fR)" 12 +Equivalent to +.BR hupcl (\c +.BR \(mihupcl ). +.IP "\fBcstopb\ \fR(\fB\(micstopb\fR)" 12 +Use two (one) stop bits per character. This shall have the effect of +setting (not setting) CSTOPB in the +.BR termios +.IR c_cflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBcread\ \fR(\fB\(micread\fR)" 12 +Enable (disable) the receiver. This shall have the effect of setting +(not setting) CREAD in the +.BR termios +.IR c_cflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBclocal\ \fR(\fB\(miclocal\fR)" 12 +Assume a line without (with) modem control. This shall have the effect +of setting (not setting) CLOCAL in the +.BR termios +.IR c_cflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.P +It is unspecified whether +.IR stty +shall report an error if an attempt to set a Control Mode fails. +.SS "Input Modes" +.IP "\fBignbrk\ \fR(\fB\(miignbrk\fR)" 12 +Ignore (do not ignore) break on input. This shall have the effect of +setting (not setting) IGNBRK in the +.BR termios +.IR c_iflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBbrkint\ \fR(\fB\(mibrkint\fR)" 12 +Signal (do not signal) INTR on break. This shall have the effect of +setting (not setting) BRKINT in the +.BR termios +.IR c_iflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBignpar\ \fR(\fB\(miignpar\fR)" 12 +Ignore (do not ignore) bytes with parity errors. This shall have the +effect of setting (not setting) IGNPAR in the +.BR termios +.IR c_iflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBparmrk\ \fR(\fB\(miparmrk\fR)" 12 +.br +Mark (do not mark) parity errors. This shall have the effect of +setting (not setting) PARMRK in the +.BR termios +.IR c_iflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBinpck\ \fR(\fB\(miinpck\fR)" 12 +Enable (disable) input parity checking. This shall have the effect of +setting (not setting) INPCK in the +.BR termios +.IR c_iflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBistrip\ \fR(\fB\(miistrip\fR)" 12 +Strip (do not strip) input characters to seven bits. This shall have +the effect of setting (not setting) ISTRIP in the +.BR termios +.IR c_iflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBinlcr\ \fR(\fB\(miinlcr\fR)" 12 +Map (do not map) NL to CR on input. This shall have the effect of +setting (not setting) INLCR in the +.BR termios +.IR c_iflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBigncr\ (\(miigncr)\fR" 12 +Ignore (do not ignore) CR on input. This shall have the effect of +setting (not setting) IGNCR in the +.BR termios +.IR c_iflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBicrnl\ \fR(\fB\(miicrnl\fR)" 12 +Map (do not map) CR to NL on input. This shall have the effect of +setting (not setting) ICRNL in the +.BR termios +.IR c_iflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBixon\ \fR(\fB\(miixon\fR)" 12 +Enable (disable) START/STOP output control. Output from the system is +stopped when the system receives STOP and started when the system +receives START. This shall have the effect of setting (not setting) +IXON in the +.BR termios +.IR c_iflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBixany\ \fR(\fB\(miixany\fR)" 12 +Allow any character to restart output. This shall have the effect of +setting (not setting) IXANY in the +.BR termios +.IR c_iflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBixoff\ \fR(\fB\(miixoff\fR)" 12 +Request that the system send (not send) STOP characters when the input +queue is nearly full and START characters to resume data transmission. +This shall have the effect of setting (not setting) IXOFF in the +.BR termios +.IR c_iflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.SS "Output Modes" +.IP "\fBopost\ \fR(\fB\(miopost\fR)" 12 +Post-process output (do not post-process output; ignore all other +output modes). This shall have the effect of setting (not setting) +OPOST in the +.BR termios +.IR c_oflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBocrnl\ \fR(\fB\(miocrnl\fR)" 12 +Map (do not map) CR to NL on output This shall have the effect of +setting (not setting) OCRNL in the +.BR termios +.IR c_oflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBonocr\ \fR(\fB\(mionocr\fR)" 12 +Do not (do) output CR at column zero. This shall have the effect of +setting (not setting) ONOCR in the +.BR termios +.IR c_oflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBonlret\ \fR(\fB\(mionlret\fR)" 12 +The terminal newline key performs (does not perform) the CR function. +This shall have the effect of setting (not setting) ONLRET in the +.BR termios +.IR c_oflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBofill\ \fR(\fB\(miofill\fR)" 12 +Use fill characters (use timing) for delays. This shall have the +effect of setting (not setting) OFILL in the +.BR termios +.IR c_oflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBofdel\ \fR(\fB\(miofdel\fR)" 12 +Fill characters are DELs (NULs). This shall have the effect of setting +(not setting) OFDEL in the +.BR termios +.IR c_oflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBcr0\ cr1\ cr2\ cr3\fR" 12 +Select the style of delay for CRs. This shall have the effect of +setting CRDLY to CR0, CR1, CR2, or CR3, respectively, in the +.BR termios +.IR c_oflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBnl0\ nl1\fR" 12 +Select the style of delay for NL. This shall have the effect of +setting NLDLY to NL0 or NL1, respectively, in the +.BR termios +.IR c_oflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBtab0\ tab1\ tab2\ tab3\fR" 12 +.br +Select the style of delay for horizontal tabs. This shall have the +effect of setting TABDLY to TAB0, TAB1, TAB2, or TAB3, respectively, +in the +.BR termios +.IR c_oflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +Note that TAB3 has the effect of expanding + +characters to + +characters. +.IP "\fBtabs\ \fR(\fB\(mitabs\fR)" 12 +Synonym for +.BR tab0 +(\c +.BR tab3 ). +.IP "\fBbs0\ bs1\fR" 12 +Select the style of delay for + +characters. This shall have the effect of setting BSDLY to BS0 or BS1, +respectively, in the +.BR termios +.IR c_oflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBff0\ ff1\fR" 12 +Select the style of delay for + +characters. This shall have the effect of setting FFDLY to FF0 or FF1, +respectively, in the +.BR termios +.IR c_oflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBvt0\ vt1\fR" 12 +Select the style of delay for + +characters. This shall have the effect of setting VTDLY to VT0 or VT1, +respectively, in the +.BR termios +.IR c_oflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.SS "Local Modes" +.IP "\fBisig\ \fR(\fB\(miisig\fR)" 12 +Enable (disable) the checking of characters against the special control +characters INTR, QUIT, and SUSP. This shall have the effect of setting +(not setting) ISIG in the +.BR termios +.IR c_lflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBicanon\ \fR(\fB\(miicanon\fR)" 12 +Enable (disable) canonical input (ERASE and KILL processing). This +shall have the effect of setting (not setting) ICANON in the +.BR termios +.IR c_lflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBiexten\ \fR(\fB\(miiexten\fR)" 12 +Enable (disable) any implementation-defined special control +characters not currently controlled by +.BR icanon , +.BR isig , +.BR ixon , +or +.BR ixoff . +This shall have the effect of setting (not setting) IEXTEN in the +.BR termios +.IR c_lflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBecho\ \fR(\fB\(miecho\fR)" 12 +Echo back (do not echo back) every character typed. This shall have +the effect of setting (not setting) ECHO in the +.BR termios +.IR c_lflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBechoe\ \fR(\fB\(miechoe\fR)" 12 +The ERASE character visually erases (does not erase) the last character +in the current line from the display, if possible. This shall have the +effect of setting (not setting) ECHOE in the +.BR termios +.IR c_lflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBechok\ \fR(\fB\(miechok\fR)" 12 +Echo (do not echo) NL after KILL character. This shall have the effect +of setting (not setting) ECHOK in the +.BR termios +.IR c_lflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBechonl\ \fR(\fB\(miechonl\fR)" 12 +Echo (do not echo) NL, even if +.BR echo +is disabled. This shall have the effect of setting (not setting) +ECHONL in the +.BR termios +.IR c_lflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBnoflsh\ \fR(\fB\(minoflsh\fR)" 12 +Disable (enable) flush after INTR, QUIT, SUSP. This shall have the +effect of setting (not setting) NOFLSH in the +.BR termios +.IR c_lflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP "\fBtostop\ \fR(\fB\(mitostop\fR)" 12 +Send SIGTTOU for background output. This shall have the effect of +setting (not setting) TOSTOP in the +.BR termios +.IR c_lflag +field, as defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.SS "Special Control Character Assignments" +.IP "<\fIcontrol\fR>\(hy\fIcharacter\ string\fR" 6 +.br +Set <\fIcontrol\fP>\(hy\fIcharacter\fR to +.IR string . +If <\fIcontrol\fP>\(hy\fIcharacter\fR is one of the character sequences +in the first column of the following table, the corresponding the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface" +control character from the second column shall be recognized. This has +the effect of setting the corresponding element of the +.BR termios +.IR c_cc +array (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 13" ", " "Headers", +.IR ). +.br +.sp +.ce 1 +\fBTable: Control Character Names in \fIstty\fP\fR +.TS +center tab(@) box; +cB | cB | cB +lB | l | l. +Control Character@c_cc Subscript@Description +_ +eof@VEOF@EOF character +eol@VEOL@EOL character +erase@VERASE@ERASE character +intr@VINTR@INTR character +kill@VKILL@KILL character +quit@VQUIT@QUIT character +susp@VSUSP@SUSP character +start@VSTART@START character +stop@VSTOP@STOP character +.TE +.RS 6 +.P +If +.IR string +is a single character, the control character shall be set to that +character. If +.IR string +is the two-character sequence +.BR \(dq^\(mi\(dq +or the string +.IR undef , +the control character shall be set to _POSIX_VDISABLE , if it is in +effect for the device; if _POSIX_VDISABLE is not in effect for the +device, it shall be treated as an error. In the POSIX locale, if +.IR string +is a two-character sequence beginning with + +(\c +.BR '^' ), +and the second character is one of those listed in the +.BR \(dq^c\(dq +column of the following table, the control character shall be set to +the corresponding character value in the Value column of the table. +.sp +.ce 1 +\fBTable: Circumflex Control Characters in \fIstty\fP\fR +.TS +center tab(@) box; +cB cB | cB cB | cB cB +lf5 2 l 6 | lf5 2 l 6 | lf5 2 l. +\&^c@Value@^c@Value@^c@Value +_ +a\fR,\fP A@@l\fR,\fP L@@w\fR,\fP W@ +b\fR,\fP B@@m\fR,\fP M@@x\fR,\fP X@ +c\fR,\fP C@@n\fR,\fP N@@y\fR,\fP Y@ +d\fR,\fP D@@o\fR,\fP O@@z\fR,\fP Z@ +e\fR,\fP E@@p\fR,\fP P@@[@ +f\fR,\fP F@@q\fR,\fP Q@@\e@ +g\fR,\fP G@@r\fR,\fP R@@]@ +h\fR,\fP H@@s\fR,\fP S@@\&^@ +i\fR,\fP I@@t\fR,\fP T@@\&_@ +j\fR,\fP J@@u\fR,\fP U@@?@ +k\fR,\fP K@@v\fR,\fP V@ +.TE +.RE +.IP "\fBmin\ \fInumber\fR" 6 +.br +Set the value of MIN to +.IR number . +MIN is used in non-canonical mode input processing (\c +.BR icanon ). +.IP "\fBtime\ \fInumber\fR" 6 +.br +Set the value of TIME to +.IR number . +TIME is used in non-canonical mode input processing (\c +.BR icanon ). +.SS "Combination Modes" +.IP "\fIsaved\ settings\fR" 6 +.br +Set the current terminal characteristics to the saved settings produced +by the +.BR \(mig +option. +.IP "\fBevenp\fR\ or\ \fBparity\fR" 6 +.br +Enable +.BR parenb +and +.BR cs7 ; +disable +.BR parodd . +.IP "\fBoddp\fR" 6 +.br +Enable +.BR parenb , +.BR cs7 , +and +.BR parodd . +.IP "\fB\(miparity\fR, \fB\(mievenp\fR, or \fB\(mioddp\fR" 6 +.br +Disable +.BR parenb , +and set +.BR cs8 . +.IP "\fBraw\ \fR(\fB\(miraw\fR\ or\ \fBcooked\fR)" 6 +.br +Enable (disable) raw input and output. Raw mode shall be equivalent to +setting: +.RS 6 +.sp +.RS 4 +.nf +\fB +stty cs8 erase ^\(mi kill ^\(mi intr ^\(mi \e + quit ^\(mi eof ^\(mi eol ^\(mi \(mipost \(miinpck +.fi \fR +.P +.RE +.RE +.IP "\fBnl\ \fR(\fB\(minl\fR)" 6 +.br +Disable (enable) +.BR icrnl . +In addition, +.BR \(minl +unsets +.BR inlcr +and +.BR igncr . +.IP "\fBek\fR" 6 +Reset ERASE and KILL characters back to system defaults. +.IP "\fBsane\fR" 6 +.br +Reset all modes to some reasonable, unspecified, values. +.SH STDIN +Although no input is read from standard input, standard input shall be +used to get the current terminal I/O characteristics and to set new +terminal I/O characteristics. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR stty : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +This variable determines the locale for the interpretation of sequences +of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments) and which characters are +in the class +.BR print . +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If operands are specified, no output shall be produced. +.P +If the +.BR \(mig +option is specified, +.IR stty +shall write to standard output the current settings in a form that can +be used as arguments to another instance of +.IR stty +on the same system. +.P +If the +.BR \(mia +option is specified, all of the information as described in the +OPERANDS section shall be written to standard output. Unless otherwise +specified, this information shall be written as +-separated +tokens in an unspecified format, on one or more lines, with an +unspecified number of tokens per line. Additional information may be +written. +.P +If no options or operands are specified, an unspecified subset of the +information written for the +.BR \(mia +option shall be written. +.P +If speed information is written as part of the default output, or if +the +.BR \(mia +option is specified and if the terminal input speed and output speed +are the same, the speed information shall be written as follows: +.sp +.RS 4 +.nf +\fB +"speed %d baud;", <\fIspeed\fR> +.fi \fR +.P +.RE +.P +Otherwise, speeds shall be written as: +.sp +.RS 4 +.nf +\fB +"ispeed %d baud; ospeed %d baud;", <\fIispeed\fR>, <\fIospeed\fR> +.fi \fR +.P +.RE +.P +In locales other than the POSIX locale, the word +.BR baud +may be changed to something more appropriate in those locales. +.P +If control characters are written as part of the default output, or if +the +.BR \(mia +option is specified, control characters shall be written as: +.sp +.RS 4 +.nf +\fB +"%s = %s;", <\fIcontrol-character name\fR>, <\fIvalue\fR> +.fi \fR +.P +.RE +.P +where <\fIvalue\fP> is either the character, or some visual +representation of the character if it is non-printable, or the string +.IR undef +if the character is disabled. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The terminal options were read or set successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.BR \(mig +flag is designed to facilitate the saving and restoring of terminal +state from the shell level. For example, a program may: +.sp +.RS 4 +.nf +\fB +saveterm="$(stty \(mig)" # save terminal state +stty \fI(new settings)\fR # set new state +\&... # ... +stty $saveterm # restore terminal state +.fi \fR +.P +.RE +.P +Since the format is unspecified, the saved value is not portable across +systems. +.P +Since the +.BR \(mia +format is so loosely specified, scripts that save and restore terminal +settings should use the +.BR \(mig +option. +.SH EXAMPLES +None. +.SH RATIONALE +The original +.IR stty +description was taken directly from System V and reflected the System V +terminal driver +.BR termio . +It has been modified to correspond to the terminal driver +.BR termios . +.P +Output modes are specified only for XSI-conformant systems. All +implementations are expected to provide +.IR stty +operands corresponding to all of the output modes they support. +.P +The +.IR stty +utility is primarily used to tailor the user interface of the terminal, +such as selecting the preferred ERASE and KILL characters. As an +application programming utility, +.IR stty +can be used within shell scripts to alter the terminal settings for the +duration of the script. +.P +The +.BR termios +section states that individual disabling of control characters is +possible through the option _POSIX_VDISABLE. +If enabled, two conventions currently exist for specifying this: System +V uses +.BR \(dq^\(mi\(dq , +and BSD uses +.IR undef . +Both are accepted by +.IR stty +in this volume of POSIX.1\(hy2008. The other BSD convention of using the letter +.BR 'u' +was rejected because it conflicts with the actual letter +.BR 'u' , +which is an acceptable value for a control character. +.P +Early proposals did not specify the mapping of +.BR \(dq^c\(dq +to control characters because the control characters were not specified +in the POSIX locale character set description file requirements. The +control character set is now specified in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 3" ", " "Definitions", +so the historical mapping is specified. Note that although the mapping +corresponds to control-character key assignments on many terminals that +use the ISO/IEC\ 646:\|1991 standard (or ASCII) character encodings, the mapping specified +here is to the control characters, not their keyboard encodings. +.P +Since +.BR termios +supports separate speeds for input and output, two new options were +added to specify each distinctly. +.P +Some historical implementations use standard input to get and set +terminal characteristics; others use standard output. Since input from +a login TTY is usually restricted to the owner while output to a TTY is +frequently open to anyone, using standard input provides fewer chances +of accidentally (or maliciously) altering the terminal settings of +other users. Using standard input also allows +.IR stty +.BR \(mia +and +.IR stty +.BR \(mig +output to be redirected for later use. Therefore, usage of standard +input is required by this volume of POSIX.1\(hy2008. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/tabs.1p b/man-pages-posix-2013/man1p/tabs.1p new file mode 100644 index 0000000..e323b9c --- /dev/null +++ b/man-pages-posix-2013/man1p/tabs.1p @@ -0,0 +1,291 @@ +'\" et +.TH TABS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tabs +\(em set terminal tabs +.SH SYNOPSIS +.LP +.nf +tabs \fB[\fR\(mi\fIn\fP|\(mia|\(mia2|\(mic|\(mic2|\(mic3|\(mif|\(mip|\(mis|\(miu\fB] [\fR\(miT \fItype\fB]\fR +.P +tabs \fB[\fR\(miT \fItype\fB] \fIn\fB[[\fIsep\fB[\fR+\fB]\fIn\fB]\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR tabs +utility shall display a series of characters that first clears the +hardware terminal tab settings and then initializes the tab stops at +the specified positions +and optionally adjusts the margin. +.P +The phrase ``tab-stop position +.IR N '' +shall be taken to mean that, from the start of a line of output, +tabbing to position +.IR N +shall cause the next character output to be in the (\c +.IR N +1)th +column position on that line. The maximum number of tab stops allowed +is terminal-dependent. +.P +It need not be possible to implement +.IR tabs +on certain terminals. If the terminal type obtained from the +.IR TERM +environment variable or +.BR \(miT +option represents such a terminal, an appropriate diagnostic message +shall be written to standard error and +.IR tabs +shall exit with a status greater than zero. +.SH OPTIONS +The +.IR tabs +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except for various extensions: the options +.BR \(mia2 , +.BR \(mic2 , +and +.BR \(mic3 +are multi-character. +.P +The following options shall be supported: +.IP "\fB\(mi\fIn\fR" 10 +Specify repetitive tab stops separated by a uniform number of column +positions, +.IR n , +where +.IR n +is a single-digit decimal number. The default usage of +.IR tabs +with no arguments shall be equivalent to +.IR tabs +\(mi8. When +.BR \(mi0 +is used, the tab stops shall be cleared and no new ones set. +.IP "\fB\(mia\fP" 10 +1,10,16,36,72 +.br +Assembler, applicable to some mainframes. +.IP "\fB\(mia2\fP" 10 +1,10,16,40,72 +.br +Assembler, applicable to some mainframes. +.IP "\fB\(mic\fP" 10 +1,8,12,16,20,55 +.br +COBOL, normal format. +.IP "\fB\(mic2\fP" 10 +1,6,10,14,49 +.br +COBOL, compact format (columns 1 to 6 omitted). +.IP "\fB\(mic3\fP" 10 +1,6,10,14,18,22,26,30,34,38,42,46,50,54,58,62,67 +.br +COBOL compact format (columns 1 to 6 omitted), with more tabs than +.BR \(mic2 . +.IP "\fB\(mif\fP" 10 +1,7,11,15,19,23 +.br +FORTRAN +.IP "\fB\(mip\fP" 10 +1,5,9,13,17,21,25,29,33,37,41,45,49,53,57,61 +.br +PL/1 +.IP "\fB\(mis\fP" 10 +1,10,55 +.br +SNOBOL +.IP "\fB\(miu\fP" 10 +1,12,20,44 +.br +Assembler, applicable to some mainframes. +.IP "\fB\(miT\ \fItype\fR" 10 +Indicate the type of terminal. If this option is not supplied and the +.IR TERM +variable is unset or null, an unspecified default terminal type shall +be used. The setting of +.IR type +shall take precedence over the value in +.IR TERM . +.SH OPERANDS +The following operand shall be supported: +.IP "\fIn\fB[[\fIsep\fB[\fR+\fB]\fIn\fB]\fR...\fB]\fR" 10 +A single command line argument that consists of one or more tab-stop +values (\c +.IR n ) +separated by a separator character (\c +.IR sep ) +which is either a + +or a + +character. The application shall ensure that the tab-stop values are +positive decimal integers in strictly ascending order. If any tab-stop +value (except the first one) is preceded by a +, +it is taken as an increment to be added to the previous value. For +example, the tab lists 1,10,20,30 and +.BR \(dq1 10 +10 +10\(dq +are considered to be identical. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR tabs : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITERM\fP" 10 +Determine the terminal type. If this variable is unset or null, and if +the +.BR \(miT +option is not specified, an unspecified default terminal type shall be +used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If standard output is a terminal, the appropriate sequence to clear and +set the tab stops may be written to standard output in an unspecified +format. If standard output is not a terminal, undefined results +occur. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +This utility makes use of the terminal's hardware tabs and the +.IR stty +.IR tabs +option. +.P +This utility is not recommended for application use. +.P +Some integrated display units might not have escape sequences to set +tab stops, but may be set by internal system calls. On these +terminals, +.IR tabs +works if standard output is directed to the terminal; if output is +directed to another file, however, +.IR tabs +fails. +.SH EXAMPLES +None. +.SH RATIONALE +Consideration was given to having the +.IR tput +utility handle all of the functions described in +.IR tabs . +However, the separate +.IR tabs +utility was retained because it seems more intuitive to use a command +named +.IR tabs +than +.IR tput +with a new option. The +.IR tput +utility does not support setting or clearing tabs, and no known +historical version of +.IR tabs +supports the capability of setting arbitrary tab stops. +.P +The System V +.IR tabs +interface is very complex; the version in this volume of POSIX.1\(hy2008 has a reduced feature +list, but many of the features omitted were restored as part of the +XSI option even though the supported languages and coding styles are +primarily historical. +.P +There was considerable sentiment for specifying only a means of +resetting the tabs back to a known state\(empresumably the ``standard'' +of tabs every eight positions. The following features were omitted: +.IP " *" 4 +Setting tab stops via the first line in a file, using \(mi\|\(mi\c +.IR file . +Since even the SVID has no complete explanation of this feature, it is +doubtful that it is in widespread use. +.P +In an early proposal, a +.BR \(mit +.IR tablist +option was added for consistency with +.IR expand ; +this was later removed when inconsistencies with the historical list of +tabs were identified. +.P +Consideration was given to adding a +.BR \(mip +option that would output the current tab settings so that they could be +saved and then later restored. This was not accepted because querying +the tab stops of the terminal is not a capability in historical +.IR terminfo +or +.IR termcap +facilities and might not be supported on a wide range of terminals. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexpand\fR\^", +.IR "\fIstty\fR\^", +.IR "\fItput\fR\^", +.IR "\fIunexpand\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/tail.1p b/man-pages-posix-2013/man1p/tail.1p new file mode 100644 index 0000000..28f5976 --- /dev/null +++ b/man-pages-posix-2013/man1p/tail.1p @@ -0,0 +1,348 @@ +'\" et +.TH TAIL "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tail +\(em copy the last part of a file +.SH SYNOPSIS +.LP +.nf +tail \fB[\fR\(mif\fB] [\fR\(mic \fInumber\fR|\(min \fInumber\fB] [\fIfile\fB]\fR +.fi +.SH DESCRIPTION +The +.IR tail +utility shall copy its input file to the standard output beginning at a +designated place. +.P +Copying shall begin at the point in the file indicated by the +.BR \(mic +.IR number +or +.BR \(min +.IR number +options. The option-argument +.IR number +shall be counted in units of lines or bytes, according to the options +.BR \(min +and +.BR \(mic . +Both line and byte counts start from 1. +.P +Tails relative to the end of the file may be saved in an internal +buffer, and thus may be limited in length. Such a buffer, if any, +shall be no smaller than +{LINE_MAX}*10 +bytes. +.SH OPTIONS +The +.IR tail +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that +.BR '\(pl' +may be recognized as an option delimiter as well as +.BR '\(mi' . +.P +The following options shall be supported: +.IP "\fB\(mic\ \fInumber\fR" 10 +The application shall ensure that the +.IR number +option-argument is a decimal integer, optionally including a sign. +The sign shall affect the location in the file, measured in bytes, +to begin the copying: +.TS +center tab(@) box; +cB | cB +cf5 | l. +Sign@Copying Starts +_ ++@Relative to the beginning of the file. +\(mi@Relative to the end of the file. +\fInone\fP@Relative to the end of the file. +.TE +.RS 10 +.P +The application shall ensure that if the sign of the +.IR number +option-argument is +.BR '\(pl' , +the +.IR number +option-argument is a non-zero decimal integer. +.P +The origin for counting shall be 1; that is, +.BR \(mic ++1 represents the first byte of the file, +.BR \(mic +\(mi1 the last. +.RE +.IP "\fB\(mif\fP" 10 +If the input file is a regular file or if the +.IR file +operand specifies a FIFO, do not terminate after the last line of the +input file has been copied, but read and copy further bytes from the +input file when they become available. If no +.IR file +operand is specified and standard input is a pipe or FIFO, the +.BR \(mif +option shall be ignored. If the input file is not a FIFO, pipe, or +regular file, it is unspecified whether or not the +.BR \(mif +option shall be ignored. +.IP "\fB\(min\ \fInumber\fR" 10 +This option shall be equivalent to +.BR \(mic +.IR number , +except the starting location in the file shall be measured in lines +instead of bytes. The origin for counting shall be 1; that is, +.BR \(min ++1 represents the first line of the file, +.BR \(min +\(mi1 the last. +.P +If neither +.BR \(mic +nor +.BR \(min +is specified, +.BR \(min +10 shall be assumed. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an input file. If no +.IR file +operand is specified, the standard input shall be used. +.SH STDIN +The standard input shall be used if no +.IR file +operand is specified, and shall be used if the +.IR file +operand is +.BR '\(mi' +and the implementation treats the +.BR '\(mi' +as meaning standard input. +Otherwise, the standard input shall not be used. +See the INPUT FILES section. +.SH "INPUT FILES" +If the +.BR \(mic +option is specified, the input file can contain arbitrary data; +otherwise, the input file shall be a text file. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR tail : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The designated portion of the input file shall be written to standard +output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.BR \(mic +option should be used with caution when the input is a text file +containing multi-byte characters; it may produce output that does not +start on a character boundary. +.P +Although the input file to +.IR tail +can be any type, the results might not be what would be expected on +some character special device files or on file types not described by +the System Interfaces volume of POSIX.1\(hy2008. Since this volume of POSIX.1\(hy2008 does not specify the block size used when doing +input, +.IR tail +need not read all of the data from devices that only perform block +transfers. +.SH EXAMPLES +The +.BR \(mif +option can be used to monitor the growth of a file that is being +written by some other process. For example, the command: +.sp +.RS 4 +.nf +\fB +tail \(mif fred +.fi \fR +.P +.RE +.P +prints the last ten lines of the file +.BR fred , +followed by any lines that are appended to +.BR fred +between the time +.IR tail +is initiated and killed. As another example, the command: +.sp +.RS 4 +.nf +\fB +tail \(mif \(mic 15 fred +.fi \fR +.P +.RE +.P +prints the last 15 bytes of the file +.BR fred , +followed by any bytes that are appended to +.BR fred +between the time +.IR tail +is initiated and killed. +.SH RATIONALE +This version of +.IR tail +was created to allow conformance to the Utility Syntax Guidelines. The +historical +.BR \(mib +option was omitted because of the general non-portability of block-sized +units of text. The +.BR \(mic +option historically meant ``characters'', but this volume of POSIX.1\(hy2008 indicates +that it means ``bytes''. This was selected to allow reasonable +implementations when multi-byte characters are possible; it was not +named +.BR \(mib +to avoid confusion with the historical +.BR \(mib . +.P +The origin of counting both lines and bytes is 1, matching all +widespread historical implementations. Hence +.IR tail +.BR \(min ++0 is not conforming usage because it attempts to output line zero; but +note that +.IR tail +.BR \(min +0 does conform, and outputs nothing. +.P +Earlier versions of this standard allowed the following forms in the +SYNOPSIS: +.sp +.RS 4 +.nf +\fB +tail \(mi\fB[\fRnumber\fB][\fRb|c|l\fB][\fRf\fB] [\fIfile\fB]\fR +tail \(pl\fB[\fRnumber\fB][\fRb|c|l\fB][\fRf\fB] [\fIfile\fB]\fR +.fi \fR +.P +.RE +.P +These forms are no longer specified by POSIX.1\(hy2008, but may be +present in some implementations. +.P +The restriction on the internal buffer is a compromise between the +historical System V implementation of 4\|096 bytes and the BSD 32\|768 +bytes. +.P +The +.BR \(mif +option has been implemented as a loop that sleeps for 1 second and +copies any bytes that are available. This is sufficient, but if more +efficient methods of determining when new data are available are +developed, implementations are encouraged to use them. +.P +Historical documentation indicates that +.IR tail +ignores the +.BR \(mif +option if the input file is a pipe (pipe and FIFO on systems that +support FIFOs). On BSD-based systems, this has been true; on System +V-based systems, this was true when input was taken from standard +input, but it did not ignore the +.BR \(mif +flag if a FIFO was named as the +.IR file +operand. Since the +.BR \(mif +option is not useful on pipes and all historical implementations ignore +.BR \(mif +if no +.IR file +operand is specified and standard input is a pipe, this volume of POSIX.1\(hy2008 requires this +behavior. However, since the +.BR \(mif +option is useful on a FIFO, this volume of POSIX.1\(hy2008 also requires that +if a FIFO is named, the +.BR \(mif +option shall not be ignored. Earlier versions of this standard did +not state any requirement for the case where no +.IR file +operand is specified and standard input is a FIFO. The standard has +been updated to reflect current practice which is to treat this case +the same as a pipe on standard input. +Although historical behavior does not ignore the +.BR \(mif +option for other file types, this is unspecified so that +implementations are allowed to ignore the +.BR \(mif +option if it is known that the file cannot be extended. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIhead\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/talk.1p b/man-pages-posix-2013/man1p/talk.1p new file mode 100644 index 0000000..f622d55 --- /dev/null +++ b/man-pages-posix-2013/man1p/talk.1p @@ -0,0 +1,309 @@ +'\" et +.TH TALK "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +talk +\(em talk to another user +.SH SYNOPSIS +.LP +.nf +talk \fIaddress \fB[\fIterminal\fB]\fR +.fi +.SH DESCRIPTION +The +.IR talk +utility is a two-way, screen-oriented communication program. +.P +When first invoked, +.IR talk +shall send a message similar to: +.sp +.RS 4 +.nf +\fB +Message from <\fIunspecified string\fP> +talk: connection requested by \fIyour_address\fP +talk: respond with: talk \fIyour_address\fP +.fi \fR +.P +.RE +.P +to the specified +.IR address . +At this point, the recipient of the message can reply by typing: +.sp +.RS 4 +.nf +\fB +talk \fIyour_address\fR +.fi \fR +.P +.RE +.P +Once communication is established, the two parties can type +simultaneously, with their output displayed in separate regions of the +screen. Characters shall be processed as follows: +.IP " *" 4 +Typing the + +character shall alert the recipient's terminal. +.IP " *" 4 +Typing \(hyL shall cause the sender's screen regions to be +refreshed. +.IP " *" 4 +Typing the erase and kill characters shall affect the sender's terminal +in the manner described by the +.BR termios +interface in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP " *" 4 +Typing the interrupt or end-of-file characters shall terminate the +local +.IR talk +utility. Once the +.IR talk +session has been terminated on one side, the other side of the +.IR talk +session shall be notified that the +.IR talk +session has been terminated and shall be able to do nothing except +exit. +.IP " *" 4 +Typing characters from +.IR LC_CTYPE +classifications +.BR print +or +.BR space +shall cause those characters to be sent to the recipient's terminal. +.IP " *" 4 +When and only when the +.IR stty +.BR iexten +local mode is enabled, the existence and processing of additional +special control characters and multi-byte or single-byte functions +shall be implementation-defined. +.IP " *" 4 +Typing other non-printable characters shall cause +implementation-defined sequences of printable characters to be sent +to the recipient's terminal. +.P +Permission to be a recipient of a +.IR talk +message can be denied or granted by use of the +.IR mesg +utility. However, a user's privilege may further constrain the domain +of accessibility of other users' terminals. The +.IR talk +utility shall fail when the user lacks appropriate privileges to +perform the requested action. +.P +Certain block-mode terminals do not have all the capabilities necessary +to support the simultaneous exchange of messages required for +.IR talk . +When this type of exchange cannot be supported on such terminals, the +implementation may support an exchange with reduced levels of +simultaneous interaction or it may report an error describing the +terminal-related deficiency. +.SH OPTIONS +None. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIaddress\fR" 10 +The recipient of the +.IR talk +session. One form of +.IR address +is the <\fIuser\ name\fP>, as returned by the +.IR who +utility. Other address formats and how they are handled are +unspecified. +.IP "\fIterminal\fR" 10 +If the recipient is logged in more than once, the +.IR terminal +argument can be used to indicate the appropriate terminal name. If +.IR terminal +is not specified, the +.IR talk +message shall be displayed on one or more accessible terminals in use +by the recipient. The format of +.IR terminal +shall be the same as that returned by the +.IR who +utility. +.SH STDIN +Characters read from standard input shall be copied to the recipient's +terminal in an unspecified manner. If standard input is not a +terminal, talk shall write a diagnostic message and exit with a +non-zero status. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR talk : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). If the +recipient's locale does not use an +.IR LC_CTYPE +equivalent to the sender's, the results are undefined. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITERM\fP" 10 +Determine the name of the invoker's terminal type. If this variable is +unset or null, an unspecified default terminal type shall be used. +.SH "ASYNCHRONOUS EVENTS" +When the +.IR talk +utility receives a SIGINT signal, the utility shall terminate and exit +with a zero status. It shall take the standard action for all other +signals. +.SH STDOUT +If standard output is a terminal, characters copied from the +recipient's standard input may be written to standard output. Standard +output also may be used for diagnostic messages. If standard output is +not a terminal, +.IR talk +shall exit with a non-zero status. +.SH STDERR +None. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred or +.IR talk +was invoked on a terminal incapable of supporting it. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Because the handling of non-printable, non-\c + +characters is tied to the +.IR stty +description of +.BR iexten , +implementation extensions within the terminal driver can be accessed. +For example, some implementations provide line editing functions with +certain control character sequences. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR write +utility was included in this volume of POSIX.1\(hy2008 since it can be implemented on all +terminal types. The +.IR talk +utility, which cannot be implemented on certain terminals, was +considered to be a ``better'' communications interface. Both of these +programs are in widespread use on historical implementations. +Therefore, both utilities have been specified. +.P +All references to networking abilities (\fItalk\fPing to a user on +another system) were removed as being outside the scope of this volume of POSIX.1\(hy2008. +.P +Historical BSD and System V versions of +.IR talk +terminate both of the conversations when either user breaks out of the +session. This can lead to adverse consequences if a user unwittingly +continues to enter text that is interpreted by the shell when the other +terminates the session. Therefore, the version of +.IR talk +specified by this volume of POSIX.1\(hy2008 requires both users to terminate their end of the +session explicitly. +.P +Only messages sent to the terminal of the invoking user can be +internationalized in any way: +.IP " *" 4 +The original ``Message from <\fIunspecified string\fP> .\|.\|.'' +message sent to the terminal of the recipient cannot be +internationalized because the environment of the recipient is as yet +inaccessible to the +.IR talk +utility. The environment of the invoking party is irrelevant. +.IP " *" 4 +Subsequent communication between the two parties cannot be +internationalized because the two parties may specify different +languages in their environment (and non-portable characters cannot be +mapped from one language to another). +.IP " *" 4 +Neither party can be required to communicate in a language other than C +and/or the one specified by their environment because unavailable +terminal hardware support (for example, fonts) may be required. +.P +The text in the STDOUT section reflects the usage of the verb +``display'' in this section; some +.IR talk +implementations actually use standard output to write to the terminal, +but this volume of POSIX.1\(hy2008 does not require that to be the case. +.P +The format of the terminal name is unspecified, but the descriptions of +.IR ps , +.IR talk , +.IR who , +and +.IR write +require that they all use or accept the same format. +.P +The handling of non-printable characters is partially +implementation-defined +because the details of mapping them to printable sequences is not +needed by the user. Historical implementations, for security reasons, +disallow the transmission of non-printable characters that may send +commands to the other terminal. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImesg\fR\^", +.IR "\fIstty\fR\^", +.IR "\fIwho\fR\^", +.IR "\fIwrite\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Chapter 11" ", " "General Terminal Interface" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/tee.1p b/man-pages-posix-2013/man1p/tee.1p new file mode 100644 index 0000000..4f8dfde --- /dev/null +++ b/man-pages-posix-2013/man1p/tee.1p @@ -0,0 +1,196 @@ +'\" et +.TH TEE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tee +\(em duplicate standard input +.SH SYNOPSIS +.LP +.nf +tee \fB[\fR\(miai\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR tee +utility shall copy standard input to standard output, making a copy in +zero or more files. The +.IR tee +utility shall not buffer output. +.P +If the +.BR \(mia +option is not specified, output files shall be written (see +.IR "Section 1.1.1.4" ", " "File Read" ", " "Write" ", " "and Creation". +.SH OPTIONS +The +.IR tee +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mia\fP" 10 +Append the output to the files. +.IP "\fB\(mii\fP" 10 +Ignore the SIGINT signal. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an output file. If a +.IR file +operand is +.BR '\(mi' , +it shall refer to a file named +.BR \(mi ; +implementations shall not treat it as meaning standard output. +Processing of at least 13 +.IR file +operands shall be supported. +.SH STDIN +The standard input can be of any type. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR tee : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default, except that if the +.BR \(mii +option was specified, SIGINT shall be ignored. +.SH STDOUT +The standard output shall be a copy of the standard input. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +If any +.IR file +operands are specified, the standard input shall be copied to each +named file. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The standard input was successfully copied to all output files. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If a write to any successfully opened +.IR file +operand fails, writes to other successfully opened +.IR file +operands and standard output shall continue, but the exit status shall +be non-zero. Otherwise, the default actions specified in +.IR "Section 1.4" ", " "Utility Description Defaults" +apply. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR tee +utility is usually used in a pipeline, to make a copy of the output of +some utility. +.P +The +.IR file +operand is technically optional, but +.IR tee +is no more useful than +.IR cat +when none is specified. +.SH EXAMPLES +Save an unsorted intermediate form of the data in a pipeline: +.sp +.RS 4 +.nf +\fB +\&... | tee unsorted | sort > sorted +.fi \fR +.P +.RE +.SH RATIONALE +The buffering requirement means that +.IR tee +is not allowed to use ISO\ C standard fully buffered or line-buffered writes. It +does not mean that +.IR tee +has to do 1-byte reads followed by 1-byte writes. +.P +It should be noted that early versions of BSD ignore any invalid +options and accept a single +.BR '\(mi' +as an alternative to +.BR \(mii . +They also print a message if unable to open a file: +.sp +.RS 4 +.nf +\fB +"tee: cannot access %s\en", <\fIpathname\fP> +.fi \fR +.P +.RE +.P +Historical implementations ignore write errors. This is explicitly not +permitted by this volume of POSIX.1\(hy2008. +.P +Some historical implementations use O_APPEND when providing append +mode; others use the +\fIlseek\fR() +function to seek to the end-of-file after opening the file without +O_APPEND. This volume of POSIX.1\(hy2008 requires functionality equivalent to using O_APPEND; +see +.IR "Section 1.1.1.4" ", " "File Read" ", " "Write" ", " "and Creation". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 1" ", " "Introduction", +.IR "\fIcat\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIlseek\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/test.1p b/man-pages-posix-2013/man1p/test.1p new file mode 100644 index 0000000..f9779dd --- /dev/null +++ b/man-pages-posix-2013/man1p/test.1p @@ -0,0 +1,1058 @@ +'\" et +.TH TEST "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +test +\(em evaluate expression +.SH SYNOPSIS +.LP +.nf +test \fB[\fIexpression\fB]\fR +.P +[ \fB[\fIexpression\fB]\fR ] +.fi +.SH DESCRIPTION +The +.IR test +utility shall evaluate the +.IR expression +and indicate the result of the evaluation by its exit status. An exit +status of zero indicates that the expression evaluated as true and an +exit status of 1 indicates that the expression evaluated as false. +.P +In the second form of the utility, which uses +.BR \(dq[]\(dq +rather than +.IR test , +the application shall ensure that the square brackets are separate +arguments. +.SH OPTIONS +The +.IR test +utility shall not recognize the +.BR \(dq\(mi\|\(mi\(dq +argument in the manner specified by Guideline 10 in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +No options shall be supported. +.SH OPERANDS +The application shall ensure that all operators and elements of +primaries are presented as separate arguments to the +.IR test +utility. +.P +The following primaries can be used to construct +.IR expression : +.IP "\fB\(mib\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to en existing directory entry for a block special file. +False if +.IR pathname +cannot be resolved, or if +.IR pathname +resolves to an existing directory entry for a file that is not a block +special file. +.IP "\fB\(mic\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to an existing directory entry for a character special file. +False if +.IR pathname +cannot be resolved, or if +.IR pathname +resolves to an existing directory entry for a file that is not a character +special file. +.IP "\fB\(mid\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to an existing directory entry for a directory. False if +.IR pathname +cannot be resolved, or if +.IR pathname +resolves to an existing directory entry for a file that is not a +directory. +.IP "\fB\(mie\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to an existing directory entry. False if +.IR pathname +cannot be resolved. +.IP "\fB\(mif\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to an existing directory entry for a regular file. False if +.IR pathname +cannot be resolved, or if +.IR pathname +resolves to an existing directory entry for a file that is not a +regular file. +.IP "\fB\(mig\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to an existing directory entry for a file that has its +set-group-ID flag set. False if +.IR pathname +cannot be resolved, or if +.IR pathname +resolves to an existing directory entry for a file that does not have +its set-group-ID flag set. +.IP "\fB\(mih\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to an existing directory entry for a symbolic link. False if +.IR pathname +cannot be resolved, or if +.IR pathname +resolves to an existing directory entry for a file that is not a symbolic +link. If the final component of +.IR pathname +is a symbolic link, that symbolic link is not followed. +.IP "\fB\(miL\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to an existing directory entry for a symbolic link. False if +.IR pathname +cannot be resolved, or if +.IR pathname +resolves to an existing directory entry for a file that is not a symbolic +link. If the final component of +.IR pathname +is a symbolic link, that symbolic link is not followed. +.IP "\fB\(min\ \fIstring\fR" 10 +True if the length of +.IR string +is non-zero; otherwise, false. +.IP "\fB\(mip\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to an existing directory entry for a FIFO. False if +.IR pathname +cannot be resolved, or if +.IR pathname +resolves to an existing directory entry for a file that is not a FIFO. +.IP "\fB\(mir\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to an existing directory entry for a file for which permission +to read from the file will be granted, as defined in +.IR "Section 1.1.1.4" ", " "File Read" ", " "Write" ", " "and Creation". +False if +.IR pathname +cannot be resolved, or if +.IR pathname +resolves to an existing directory entry for a file for which permission +to read from the file will not be granted. +.IP "\fB\(miS\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to an existing directory entry for a socket. False if +.IR pathname +cannot be resolved, or if +.IR pathname +resolves to an existing directory entry for a file that is not a socket. +.IP "\fB\(mis\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to an existing directory entry for a file that has a size +greater than zero. False if +.IR pathname +cannot be resolved, or if +.IR pathname +resolves to an existing directory entry for a file that does not have +a size greater than zero. +.IP "\fB\(mit\ \fIfile_descriptor\fR" 10 +.br +True if file descriptor number +.IR file_descriptor +is open and is associated with a terminal. False if +.IR file_descriptor +is not a valid file descriptor number, or if file descriptor number +.IR file_descriptor +is not open, or if it is open but is not associated with a terminal. +.IP "\fB\(miu\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to an existing directory entry for a file that has its +set-user-ID flag set. False if +.IR pathname +cannot be resolved, or if +.IR pathname +resolves to an existing directory entry for a file that does not have +its set-user-ID flag set. +.IP "\fB\(miw\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to an existing directory entry for a file for which permission +to write to the file will be granted, as defined in +.IR "Section 1.1.1.4" ", " "File Read" ", " "Write" ", " "and Creation". +False if +.IR pathname +cannot be resolved, or if +.IR pathname +resolves to an existing directory entry for a file for which permission +to write to the file will not be granted. +.IP "\fB\(mix\ \fIpathname\fR" 10 +True if +.IR pathname +resolves to an existing directory entry for a file for which permission +to execute the file (or search it, if it is a directory) will be granted, +as defined in +.IR "Section 1.1.1.4" ", " "File Read" ", " "Write" ", " "and Creation". +False if +.IR pathname +cannot be resolved, or if +.IR pathname +resolves to an existing directory entry for a file for which permission +to execute (or search) the file will not be granted. +.IP "\fB\(miz\ \fIstring\fR" 10 +True if the length of string +.IR string +is zero; otherwise, false. +.IP "\fIstring\fR" 10 +True if the string +.IR string +is not the null string; otherwise, false. +.IP "\fIs1\fB\ \(eq\ \fIs2\fR" 10 +True if the strings +.IR s1 +and +.IR s2 +are identical; otherwise, false. +.IP "\fIs1\fB\ !=\ \fIs2\fR" 10 +True if the strings +.IR s1 +and +.IR s2 +are not identical; otherwise, false. +.IP "\fIn1\fB\ \(mieq\ \fIn2\fR" 10 +True if the integers +.IR n1 +and +.IR n2 +are algebraically equal; otherwise, false. +.IP "\fIn1\fB\ \(mine\ \fIn2\fR" 10 +True if the integers +.IR n1 +and +.IR n2 +are not algebraically equal; otherwise, false. +.IP "\fIn1\fB\ \(migt\ \fIn2\fR" 10 +True if the integer +.IR n1 +is algebraically greater than the integer +.IR n2 ; +otherwise, false. +.IP "\fIn1\fB\ \(mige\ \fIn2\fR" 10 +True if the integer +.IR n1 +is algebraically greater than or equal to the integer +.IR n2 ; +otherwise, false. +.IP "\fIn1\fB\ \(milt\ \fIn2\fR" 10 +True if the integer +.IR n1 +is algebraically less than the integer +.IR n2 ; +otherwise, false. +.IP "\fIn1\fB\ \(mile\ \fIn2\fR" 10 +True if the integer +.IR n1 +is algebraically less than or equal to the integer +.IR n2 ; +otherwise, false. +.IP "\fIexpression1\fB\ \(mia\ \fIexpression2\fR" 10 +.br +True if both +.IR expression1 +and +.IR expression2 +are true; otherwise, false. The +.BR \(mia +binary primary is left associative. It has a higher precedence than +.BR \(mio . +.IP "\fIexpression1\fB\ \(mio\ \fIexpression2\fR" 10 +.br +True if either +.IR expression1 +or +.IR expression2 +is true; otherwise, false. The +.BR \(mio +binary primary is left associative. +.P +With the exception of the +.BR \(mih +.IR pathname +and +.BR \(miL +.IR pathname +primaries, if a +.IR pathname +argument is a symbolic link, +.IR test +shall evaluate the expression by resolving the symbolic link and using +the file referenced by the link. +.P +These primaries can be combined with the following operators: +.IP "\fB!\ \fIexpression\fR" 10 +True if +.IR expression +is false. False if +.IR expression +is true. +.IP "\fB(\ \fIexpression\ \fB)\fR" 10 +True if +.IR expression +is true. False if +.IR expression +is false. The parentheses can be used to alter the normal precedence +and associativity. +.P +The primaries with two elements of the form: +.sp +.RS 4 +.nf +\fB +\(mi\fIprimary_operator primary_operand\fR +.fi \fR +.P +.RE +.P +are known as +.IR "unary primaries" . +The primaries with three elements in either of the two forms: +.sp +.RS 4 +.nf +\fB +\fIprimary_operand \fR\(mi\fIprimary_operator primary_operand +.P +primary_operand primary_operator primary_operand\fR +.fi \fR +.P +.RE +.P +are known as +.IR "binary primaries" . +Additional implementation-defined operators and +.IR primary_operator s +may be provided by implementations. They shall be of the form \(mi\c +.IR operator +where the first character of +.IR operator +is not a digit. +.P +The algorithm for determining the precedence of the operators and the +return value that shall be generated is based on the number of +arguments presented to +.IR test . +(However, when using the +.BR \(dq[...]\(dq +form, the + +final argument shall not be counted in this algorithm.) +.P +In the following list, $1, $2, $3, and $4 represent the arguments +presented to +.IR test : +.IP "0\ arguments:" 12 +Exit false (1). +.IP "1\ argument:" 12 +Exit true (0) if $1 is not null; otherwise, exit false. +.IP "2\ arguments:" 12 +.sp -1v +.RS 12 +.IP " *" 4 +If $1 is +.BR '!' , +exit true if $2 is null, false if $2 is not null. +.IP " *" 4 +If $1 is a unary primary, exit true if the unary test is true, false if +the unary test is false. +.IP " *" 4 +Otherwise, produce unspecified results. +.RE +.IP "3\ arguments:" 12 +.sp -1v +.RS 12 +.IP " *" 4 +If $2 is a binary primary, perform the binary test of $1 and $3. +.IP " *" 4 +If $1 is +.BR '!' , +negate the two-argument test of $2 and $3. +.IP " *" 4 +If $1 is +.BR '(' +and $3 is +.BR ')' , +perform the unary test of $2. +On systems that do not support the XSI option, the results are +unspecified if $1 is +.BR '(' +and $3 is +.BR ')' . +.IP " *" 4 +Otherwise, produce unspecified results. +.RE +.IP "4\ arguments:" 12 +.sp -1v +.RS 12 +.IP " *" 4 +If $1 is +.BR '!' , +negate the three-argument test of $2, $3, and $4. +.IP " *" 4 +If $1 is +.BR '(' +and $4 is +.BR ')' , +perform the two-argument test of $2 and $3. +On systems that do not support the XSI option, the results are +unspecified if $1 is +.BR '(' +and $4 is +.BR ')' . +.IP " *" 4 +Otherwise, the results are unspecified. +.RE +.IP ">4\ arguments:" 12 +The results are unspecified. +.RS 12 +.P +On XSI-conformant systems, combinations of primaries and operators +shall be evaluated using the precedence and associativity rules +described previously. In addition, the string comparison binary +primaries +.BR '=' +and +.BR \(dq!=\(dq +shall have a higher precedence than any unary primary. +.RE +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR test : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +.IR expression +evaluated to true. +.IP "\01" 6 +.IR expression +evaluated to false or +.IR expression +was missing. +.IP >1 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The XSI extensions specifying the +.BR \(mia +and +.BR \(mio +binary primaries and the +.BR '(' +and +.BR ')' +operators have been marked obsolescent. (Many expressions using them +are ambiguously defined by the grammar depending on the specific +expressions being evaluated.) Scripts using these expressions should be +converted to the forms given below. Even though many implementations +will continue to support these obsolescent forms, scripts should be +extremely careful when dealing with user-supplied input that could be +confused with these and other primaries and operators. Unless the +application developer knows all the cases that produce input to the +script, invocations like: +.sp +.RS 4 +.nf +\fB +test "$1" \(mia "$2" +.fi \fR +.P +.RE +.P +should be written as: +.sp +.RS 4 +.nf +\fB +test "$1" && test "$2" +.fi \fR +.P +.RE +.P +to avoid problems if a user supplied values such as $1 set to +.BR '!' +and $2 set to the null string. That is, in cases where maximal +portability is of concern, replace: +.sp +.RS 4 +.nf +\fB +test expr1 \(mia expr2 +.fi \fR +.P +.RE +.P +with: +.sp +.RS 4 +.nf +\fB +test expr1 && test expr2 +.fi \fR +.P +.RE +.P +and replace: +.sp +.RS 4 +.nf +\fB +test expr1 \(mio expr2 +.fi \fR +.P +.RE +.P +with: +.sp +.RS 4 +.nf +\fB +test expr1 || test expr2 +.fi \fR +.P +.RE +.P +but note that, in +.IR test , +.BR \(mia +has higher precedence than +.BR \(mio +while +.BR \(dq&&\(dq +and +.BR \(dq||\(dq +have equal precedence in the shell. +.P +Parentheses or braces can be used in the shell command language to +effect grouping. +.P +Parentheses must be escaped when using +.IR sh ; +for example: +.sp +.RS 4 +.nf +\fB +test \e( expr1 \(mia expr2 \e) \(mio expr3 +.fi \fR +.P +.RE +.P +This command is not always portable even on XSI-conformant systems +depending on the expressions specified by +.IR expr 1, +.IR expr 2, +and +.IR expr 3. +The following form can be used instead: +.sp +.RS 4 +.nf +\fB +( test expr1 && test expr2 ) || test expr3 +.fi \fR +.P +.RE +.P +The two commands: +.sp +.RS 4 +.nf +\fB +test "$1" +test ! "$1" +.fi \fR +.P +.RE +.P +could not be used reliably on some historical systems. Unexpected +results would occur if such a +.IR string +expression were used and $1 expanded to +.BR '!' , +.BR '(' , +or a known unary primary. Better constructs are: +.sp +.RS 4 +.nf +\fB +test \(min "$1" +test \(miz "$1" +.fi \fR +.P +.RE +respectively. +.P +Historical systems have also been unreliable given the common +construct: +.sp +.RS 4 +.nf +\fB +test "$response" = "expected string" +.fi \fR +.P +.RE +.P +One of the following is a more reliable form: +.sp +.RS 4 +.nf +\fB +test "X$response" = "Xexpected string" +test "expected string" = "$response" +.fi \fR +.P +.RE +.P +Note that the second form assumes that +.IR "expected string" +could not be confused with any unary primary. If +.IR "expected string" +starts with +.BR '\(mi' , +.BR '(' , +.BR '!' , +or even +.BR '=' , +the first form should be used instead. Using the preceding rules +without the XSI marked extensions, any of the three comparison forms is +reliable, given any input. (However, note that the strings are quoted +in all cases.) +.P +Because the string comparison binary primaries, +.BR '=' +and +.BR \(dq!=\(dq , +have a higher precedence than any unary primary in the greater than 4 +argument case, unexpected results can occur if arguments are not +properly prepared. For example, in: +.sp +.RS 4 +.nf +\fB +test \(mid $1 \(mio \(mid $2 +.fi \fR +.P +.RE +.P +If $1 evaluates to a possible directory name of +.BR '=' , +the first three arguments are considered a string comparison, which +shall cause a syntax error when the second +.BR \(mid +is encountered. One of the following forms prevents this; the second +is preferred: +.sp +.RS 4 +.nf +\fB +test \e( \(mid "$1" \e) \(mio \e( \(mid "$2" \e) +test \(mid "$1" || test \(mid "$2" +.fi \fR +.P +.RE +.P +Also in the greater than 4 argument case: +.sp +.RS 4 +.nf +\fB +test "$1" = "bat" \(mia "$2" = "ball" +.fi \fR +.P +.RE +.P +syntax errors occur if $1 evaluates to +.BR '(' +or +.BR '!' . +One of the following forms prevents this; the third is preferred: +.sp +.RS 4 +.nf +\fB +test "X$1" = "Xbat" \(mia "X$2" = "Xball" +test "$1" = "bat" && test "$2" = "ball" +test "X$1" = "Xbat" && test "X$2" = "Xball" +.fi \fR +.P +.RE +.SH EXAMPLES +.IP " 1." 4 +Exit if there are not two or three arguments (two variations): +.RS 4 +.sp +.RS 4 +.nf +\fB +if [ $# \(mine 2 ] && [ $# \(mine 3 ]; then exit 1; fi +if [ $# \(milt 2 ] || [ $# \(migt 3 ]; then exit 1; fi +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +Perform a +.IR mkdir +if a directory does not exist: +.RS 4 +.sp +.RS 4 +.nf +\fB +test ! \(mid tempdir && mkdir tempdir +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +Wait for a file to become non-readable: +.RS 4 +.sp +.RS 4 +.nf +\fB +while test \(mir thefile +do + sleep 30 +done +echo '"thefile" is no longer readable' +.fi \fR +.P +.RE +.RE +.IP " 4." 4 +Perform a command if the argument is one of three strings (two +variations): +.RS 4 +.sp +.RS 4 +.nf +\fB +if [ "$1" = "pear" ] || [ "$1" = "grape" ] || [ "$1" = "apple" ] +then + \fIcommand\fP +fi +.P +case "$1" in + pear|grape|apple) \fIcommand\fP ;; +esac +.fi \fR +.P +.RE +.RE +.SH RATIONALE +The KornShell-derived conditional command (double bracket +.BR [[\|]] ) +was removed from the shell command language description in an early +proposal. Objections were raised that the real problem is misuse of the +.IR test +command (\c +.BR [ ), +and putting it into the shell is the wrong way to fix the problem. +Instead, proper documentation and a new shell reserved word (\c +.BR ! ) +are sufficient. +.P +Tests that require multiple +.IR test +operations can be done at the shell level using individual invocations +of the +.IR test +command and shell logicals, rather than using the error-prone +.BR \(mio +flag of +.IR test . +.P +XSI-conformant systems support more than four arguments. +.P +XSI-conformant systems support the combining of primaries with the +following constructs: +.IP "\fIexpression1\fB \(mia \fIexpression2\fR" 6 +.br +True if both +.IR expression1 +and +.IR expression2 +are true. +.IP "\fIexpression1\fB \(mio \fIexpression2\fR" 6 +.br +True if at least one of +.IR expression1 +and +.IR expression2 +are true. +.IP "\fB( \fIexpression \fB)\fR" 6 +.br +True if +.IR expression +is true. +.P +In evaluating these more complex combined expressions, the following +precedence rules are used: +.IP " *" 4 +The unary primaries have higher precedence than the algebraic binary +primaries. +.IP " *" 4 +The unary primaries have lower precedence than the string binary +primaries. +.IP " *" 4 +The unary and binary primaries have higher precedence than the unary +.IR string +primary. +.IP " *" 4 +The +.BR ! +operator has higher precedence than the +.BR \(mia +operator, and the +.BR \(mia +operator has higher precedence than the +.BR \(mio +operator. +.IP " *" 4 +The +.BR \(mia +and +.BR \(mio +operators are left associative. +.IP " *" 4 +The parentheses can be used to alter the normal precedence and +associativity. +.P +The BSD and System V versions of +.BR \(mif +are not the same. The BSD definition was: +.IP "\fB\(mif\ \fIfile\fR" 10 +True if +.IR file +exists and is not a directory. +.P +The SVID version (true if the file exists and is a regular file) was +chosen for this volume of POSIX.1\(hy2008 because its use is consistent with the +.BR \(mib , +.BR \(mic , +.BR \(mid , +and +.BR \(mip +operands (\c +.IR file +exists and is a specific file type). +.P +The +.BR \(mie +primary, possessing similar functionality to that provided by the C +shell, was added because it provides the only way for a shell script to +find out if a file exists without trying to open the file. Since +implementations are allowed to add additional file types, a portable +script cannot use: +.sp +.RS 4 +.nf +\fB +test \(mib foo \(mio \(mic foo \(mio \(mid foo \(mio \(mif foo \(mio \(mip foo +.fi \fR +.P +.RE +.P +to find out if +.BR foo +is an existing file. On historical BSD systems, the existence of a +file could be determined by: +.sp +.RS 4 +.nf +\fB +test \(mif foo \(mio \(mid foo +.fi \fR +.P +.RE +.P +but there was no easy way to determine that an existing file was a +regular file. An early proposal used the KornShell +.BR \(mia +primary (with the same meaning), but this was changed to +.BR \(mie +because there were concerns about the high probability of humans +confusing the +.BR \(mia +primary with the +.BR \(mia +binary operator. +.P +The following options were not included in this volume of POSIX.1\(hy2008, although they are +provided by some implementations. These operands should not be used by +new implementations for other purposes: +.IP "\fB\(mik\ \fIfile\fR" 10 +True if +.IR file +exists and its sticky bit is set. +.IP "\fB\(miC\ \fIfile\fR" 10 +True if +.IR file +is a contiguous file. +.IP "\fB\(miV\ \fIfile\fR" 10 +True if +.IR file +is a version file. +.P +The following option was not included because it was undocumented in +most implementations, has been removed from some implementations +(including System V), and the functionality is provided by the shell +(see +.IR "Section 2.6.2" ", " "Parameter Expansion". +.IP "\fB\(mil\ \fIstring\fR" 10 +The length of the string +.IR string . +.P +The +.BR \(mib , +.BR \(mic , +.BR \(mig , +.BR \(mip , +.BR \(miu , +and +.BR \(mix +operands are derived from the SVID; historical BSD does not provide +them. The +.BR \(mik +operand is derived from System V; historical BSD does not provide it. +.P +On historical BSD systems, +.IR test +.BR \(miw +.IR directory +always returned false because +.IR test +tried to open the directory for writing, which always fails. +.P +Some additional primaries newly invented or from the KornShell appeared +in an early proposal as part of the conditional command (\c +.BR [[\|]] ): +.IR s1 +.BR > +.IR s2 , +.IR s1 +.BR < +.IR s2 , +.IR str +.BR = +.IR pattern , +.IR str +.BR != +.IR pattern , +.IR f1 +.BR \(mint +.IR f2 , +.IR f1 +.BR \(miot +.IR f2 , +and +.IR f1 +.BR \(mief +.IR f2 . +They were not carried forward into the +.IR test +utility when the conditional command was removed from the shell because +they have not been included in the +.IR test +utility built into historical implementations of the +.IR sh +utility. +.P +The +.BR \(mit +.IR file_descriptor +primary is shown with a mandatory argument because the grammar is +ambiguous if it can be omitted. Historical implementations have allowed +it to be omitted, providing a default of 1. +.P +It is noted that +.BR '[' +is not part of the portable filename character set; however, since it +is required to be encoded by a single byte, and is part of the portable +character set, the name of this utility forms a character string across +all supported locales. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 1.1.1.4" ", " "File Read" ", " "Write" ", " "and Creation", +.IR "\fIfind\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/time.1p b/man-pages-posix-2013/man1p/time.1p new file mode 100644 index 0000000..7dc70ab --- /dev/null +++ b/man-pages-posix-2013/man1p/time.1p @@ -0,0 +1,320 @@ +'\" et +.TH TIME "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 time a simple command +.SH SYNOPSIS +.LP +.nf +time \fB[\fR\(mip\fB] \fIutility \fB[\fIargument\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR time +utility shall invoke the utility named by the +.IR utility +operand with arguments supplied as the +.IR argument +operands and write a message to standard error that lists timing +statistics for the utility. The message shall include the following +information: +.IP " *" 4 +The elapsed (real) time between invocation of +.IR utility +and its termination. +.IP " *" 4 +The User CPU time, equivalent to the sum of the +.IR tms_utime +and +.IR tms_cutime +fields returned by the +\fItimes\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008 for the process in which +.IR utility +is executed. +.IP " *" 4 +The System CPU time, equivalent to the sum of the +.IR tms_stime +and +.IR tms_cstime +fields returned by the +\fItimes\fR() +function for the process in which +.IR utility +is executed. +.P +The precision of the timing shall be no less than the granularity +defined for the size of the clock tick unit on the system, but the +results shall be reported in terms of standard time units (for example, +0.02 seconds, 00:00:00.02, 1m33.75s, 365.21 seconds), not numbers of +clock ticks. +.P +When +.IR time +is used as part of a pipeline, the times reported are unspecified, +except when it is the sole command within a grouping command (see +.IR "Section 2.9.4.1" ", " "Grouping Commands") +in that pipeline. For example, the commands on the left are +unspecified; those on the right report on utilities +.BR a +and +.BR c , +respectively: +.sp +.RS 4 +.nf +\fB +time a | b | c { time a; } | b | c +a | b | time c a | b | (time c) +.fi \fR +.P +.RE +.SH OPTIONS +The +.IR time +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(mip\fP" 10 +Write the timing output to standard error in the format shown in the +STDERR section. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIutility\fR" 10 +The name of a utility that is to be invoked. If the +.IR utility +operand names any of the special built-in utilities in +.IR "Section 2.14" ", " "Special Built-In Utilities", +the results are undefined. +.IP "\fIargument\fR" 10 +Any string to be supplied as an argument when invoking the utility +named by the +.IR utility +operand. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR time : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic and informative messages written to standard +error. +.IP "\fILC_NUMERIC\fP" 10 +.br +Determine the locale for numeric formatting. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPATH\fP" 10 +Determine the search path that shall be used to locate the utility to +be invoked; see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used to write the timing statistics. If +.BR \(mip +is specified, the following format shall be used in the POSIX locale: +.sp +.RS 4 +.nf +\fB +"real %f\enuser %f\ensys %f\en", <\fIreal seconds\fR>, <\fIuser seconds\fR>, + <\fIsystem seconds\fR> +.fi \fR +.P +.RE +.P +where each floating-point number shall be expressed in seconds. The +precision used may be less than the default six digits of +.BR %f , +but shall be sufficiently precise to accommodate the size of the clock +tick on the system (for example, if there were 60 clock ticks per +second, at least two digits shall follow the radix character). The +number of digits following the radix character shall be no less than +one, even if this always results in a trailing zero. The implementation +may append white space and additional information following the format +shown here. The implementation may also prepend a single empty line +before the format shown here. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +If the +.IR utility +utility is invoked, the exit status of +.IR time +shall be the exit status of +.IR utility ; +otherwise, the +.IR time +utility shall exit with one of the following values: +.IP "1\(hy125" 8 +An error occurred in the +.IR time +utility. +.IP "\0\0126" 8 +The utility specified by +.IR utility +was found but could not be invoked. +.IP "\0\0127" 8 +The utility specified by +.IR utility +could not be found. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR command , +.IR env , +.IR nice , +.IR nohup , +.IR time , +and +.IR xargs +utilities have been specified to use exit code 127 if an error occurs +so that applications can distinguish ``failure to find a utility'' from +``invoked utility exited with an error indication''. The value 127 was +chosen because it is not commonly used for other meanings; most +utilities use small values for ``normal error conditions'' and the +values above 128 can be confused with termination due to receipt of a +signal. The value 126 was chosen in a similar manner to indicate that +the utility could be found, but not invoked. Some scripts produce +meaningful error messages differentiating the 126 and 127 cases. The +distinction between exit codes 126 and 127 is based on KornShell +practice that uses 127 when all attempts to +.IR exec +the utility fail with +.BR [ENOENT] , +and uses 126 when any attempt to +.IR exec +the utility fails for any other reason. +.SH EXAMPLES +It is frequently desirable to apply +.IR time +to pipelines or lists of commands. This can be done by placing +pipelines and command lists in a single file; this file can then be +invoked as a utility, and the +.IR time +applies to everything in the file. +.P +Alternatively, the following command can be used to apply +.IR time +to a complex command: +.sp +.RS 4 +.nf +\fB +time sh \(mic '\fIcomplex-command-line\fP' +.fi \fR +.P +.RE +.SH RATIONALE +When the +.IR time +utility was originally proposed to be included in the ISO\ POSIX\(hy2:\|1993 standard, +questions were raised about its suitability for inclusion on +the grounds that it was not useful for conforming applications, +specifically: +.IP " *" 4 +The underlying CPU definitions from the System Interfaces volume of POSIX.1\(hy2008 are +vague, so the numeric output could not be compared accurately between +systems or even between invocations. +.IP " *" 4 +The creation of portable benchmark programs was outside the scope this volume of POSIX.1\(hy2008. +.P +However, +.IR time +does fit in the scope of user portability. Human judgement can be +applied to the analysis of the output, and it could be very useful in +hands-on debugging of applications or in providing subjective measures +of system performance. Hence it has been included in this volume of POSIX.1\(hy2008. +.P +The default output format has been left unspecified because historical +implementations differ greatly in their style of depicting this numeric +output. The +.BR \(mip +option was invented to provide scripts with a common means of obtaining +this information. +.P +In the KornShell, +.IR time +is a shell reserved word that can be used to time an entire pipeline, +rather than just a simple command. The POSIX definition has been +worded to allow this implementation. Consideration was given to +invalidating this approach because of the historical model from the C +shell and System V shell. However, since the System V +.IR time +utility historically has not produced accurate results in pipeline +timing (because the constituent processes are not all owned by the same +parent process, as allowed by POSIX), it did not seem worthwhile to +break historical KornShell usage. +.P +The term +.IR utility +is used, rather than +.IR command , +to highlight the fact that shell compound commands, pipelines, special +built-ins, and so on, cannot be used directly. +However, +.IR utility +includes user application programs and shell scripts, not just the +standard utilities. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIsh\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fItimes\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/times.1p b/man-pages-posix-2013/man1p/times.1p new file mode 100644 index 0000000..79cb57a --- /dev/null +++ b/man-pages-posix-2013/man1p/times.1p @@ -0,0 +1,112 @@ +'\" et +.TH TIMES "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 write process times +.SH SYNOPSIS +.LP +.nf +times\fR +.fi +.SH DESCRIPTION +The +.IR times +utility shall write the accumulated user and system times for the shell +and for all of its child processes, in the following POSIX locale +format: +.sp +.RS 4 +.nf +\fB +"%dm%fs %dm%fs\en%dm%fs %dm%fs\en", <\fIshell user minutes\fR>, + <\fIshell user seconds\fR>, <\fIshell system minutes\fR>, + <\fIshell system seconds\fR>, <\fIchildren user minutes\fR>, + <\fIchildren user seconds\fR>, <\fIchildren system minutes\fR>, + <\fIchildren system seconds\fR> +.fi \fR +.P +.RE +.P +The four pairs of times shall correspond to the members of the +.IR +.BR tms +structure (defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 13" ", " "Headers") +as returned by +\fItimes\fR(): +.IR tms_utime , +.IR tms_stime , +.IR tms_cutime , +and +.IR tms_cstime , +respectively. +.SH OPTIONS +None. +.SH OPERANDS +None. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +See the DESCRIPTION. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +Zero. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +.LP +.nf +\fB$\fP times +\fB0m0.43s 0m1.11s +8m44.18s 1m43.23s\fR +.fi +.SH "RATIONALE" +The +.IR times +special built-in from the Single UNIX Specification is now required +for all conforming shells. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/touch.1p b/man-pages-posix-2013/man1p/touch.1p new file mode 100644 index 0000000..a9fca6f --- /dev/null +++ b/man-pages-posix-2013/man1p/touch.1p @@ -0,0 +1,646 @@ +'\" et +.TH TOUCH "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +touch +\(em change file access and modification times +.SH SYNOPSIS +.LP +.nf +touch \fB[\fR\(miacm\fB] [\fR\(mir \fIref_file\fR|\(mit \fItime\fR|\(mid \fIdate_time\fB] \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR touch +utility shall change the last data modification timestamps, the +last data access timestamps, or both. +.P +The time used can be specified by the +.BR \(mit +.IR time +option-argument, the corresponding +.IR time +fields of the file referenced by the +.BR \(mir +.IR ref_file +option-argument, or the +.BR \(mid +.IR date_time +option-argument, as specified in the following sections. If none of +these are specified, +.IR touch +shall use the current time. +.P +For each +.IR file +operand, +.IR touch +shall perform actions equivalent to the following functions defined in +the System Interfaces volume of POSIX.1\(hy2008: +.IP " 1." 4 +If +.IR file +does not exist: +.RS 4 +.IP " a." 4 +The +\fIcreat\fR() +function is called with the following arguments: +.RS 4 +.IP -- 4 +The +.IR file +operand is used as the +.IR path +argument. +.IP -- 4 +The value of the bitwise-inclusive OR of S_IRUSR, S_IWUSR, +S_IRGRP, S_IWGRP, S_IROTH, and S_IWOTH is used as the +.IR mode +argument. +.RE +.IP " b." 4 +The +\fIfutimens\fR() +function is called with the following arguments: +.RS 4 +.IP -- 4 +The file descriptor opened in step 1a. +.IP -- 4 +The access time and the modification time, set as described in the +OPTIONS section, are used as the first and second elements of the +.IR times +array argument, respectively. +.RE +.RE +.IP " 2." 4 +If +.IR file +exists, the +\fIutimensat\fR() +function is called with the following arguments: +.RS 4 +.IP " a." 4 +The AT_FDCWD special value is used as the +.IR fd +argument. +.IP " b." 4 +The +.IR file +operand is used as the +.IR path +argument. +.IP " c." 4 +The access time and the modification time, set as described in the +OPTIONS section, are used as the first and second elements of the +.IR times +array argument, respectively. +.IP " d." 4 +The +.IR flag +argument is set to zero. +.RE +.SH OPTIONS +The +.IR touch +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mia\fP" 10 +Change the access time of +.IR file . +Do not change the modification time unless +.BR \(mim +is also specified. +.IP "\fB\(mic\fP" 10 +Do not create a specified +.IR file +if it does not exist. Do not write any diagnostic messages concerning +this condition. +.IP "\fB\(mid\ \fIdate_time\fR" 10 +Use the specified +.IR date_time +instead of the current time. The option-argument shall be a string of +the form: +.RS 10 +.sp +.RS 4 +.nf +\fB +\fIYYYY\fR\(mi\fIMM\fR\(mi\fIDD\fRT\fIhh\fR:\fImm\fR:\fISS\fB[\fR.\fIfrac\fB][\fItz\fB]\fR +.fi \fR +.P +.RE +.P +or: +.sp +.RS 4 +.nf +\fB +\fIYYYY\fR\(mi\fIMM\fR\(mi\fIDD\fRT\fIhh\fR:\fImm\fR:\fISS\fB[\fR,\fIfrac\fB][\fItz\fB]\fR +.fi \fR +.P +.RE +.P +where: +.IP " *" 4 +.IR YYYY +are at least four decimal digits giving the year. +.IP " *" 4 +.IR MM , +.IR DD , +.IR hh , +.IR mm , +and +.IR SS +are as with +.BR \(mit +.IR time . +.IP " *" 4 +\fRT\fR is the time designator, and can be replaced by a single +. +.IP " *" 4 +\fR[.\fIfrac\fR]\fR and \fR[,\fIfrac\fR]\fR are either empty, or a + +(\c +.BR '.' ) +or a + +(\c +.BR ',' ) +respectively, followed by one or more decimal digits, specifying +a fractional second. +.IP " *" 4 +\fR[\fItz\fR]\fR is either empty, signifying local time, or the letter +.BR 'Z' , +signifying UTC. If \fR[\fItz\fR]\fR is empty, the resulting time shall +be affected by the value of the +.IR TZ +environment variable. +.P +If the resulting time precedes the Epoch, the behavior is +implementation-defined. If the time cannot be represented as the file's +timestamp, +.IR touch +shall exit immediately with an error status. +.RE +.IP "\fB\(mim\fP" 10 +Change the modification time of +.IR file . +Do not change the access time unless +.BR \(mia +is also specified. +.IP "\fB\(mir\ \fIref_file\fR" 10 +Use the corresponding time of the file named by the pathname +.IR ref_file +instead of the current time. +.IP "\fB\(mit\ \fItime\fR" 10 +Use the specified +.IR time +instead of the current time. The option-argument shall be a decimal +number of the form: +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[[\fICC\fB]\fIYY\fB]\fIMMDDhhmm\fB[\fR.\fISS\fB]\fR +.fi \fR +.P +.RE +.P +where each two digits represents the following: +.IP "\fIMM\fR" 8 +The month of the year [01,12]. +.IP "\fIDD\fR" 8 +The day of the month [01,31]. +.IP "\fIhh\fR" 8 +The hour of the day [00,23]. +.IP "\fImm\fR" 8 +The minute of the hour [00,59]. +.IP "\fICC\fR" 8 +The first two digits of the year (the century). +.IP "\fIYY\fR" 8 +The second two digits of the year. +.IP "\fISS\fR" 8 +The second of the minute [00,60]. +.P +Both +.IR CC +and +.IR YY +shall be optional. If neither is given, the current year shall be +assumed. If +.IR YY +is specified, but +.IR CC +is not, +.IR CC +shall be derived as follows: +.TS +center tab(@) box; +cB | cB +c | n. +If \fIYY\fP is:@\fICC\fP becomes: +_ +[69,99]@19 +[00,68]@20 +.TE +.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 +.P +The resulting time shall be affected by the value of the +.IR TZ +environment variable. If the resulting time value precedes the Epoch, +the behavior is implementation-defined. If the time is out of range for +the file's timestamp, +.IR touch +shall exit immediately with an error status. The range of valid times +past the Epoch is implementation-defined, but it shall extend to at +least the time 0 hours, 0 minutes, 0 seconds, January 1, 2038, +Coordinated Universal Time. Some implementations may not be able to +represent dates beyond January 18, 2038, because they use +.BR "signed int" +as a time holder. +.P +The range for +.IR SS +is [00,60] rather than [00,59] because of leap seconds. If +.IR SS +is 60, and the resulting time, as affected by the +.IR TZ +environment variable, does not refer to a leap second, the resulting +time shall be one second after a time where +.IR SS +is 59. If +.IR SS +is not given a value, it is assumed to be zero. +.RE +.P +If neither the +.BR \(mia +nor +.BR \(mim +options were specified, +.IR touch +shall behave as if both the +.BR \(mia +and +.BR \(mim +options were specified. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file whose times shall be modified. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR touch : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITZ\fP" 10 +Determine the timezone to be used for interpreting the +.IR time +option-argument. If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The utility executed successfully and all requested changes were made. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The interpretation of time is taken to be +.IR "seconds since the Epoch" +(see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.15" ", " "Seconds Since the Epoch"). +It should be noted that implementations conforming to the System Interfaces volume of POSIX.1\(hy2008 do +not take leap seconds into account when computing seconds since the +Epoch. When +.IR SS =60 +is used, the resulting time always refers to 1 plus +.IR "seconds since the Epoch" +for a time when +.IR SS =59. +.P +Although the +.BR \(mit +.IR time +option-argument specifies values in 1969, the access time and +modification time fields are defined in terms of seconds since the +Epoch (00:00:00 on 1 January 1970 UTC). Therefore, depending on the +value of +.IR TZ +when +.IR touch +is run, there is never more than a few valid hours in 1969 and there +need not be any valid times in 1969. +.P +One ambiguous situation occurs if +.BR \(mit +.IR time +is not specified, +.BR \(mir +.IR ref_file +is not specified, and the first operand is an eight or ten-digit +decimal number. A portable script can avoid this problem by using: +.sp +.RS 4 +.nf +\fB +touch \(mi\|\(mi file +.fi \fR +.P +.RE +.P +or: +.sp +.RS 4 +.nf +\fB +touch ./file +.fi \fR +.P +.RE +.P +in this case. +.P +If the +.IR T +time designator is replaced by a + +for the +.BR \(mid +.IR date_time +option-argument, the + +must be quoted to prevent the shell from splitting the argument. +.SH EXAMPLES +Create or update a file called +.BR dwc ; +the resulting file has both the last data modification and last data +access timestamps set to November 12, 2007 at 10:15:30 local time: +.sp +.RS 4 +.nf +\fB +touch \(mid 2007-11-12T10:15:30 dwc +.fi \fR +.P +.RE +.P +Create or update a file called +.BR nick ; +the resulting file has both the last data modification and last data +access timestamps set to November 12, 2007 at 10:15:30 UTC: +.sp +.RS 4 +.nf +\fB +touch \(mid 2007-11-12T10:15:30Z nick +.fi \fR +.P +.RE +.P +Create or update a file called +.BR gwc ; +the resulting file has both the last data modification and last data +access timestamps set to November 12, 2007 at 10:15:30 local time with +a fractional second timestamp of .002 seconds: +.sp +.RS 4 +.nf +\fB +touch \(mid 2007-11-12T10:15:30,002 gwc +.fi \fR +.P +.RE +.P +Create or update a file called +.BR ajosey ; +the resulting file has both the last data modification and last data +access timestamps set to November 12, 2007 at 10:15:30 UTC with a +fractional second timestamp of .002 seconds: +.sp +.RS 4 +.nf +\fB +touch \(mid "2007-11-12 10:15:30.002Z" ajosey +.fi \fR +.P +.RE +.P +Create or update a file called +.BR cathy ; +the resulting file has both the last data modification and last data +access timestamps set to November 12, 2007 at 10:15:00 local time: +.sp +.RS 4 +.nf +\fB +touch \(mit 200711121015 cathy +.fi \fR +.P +.RE +.P +Create or update a file called +.BR drepper ; +the resulting file has both the last data modification and last data +access timestamps set to November 12, 2007 at 10:15:30 local time: +.sp +.RS 4 +.nf +\fB +touch \(mit 200711121015.30 drepper +.fi \fR +.P +.RE +.P +Create or update a file called +.BR ebb9 ; +the resulting file has both the last data modification and last data +access timestamps set to November 12, 2007 at 10:15:30 local time: +.sp +.RS 4 +.nf +\fB +touch \(mit 0711121015.30 ebb9 +.fi \fR +.P +.RE +.P +Create or update a file called +.BR eggert ; +the resulting file has the last data access timestamp set to the +corresponding time of the file named +.BR mark +instead of the current time. If the file exists, the last data +modification time is not changed: +.sp +.RS 4 +.nf +\fB +touch \(mia \(mir mark eggert +.fi \fR +.P +.RE +.SH RATIONALE +The functionality of +.IR touch +is described almost entirely through references to functions in +the System Interfaces volume of POSIX.1\(hy2008. In this way, there is no duplication of effort required for +describing such side-effects as the relationship of user IDs to the +user database, permissions, and so on. +.P +There are some significant differences between the +.IR touch +utility in this volume of POSIX.1\(hy2008 and those in System V and BSD systems. They are +upwards-compatible for historical applications from both +implementations: +.IP " 1." 4 +In System V, an ambiguity exists when a pathname that is a decimal +number leads the operands; it is treated as a time value. In BSD, no +.IR time +value is allowed; files may only be +.IR touch ed +to the current time. The +.BR \(mit +.IR time +construct solves these problems for future conforming applications (note +that the +.BR \(mit +option is not historical practice). +.IP " 2." 4 +The inclusion of the century digits, +.IR CC , +is also new. Note that a ten-digit +.IR time +value is treated as if +.IR YY , +and not +.IR CC , +were specified. The caveat about the range of dates following the +Epoch was included as recognition that some implementations are not +able to represent dates beyond 18 January 2038 because they use +.BR "signed int" +as a time holder. +.P +The +.BR \(mir +option was added because several comments requested this capability. +This option was named +.BR \(mif +in an early proposal, but was changed because the +.BR \(mif +option is used in the BSD version of +.IR touch +with a different meaning. +.P +At least one historical implementation of +.IR touch +incremented the exit code if +.BR \(mic +was specified and the file did not exist. This volume of POSIX.1\(hy2008 requires exit status +zero if no errors occur. +.P +In previous version of the standard, if at least two operands are +specified, and the first operand is an eight or ten-digit decimal +integer, the first operand was assumed to be a +.IR date_time +operand. This usage was removed in this version of the standard since +it had been marked obsolescent previously. +.P +The +.BR \(mid +.IR date_time +format is an ISO\ 8601:\|2004 standard complete representation of date and time extended +format with an optional decimal point or + +followed by a string of digits following the seconds portion to specify +fractions of a second. It is not necessary to recognize +.BR \(dq[+/-]hh:mm\(dq +and +.BR \(dq[+/-]hh\(dq +to specify timezones other than local time and UTC. The +.IR T +time designator in the ISO\ 8601:\|2004 standard extended format may be replaced by +. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdate\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.15" ", " "Seconds Since the Epoch", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +.IR "\fB\fP" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIcreat\fR\^(\|)", +.IR "\fIfutimens\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fIutime\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/tput.1p b/man-pages-posix-2013/man1p/tput.1p new file mode 100644 index 0000000..0ec6ad2 --- /dev/null +++ b/man-pages-posix-2013/man1p/tput.1p @@ -0,0 +1,222 @@ +'\" et +.TH TPUT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tput +\(em change terminal characteristics +.SH SYNOPSIS +.LP +.nf +tput \fB[\fR\(miT \fItype\fB] \fIoperand\fR... +.fi +.SH DESCRIPTION +The +.IR tput +utility shall display terminal-dependent information. The manner in +which this information is retrieved is unspecified. The information +displayed shall clear the terminal screen, initialize the user's +terminal, or reset the user's terminal, depending on the operand +given. The exact consequences of displaying this information are +unspecified. +.SH OPTIONS +The +.IR tput +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(miT\ \fItype\fR" 10 +Indicate the type of terminal. If this option is not supplied and the +.IR TERM +variable is unset or null, an unspecified default terminal type shall +be used. The setting of +.IR type +shall take precedence over the value in +.IR TERM . +.SH OPERANDS +The following strings shall be supported as operands by the +implementation in the POSIX locale: +.IP "\fBclear\fR" 10 +Display the clear-screen sequence. +.IP "\fBinit\fR" 10 +Display the sequence that initializes the user's terminal in an +implementation-defined manner. +.IP "\fBreset\fR" 10 +Display the sequence that resets the user's terminal in an +implementation-defined manner. +.P +If a terminal does not support any of the operations described by these +operands, this shall not be considered an error condition. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR tput : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITERM\fP" 10 +Determine the terminal type. If this variable is unset or null, and if +the +.BR \(miT +option is not specified, an unspecified default terminal type shall be +used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If standard output is a terminal device, it may be used for writing the +appropriate sequence to clear the screen or reset or initialize the +terminal. If standard output is not a terminal device, undefined +results occur. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The requested string was written successfully. +.IP "\01" 6 +Unspecified. +.IP "\02" 6 +Usage error. +.IP "\03" 6 +No information is available about the specified terminal type. +.IP "\04" 6 +The specified operand is invalid. +.IP >4 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If one of the operands is not available for the terminal, +.IR tput +continues processing the remaining operands. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The difference between resetting and initializing a terminal is left +unspecified, as they vary greatly based on hardware types. In general, +resetting is a more severe action. +.P +Some terminals use control characters to perform the stated functions, +and on such terminals it might make sense to use +.IR tput +to store the initialization strings in a file or environment variable +for later use. However, because other terminals might rely on system +calls to do this work, the standard output cannot be used in a portable +manner, such as the following non-portable constructs: +.sp +.RS 4 +.nf +\fB +ClearVar=`tput clear` +tput reset | mailx \(mis "Wake Up" ddg +.fi \fR +.P +.RE +.SH EXAMPLES +.IP " 1." 4 +Initialize the terminal according to the type of terminal in the +environmental variable +.IR TERM . +This command can be included in a +.BR .profile +file. +.RS 4 +.sp +.RS 4 +.nf +\fB +tput init +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +Reset a 450 terminal. +.RS 4 +.sp +.RS 4 +.nf +\fB +tput \(miT 450 reset +.fi \fR +.P +.RE +.RE +.SH RATIONALE +The list of operands was reduced to a minimum for the following +reasons: +.IP " *" 4 +The only features chosen were those that were likely to be used by +human users interacting with a terminal. +.IP " *" 4 +Specifying the full +.IR terminfo +set was not considered desirable, but the standard developers did not +want to select among operands. +.IP " *" 4 +This volume of POSIX.1\(hy2008 does not attempt to provide applications with sophisticated +terminal handling capabilities, as that falls outside of its assigned +scope and intersects with the responsibilities of other standards +bodies. +.P +The difference between resetting and initializing a terminal is left +unspecified as this varies greatly based on hardware types. In +general, resetting is a more severe action. +.P +The exit status of 1 is historically reserved for finding out if a +Boolean operand is not set. Although the operands were reduced to a +minimum, the exit status of 1 should still be reserved for the Boolean +operands, for those sites that wish to support them. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstty\fR\^", +.IR "\fItabs\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/tr.1p b/man-pages-posix-2013/man1p/tr.1p new file mode 100644 index 0000000..8706a0e --- /dev/null +++ b/man-pages-posix-2013/man1p/tr.1p @@ -0,0 +1,699 @@ +'\" et +.TH TR "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tr +\(em translate characters +.SH SYNOPSIS +.LP +.nf +tr \fB[\fR\(mic|\(miC\fB] [\fR\(mis\fB] \fIstring1 string2\fR +.P +tr \(mis \fB[\fR\(mic|\(miC\fB] \fIstring1\fR +.P +tr \(mid \fB[\fR\(mic|\(miC\fB] \fIstring1\fR +.P +tr \(mids \fB[\fR\(mic|\(miC\fB] \fIstring1 string2\fR +.fi +.SH DESCRIPTION +The +.IR tr +utility shall copy the standard input to the standard output with +substitution or deletion of selected characters. The options specified +and the +.IR string1 +and +.IR string2 +operands shall control translations that occur while copying characters +and single-character collating elements. +.SH OPTIONS +The +.IR tr +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mic\fP" 10 +Complement the set of values specified by +.IR string1 . +See the EXTENDED DESCRIPTION section. +.IP "\fB\(miC\fP" 10 +Complement the set of characters specified by +.IR string1 . +See the EXTENDED DESCRIPTION section. +.IP "\fB\(mid\fP" 10 +Delete all occurrences of input characters that are specified by +.IR string1 . +.IP "\fB\(mis\fP" 10 +Replace instances of repeated characters with a single character, as +described in the EXTENDED DESCRIPTION section. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIstring1\fR,\ \fIstring2\fR" 10 +.br +Translation control strings. Each string shall represent a set of +characters to be converted into an array of characters used for the +translation. For a detailed description of how the strings are +interpreted, see the EXTENDED DESCRIPTION section. +.SH STDIN +The standard input can be any type of file. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR tr : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of range expressions and +equivalence classes. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments) and the behavior of character +classes. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR tr +output shall be identical to the input, with the exception of the +specified transformations. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +The operands +.IR string1 +and +.IR string2 +(if specified) define two arrays of characters. The constructs in the +following list can be used to specify characters or single-character +collating elements. If any of the constructs result in multi-character +collating elements, +.IR tr +shall exclude, without a diagnostic, those multi-character elements +from the resulting array. +.IP "\fIcharacter\fR" 10 +Any character not described by one of the conventions below shall +represent itself. +.IP "\e\fIoctal\fR" 10 +Octal sequences can be used to represent characters with specific coded +values. An octal sequence shall consist of a + +followed by the longest sequence of one, two, or three-octal-digit +characters (01234567). The sequence shall cause the value whose encoding +is represented by the one, two, or three-digit octal integer to be placed +into the array. Multi-byte characters require multiple, concatenated +escape sequences of this type, including the leading + +for each byte. +.IP "\e\fIcharacter\fR" 10 +The +-escape +sequences in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Table 5-1" ", " "Escape Sequences and Associated Actions" +(\c +.BR '\e\e' , +.BR '\ea' , +.BR '\eb' , +.BR '\ef' , +.BR '\en' , +.BR '\er' , +.BR '\et' , +.BR '\ev' ) +shall be supported. The results of using any other character, other +than an octal digit, following the + +are unspecified. Also, if there is no character following the +, +the results are unspecified. +.IP "\fIc\fR\(mi\fIc\fR" 10 +In the POSIX locale, this construct shall represent the range of +collating elements between the range endpoints (as long as neither +endpoint is an octal sequence of the form \e\fIoctal\fP), inclusive, as +defined by the collation sequence. The characters or collating elements +in the range shall be placed in the array in ascending collation +sequence. If the second endpoint precedes the starting endpoint in the +collation sequence, it is unspecified whether the range of collating +elements is empty, or this construct is treated as invalid. In locales +other than the POSIX locale, this construct has unspecified behavior. +.RS 10 +.P +If either or both of the range endpoints are octal sequences of the +form \e\fIoctal\fP, this shall represent the range of specific coded +values between the two range endpoints, inclusive. +.RE +.IP "[:\fIclass\fR:]" 10 +Represents all characters belonging to the defined character class, as +defined by the current setting of the +.IR LC_CTYPE +locale category. The following character class names shall be accepted +when specified in +.IR string1 : +.TS +tab(@); +lB lB lB lB lB lB. +alnum@blank@digit@lower@punct@upper +alpha@cntrl@graph@print@space@xdigit +.TE +.RS 10 +.P +In addition, character class expressions of the form [:\c +.IR name :] +shall be recognized in those locales where the +.IR name +keyword has been given a +.BR charclass +definition in the +.IR LC_CTYPE +category. +.P +When both the +.BR \(mid +and +.BR \(mis +options are specified, any of the character class names shall be +accepted in +.IR string2 . +Otherwise, only character class names +.BR lower +or +.BR upper +are valid in +.IR string2 +and then only if the corresponding character class (\c +.BR upper +and +.BR lower , +respectively) is specified in the same relative position in +.IR string1 . +Such a specification shall be interpreted as a request for case +conversion. When [:\c +.IR lower :] +appears in +.IR string1 +and [:\c +.IR upper :] +appears in +.IR string2 , +the arrays shall contain the characters from the +.BR toupper +mapping in the +.IR LC_CTYPE +category of the current locale. When [:\c +.IR upper :] +appears in +.IR string1 +and [:\c +.IR lower :] +appears in +.IR string2 , +the arrays shall contain the characters from the +.BR tolower +mapping in the +.IR LC_CTYPE +category of the current locale. The first character from each mapping +pair shall be in the array for +.IR string1 +and the second character from each mapping pair shall be in the array +for +.IR string2 +in the same relative position. +.P +Except for case conversion, the characters specified by a character +class expression shall be placed in the array in an unspecified order. +.P +If the name specified for +.IR class +does not define a valid character class in the current locale, the +behavior is undefined. +.RE +.IP "[=\fIequiv\fR=]" 10 +Represents all characters or collating elements belonging to the same +equivalence class as +.IR equiv , +as defined by the current setting of the +.IR LC_COLLATE +locale category. An equivalence class expression shall be allowed only +in +.IR string1 , +or in +.IR string2 +when it is being used by the combined +.BR \(mid +and +.BR \(mis +options. The characters belonging to the equivalence class shall be +placed in the array in an unspecified order. +.IP "[\fIx\fR*\fIn\fR]" 10 +Represents +.IR n +repeated occurrences of the character +.IR x . +Because this expression is used to map multiple characters to one, it +is only valid when it occurs in +.IR string2 . +If +.IR n +is omitted or is zero, it shall be interpreted as large enough to +extend the +.IR string2 -based +sequence to the length of the +.IR string1 -based +sequence. If +.IR n +has a leading zero, it shall be interpreted as an octal value. +Otherwise, it shall be interpreted as a decimal value. +.P +When the +.BR \(mid +option is not specified: +.IP " *" 4 +If +.IR string2 +is present, each input character found in the array specified by +.IR string1 +shall be replaced by the character in the same relative position in the +array specified by +.IR string2 . +If the array specified by +.IR string2 +is shorter that the one specified by +.IR string1 , +or if a character occurs more than once in +.IR string1 , +the results are unspecified. +.IP " *" 4 +If the +.BR \(miC +option is specified, the complements of the characters specified by +.IR string1 +(the set of all characters in the current character set, as defined by +the current setting of +.IR LC_CTYPE , +except for those actually specified in the +.IR string1 +operand) shall be placed in the array in ascending collation sequence, +as defined by the current setting of +.IR LC_COLLATE . +.IP " *" 4 +If the +.BR \(mic +option is specified, the complement of the values specified by +.IR string1 +shall be placed in the array in ascending order by binary value. +.IP " *" 4 +Because the order in which characters specified by character class +expressions or equivalence class expressions is undefined, such +expressions should only be used if the intent is to map several +characters into one. An exception is case conversion, as described +previously. +.P +When the +.BR \(mid +option is specified: +.IP " *" 4 +Input characters found in the array specified by +.IR string1 +shall be deleted. +.IP " *" 4 +When the +.BR \(miC +option is specified with +.BR \(mid , +all characters except those specified by +.IR string1 +shall be deleted. The contents of +.IR string2 +are ignored, unless the +.BR \(mis +option is also specified. +.IP " *" 4 +When the +.BR \(mic +option is specified with +.BR \(mid , +all values except those specified by +.IR string1 +shall be deleted. The contents of +.IR string2 +shall be ignored, unless the +.BR \(mis +option is also specified. +.IP " *" 4 +The same string cannot be used for both the +.BR \(mid +and the +.BR \(mis +option; when both options are specified, both +.IR string1 +(used for deletion) and +.IR string2 +(used for squeezing) shall be required. +.P +When the +.BR \(mis +option is specified, after any deletions or translations have taken +place, repeated sequences of the same character shall be replaced by +one occurrence of the same character, if the character is found in the +array specified by the last operand. If the last operand contains a +character class, such as the following example: +.sp +.RS 4 +.nf +\fB +tr \(mis '[:space:]' +.fi \fR +.P +.RE +.P +the last operand's array shall contain all of the characters in that +character class. However, in a case conversion, as described +previously, such as: +.sp +.RS 4 +.nf +\fB +tr \(mis '[:upper:]' '[:lower:]' +.fi \fR +.P +.RE +.P +the last operand's array shall contain only those characters defined as +the second characters in each of the +.BR toupper +or +.BR tolower +character pairs, as appropriate. +.P +An empty string used for +.IR string1 +or +.IR string2 +produces undefined results. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All input was processed successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +If necessary, +.IR string1 +and +.IR string2 +can be quoted to avoid pattern matching by the shell. +.P +If an ordinary digit (representing itself) is to follow an octal +sequence, the octal sequence must use the full three digits to avoid +ambiguity. +.P +When +.IR string2 +is shorter than +.IR string1 , +a difference results between historical System\ V and BSD systems. A +BSD system pads +.IR string2 +with the last character found in +.IR string2 . +Thus, it is possible to do the following: +.sp +.RS 4 +.nf +\fB +tr 0123456789 d +.fi \fR +.P +.RE +.P +which would translate all digits to the letter +.BR 'd' . +Since this area is specifically unspecified in this volume of POSIX.1\(hy2008, both the BSD and +System\ V behaviors are allowed, but a conforming application cannot rely +on the BSD behavior. It would have to code the example in the +following way: +.sp +.RS 4 +.nf +\fB +tr 0123456789 '[d*]' +.fi \fR +.P +.RE +.P +It should be noted that, despite similarities in appearance, the string +operands used by +.IR tr +are not regular expressions. +.P +Unlike some historical implementations, this definition of the +.IR tr +utility correctly processes NUL characters in its input stream. NUL +characters can be stripped by using: +.sp +.RS 4 +.nf +\fB +tr \(mid '\e000' +.fi \fR +.P +.RE +.SH EXAMPLES +.IP " 1." 4 +The following example creates a list of all words in +.BR file1 +one per line in +.BR file2 , +where a word is taken to be a maximal string of letters. +.RS 4 +.sp +.RS 4 +.nf +\fB +tr \(mics "[:alpha:]" "[\en*]" file2 +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +The next example translates all lowercase characters in +.BR file1 +to uppercase and writes the results to standard output. +.RS 4 +.sp +.RS 4 +.nf +\fB +tr "[:lower:]" "[:upper:]" file2 +.fi \fR +.P +.RE +.RE +.SH RATIONALE +In some early proposals, an explicit option +.BR \(min +was added to disable the historical behavior of stripping NUL +characters from the input. It was considered that automatically +stripping NUL characters from the input was not correct functionality. +However, the removal of +.BR \(min +in a later proposal does not remove the requirement that +.IR tr +correctly process NUL characters in its input stream. NUL characters +can be stripped by using +.IR tr +.BR \(mid +\&'\e000'. +.P +Historical implementations of +.IR tr +differ widely in syntax and behavior. For example, the BSD version has +not needed the bracket characters for the repetition sequence. The +.IR tr +utility syntax is based more closely on the System V and XPG3 model +while attempting to accommodate historical BSD implementations. In the +case of the short +.IR string2 +padding, the decision was to unspecify the behavior and preserve System +V and XPG3 scripts, which might find difficulty with the BSD method. +The assumption was made that BSD users of +.IR tr +have to make accommodations to meet the syntax defined here. Since it +is possible to use the repetition sequence to duplicate the desired +behavior, whereas there is no simple way to achieve the System V +method, this was the correct, if not desirable, approach. +.P +The use of octal values to specify control characters, while having +historical precedents, is not portable. The introduction of escape +sequences for control characters should provide the necessary +portability. It is recognized that this may cause some historical +scripts to break. +.P +An early proposal included support for multi-character collating elements. +It was pointed out that, while +.IR tr +does employ some syntactical elements from REs, the aim of +.IR tr +is quite different; ranges, for example, do not have a similar meaning +(``any of the chars in the range matches'', \fIversus\fP ``translate +each character in the range to the output counterpart''). As a result, +the previously included support for multi-character collating elements +has been removed. What remains are ranges in current collation order +(to support, for example, accented characters), character classes, and +equivalence classes. +.P +In XPG3 the [:\c +.IR class :] +and [=\c +.IR equiv =] +conventions are shown with double brackets, as in RE syntax. However, +.IR tr +does not implement RE principles; it just borrows part of the syntax. +Consequently, [:\c +.IR class :] +and [=\c +.IR equiv =] +should be regarded as syntactical elements on a par with [\c +.IR x *\c +.IR n ], +which is not an RE bracket expression. +.P +The standard developers will consider changes to +.IR tr +that allow it to translate characters between different character +encodings, or they will consider providing a new utility to accomplish +this. +.P +On historical System V systems, a range expression requires enclosing +square-brackets, such as: +.sp +.RS 4 +.nf +\fB +tr '[a-z]' '[A-Z]' +.fi \fR +.P +.RE +.P +However, BSD-based systems did not require the brackets, and this +convention is used here to avoid breaking large numbers of BSD scripts: +.sp +.RS 4 +.nf +\fB +tr a-z A-Z +.fi \fR +.P +.RE +.P +The preceding System V script will continue to work because the +brackets, treated as regular characters, are translated to themselves. +However, any System V script that relied on +.BR \(dqa\(hyz\(dq +representing the three characters +.BR 'a' , +.BR '\(mi' , +and +.BR 'z' +have to be rewritten as +.BR \(dqaz\(mi\(dq . +.P +The ISO\ POSIX\(hy2:\|1993 standard had a +.BR \(mic +option that behaved similarly to the +.BR \(miC +option, but did not supply functionality equivalent to the +.BR \(mic +option specified in POSIX.1\(hy2008. This meant that historical practice of being +able to specify +.IR tr +.BR \(micd \e000\(mi\e177 +(which would delete all bytes with the top bit set) would have no +effect because, in the C locale, bytes with the values octal 200 to +octal 377 are not characters. +.P +The earlier version also said that octal sequences referred to +collating elements and could be placed adjacent to each other to +specify multi-byte characters. However, it was noted that this caused +ambiguities because +.IR tr +would not be able to tell whether adjacent octal sequences were +intending to specify multi-byte characters or multiple single byte +characters. POSIX.1\(hy2008 specifies that octal sequences always refer to single +byte binary values when used to specify an endpoint of a range of +collating elements. +.P +Earlier versions of this standard allowed for implementations with +bytes other than eight bits, but this has been modified in this +version. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsed\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Table 5-1" ", " "Escape Sequences and Associated Actions", +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/trap.1p b/man-pages-posix-2013/man1p/trap.1p new file mode 100644 index 0000000..264ce1f --- /dev/null +++ b/man-pages-posix-2013/man1p/trap.1p @@ -0,0 +1,362 @@ +'\" et +.TH TRAP "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +trap +\(em trap signals +.SH SYNOPSIS +.LP +.nf +trap \fIn \fB[\fIcondition\fR...\fB]\fR +trap \fB[\fIaction condition\fR...\fB]\fR +.fi +.SH DESCRIPTION +If the first operand is an unsigned decimal integer, the shell shall +treat all operands as conditions, and shall reset each condition to +the default value. Otherwise, if there are operands, the first is +treated as an action and the remaining as conditions. +.P +If +.IR action +is +.BR '\(mi' , +the shell shall reset each +.IR condition +to the default value. If +.IR action +is null (\c +.BR \(dq\^\(dq ), +the shell shall ignore each specified +.IR condition +if it arises. Otherwise, the argument +.IR action +shall be read and executed by the shell when one of the corresponding +conditions arises. The action of +.IR trap +shall override a previous action (either default action or one +explicitly set). The value of +.BR \(dq$?\(dq +after the +.IR trap +action completes shall be the value it had before +.IR trap +was invoked. +.P +The condition can be EXIT, 0 (equivalent to EXIT), or a signal +specified using a symbolic name, without the SIG prefix, as listed in +the tables of signal names in the +.IR +header defined in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 13" ", " "Headers"; +for example, HUP, INT, QUIT, TERM. Implementations may permit names with +the SIG prefix or ignore case in signal names as an extension. Setting +a trap for SIGKILL or SIGSTOP produces undefined results. +.P +The environment in which the shell executes a +.IR trap +on EXIT shall be identical to the environment immediately after the +last command executed before the +.IR trap +on EXIT was taken. +.P +Each time +.IR trap +is invoked, the +.IR action +argument shall be processed in a manner equivalent to: +.sp +.RS 4 +.nf +\fB +eval \fIaction\fR +.fi \fR +.P +.RE +.P +Signals that were ignored on entry to a non-interactive shell cannot be +trapped or reset, although no error need be reported when attempting to +do so. An interactive shell may reset or catch signals ignored on +entry. Traps shall remain in place for a given shell until explicitly +changed with another +.IR trap +command. +.P +When a subshell is entered, traps that are not being ignored shall be +set to the default actions, except in the case of a command substitution +containing only a single +.IR trap +command, when the traps need not be altered. Implementations may check +for this case using only lexical analysis; for example, if +.IR `trap` +and +.IR "$( trap -- )" +do not alter the traps in the subshell, cases such as assigning +.IR var=trap +and then using +.IR $($var) +may still alter them. This does not imply that the +.IR trap +command cannot be used within the subshell to set new traps. +.P +The +.IR trap +command with no operands shall write to standard output a list of commands +associated with each condition. If the command is executed in a subshell, +the implementation does not perform the optional check described above +for a command substitution containing only a single +.IR trap +command, and no +.IR trap +commands with operands have been executed since entry to the subshell, +the list shall contain the commands that were associated with each +condition immediately before the subshell environment was entered. +Otherwise, the list shall contain the commands currently associated with +each condition. The format shall be: +.sp +.RS 4 +.nf +\fB +"trap \(mi\|\(mi %s %s ...\en", <\fIaction\fR>, <\fIcondition\fR> ... +.fi \fR +.P +.RE +.P +The shell shall format the output, including the proper use of quoting, +so that it is suitable for reinput to the shell as commands that +achieve the same trapping results. For example: +.sp +.RS 4 +.nf +\fB +save_traps=$(trap) +\&... +eval "$save_traps" +.fi \fR +.P +.RE +.P +XSI-conformant systems also allow numeric signal numbers for the +conditions corresponding to the following signal names: +.IP 1 6 +SIGHUP +.IP 2 6 +SIGINT +.IP 3 6 +SIGQUIT +.IP 6 6 +SIGABRT +.IP 9 6 +SIGKILL +.IP 14 6 +SIGALRM +.IP 15 6 +SIGTERM +.P +The +.IR trap +special built-in shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.SH OPTIONS +None. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +See the DESCRIPTION. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +If the trap name +or number +is invalid, a non-zero exit status shall be returned; otherwise, zero +shall be returned. For both interactive and non-interactive shells, +invalid signal names +or numbers +shall not be considered a syntax error and do not cause the shell to +abort. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +Write out a list of all traps and actions: +.sp +.RS 4 +.nf +\fB +trap +.fi \fR +.P +.RE +.P +Set a trap so the +.IR logout +utility in the directory referred to by the +.IR HOME +environment variable executes when the shell terminates: +.sp +.RS 4 +.nf +\fB +trap '"$HOME"/logout' EXIT +.fi \fR +.P +.RE +.P +or: +.sp +.RS 4 +.nf +\fB +trap '"$HOME"/logout' 0 +.fi \fR +.P +.RE +.P +Unset traps on INT, QUIT, TERM, and EXIT: +.sp +.RS 4 +.nf +\fB +trap \(mi INT QUIT TERM EXIT +.fi \fR +.P +.RE +.SH "RATIONALE" +Implementations may permit lowercase signal names as an extension. +Implementations may also accept the names with the SIG prefix; no known +historical shell does so. The +.IR trap +and +.IR kill +utilities in this volume of POSIX.1\(hy2008 are now consistent in their omission of the SIG +prefix for signal names. Some +.IR kill +implementations do not allow the prefix, and +.IR kill +.BR \(mil +lists the signals without prefixes. +.P +Trapping SIGKILL or SIGSTOP is syntactically accepted by some +historical implementations, but it has no effect. Portable POSIX +applications cannot attempt to trap these signals. +.P +The output format is not historical practice. Since the output of +historical +.IR trap +commands is not portable (because numeric signal values are not +portable) and had to change to become so, an opportunity was taken to +format the output in a way that a shell script could use to save and +then later reuse a trap if it wanted. +.P +The KornShell uses an +.BR ERR +trap that is triggered whenever +.IR set +.BR \(mie +would cause an exit. This is allowable as an extension, but was not +mandated, as other shells have not used it. +.P +The text about the environment for the EXIT trap invalidates the +behavior of some historical versions of interactive shells which, for +example, close the standard input before executing a trap on 0. For +example, in some historical interactive shell sessions the following +trap on 0 would always print +.BR \(dq\(mi\|\(mi\(dq : +.sp +.RS 4 +.nf +\fB +trap 'read foo; echo "\(mi$foo\(mi"' 0 +.fi \fR +.P +.RE +.P +The command: +.sp +.RS 4 +.nf +\fB +trap 'eval " $cmd"' 0 +.fi \fR +.P +.RE +.P +causes the contents of the shell variable +.IR cmd +to be executed as a command when the shell exits. Using: +.sp +.RS 4 +.nf +\fB +trap '$cmd' 0 +.fi \fR +.P +.RE +.P +does not work correctly if +.IR cmd +contains any special characters such as quoting or redirections. Using: +.sp +.RS 4 +.nf +\fB +trap " $cmd" 0 +.fi \fR +.P +.RE +.P +also works (the leading + +character protects against unlikely cases where +.IR cmd +is a decimal integer or begins with +.BR '\(mi' ), +but it expands the +.IR cmd +variable when the +.IR trap +command is executed, not when the exit action is executed. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/true.1p b/man-pages-posix-2013/man1p/true.1p new file mode 100644 index 0000000..99c5fdd --- /dev/null +++ b/man-pages-posix-2013/man1p/true.1p @@ -0,0 +1,97 @@ +'\" et +.TH TRUE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +true +\(em return true value +.SH SYNOPSIS +.LP +.nf +true +.fi +.SH DESCRIPTION +The +.IR true +utility shall return with exit code zero. +.SH OPTIONS +None. +.SH OPERANDS +None. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +Not used. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +Zero. +.SH "CONSEQUENCES OF ERRORS" +None. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +This utility is typically used in shell scripts, as shown in the +EXAMPLES section. The special built-in utility +.BR : +is sometimes more efficient than +.IR true . +.SH EXAMPLES +This command is executed forever: +.sp +.RS 4 +.nf +\fB +while true +do + command +done +.fi \fR +.P +.RE +.SH RATIONALE +The +.IR true +utility has been retained in this volume of POSIX.1\(hy2008, even though the shell special +built-in +.BR : +provides similar functionality, because +.IR true +is widely used in historical scripts and is less cryptic to novice +script readers. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.9" ", " "Shell Commands", +.IR "\fIfalse\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/tsort.1p b/man-pages-posix-2013/man1p/tsort.1p new file mode 100644 index 0000000..a1519f2 --- /dev/null +++ b/man-pages-posix-2013/man1p/tsort.1p @@ -0,0 +1,156 @@ +'\" et +.TH TSORT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tsort +\(em topological sort +.SH SYNOPSIS +.LP +.nf +tsort \fB[\fIfile\fB]\fR +.fi +.SH DESCRIPTION +The +.IR tsort +utility shall write to standard output a totally ordered list of items +consistent with a partial ordering of items contained in the input. +.P +The application shall ensure that the input consists of pairs of items +(non-empty strings) separated by + +characters. Pairs of different items indicate ordering. Pairs of +identical items indicate presence, but not ordering. +.SH OPTIONS +None. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a text file to order. If no +.IR file +operand is given, the standard input shall be used. +.SH STDIN +The standard input shall be used if no +.IR file +operand is specified, and shall be used if the +.IR file +operand is +.BR '\(mi' +and the implementation treats the +.BR '\(mi' +as meaning standard input. +Otherwise, the standard input shall not be used. +See the INPUT FILES section. +.SH "INPUT FILES" +The input file shall be a text file. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR tsort : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall be a text file consisting of the order list +produced from the partially ordered input. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR LC_COLLATE +variable need not affect the actions of +.IR tsort . +The output ordering is not lexicographic, but depends on the pairs of +items given as input. +.SH EXAMPLES +The command: +.sp +.RS 4 +.nf +\fB +tsort < +.fi \fR +.P +.RE +.P +Otherwise, a message shall be written indicating that standard input is +not connected to a terminal. In the POSIX locale, the +.IR tty +utility shall use the format: +.sp +.RS 4 +.nf +\fB +"not a tty\en" +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Standard input is a terminal. +.IP "\01" 6 +Standard input is not a terminal. +.IP >1 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +This utility checks the status of the file open as standard input +against that of an implementation-defined set of files. It is possible +that no match can be found, or that the match found need not be the +same file as that which was opened for standard input (although they +are the same device). +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIisatty\fR\^(\|)", +.IR "\fIttyname\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/type.1p b/man-pages-posix-2013/man1p/type.1p new file mode 100644 index 0000000..d1f3d69 --- /dev/null +++ b/man-pages-posix-2013/man1p/type.1p @@ -0,0 +1,133 @@ +'\" et +.TH TYPE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +type +\(em write a description of command type +.SH SYNOPSIS +.LP +.nf +type \fIname\fR... +.fi +.SH DESCRIPTION +The +.IR type +utility shall indicate how each argument would be interpreted if used +as a command name. +.SH OPTIONS +None. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIname\fR" 10 +A name to be interpreted. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR type : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPATH\fP" 10 +Determine the location of +.IR name , +as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output of +.IR type +contains information about each operand in an unspecified format. The +information provided typically identifies the operand as a shell +built-in, function, alias, or keyword, and where applicable, may +display the operand's pathname. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Since +.IR type +must be aware of the contents of the current shell execution +environment (such as the lists of commands, functions, and built-ins +processed by +.IR hash ), +it is always provided as a shell regular built-in. If it is called in +a separate utility execution environment, such as one of the +following: +.sp +.RS 4 +.nf +\fB +nohup type writer +find . \(mitype f | xargs type +.fi \fR +.P +.RE +it might not produce accurate results. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcommand\fR\^", +.IR "\fIhash\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/ulimit.1p b/man-pages-posix-2013/man1p/ulimit.1p new file mode 100644 index 0000000..f14b213 --- /dev/null +++ b/man-pages-posix-2013/man1p/ulimit.1p @@ -0,0 +1,169 @@ +'\" et +.TH ULIMIT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 set or report file size limit +.SH SYNOPSIS +.LP +.nf +ulimit \fB[\fR\(mif\fB] [\fIblocks\fB]\fR +.fi +.SH DESCRIPTION +The +.IR ulimit +utility shall set or report the file-size writing limit imposed on +files written by the shell and its child processes (files of any size +may be read). Only a process with appropriate privileges can increase +the limit. +.SH OPTIONS +The +.IR ulimit +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(mif\fP" 10 +Set (or report, if no +.IR blocks +operand is present), the file size limit in blocks. The +.BR \(mif +option shall also be the default case. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIblocks\fR" 10 +The number of 512-byte blocks to use as the new file size limit. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR ulimit : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall be used when no +.IR blocks +operand is present. If the current number of blocks is limited, the +number of blocks in the current limit shall be written in the following +format: +.sp +.RS 4 +.nf +\fB +"%d\en", <\fInumber of 512-byte blocks\fR> +.fi \fR +.P +.RE +.P +If there is no current limit on the number of blocks, in the POSIX +locale the following format shall be used: +.sp +.RS 4 +.nf +\fB +"unlimited\en" +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +A request for a higher limit was rejected or an error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Since +.IR ulimit +affects the current shell execution environment, it is always provided +as a shell regular built-in. If it is called in a separate utility +execution environment, such as one of the following: +.sp +.RS 4 +.nf +\fB +nohup ulimit \(mif 10000 +env ulimit 10000 +.fi \fR +.P +.RE +.P +it does not affect the file size limit of the caller's environment. +.P +Once a limit has been decreased by a process, it cannot be increased +(unless appropriate privileges are involved), even back to the original +system limit. +.SH EXAMPLES +Set the file size limit to 51\|200 bytes: +.sp +.RS 4 +.nf +\fB +ulimit \(mif 100 +.fi \fR +.P +.RE +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIulimit\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/umask.1p b/man-pages-posix-2013/man1p/umask.1p new file mode 100644 index 0000000..128c265 --- /dev/null +++ b/man-pages-posix-2013/man1p/umask.1p @@ -0,0 +1,372 @@ +'\" et +.TH UMASK "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 get or set the file mode creation mask +.SH SYNOPSIS +.LP +.nf +umask \fB[\fR\(miS\fB] [\fImask\fB]\fR +.fi +.SH DESCRIPTION +The +.IR umask +utility shall set the file mode creation mask of the current shell +execution environment (see +.IR "Section 2.12" ", " "Shell Execution Environment") +to the value specified by the +.IR mask +operand. This mask shall affect the initial value of the file +permission bits of subsequently created files. If +.IR umask +is called in a subshell or separate utility execution environment, such +as one of the following: +.sp +.RS 4 +.nf +\fB +(umask 002) +nohup umask ... +find . \(miexec umask ... \e; +.fi \fR +.P +.RE +.P +it shall not affect the file mode creation mask of the caller's +environment. +.P +If the +.IR mask +operand is not specified, the +.IR umask +utility shall write to standard output the value of the +file mode creation mask of the invoking process. +.SH OPTIONS +The +.IR umask +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(miS\fP" 10 +Produce symbolic output. +.P +The default output style is unspecified, but shall be recognized on a +subsequent invocation of +.IR umask +on the same system as a +.IR mask +operand to restore the previous file mode creation mask. +.SH OPERANDS +The following operand shall be supported: +.IP "\fImask\fR" 10 +A string specifying the new file mode creation mask. The string is +treated in the same way as the +.IR mode +operand described in the EXTENDED DESCRIPTION section for +.IR chmod . +.RS 10 +.P +For a +.IR symbolic_mode +value, the new value of the file mode creation mask shall be the +logical complement of the file permission bits portion of the file mode +specified by the +.IR symbolic_mode +string. +.P +In a +.IR symbolic_mode +value, the permissions +.IR op +characters +.BR '\(pl' +and +.BR '\(mi' +shall be interpreted relative to the current file mode creation mask; +.BR '\(pl' +shall cause the bits for the indicated permissions to be cleared in the +mask; +.BR '\(mi' +shall cause the bits for the indicated permissions to be set in the +mask. +.P +The interpretation of +.IR mode +values that specify file mode bits other than the file permission bits +is unspecified. +.P +In the octal integer form of +.IR mode , +the specified bits are set in the file mode creation mask. +.P +The file mode creation mask shall be set to the resulting numeric +value. +.P +The default output of a prior invocation of +.IR umask +on the same system with no operand also shall be recognized as a +.IR mask +operand. +.RE +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR umask : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +When the +.IR mask +operand is not specified, the +.IR umask +utility shall write a message to standard output that can later be used +as a +.IR umask +.IR mask +operand. +.P +If +.BR \(miS +is specified, the message shall be in the following format: +.sp +.RS 4 +.nf +\fB +"u=%s,g=%s,o=%s\en", <\fIowner permissions\fR>, <\fIgroup permissions\fR>, + <\fIother permissions\fR> +.fi \fR +.P +.RE +.P +where the three values shall be combinations of letters from the set +{\c +.IR r , +.IR w , +.IR x }; +the presence of a letter shall indicate that the corresponding bit is +clear in the file mode creation mask. +.P +If a +.IR mask +operand is specified, there shall be no output written to standard +output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The file mode creation mask was successfully changed, or no +.IR mask +operand was supplied. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Since +.IR umask +affects the current shell execution environment, it is generally +provided as a shell regular built-in. +.P +In contrast to the negative permission logic provided by the file mode +creation mask and the octal number form of the +.IR mask +argument, the symbolic form of the +.IR mask +argument specifies those permissions that are left alone. +.SH EXAMPLES +Either of the commands: +.sp +.RS 4 +.nf +\fB +umask a=rx,ug+w +.P +umask 002 +.fi \fR +.P +.RE +.P +sets the mode mask so that subsequently created files have their +S_IWOTH bit cleared. +.P +After setting the mode mask with either of the above commands, the +.IR umask +command can be used to write out the current value of the mode mask: +.sp +.RS 4 +.nf +\fB +\fB$ \fRumask +\fB0002\fR +.fi \fR +.P +.RE +.P +(The output format is unspecified, but historical implementations use +the octal integer mode format.) +.sp +.RS 4 +.nf +\fB +\fB$ \fRumask \(miS +\fBu=rwx,g=rwx,o=rx\fR +.fi \fR +.P +.RE +.P +Either of these outputs can be used as the mask operand to a subsequent +invocation of the +.IR umask +utility. +.P +Assuming the mode mask is set as above, the command: +.sp +.RS 4 +.nf +\fB +umask g\(miw +.fi \fR +.P +.RE +.P +sets the mode mask so that subsequently created files have their +S_IWGRP and S_IWOTH bits cleared. +.P +The command: +.sp +.RS 4 +.nf +\fB +umask \(mi\|\(mi \(miw +.fi \fR +.P +.RE +.P +sets the mode mask so that subsequently created files have all their +write bits cleared. Note that +.IR mask +operands +.BR \(mir , +.BR \(miw , +.BR \(mix +or anything beginning with a +, +must be preceded by +.BR \(dq\(mi\|\(mi\(dq +to keep it from being interpreted as an option. +.SH RATIONALE +Since +.IR umask +affects the current shell execution environment, +it is generally provided as a shell regular built-in. If it is called +in a subshell or separate utility execution environment, such as one of +the following: +.sp +.RS 4 +.nf +\fB +(umask 002) +nohup umask ... +find . \(miexec umask ... \e; +.fi \fR +.P +.RE +.P +it does not affect the file mode creation mask of the environment of +the caller. +.P +The description of the historical utility was modified to allow it to +use the symbolic modes of +.IR chmod . +The +.BR \(mis +option used in early proposals was changed to +.BR \(miS +because +.BR \(mis +could be confused with a +.IR symbolic_mode +form of mask referring to the S_ISUID and S_ISGID bits. +.P +The default output style is unspecified to permit implementors to +provide migration to the new symbolic style at the time most +appropriate to their users. A +.BR \(mio +flag to force octal mode output was omitted because the octal mode may +not be sufficient to specify all of the information that may be present +in the file mode creation mask when more secure file access permission +checks are implemented. +.P +It has been suggested that trusted systems developers might appreciate +ameliorating the requirement that the mode mask ``affects'' the file +access permissions, since it seems access control lists might replace +the mode mask to some degree. The wording has been changed to say that +it affects the file permission bits, and it leaves the details of the +behavior of how they affect the file access permissions to the +description in the System Interfaces volume of POSIX.1\(hy2008. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIchmod\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIumask\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/unalias.1p b/man-pages-posix-2013/man1p/unalias.1p new file mode 100644 index 0000000..78602cb --- /dev/null +++ b/man-pages-posix-2013/man1p/unalias.1p @@ -0,0 +1,150 @@ +'\" et +.TH UNALIAS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +unalias +\(em remove alias definitions +.SH SYNOPSIS +.LP +.nf +unalias \fIalias-name\fR... +.P +unalias \(mia +.fi +.SH DESCRIPTION +The +.IR unalias +utility shall remove the definition for each alias name specified. See +.IR "Section 2.3.1" ", " "Alias Substitution". +The aliases shall be removed from the current shell execution +environment; see +.IR "Section 2.12" ", " "Shell Execution Environment". +.SH OPTIONS +The +.IR unalias +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(mia\fP" 10 +Remove all alias definitions from the current shell execution +environment. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIalias-name\fR" 10 +The name of an alias to be removed. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR unalias : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +One of the +.IR alias-name +operands specified did not represent a valid alias definition, or an +error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Since +.IR unalias +affects the current shell execution environment, it is generally +provided as a shell regular built-in. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR unalias +description is based on that from historical KornShell implementations. +Known differences exist between that and the C shell. The KornShell +version was adopted to be consistent with all the other KornShell +features in this volume of POSIX.1\(hy2008, such as command line editing. +.P +The +.BR \(mia +option is the equivalent of the +.IR unalias +* form of the C shell and is provided to address security concerns +about unknown aliases entering the environment of a user (or +application) through the allowable implementation-defined predefined +alias route or as a result of an +.IR ENV +file. (Although +.IR unalias +could be used to simplify the ``secure'' shell script shown in the +.IR command +rationale, it does not obviate the need to quote all command names. An +initial call to +.IR unalias +.BR \(mia +would have to be quoted in case there was an alias for +.IR unalias .) +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIalias\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/uname.1p b/man-pages-posix-2013/man1p/uname.1p new file mode 100644 index 0000000..511d53c --- /dev/null +++ b/man-pages-posix-2013/man1p/uname.1p @@ -0,0 +1,201 @@ +'\" et +.TH UNAME "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 return system name +.SH SYNOPSIS +.LP +.nf +uname \fB[\fR\(miamnrsv\fB]\fR +.fi +.SH DESCRIPTION +By default, the +.IR uname +utility shall write the operating system name to standard output. When +options are specified, symbols representing one or more system +characteristics shall be written to the standard output. The format +and contents of the symbols are implementation-defined. On systems +conforming to the System Interfaces volume of POSIX.1\(hy2008, the symbols written shall be those supported +by the +\fIuname\fR() +function as defined in the System Interfaces volume of POSIX.1\(hy2008. +.SH OPTIONS +The +.IR uname +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mia\fP" 10 +Behave as though all of the options +.BR \(mimnrsv +were specified. +.IP "\fB\(mim\fP" 10 +Write the name of the hardware type on which the system is running to +standard output. +.IP "\fB\(min\fP" 10 +Write the name of this node within an implementation-defined +communications network. +.IP "\fB\(mir\fP" 10 +Write the current release level of the operating system +implementation. +.IP "\fB\(mis\fP" 10 +Write the name of the implementation of the operating system. +.IP "\fB\(miv\fP" 10 +Write the current version level of this release of the operating system +implementation. +.P +If no options are specified, the +.IR uname +utility shall write the operating system name, as if the +.BR \(mis +option had been specified. +.SH OPERANDS +None. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR uname : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +By default, the output shall be a single line of the following form: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIsysname\fR> +.fi \fR +.P +.RE +.P +If the +.BR \(mia +option is specified, the output shall be a single line of the following +form: +.sp +.RS 4 +.nf +\fB +"%s %s %s %s %s\en", <\fIsysname\fR>, <\fInodename\fR>, <\fIrelease\fR>, + <\fIversion\fR>, <\fImachine\fR> +.fi \fR +.P +.RE +.P +Additional implementation-defined symbols may be written; all such +symbols shall be written at the end of the line of output before the +. +.P +If options are specified to select different combinations of the +symbols, only those symbols shall be written, in the order shown above +for the +.BR \(mia +option. If a symbol is not selected for writing, its corresponding +trailing + +characters also shall not be written. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The requested information was successfully written. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Note that any of the symbols could include embedded + +characters, which may affect parsing algorithms if multiple options are +selected for output. +.P +The node name is typically a name that the system uses to identify +itself for inter-system communication addressing. +.SH EXAMPLES +The following command: +.sp +.RS 4 +.nf +\fB +uname \(misr +.fi \fR +.P +.RE +.P +writes the operating system name and release level, separated by one or +more + +characters. +.SH RATIONALE +It was suggested that this utility cannot be used portably since the +format of the symbols is implementation-defined. The POSIX.1 working +group could not achieve consensus on defining these formats in the +underlying +\fIuname\fR() +function, and there was no expectation that this volume of POSIX.1\(hy2008 would be any more +successful. Some applications may still find this historical utility of +value. For example, the symbols could be used for system log entries or +for comparison with operator or user input. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIuname\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/uncompress.1p b/man-pages-posix-2013/man1p/uncompress.1p new file mode 100644 index 0000000..7ab1245 --- /dev/null +++ b/man-pages-posix-2013/man1p/uncompress.1p @@ -0,0 +1,186 @@ +'\" et +.TH UNCOMPRESS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +uncompress +\(em expand compressed data +.SH SYNOPSIS +.LP +.nf +uncompress \fB[\fR\(micfv\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR uncompress +utility shall restore files to their original state after they have +been compressed using the +.IR compress +utility. If no files are specified, the standard input shall be +uncompressed to the standard output. If the invoking process has +appropriate privileges, the ownership, modes, access time, and +modification time of the original file shall be preserved. +.P +This utility shall support the uncompressing of any files produced by +the +.IR compress +utility on the same implementation. For files produced by +.IR compress +on other systems, +.IR uncompress +supports 9 to 14-bit compression (see +.IR "\fIcompress\fR\^", +.BR \(mib ); +it is implementation-defined whether values of +.BR \(mib +greater than 14 are supported. +.SH OPTIONS +The +.IR uncompress +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that Guideline 1 does apply since the utility name has ten letters. +.P +The following options shall be supported: +.IP "\fB\(mic\fP" 10 +Write to standard output; no files are changed. +.IP "\fB\(mif\fP" 10 +Do not prompt for overwriting files. Except when run in the +background, if +.BR \(mif +is not given the user shall be prompted as to whether an existing file +should be overwritten. If the standard input is not a terminal and +.BR \(mif +is not given, +.IR uncompress +shall write a diagnostic message to standard error and exit with a +status greater than zero. +.IP "\fB\(miv\fP" 10 +Write messages to standard error concerning the expansion of each file. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file. If +.IR file +already has the +.BR .Z +suffix specified, it shall be used as the input file and the output +file shall be named +.BR file +with the +.BR .Z +suffix removed. Otherwise, +.IR file +shall be used as the name of the output file and +.BR file +with the +.BR .Z +suffix appended shall be used as the input file. +.SH STDIN +The standard input shall be used only if no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' . +.SH "INPUT FILES" +Input files shall be in the format produced by the +.IR compress +utility. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR uncompress : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +When there are no +.IR file +operands or the +.BR \(mic +option is specified, the uncompressed output is written to standard +output. +.SH STDERR +Prompts shall be written to the standard error output under the +conditions specified in the DESCRIPTION and OPTIONS sections. The +prompts shall contain the +.IR file +pathname, but their format is otherwise unspecified. Otherwise, the +standard error output shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +Output files are the same as the respective input files to +.IR compress . +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +The input file remains unmodified. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The limit of 14 on the +.IR compress +.BR \(mib +.IR bits +argument is to achieve portability to all systems (within the +restrictions imposed by the lack of an explicit published file +format). Some implementations based on 16-bit architectures cannot +support 15 or 16-bit uncompression. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcompress\fR\^", +.IR "\fIzcat\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/unexpand.1p b/man-pages-posix-2013/man1p/unexpand.1p new file mode 100644 index 0000000..c65a979 --- /dev/null +++ b/man-pages-posix-2013/man1p/unexpand.1p @@ -0,0 +1,238 @@ +'\" et +.TH UNEXPAND "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +unexpand +\(em convert spaces to tabs +.SH SYNOPSIS +.LP +.nf +unexpand \fB[\fR\(mia|\(mit \fItablist\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR unexpand +utility shall copy files or standard input to standard output, +converting + +characters at the beginning of each line into the maximum number of + +characters followed by the minimum number of + +characters needed to fill the same column positions originally filled +by the translated + +characters. By default, tabstops shall be set at every eighth column +position. Each + +shall be copied to the output, and shall cause the column position +count for tab calculations to be decremented; the count shall never be +decremented to a value less than one. +.SH OPTIONS +The +.IR unexpand +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mia\fP" 10 +In addition to translating + +characters at the beginning of each line, translate all sequences of +two or more + +characters immediately preceding a tab stop to the maximum number of + +characters followed by the minimum number of + +characters needed to fill the same column positions originally filled +by the translated + +characters. +.IP "\fB\(mit\ \fItablist\fR" 10 +Specify the tab stops. The application shall ensure that the +.IR tablist +option-argument is a single argument consisting of a single positive +decimal integer or multiple positive decimal integers, separated by + +or + +characters, in ascending order. If a single number is given, tabs shall +be set +.IR tablist +column positions apart instead of the default 8. If multiple numbers +are given, the tabs shall be set at those specific column positions. +.RS 10 +.P +The application shall ensure that each tab-stop position +.IR N +is an integer value greater than zero, and the list shall be in +strictly ascending order. This is taken to mean that, from the start of +a line of output, tabbing to position +.IR N +shall cause the next character output to be in the (\c +.IR N +1)th +column position on that line. When the +.BR \(mit +option is not specified, the default shall be the equivalent of +specifying +.BR "\(mit\ 8" +(except for the interaction with +.BR \(mia , +described below). +.P +No +-to-\c + +conversions shall occur for characters at positions beyond the last of +those specified in a multiple tab-stop list. +.P +When +.BR \(mit +is specified, the presence or absence of the +.BR \(mia +option shall be ignored; conversion shall not be limited to the +processing of leading + +characters. +.RE +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a text file to be used as input. +.SH STDIN +See the INPUT FILES section. +.SH "INPUT FILES" +The input files shall be text files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR unexpand : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files), the processing of + +and + +characters, and for the determination of the width in column positions +each character would occupy on an output device. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall be equivalent to the input files with +the specified +-to-\c + +conversions. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +One non-intuitive aspect of +.IR unexpand +is its restriction to leading + +characters when neither +.BR \(mia +nor +.BR \(mit +is specified. Users who always want to convert all + +characters in a file can easily alias +.IR unexpand +to use the +.BR \(mia +or +.BR "\(mit\ 8" +option. +.SH EXAMPLES +None. +.SH RATIONALE +On several occasions, consideration was given to adding a +.BR \(mit +option to the +.IR unexpand +utility to complement the +.BR \(mit +in +.IR expand +(see +.IR "\fIexpand\fR\^"). +The historical intent of +.IR unexpand +was to translate multiple + +characters into tab stops, where tab stops were a multiple of eight +column positions on most UNIX systems. An early proposal omitted +.BR \(mit +because it seemed outside the scope of the User Portability Utilities +option; it was not described in any of the base documents. However, +hard-coding tab stops every eight columns was not suitable for the +international community and broke historical precedents for some +vendors in the FORTRAN community, so +.BR \(mit +was restored in conjunction with the list of valid extension categories +considered by the standard developers. Thus, +.IR unexpand +is now the logical converse of +.IR expand . +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexpand\fR\^", +.IR "\fItabs\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/unget.1p b/man-pages-posix-2013/man1p/unget.1p new file mode 100644 index 0000000..7a0a579 --- /dev/null +++ b/man-pages-posix-2013/man1p/unget.1p @@ -0,0 +1,189 @@ +'\" et +.TH UNGET "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +unget +\(em undo a previous get of an SCCS file (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +unget \fB[\fR\(mins\fB] [\fR\(mir \fISID\fB] \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR unget +utility shall reverse the effect of a +.IR get +.BR \(mie +done prior to creating the intended new delta. +.SH OPTIONS +The +.IR unget +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mir\ \fISID\fR" 10 +Uniquely identify which delta is no longer intended. (This would have +been specified by +.IR get +as the new delta.) The use of this option is necessary only if two or +more outstanding +.IR get +commands for editing on the same SCCS file were done by the same person +(login name). +.IP "\fB\(mis\fP" 10 +Suppress the writing to standard output of the intended delta's SID. +.IP "\fB\(min\fP" 10 +Retain the file that was obtained by +.IR get , +which would normally be removed from the current directory. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an existing SCCS file or a directory. If +.IR file +is a directory, the +.IR unget +utility shall behave as though each file in the directory were specified as a named +file, except that non-SCCS files (last component of the pathname does +not begin with +.BR s. ) +and unreadable files shall be silently ignored. +.RS 10 +.P +If exactly one +.IR file +operand appears, and it is +.BR '\(mi' , +the standard input shall be read; each line of the standard input shall +be taken to be the name of an SCCS file to be processed. Non-SCCS files +and unreadable files shall be silently ignored. +.RE +.SH STDIN +The standard input shall be a text file used only when the +.IR file +operand is specified as +.BR '\(mi' . +Each line of the text file shall be interpreted as an SCCS pathname. +.SH "INPUT FILES" +Any SCCS files processed shall be files of an unspecified format. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR unget : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall consist of a line for each file, in the +following format: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fISID removed from file\fR> +.fi \fR +.P +.RE +.P +If there is more than one named file or if a directory or standard +input is named, each pathname shall be written before each of the +preceding lines: +.sp +.RS 4 +.nf +\fB +"\en%s:\en", <\fIpathname\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +Any SCCS files updated shall be files of an unspecified format. +During processing of a +.IR file , +a locking +.IR z-file , +as described in +.IR get , +and a +.IR q-file +(a working copy of the +.IR p-file ), +may be created and deleted. The +.IR p-file +and +.IR g-file , +as described in +.IR get , +shall be deleted. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdelta\fR\^", +.IR "\fIget\fR\^", +.IR "\fIsact\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/uniq.1p b/man-pages-posix-2013/man1p/uniq.1p new file mode 100644 index 0000000..47a3d2b --- /dev/null +++ b/man-pages-posix-2013/man1p/uniq.1p @@ -0,0 +1,355 @@ +'\" et +.TH UNIQ "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +uniq +\(em report or filter out repeated lines in a file +.SH SYNOPSIS +.LP +.nf +uniq \fB[\fR\(mic|\(mid|\(miu\fB] [\fR\(mif \fIfields\fB] [\fR\(mis \fIchar\fB] [\fIinput_file \fB[\fIoutput_file\fB]]\fR +.fi +.SH DESCRIPTION +The +.IR uniq +utility shall read an input file comparing adjacent lines, and write +one copy of each input line on the output. The second and succeeding +copies of repeated adjacent input lines shall not be written. +The trailing + +of each line in the input shall be ignored when doing comparisons. +.P +Repeated lines in the input shall not be detected if they are not +adjacent. +.SH OPTIONS +The +.IR uniq +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that +.BR '\(pl' +may be recognized as an option delimiter as well as +.BR '\(mi' . +.P +The following options shall be supported: +.IP "\fB\(mic\fP" 10 +Precede each output line with a count of the number of times the line +occurred in the input. +.IP "\fB\(mid\fP" 10 +Suppress the writing of lines that are not repeated in the input. +.IP "\fB\(mif\ \fIfields\fR" 10 +Ignore the first +.IR fields +fields on each input line when doing comparisons, where +.IR fields +is a positive decimal integer. A field is the maximal string matched +by the basic regular expression: +.RS 10 +.sp +.RS 4 +.nf +\fB +[[:blank:]]*[^[:blank:]]* +.fi \fR +.P +.RE +.P +If the +.IR fields +option-argument specifies more fields than appear on an input line, a +null string shall be used for comparison. +.RE +.IP "\fB\(mis\ \fIchars\fR" 10 +Ignore the first +.IR chars +characters when doing comparisons, where +.IR chars +shall be a positive decimal integer. If specified in conjunction with +the +.BR \(mif +option, the first +.IR chars +characters after the first +.IR fields +fields shall be ignored. If the +.IR chars +option-argument specifies more characters than remain on an input line, +a null string shall be used for comparison. +.IP "\fB\(miu\fP" 10 +Suppress the writing of lines that are repeated in the input. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIinput_file\fR" 10 +A pathname of the input file. If the +.IR input_file +operand is not specified, or if the +.IR input_file +is +.BR '\(mi' , +the standard input shall be used. +.IP "\fIoutput_file\fR" 10 +A pathname of the output file. If the +.IR output_file +operand is not specified, the standard output shall be used. The +results are unspecified if the file named by +.IR output_file +is the file named by +.IR input_file . +.SH STDIN +The standard input shall be used only if no +.IR input_file +operand is specified or if +.IR input_file +is +.BR '\(mi' . +See the INPUT FILES section. +.SH "INPUT FILES" +The input file shall be a text file. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR uniq : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for ordering rules. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files) and which +characters constitute a + +in the current locale. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall be used if no +.IR output_file +operand is specified, and shall be used if the +.IR output_file +operand is +.BR '\(mi' +and the implementation treats the +.BR '\(mi' +as meaning standard output. Otherwise, the standard output shall +not be used. +See the OUTPUT FILES section. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +If the +.BR \(mic +option is specified, the output file shall be empty or each line +shall be of the form: +.sp +.RS 4 +.nf +\fB +"%d %s", <\fInumber of duplicates\fR>, <\fIline\fR> +.fi \fR +.P +.RE +.P +otherwise, the output file shall be empty or each line shall be +of the form: +.sp +.RS 4 +.nf +\fB +"%s", <\fIline\fR> +.fi \fR +.P +.RE +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +The utility executed successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR sort +utility can be used to cause repeated lines to be adjacent in the input +file. +.SH EXAMPLES +The following input file data (but flushed left) was used for a test +series on +.IR uniq : +.sp +.RS 4 +.nf +\fB +#01 foo0 bar0 foo1 bar1 +#02 bar0 foo1 bar1 foo1 +#03 foo0 bar0 foo1 bar1 +#04 +#05 foo0 bar0 foo1 bar1 +#06 foo0 bar0 foo1 bar1 +#07 bar0 foo1 bar1 foo0 +.fi \fR +.P +.RE +.P +What follows is a series of test invocations of the +.IR uniq +utility that use a mixture of +.IR uniq +options against the input file data. These tests verify the meaning of +.IR adjacent . +The +.IR uniq +utility views the input data as a sequence of strings delimited by +.BR '\en' . +Accordingly, for the +.IR fields th +member of the sequence, +.IR uniq +interprets unique or repeated adjacent lines strictly relative to the +.IR fields +1th +member. +.IP " 1." 4 +This first example tests the line counting option, comparing each line +of the input file data starting from the second field: +.RS 4 +.sp +.RS 4 +.nf +\fB +uniq \(mic \(mif 1 uniq_0I.t + 1 #01 foo0 bar0 foo1 bar1 + 1 #02 bar0 foo1 bar1 foo1 + 1 #03 foo0 bar0 foo1 bar1 + 1 #04 + 2 #05 foo0 bar0 foo1 bar1 + 1 #07 bar0 foo1 bar1 foo0 +.fi \fR +.P +.RE +.P +The number +.BR '2' , +prefixing the fifth line of output, signifies that the +.IR uniq +utility detected a pair of repeated lines. Given the input data, this +can only be true when +.IR uniq +is run using the +.BR "\(mif\ 1" +option (which shall cause +.IR uniq +to ignore the first field on each input line). +.RE +.IP " 2." 4 +The second example tests the option to suppress unique lines, comparing +each line of the input file data starting from the second field: +.RS 4 +.sp +.RS 4 +.nf +\fB +uniq \(mid \(mif 1 uniq_0I.t +#05 foo0 bar0 foo1 bar1 +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +This test suppresses repeated lines, comparing each line of the input +file data starting from the second field: +.RS 4 +.sp +.RS 4 +.nf +\fB +uniq \(miu \(mif 1 uniq_0I.t +#01 foo0 bar0 foo1 bar1 +#02 bar0 foo1 bar1 foo1 +#03 foo0 bar0 foo1 bar1 +#04 +#07 bar0 foo1 bar1 foo0 +.fi \fR +.P +.RE +.RE +.IP " 4." 4 +This suppresses unique lines, comparing each line of the input file +data starting from the third character: +.RS 4 +.sp +.RS 4 +.nf +\fB +uniq \(mid \(mis 2 uniq_0I.t +.fi \fR +.P +.RE +.P +In the last example, the +.IR uniq +utility found no input matching the above criteria. +.RE +.SH RATIONALE +Some historical implementations have limited lines to be 1\|080 bytes +in length, which does not meet the implied +{LINE_MAX} +limit. +.P +Earlier versions of this standard allowed the +.BR \(mi \c +.IR number +and +.BR \(pl \c +.IR number +options. These options are no longer specified by POSIX.1\(hy2008 but +may be present in some implementations. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcomm\fR\^", +.IR "\fIsort\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/unlink.1p b/man-pages-posix-2013/man1p/unlink.1p new file mode 100644 index 0000000..54884d4 --- /dev/null +++ b/man-pages-posix-2013/man1p/unlink.1p @@ -0,0 +1,121 @@ +'\" et +.TH UNLINK "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\(em call the +\fIunlink\fR() +function +.SH SYNOPSIS +.LP +.nf +unlink \fIfile\fP +.fi +.SH DESCRIPTION +The +.IR unlink +utility shall perform the function call: +.sp +.RS 4 +.nf +\fB +unlink(\fIfile\fP); +.fi \fR +.P +.RE +.P +A user may need appropriate privileges to invoke the +.IR unlink +utility. +.SH OPTIONS +None. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile\fP" 10 +The pathname of an existing file. +.SH STDIN +Not used. +.SH "INPUT FILES" +Not used. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR unlink : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +None. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIlink\fR\^", +.IR "\fIrm\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIunlink\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/unset.1p b/man-pages-posix-2013/man1p/unset.1p new file mode 100644 index 0000000..cabb5c3 --- /dev/null +++ b/man-pages-posix-2013/man1p/unset.1p @@ -0,0 +1,177 @@ +'\" et +.TH UNSET "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +unset +\(em unset values and attributes of variables and functions +.SH SYNOPSIS +.LP +.nf +unset \fB[\fR\(mifv\fB] \fIname\fR... +.fi +.SH DESCRIPTION +Each variable or function specified by +.IR name +shall be unset. +.P +If +.BR \(miv +is specified, +.IR name +refers to a variable name and the shell shall unset it and remove it +from the environment. Read-only variables cannot be unset. +.P +If +.BR \(mif +is specified, +.IR name +refers to a function and the shell shall unset the function definition. +.P +If neither +.BR \(mif +nor +.BR \(miv +is specified, +.IR name +refers to a variable; if a variable by that name does not exist, it is +unspecified whether a function by that name, if any, shall be unset. +.P +Unsetting a variable or function that was not previously set shall not +be considered an error and does not cause the shell to abort. +.P +The +.IR unset +special built-in shall support the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +Note that: +.sp +.RS 4 +.nf +\fB +VARIABLE= +.fi \fR +.P +.RE +.P +is not equivalent to an +.IR unset +of +.BR VARIABLE ; +in the example, +.BR VARIABLE +is set to +.BR \(dq\^\(dq . +Also, the variables that can be +.IR unset +should not be misinterpreted to include the special parameters (see +.IR "Section 2.5.2" ", " "Special Parameters"). +.SH OPTIONS +See the DESCRIPTION. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +.IP "\00" 6 +All +.IR name +operands were successfully unset. +.IP >0 6 +At least one +.IR name +could not be unset. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +Unset +.IR VISUAL +variable: +.sp +.RS 4 +.nf +\fB +unset \(miv VISUAL +.fi \fR +.P +.RE +.P +Unset the functions +.BR foo +and +.BR bar : +.sp +.RS 4 +.nf +\fB +unset \(mif foo bar +.fi \fR +.P +.RE +.SH "RATIONALE" +Consideration was given to omitting the +.BR \(mif +option in favor of an +.IR unfunction +utility, but the standard developers decided to retain historical +practice. +.P +The +.BR \(miv +option was introduced because System V historically used one name space +for both variables and functions. When +.IR unset +is used without options, System V historically unset either a function +or a variable, and there was no confusion about which one was intended. +A portable POSIX application can use +.IR unset +without an option to unset a variable, but not a function; the +.BR \(mif +option must be used. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/uucp.1p b/man-pages-posix-2013/man1p/uucp.1p new file mode 100644 index 0000000..05c753c --- /dev/null +++ b/man-pages-posix-2013/man1p/uucp.1p @@ -0,0 +1,292 @@ +'\" et +.TH UUCP "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +uucp +\(em system-to-system copy +.SH SYNOPSIS +.LP +.nf +uucp \fB[\fR\(micCdfjmr\fB] [\fR\(min \fIuser\fB] \fIsource-file\fR... \fIdestination-file\fR +.fi +.SH DESCRIPTION +The +.IR uucp +utility shall copy files named by the +.IR source-file +argument to the +.IR destination-file +argument. The files named can be on local or remote systems. +.P +The +.IR uucp +utility cannot guarantee support for all character encodings in all +circumstances. For example, transmission data may be restricted to 7 +bits by the underlying network, 8-bit data and filenames need not be +portable to non-internationalized systems, and so on. Under these +circumstances, it is recommended that only characters defined in the +ISO/IEC\ 646:\|1991 standard International Reference Version (equivalent to ASCII) 7-bit range +of characters be used, and that only characters defined in the portable +filename character set be used for naming files. The protocol for +transfer of files is unspecified by POSIX.1\(hy2008. +.P +Typical implementations of this utility require a communications line +configured to use the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface", +but other communications means may be used. On systems where there are +no available communications means (either temporarily or permanently), +this utility shall write an error message describing the problem and +exit with a non-zero exit status. +.SH OPTIONS +The +.IR uucp +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mic\fP" 10 +Do not copy local file to the spool directory for transfer to the +remote machine (default). +.IP "\fB\(miC\fP" 10 +Force the copy of local files to the spool directory for transfer. +.IP "\fB\(mid\fP" 10 +Make all necessary directories for the file copy (default). +.IP "\fB\(mif\fP" 10 +Do not make intermediate directories for the file copy. +.IP "\fB\(mij\fP" 10 +Write the job identification string to standard output. This job +identification can be used by +.IR uustat +to obtain the status or terminate a job. +.IP "\fB\(mim\fP" 10 +Send mail to the requester when the copy is completed. +.IP "\fB\(min\ \fIuser\fR" 10 +Notify +.IR user +on the remote system that a file was sent. +.IP "\fB\(mir\fP" 10 +Do not start the file transfer; just queue the job. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIdestination-file\fR,\ \fIsource-file\fR" 10 +.br +A pathname of a file to be copied to, or from, respectively. Either +name can be a pathname on the local machine, or can have the form: +.RS 10 +.sp +.RS 4 +.nf +\fB +\fIsystem-name\fR!\fIpathname\fR +.fi \fR +.P +.RE +.P +where +.IR system-name +is taken from a list of system names that +.IR uucp +knows about. +The destination +.IR system-name +can also be a list of names such as: +.sp +.RS 4 +.nf +\fB +\fIsystem-name\fR!\fIsystem-name\fR!...!\fIsystem-name\fR!\fIpathname\fR +.fi \fR +.P +.RE +.P +in which case, an attempt is made to send the file via the specified +route to the destination. Care should be taken to ensure that +intermediate nodes in the route are willing to forward information. +.P +The shell pattern matching notation characters +.BR '?' , +.BR '*' , +and +.BR \(dq[...]\(dq +appearing in +.IR pathname +shall be expanded on the appropriate system. +.P +Pathnames can be one of: +.IP " 1." 4 +An absolute pathname. +.IP " 2." 4 +A pathname preceded by ~\c +.IR user +where +.IR user +is a login name on the specified system and is replaced by that user's +login directory. Note that if an invalid login is specified, the +default is to the public directory (called +.IR PUBDIR ; +the actual location of +.IR PUBDIR +is implementation-defined). +.IP " 3." 4 +A pathname preceded by ~/\c +.IR destination +where +.IR destination +is appended to +.IR PUBDIR . +.RS 4 +.TP 10 +.BR Note: +This destination is treated as a filename unless more than one file is +being transferred by this request or the destination is already a +directory. To ensure that it is a directory, follow the destination +with a +.BR '/' . +For example, +.BR ~/dan/ +as the destination makes the directory +.BR PUBDIR/dan +if it does not exist and puts the requested files in that directory. +.P +.RE +.IP " 4." 4 +Anything else shall be prefixed by the current directory. +.P +If the result is an erroneous pathname for the remote system, the copy +shall fail. If the +.IR destination-file +is a directory, the last part of the +.IR source-file +name shall be used. +.P +The read, write, and execute permissions given by +.IR uucp +are implementation-defined. +.RE +.SH STDIN +Not used. +.SH "INPUT FILES" +The files to be copied are regular files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR uucp : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within bracketed filename +patterns. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files) and the behavior of +character classes within bracketed filename patterns (for example, +.BR \(dq'[[:lower:]]*'\(dq ). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error, and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The output files (which may be on other systems) are copies of the +input files. +.P +If +.BR \(mim +is used, mail files are modified. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +This utility is part of the UUCP Utilities option and need not be +supported by all implementations. +.P +The domain of remotely accessible files can (and for obvious security +reasons usually should) be severely restricted. +.P +Note that the +.BR '!' +character in addresses has to be escaped when using +.IR csh +as a command interpreter because of its history substitution syntax. +For +.IR ksh +and +.IR sh +the escape is not necessary, but may be used. +.P +As noted above, shell metacharacters appearing in pathnames are +expanded on the appropriate system. On an internationalized system, +this is done under the control of local settings of +.IR LC_COLLATE +and +.IR LC_CTYPE . +Thus, care should be taken when using bracketed filename patterns, as +collation and typing rules may vary from one system to another. Also +be aware that certain types of expression (that is, equivalence +classes, character classes, and collating symbols) need not be +supported on non-internationalized systems. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImailx\fR\^", +.IR "\fIuuencode\fR\^", +.IR "\fIuustat\fR\^", +.IR "\fIuux\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/uudecode.1p b/man-pages-posix-2013/man1p/uudecode.1p new file mode 100644 index 0000000..f93cd87 --- /dev/null +++ b/man-pages-posix-2013/man1p/uudecode.1p @@ -0,0 +1,215 @@ +'\" et +.TH UUDECODE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +uudecode +\(em decode a binary file +.SH SYNOPSIS +.LP +.nf +uudecode \fB[\fR\(mio \fIoutfile\fB] [\fIfile\fB]\fR +.fi +.SH DESCRIPTION +The +.IR uudecode +utility shall read a file, or standard input if no file is specified, +that includes data created by the +.IR uuencode +utility. The +.IR uudecode +utility shall scan the input file, searching for data compatible with +one of the formats specified in +.IR uuencode , +and attempt to create or overwrite the file described by the data (or +overridden by the +.BR \(mio +option). The pathname shall be contained in the data or specified by +the +.BR \(mio +option. The file access permission bits and contents for the file to be +produced shall be contained in that data. The mode bits of the created +file (other than standard output) shall be set from the file access +permission bits contained in the data; that is, other attributes of the +mode, including the file mode creation mask (see +.IR umask ), +shall not affect the file being produced. If either of the +.IR op +characters +.BR '\(pl' +and +.BR '\(mi' +(see +.IR chmod ) +are specified in symbolic mode, the initial mode on which those +operations are based is unspecified. +.P +If the pathname of the file to be produced exists, and the user does +not have write permission on that file, +.IR uudecode +shall terminate with an error. If the pathname of the file to be +produced exists, and the user has write permission on that file, the +existing file shall be overwritten. +.P +If the input data was produced by +.IR uuencode +on a system with a different number of bits per byte than on the target +system, the results of +.IR uudecode +are unspecified. +.SH OPTIONS +The +.IR uudecode +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported by the implementation: +.IP "\fB\(mio\ \fIoutfile\fR" 10 +A pathname of a file that shall be used instead of any pathname +contained in the input data. Specifying an +.IR outfile +option-argument of +.BR /dev/stdout +shall indicate standard output. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +The pathname of a file containing the output of +.IR uuencode . +.SH STDIN +See the INPUT FILES section. +.SH "INPUT FILES" +The input files shall be files containing the output of +.IR uuencode . +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR uudecode : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If the file data header encoded by +.IR uuencode +is +.BR \(mi +or +.BR /dev/stdout , +or the +.BR \(mio +.BR /dev/stdout +option overrides the file data, the standard output shall be in the +same format as the file originally encoded by +.IR uuencode . +Otherwise, the standard output shall not be used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The output file shall be in the same format as the file originally +encoded by +.IR uuencode . +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The user who is invoking +.IR uudecode +must have write permission on any file being created. +.P +The output of +.IR uuencode +is essentially an encoded bit stream that is not cognizant of byte +boundaries. It is possible that a 9-bit byte target machine can +process input from an 8-bit source, if it is aware of the requirement, +but the reverse is unlikely to be satisfying. Of course, the only data +that is meaningful for such a transfer between architectures is +generally character data. +.SH EXAMPLES +None. +.SH RATIONALE +Input files are not necessarily text files, as stated by an early +proposal. Although the +.IR uuencode +output is a text file, that output could have been wrapped within +another file or mail message that is not a text file. +.P +The +.BR \(mio +option is not historical practice, but was added at the request of WG15 +so that the user could override the target pathname without having to +edit the input data itself. +.P +In early drafts, the [\c +.BR \(mio +.IR outfile ] +option-argument allowed the use of +.BR \(mi +to mean standard output. The symbol +.BR \(mi +has only been used previously in POSIX.1\(hy2008 as a standard input indicator. +The standard developers did not wish to overload the meaning of +.BR \(mi +in this manner. The +.BR /dev/stdout +concept exists on most modern systems. The +.BR /dev/stdout +syntax does not refer to a new special file. It is just a magic cookie +to specify standard output. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^", +.IR "\fIumask\fR\^", +.IR "\fIuuencode\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/uuencode.1p b/man-pages-posix-2013/man1p/uuencode.1p new file mode 100644 index 0000000..f307713 --- /dev/null +++ b/man-pages-posix-2013/man1p/uuencode.1p @@ -0,0 +1,378 @@ +'\" et +.TH UUENCODE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +uuencode +\(em encode a binary file +.SH SYNOPSIS +.LP +.nf +uuencode \fB[\fR\(mim\fB] [\fIfile\fB] \fIdecode_pathname\fR +.fi +.SH DESCRIPTION +The +.IR uuencode +utility shall write an encoded version of the named input file, or +standard input if no +.IR file +is specified, to standard output. The output shall be encoded using +one of the algorithms described in the STDOUT section and shall +include the file access permission bits (in +.IR chmod +octal or symbolic notation) of the input file and the +.IR decode_pathname , +for re-creation of the file on another system that conforms to this volume of POSIX.1\(hy2008. +.SH OPTIONS +The +.IR uuencode +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported by the implementation: +.IP "\fB\(mim\fP" 10 +Encode the output using the MIME Base64 algorithm described in STDOUT. +If +.BR \(mim +is not specified, the historical algorithm described in STDOUT shall be +used. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIdecode_pathname\fR" 10 +.br +The pathname of the file into which the +.IR uudecode +utility shall place the decoded file. Specifying a +.IR decode_pathname +operand of +.BR /dev/stdout +shall indicate that +.IR uudecode +is to use standard output. If there are characters in +.IR decode_pathname +that are not in the portable filename character set the results are +unspecified. +.IP "\fIfile\fR" 10 +A pathname of the file to be encoded. +.SH STDIN +See the INPUT FILES section. +.SH "INPUT FILES" +Input files can be files of any type. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR uuencode : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +.SS "uuencode Base64 Algorithm" +.P +The standard output shall be a text file (encoded in the character set +of the current locale) that begins with the line: +.sp +.RS 4 +.nf +\fB +"begin-base64 %s %s\en", <\fImode\fR>, <\fIdecode_pathname\fR> +.fi \fR +.P +.RE +.P +and ends with the line: +.sp +.RS 4 +.nf +\fB +"====\en" +.fi \fR +.P +.RE +.P +In both cases, the lines shall have no preceding or trailing + +characters. +.P +The encoding process represents 24-bit groups of input bits as output +strings of four encoded characters. Proceeding from left to right, a +24-bit input group shall be formed by concatenating three 8-bit input +groups. Each 24-bit input group then shall be treated as four +concatenated 6-bit groups, each of which shall be translated into a +single digit in the Base64 alphabet. When encoding a bit stream via the +Base64 encoding, the bit stream shall be presumed to be ordered with +the most-significant bit first. That is, the first bit in the stream +shall be the high-order bit in the first byte, and the eighth bit shall +be the low-order bit in the first byte, and so on. Each 6-bit group is +used as an index into an array of 64 printable characters, as shown in +.IR "Table 4-22, uuencode Base64 Values". +.sp +.ce 1 +\fBTable 4-22: uuencode Base64 Values\fR +.TS +center box tab(!); +cB | cB || cB | cB || cB | cB || cB | cB +n | cf5 || n | cf5 || n | cf5 || n | cf5. +Value!Encoding!Value!Encoding!Value!Encoding!Value!Encoding +_ +0!A!17!R!34!i!51!z +1!B!18!S!35!j!52!0 +2!C!19!T!36!k!53!1 +3!D!20!U!37!l!54!2 +4!E!21!V!38!m!55!3 +5!F!22!W!39!n!56!4 +6!G!23!X!40!o!57!5 +7!H!24!Y!41!p!58!6 +8!I!25!Z!42!q!59!7 +9!J!26!a!43!r!60!8 +10!K!27!b!44!s!61!9 +11!L!28!c!45!t!62!+ +12!M!29!d!46!u!63!/ +13!N!30!e!47!v +14!O!31!f!48!w!(pad)!\&= +15!P!32!g!49!x +16!Q!33!h!50!y +.TE +.P +The character referenced by the index shall be placed in the output +string. +.P +The output stream (encoded bytes) shall be represented in lines of no +more than 76 characters each. All line breaks or other characters not +found in the table shall be ignored by decoding software (see +.IR "\fIuudecode\fR\^"). +.P +Special processing shall be performed if fewer than 24 bits are +available at the end of a message or encapsulated part of a message. A +full encoding quantum shall always be completed at the end of a +message. When fewer than 24 input bits are available in an input group, +zero bits shall be added (on the right) to form an integral number of +6-bit groups. Output character positions that are not required to +represent actual input data shall be set to the character +.BR '=' . +Since all Base64 input is an integral number of octets, only the +following cases can arise: +.IP " 1." 4 +The final quantum of encoding input is an integral multiple of 24 bits; +here, the final unit of encoded output shall be an integral multiple of +4 characters with no +.BR '=' +padding. +.IP " 2." 4 +The final quantum of encoding input is exactly 16 bits; here, the final +unit of encoded output shall be three characters followed by one +.BR '=' +padding character. +.IP " 3." 4 +The final quantum of encoding input is exactly 8 bits; here, the final +unit of encoded output shall be two characters followed by two +.BR '=' +padding characters. +.P +A terminating +.BR \(dq====\(dq +evaluates to nothing and denotes the end of the encoded data. +.SS "uuencode Historical Algorithm" +.P +The standard output shall be a text file (encoded in the character set +of the current locale) that begins with the line: +.sp +.RS 4 +.nf +\fB +"begin %s %s\en" <\fImode\fR>, <\fIdecode_pathname\fR> +.fi \fR +.P +.RE +.P +and ends with the line: +.sp +.RS 4 +.nf +\fB +"end\en" +.fi \fR +.P +.RE +.P +In both cases, the lines shall have no preceding or trailing + +characters. +.P +The algorithm that shall be used for lines in between +.BR begin +and +.BR end +takes three octets as input and writes four characters of output by +splitting the input at six-bit intervals into four octets, containing +data in the lower six bits only. These octets shall be converted to +characters by adding a value of 0x20 to each octet, so that each octet +is in the range [0x20,0x5f], and then it shall be assumed to represent +a printable character in the ISO/IEC\ 646:\|1991 standard encoded character set. It then +shall be translated into the corresponding character codes for the +codeset in use in the current locale. (For example, the octet 0x41, +representing +.BR 'A' , +would be translated to +.BR 'A' +in the current codeset, such as 0xc1 if it were EBCDIC.) +.P +Where the bits of two octets are combined, the least significant bits +of the first octet shall be shifted left and combined with the most +significant bits of the second octet shifted right. Thus the three +octets +.IR A , +.IR B , +.IR C +shall be converted into the four octets: +.sp +.RS 4 +.nf +\fB +0x20 + (( A >> 2 ) & 0x3F) +0x20 + (((A << 4) |\h'\n(XX' ((B >> 4) & 0xF)) & 0x3F) +0x20 + (((B << 2) |\h'\n(XX' ((C >> 6) & 0x3)) & 0x3F) +0x20 + (( C ) & 0x3F) +.fi \fR +.P +.RE +.P +These octets then shall be translated into the local character set. +.P +Each encoded line contains a length character, equal to the number of +characters to be decoded plus 0x20 translated to the local character +set as described above, followed by the encoded characters. The +maximum number of octets to be encoded on each line shall be 45. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The file is expanded by 35 percent (each three octets become four, plus +control information) causing it to take longer to transmit. +.P +Since this utility is intended to create files to be used for data +interchange between systems with possibly different codesets, and to +represent binary data as a text file, the ISO/IEC\ 646:\|1991 standard was chosen for a +midpoint in the algorithm as a known reference point. The output from +.IR uuencode +is a text file on the local system. If the output were in the ISO/IEC\ 646:\|1991 standard +codeset, it might not be a text file (at least because the + +characters might not match), and the goal of creating a text file would +be defeated. If this text file was then carried to another machine with +the same codeset, it would be perfectly compatible with that system's +.IR uudecode . +If it was transmitted over a mail system or sent to a machine with a +different codeset, it is assumed that, as for every other text file, +some translation mechanism would convert it (by the time it reached a +user on the other system) into an appropriate codeset. This +translation only makes sense from the local codeset, not if the file +has been put into a ISO/IEC\ 646:\|1991 standard representation first. Similarly, files +processed by +.IR uuencode +can be placed in +.IR pax +archives, intermixed with other text files in the same codeset. +.SH EXAMPLES +None. +.SH RATIONALE +A new algorithm was added at the request of the international community +to parallel work in RFC\ 2045 (MIME). As with the historical +.IR uuencode +format, the Base64 Content-Transfer-Encoding is designed to represent +arbitrary sequences of octets in a form that is not humanly readable. A +65-character subset of the ISO/IEC\ 646:\|1991 standard is used, enabling 6 bits to be +represented per printable character. (The extra 65th character, +.BR '=' , +is used to signify a special processing function.) +.P +This subset has the important property that it is represented +identically in all versions of the ISO/IEC\ 646:\|1991 standard, including US ASCII, and all +characters in the subset are also represented identically in all +versions of EBCDIC. The historical +.IR uuencode +algorithm does not share this property, which is the reason that a +second algorithm was added to the ISO\ POSIX\(hy2 standard. +.P +The string +.BR \(dq====\(dq +was used for the termination instead of the end used in the original +format because the latter is a string that could be valid encoded +input. +.P +In an early draft, the +.BR \(mim +option was named +.BR \(mib +(for Base64), but it was renamed to reflect its relationship to the +RFC\ 2045. A +.BR \(miu +was also present to invoke the default algorithm, but since this was +not historical practice, it was omitted as being unnecessary. +.P +See the RATIONALE section in +.IR "\fIuudecode\fR\^" +for the derivation of the +.BR /dev/stdout +symbol. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^", +.IR "\fImailx\fR\^", +.IR "\fIuudecode\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/uustat.1p b/man-pages-posix-2013/man1p/uustat.1p new file mode 100644 index 0000000..dcab76d --- /dev/null +++ b/man-pages-posix-2013/man1p/uustat.1p @@ -0,0 +1,162 @@ +'\" et +.TH UUSTAT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +uustat +\(em uucp status enquiry and job control +.SH SYNOPSIS +.LP +.nf +uustat \fB[\fR\(miq|\(mik \fIjobid\fR|\(mir \fIjobid\fB]\fR +.P +uustat \fB[\fR\(mis \fIsystem\fB] [\fR\(miu \fIuser\fB]\fR +.fi +.SH DESCRIPTION +The +.IR uustat +utility shall display the status of, or cancel, previously specified +.IR uucp +requests, or provide general status on +.IR uucp +connections to other systems. +.P +When no options are given, +.IR uustat +shall write to standard output the status of all +.IR uucp +requests issued by the current user. +.P +Typical implementations of this utility require a communications line +configured to use the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface", +but other communications means may be used. On systems where there are +no available communications means (either temporarily or permanently), +this utility shall write an error message describing the problem and +exit with a non-zero exit status. +.SH OPTIONS +The +.IR uustat +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(miq\fP" 10 +Write the jobs queued for each machine. +.IP "\fB\(mik\ \fIjobid\fR" 10 +Kill the +.IR uucp +request whose job identification is +.IR jobid . +The application shall ensure that the killed +.IR uucp +request belongs to the person invoking +.IR uustat +unless that user has appropriate privileges. +.IP "\fB\(mir\ \fIjobid\fR" 10 +Rejuvenate +.IR jobid . +The files associated with +.IR jobid +are touched so that their modification time is set to the current +time. This prevents the cleanup program from deleting the job until +the jobs modification time reaches the limit imposed by the program. +.IP "\fB\(mis\ \fIsystem\fR" 10 +Write the status of all +.IR uucp +requests for remote system +.IR system . +.IP "\fB\(miu\ \fIuser\fR" 10 +Write the status of all +.IR uucp +requests issued by +.IR user . +.SH OPERANDS +None. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR uustat : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error, and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall consist of information about each job +selected, in an unspecified format. The information shall include at +least the job ID, the user ID or name, and the remote system name. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +This utility is part of the UUCP Utilities option and need not be +supported by all implementations. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIuucp\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/uux.1p b/man-pages-posix-2013/man1p/uux.1p new file mode 100644 index 0000000..903f6cc --- /dev/null +++ b/man-pages-posix-2013/man1p/uux.1p @@ -0,0 +1,361 @@ +'\" et +.TH UUX "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +uux +\(em remote command execution +.SH SYNOPSIS +.LP +.nf +uux \fB[\fR\(mijnp\fB] \fIcommand\(mistring\fR +.fi +.SH DESCRIPTION +The +.IR uux +utility shall gather zero or more files from various systems, execute a +shell pipeline (see +.IR "Section 2.9" ", " "Shell Commands") +on a specified system, and then send the standard output of the command +to a file on a specified system. Only the first command of a pipeline +can have a +.IR system-name ! +prefix. All other commands in the pipeline shall be executed on the +system of the first command. +.P +The following restrictions are applicable to the shell pipeline +processed by +.IR uux : +.IP " *" 4 +In gathering files from different systems, pathname expansion shall +not be performed by +.IR uux . +Thus, a request such as: +.RS 4 +.sp +.RS 4 +.nf +\fB +uux "c99 remsys!~/*.c" +.fi \fR +.P +.RE +.P +would attempt to copy the file named literally +.BR *.c +to the local system. +.RE +.IP " *" 4 +The redirection operators +.BR \(dq>>\(dq , +.BR \(dq<<\(dq , +.BR \(dq>|\(dq , +and +.BR \(dq>&\(dq +shall not be accepted. Any use of these redirection operators shall +cause this utility to write an error message describing the problem +and exit with a non-zero exit status. +.IP " *" 4 +The reserved word +.BR ! +cannot be used at the head of the pipeline to modify the exit status. +(See the +.IR command-string +operand description below.) +.IP " *" 4 +Alias substitution shall not be performed. +.P +A filename can be specified as for +.IR uucp ; +it can be an absolute pathname, a pathname preceded by ~\c +.IR name +(which is replaced by the corresponding login directory), a pathname +specified as ~/\^\c +.IR dest +(\c +.IR dest +is prefixed by the public directory called +.IR PUBDIR ; +the actual location of +.IR PUBDIR +is implementation-defined), or a simple filename (which is prefixed +by +.IR uux +with the current directory). See +.IR "\fIuucp\fR\^" +for the details. +.P +The execution of commands on remote systems shall take place in an +execution directory known to the +.IR uucp +system. All files required for the execution shall be put into this +directory unless they already reside on that machine. Therefore, the +application shall ensure that non-local filenames (without path or +machine reference) are unique within the +.IR uux +request. +.P +The +.IR uux +utility shall attempt to get all files to the execution system. For +files that are output files, the application shall ensure that the +filename is escaped using parentheses. +.P +The remote system shall notify the user by mail if the requested +command on the remote system was disallowed or the files were not +accessible. This notification can be turned off by the +.BR \(min +option. +.P +Typical implementations of this utility require a communications line +configured to use the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface", +but other communications means may be used. On systems where there are +no available communications means (either temporarily or permanently), +this utility shall write an error message describing the problem and +exit with a non-zero exit status. +.P +The +.IR uux +utility cannot guarantee support for all character encodings in all +circumstances. For example, transmission data may be restricted to 7 +bits by the underlying network, 8-bit data and filenames need not be +portable to non-internationalized systems, and so on. Under these +circumstances, it is recommended that only characters defined in the +ISO/IEC\ 646:\|1991 standard International Reference Version (equivalent to ASCII) 7-bit range +of characters be used and that only characters defined in the portable +filename character set be used for naming files. +.SH OPTIONS +The +.IR uux +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mij\fP" 10 +Write the job identification string to standard output. This job +identification can be used by +.IR uustat +to obtain the status or terminate a job. +.IP "\fB\(min\fP" 10 +Do not notify the user if the command fails. +.IP "\fB\(mip\fP" 10 +Make the standard input to +.IR uux +the standard input to the +.IR command-string . +.SH OPERANDS +The following operand shall be supported: +.IP "\fIcommand-string\fR" 10 +.br +A string made up of one or more arguments that are similar to normal +command arguments, except that the command and any filenames can be +prefixed by +.IR system-name !. +A null +.IR system-name +shall be interpreted as the local system. +.SH STDIN +The standard input shall not be used unless the +.BR '\(mi' +or +.BR \(mip +option is specified; in those cases, the standard input shall be made +the standard input of the +.IR command-string . +.SH "INPUT FILES" +Input files shall be selected according to the contents of +.IR command-string . +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR uux : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall not be used unless the +.BR \(mij +option is specified; in that case, the job identification string shall +be written to standard output in the following format: +.sp +.RS 4 +.nf +\fB +"%s\en", <\fIjobid\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +Output files shall be created or written, or both, according to the +contents of +.IR command-string . +.P +If +.BR \(min +is not used, mail files shall be modified following any command or +file-access failures on the remote system. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +This utility is part of the UUCP Utilities option and need not be +supported by all implementations. +.P +Note that, for security reasons, many installations limit the list of +commands executable on behalf of an incoming request from +.IR uux . +Many sites permit little more than the receipt of mail via +.IR uux . +.P +Any characters special to the command interpreter should be quoted +either by quoting the entire +.IR command-string +or quoting the special characters as individual arguments. +.P +As noted in +.IR uucp , +shell pattern matching notation +characters appearing in pathnames are expanded on the appropriate local +system. This is done under the control of local settings of +.IR LC_COLLATE +and +.IR LC_CTYPE . +Thus, care should be taken when using bracketed filename patterns, as +collation and typing rules may vary from one system to another. Also +be aware that certain types of expression (that is, equivalence +classes, character classes, and collating symbols) need not be +supported on non-internationalized systems. +.SH EXAMPLES +.IP " 1." 4 +The following command gets +.BR file1 +from system +.BR a +and +.BR file2 +from system +.BR b , +executes +.IR diff +on the local system, and puts the results in +.BR file.diff +in the local +.IR PUBDIR +directory. (\c +.IR PUBDIR +is the +.IR uucp +public directory on the local system.) +.RS 4 +.sp +.RS 4 +.nf +\fB +uux "!diff a!/usr/file1 b!/a4/file2 >!~/file.diff" +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +The following command fails because +.IR uux +places all files copied to a system in the same working directory. +Although the files +.BR xyz +are from two different systems, their filenames are the same and +conflict. +.RS 4 +.sp +.RS 4 +.nf +\fB +uux "!diff a!/usr1/xyz b!/usr2/xyz >!~/xyz.diff" +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +The following command succeeds (assuming +.IR diff +is permitted on system +.BR a ) +because the file local to system +.BR a +is not copied to the working directory, and hence does not conflict with +the file from system +.BR c . +.RS 4 +.sp +.RS 4 +.nf +\fB +uux "a!diff a!/usr/xyz c!/usr/xyz >!~/xyz.diff" +.fi \fR +.P +.RE +.RE +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIuucp\fR\^", +.IR "\fIuuencode\fR\^", +.IR "\fIuustat\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/val.1p b/man-pages-posix-2013/man1p/val.1p new file mode 100644 index 0000000..0a83f4d --- /dev/null +++ b/man-pages-posix-2013/man1p/val.1p @@ -0,0 +1,248 @@ +'\" et +.TH VAL "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +val +\(em validate SCCS files (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +val \(mi +.P +val \fB[\fR\(mis\fB] [\fR\(mim \fIname\fB] [\fR\(mir \fISID\fB] [\fR\(miy \fItype\fB] \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR val +utility shall determine whether the specified +.IR file +is an SCCS file meeting the characteristics specified by the options. +.SH OPTIONS +The +.IR val +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except that the usage of the +.BR '\(mi' +operand is not strictly as intended by the guidelines (that is, reading +options and operands from standard input). +.P +The following options shall be supported: +.IP "\fB\(mim\ \fIname\fR" 10 +Specify a +.IR name , +which is compared with the SCCS %\fBM\fP% keyword in +.IR file ; +see +.IR "\fIget\fR\^". +.IP "\fB\(mir\ \fISID\fR" 10 +Specify a +.IR SID +(SCCS Identification String), an SCCS delta number. A check shall be +made to determine whether the +.IR SID +is ambiguous (for example, +.BR "\(mir\ 1" +is ambiguous because it physically does not exist but implies 1.1, 1.2, +and so on, which may exist) or invalid (for example, +.BR "\(mir\ 1.0" +or +.BR "\(mir\ 1.1.0" +are invalid because neither case can exist as a valid delta number). +If the +.IR SID +is valid and not ambiguous, a check shall be made to determine whether +it actually exists. +.IP "\fB\(mis\fP" 10 +Silence the diagnostic message normally written to standard output for +any error that is detected while processing each named file on a given +command line. +.IP "\fB\(miy\ \fItype\fR" 10 +Specify a +.IR type , +which shall be compared with the SCCS %\fBY\fP% keyword in +.IR file ; +see +.IR "\fIget\fR\^". +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an existing SCCS file. If exactly one +.IR file +operand appears, and it is +.BR '\(mi' , +the standard input shall be read: each line shall be independently +processed as if it were a command line argument list. (However, the +line is not subjected to any of the shell word expansions, such as +parameter expansion or quote removal.) +.SH STDIN +The standard input shall be a text file used only when the +.IR file +operand is specified as +.BR '\(mi' . +.SH "INPUT FILES" +Any SCCS files processed shall be files of an unspecified format. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR val : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error, and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall consist of informative messages about either: +.IP " 1." 4 +Each file processed +.IP " 2." 4 +Each command line read from standard input +.P +If the standard input is not used, for each +.IR file +operand yielding a discrepancy, the output line shall have the +following format: +.sp +.RS 4 +.nf +\fB +"%s: %s\en", <\fIpathname\fR>, <\fIunspecified string\fR> +.fi \fR +.P +.RE +.P +If the standard input is used, for each input line yielding a discrepancy, +the output shall have the following format: +.sp +.RS 4 +.nf +\fB +"%s\en\en %s: %s\en", <\fIinput\fR>, <\fIpathname\fR>, <\fIunspecified string\fR> +.fi \fR +.P +.RE +.P +where <\fIinput\fP> is the input line minus its terminating +. +.SH STDERR +Not used. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The 8-bit code returned by +.IR val +shall be a disjunction of the possible errors; that is, it can be +interpreted as a bit string where set bits are interpreted as follows: +.TS +tab(@); +l c l. +0x80@\&=@Missing file argument. +0x40@\&=@Unknown or duplicate option. +0x20@\&=@Corrupted SCCS file. +0x10@\&=@Cannot open file or file not SCCS. +0x08@\&=@\fISID\fR is invalid or ambiguous. +0x04@\&=@\fISID\fR does not exist. +0x02@\&=@%\fBY\fR%, \fB\(miy\fR mismatch. +0x01@\&=@%\fBM\fR%, \fB\(mim\fR mismatch. +.TE +.P +Note that +.IR val +can process two or more files on a given command line and can process +multiple command lines (when reading the standard input). In these +cases an aggregate code shall be returned: a logical OR of the codes +generated for each command line and file processed. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Since the +.IR val +exit status sets the 0x80 bit, shell applications checking +.BR \(dq$?\(dq +cannot tell if it terminated due to a missing file argument or receipt +of a signal. +.SH EXAMPLES +In a directory with three SCCS files\(em\c +.BR s.x +(of +.BR t +type ``text''), +.BR s.y , +and +.BR s.z +(a corrupted file)\(emthe following command could produce the output +shown: +.sp +.RS 4 +.nf +\fB +val \(mi < +can be used to return to command mode; other uses of + +are described later in this section; see +.IR "Terminate Command or Input Mode". +.SS "Initialization in ex and vi" +.P +See +.IR "Initialization in ex and vi" +for a description of +.IR ex +and +.IR vi +initialization for the +.IR vi +utility. +.SS "Command Descriptions in vi" +.P +The following symbols are used in this reference page to represent +arguments to commands. +.IP "\fIbuffer\fR" 8 +See the description of +.IR buffer +in the EXTENDED DESCRIPTION section of the +.IR ex +utility; see +.IR "Command Descriptions in ex". +.RS 8 +.P +In open and visual mode, when a command synopsis shows both [\c +.IR buffer ] +and [\c +.IR count ] +preceding the command name, they can be specified in either order. +.RE +.IP "\fIcount\fR" 8 +A positive integer used as an optional argument to most commands, +either to give a repeat count or as a size. This argument is optional +and shall default to 1 unless otherwise specified. +.RS 8 +.P +The Synopsis lines for the +.IR vi +commands +\(hyG, +\(hyL, +\(hyR, +\(hy], +.BR % , +.BR & , +.BR ^ , +.BR D , +.BR m , +.BR M , +.BR Q , +.BR u , +.BR U , +and +.BR ZZ +do not have +.IR count +as an optional argument. Regardless, it shall not be an error to +specify a +.IR count +to these commands, and any specified +.IR count +shall be ignored. +.RE +.IP "\fImotion\fR" 8 +An optional trailing argument used by the +.BR ! , +.BR < , +.BR > , +.BR c , +.BR d , +and +.BR y +commands, which is used to indicate the region of text that shall be +affected by the command. The motion can be either one of the command +characters repeated or one of several other +.IR vi +commands (listed in the following table). Each of the applicable +commands specifies the region of text matched by repeating the command; +each command that can be used as a motion command specifies the region +of text it affects. +.RS 8 +.P +Commands that take +.IR motion +arguments operate on either lines or characters, depending on the +circumstances. When operating on lines, all lines that fall partially +or wholly within the text region specified for the command shall be +affected. When operating on characters, only the exact characters in +the specified text region shall be affected. Each motion command +specifies this individually. +.P +When commands that may be motion commands are not used as motion +commands, they shall set the current position to the current line and +column as specified. +.P +The following commands shall be valid cursor motion commands: +.sp +.RS 4 +.nf +\fB + ( - j H + ) $ k L + [[ % l M +-H ]] _ n N +-N { ; t T +-P } ? w W + ^ b B + + e E + | f F + / h G +.fi \fR +.P +.RE +.P +Any +.IR count +that is specified to a command that has an associated motion command +shall be applied to the motion command. If a +.IR count +is applied to both the command and its associated motion command, the +effect shall be multiplicative. +.RE +.P +The following symbols are used in this section to specify locations +in the edit buffer: +.IP "\fIcurrent\ character\fP" 8 +.br +The character that is currently indicated by the cursor. +.IP "\fIend\ of\ a\ line\fP" 8 +.br +The point located between the last non-\c + +(if any) and the terminating + +of a line. For an empty line, this location coincides with the +beginning of the line. +.IP "\fIend\ of\ the\ edit\ buffer\fP" 8 +.br +The location corresponding to the end of the last line in the edit +buffer. +.P +The following symbols are used in this section to specify command +actions: +.IP "\fIbigword\fP" 8 +In the POSIX locale, +.IR vi +shall recognize four kinds of +.IR bigwords : +.RS 8 +.IP " 1." 4 +A maximal sequence of non-\c + +characters preceded and followed by + +characters or the beginning or end of a line or the edit buffer +.IP " 2." 4 +One or more sequential blank lines +.IP " 3." 4 +The first character in the edit buffer +.IP " 4." 4 +The last non-\c + +in the edit buffer +.RE +.IP "\fIword\fP" 8 +In the POSIX locale, +.IR vi +shall recognize five kinds of words: +.RS 8 +.IP " 1." 4 +A maximal sequence of letters, digits, and underscores, delimited at +both ends by: +.RS 4 +.IP -- 4 +Characters other than letters, digits, or underscores +.IP -- 4 +The beginning or end of a line +.IP -- 4 +The beginning or end of the edit buffer +.RE +.IP " 2." 4 +A maximal sequence of characters other than letters, digits, underscores, or + +characters, delimited at both ends by: +.RS 4 +.IP -- 4 +A letter, digit, underscore +.IP -- 4 + +characters +.IP -- 4 +The beginning or end of a line +.IP -- 4 +The beginning or end of the edit buffer +.RE +.IP " 3." 4 +One or more sequential blank lines +.IP " 4." 4 +The first character in the edit buffer +.IP " 5." 4 +The last non-\c + +in the edit buffer +.RE +.IP "\fIsection\ boundary\fR" 8 +.br +A +.IR "section boundary" +is one of the following: +.RS 8 +.IP " 1." 4 +A line whose first character is a + +.IP " 2." 4 +A line whose first character is an open curly brace (\c +.BR '{' ) +.IP " 3." 4 +A line whose first character is a + +and whose second and third characters match a two-character pair in the +.BR sections +edit option (see +.IR ed ) +.IP " 4." 4 +A line whose first character is a + +and whose only other character matches the first character of a +two-character pair in the +.BR sections +edit option, where the second character of the two-character pair is a + +.IP " 5." 4 +The first line of the edit buffer +.IP " 6." 4 +The last line of the edit buffer if the last line of the edit buffer is +empty or if it is a +.BR ]] +or +.BR } +command; otherwise, the last non-\c + +of the last line of the edit buffer +.RE +.IP "\fIparagraph\ boundary\fR" 8 +.br +A +.IR "paragraph boundary" +is one of the following: +.RS 8 +.IP " 1." 4 +A section boundary +.IP " 2." 4 +A line whose first character is a + +and whose second and third characters match a two-character pair in the +.BR paragraphs +edit option (see +.IR ed ) +.IP " 3." 4 +A line whose first character is a + +and whose only other character matches the first character of a +two-character pair in the +.IR paragraphs +edit option, where the second character of the two-character pair is a + +.IP " 4." 4 +One or more sequential blank lines +.RE +.IP "\fIremembered\ search\ direction\fR" 8 +.br +See the description of \fIremembered search direction\fP in +.IR ed . +.IP "\fIsentence\ boundary\fR" 8 +.br +A +.IR "sentence boundary" +is one of the following: +.RS 8 +.IP " 1." 4 +A paragraph boundary +.IP " 2." 4 +The first non-\c + +that occurs after a paragraph boundary +.IP " 3." 4 +The first non-\c + +that occurs after a + +(\c +.BR '.' ), + +(\c +.BR '!' ), +or + +(\c +.BR '?' ), +followed by two + +characters or the end of a line; any number of closing parenthesis (\c +.BR ')' ), +closing brackets (\c +.BR ']' ), +double-quote (\c +.BR '\&"' ), +or single-quote (\c +) +characters can appear between the punctuation mark and the two + +characters or end-of-line +.RE +.P +In the remainder of the description of the +.IR vi +utility, the term ``buffer line'' refers to a line in the edit buffer +and the term ``display line'' refers to the line or lines on the +display screen used to display one buffer line. The term ``current +line'' refers to a specific ``buffer line''. +.P +If there are display lines on the screen for which there are no +corresponding buffer lines because they correspond to lines that would +be after the end of the file, they shall be displayed as a single + +(\c +.BR '~' ) +character, plus the terminating +. +.P +The last line of the screen shall be used to report errors or display +informational messages. It shall also be used to display the input for +``line-oriented commands'' (\c +.BR / , +.BR ? , +.BR : , +and +.BR ! ). +When a line-oriented command is executed, the editor shall enter text +input mode on the last line on the screen, using the respective command +characters as prompt characters. (In the case of the +.BR ! +command, the associated motion shall be entered by the user before the +editor enters text input mode.) The line entered by the user shall be +terminated by a +, +a non-\c +\(hyV-escaped +, +or unescaped +. +It is unspecified if more characters than require a display width minus +one column number of screen columns can be entered. +.P +If any command is executed that overwrites a portion of the screen +other than the last line of the screen (for example, the +.IR ex +.BR suspend +or +.BR ! +commands), other than the +.IR ex +.BR shell +command, the user shall be prompted for a character before the screen +is refreshed and the edit session continued. +.P + +characters shall take up the number of columns on the screen set by the +.BR tabstop +edit option (see +.IR ed ), +unless there are less than that number of columns before the display +margin that will cause the displayed line to be folded; in this case, +they shall only take up the number of columns up to that boundary. +.P +The cursor shall be placed on the current line and relative to the +current column as specified by each command described in the following +sections. +.P +In open mode, if the current line is not already displayed, then it +shall be displayed. +.P +In visual mode, if the current line is not displayed, then the lines +that are displayed shall be expanded, scrolled, or redrawn to cause an +unspecified portion of the current line to be displayed. If the screen +is redrawn, no more than the number of display lines specified by the +value of the +.BR window +edit option shall be displayed (unless the current line cannot be +completely displayed in the number of display lines specified by the +.BR window +edit option) and the current line shall be positioned as close to the +center of the displayed lines as possible (within the constraints +imposed by the distance of the line from the beginning or end of the +edit buffer). If the current line is before the first line in the +display and the screen is scrolled, an unspecified portion of the +current line shall be placed on the first line of the display. If the +current line is after the last line in the display and the screen is +scrolled, an unspecified portion of the current line shall be placed on +the last line of the display. +.P +In visual mode, if a line from the edit buffer (other than the current +line) does not entirely fit into the lines at the bottom of the display +that are available for its presentation, the editor may choose not to +display any portion of the line. The lines of the display that do not +contain text from the edit buffer for this reason shall each consist of +a single +.BR '@' +character. +.P +In visual mode, the editor may choose for unspecified reasons to not +update lines in the display to correspond to the underlying edit buffer +text. The lines of the display that do not correctly correspond to text +from the edit buffer for this reason shall consist of a single +.BR '@' +character (plus the terminating +), +and the +\(hyR +command shall cause the editor to update the screen to correctly +represent the edit buffer. +.P +Open and visual mode commands that set the current column set it to a +column position in the display, and not a character position in the +line. In this case, however, the column position in the display shall +be calculated for an infinite width display; for example, the column +related to a character that is part of a line that has been folded onto +additional screen lines will be offset from the display line column +where the buffer line begins, not from the beginning of a particular +display line. +.P +The display cursor column in the display is based on the value of the +current column, as follows, with each rule applied in turn: +.IP " 1." 4 +If the current column is after the last display line column used by the +displayed line, the display cursor column shall be set to the last +display line column occupied by the last non-\c + +in the current line; otherwise, the display cursor column shall be set +to the current column. +.IP " 2." 4 +If the character of which some portion is displayed in the display line +column specified by the display cursor column requires more than a +single display line column: +.RS 4 +.IP " a." 4 +If in text input mode, the display cursor column shall be adjusted to +the first display line column in which any portion of that character is +displayed. +.IP " b." 4 +Otherwise, the display cursor column shall be adjusted to the last +display line column in which any portion of that character is +displayed. +.RE +.P +The current column shall not be changed by these adjustments to the +display cursor column. +.P +If an error occurs during the parsing or execution of a +.IR vi +command: +.IP " *" 4 +The terminal shall be alerted. Execution of the +.IR vi +command shall stop, and the cursor (for example, the current line and +column) shall not be further modified. +.IP " *" 4 +Unless otherwise specified by the following command sections, it is +unspecified whether an informational message shall be displayed. +.IP " *" 4 +Any partially entered +.IR vi +command shall be discarded. +.IP " *" 4 +If the +.IR vi +command resulted from a +.BR map +expansion, all characters from that +.BR map +expansion shall be discarded, except as otherwise specified by the +.BR map +command (see +.IR ed ). +.IP " *" 4 +If the +.IR vi +command resulted from the execution of a buffer, no further commands +caused by the execution of the buffer shall be executed. +.SS "Page Backwards" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR -B +.fi \fR +.P +.RE +.RE +.P +If in open mode, the +\(hyB +command shall behave identically to the +.BR z +command. Otherwise, if the current line is the first line of the edit +buffer, it shall be an error. +.P +If the +.BR window +edit option is less than 3, display a screen where the last line of the +display shall be some portion of: +.sp +.RS 4 +.nf +\fB +(\fIcurrent first line\fR) \(mi1 +.fi \fR +.P +.RE +.P +otherwise, display a screen where the first line of the display shall +be some portion of: +.sp +.RS 4 +.nf +\fB +(\fIcurrent first line\fR) \(mi \fIcount\fR x ((window edit option) \(mi2) +.fi \fR +.P +.RE +.P +If this calculation would result in a line that is before the first +line of the edit buffer, the first line of the display shall display +some portion of the first line of the edit buffer. +.P +.IR "Current line" : +If no lines from the previous display remain on the screen, set to the +last line of the display; otherwise, set to (\c +.IR line +\(mi the number of new lines displayed on this screen). +.P +.IR "Current column" : +Set to non-\c +. +.SS "Scroll Forward" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR -D +.fi \fR +.P +.RE +.RE +.P +If the current line is the last line of the edit buffer, it shall be an +error. +.P +If no +.IR count +is specified, +.IR count +shall default to the +.IR count +associated with the previous +\(hyD +or +\(hyU +command. If there was no previous +\(hyD +or +\(hyU +command, +.IR count +shall default to the value of the +.BR scroll +edit option. +.P +If in open mode, write lines starting with the line after the current +line, until +.IR count +lines or the last line of the file have been written. +.P +.IR "Current line" : +If the current line + +.IR count +is past the last line of the edit buffer, set to the last line of the +edit buffer; otherwise, set to the current line + +.IR count . +.P +.IR "Current column" : +Set to non-\c +. +.SS "Scroll Forward by Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR -E +.fi \fR +.P +.RE +.RE +.P +Display the line count lines after the last line currently displayed. +.P +If the last line of the edit buffer is displayed, it shall be an error. +If there is no line +.IR count +lines after the last line currently displayed, the last line of the +display shall display some portion of the last line of the edit +buffer. +.P +.IR "Current line" : +Unchanged if the previous current character is displayed; otherwise, +set to the first line displayed. +.P +.IR "Current column" : +Unchanged. +.SS "Page Forward" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR -F +.fi \fR +.P +.RE +.RE +.P +If in open mode, the +\(hyF +command shall behave identically to the +.BR z +command. Otherwise, if the current line is the last line of the edit +buffer, it shall be an error. +.P +If the +.BR window +edit option is less than 3, display a screen where the first line of +the display shall be some portion of: +.sp +.RS 4 +.nf +\fB +(\fIcurrent last line\fR) +1 +.fi \fR +.P +.RE +.P +otherwise, display a screen where the first line of the display shall +be some portion of: +.sp +.RS 4 +.nf +\fB +(\fIcurrent first line\fR) + \fIcount\fR x ((window edit option) \(mi2) +.fi \fR +.P +.RE +.P +If this calculation would result in a line that is after the last line +of the edit buffer, the last line of the display shall display some +portion of the last line of the edit buffer. +.P +.IR "Current line" : +If no lines from the previous display remain on the screen, set to the +first line of the display; otherwise, set to (\c +.IR line ++ the number of new lines displayed on this screen). +.P +.IR "Current column" : +Set to non-\c +. +.SS "Display Information" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +-G +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the +.IR ex +.BR file +command. +.SS "Move Cursor Backwards" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR -H +.br +\fB[\fIcount\fB]\fR h +.br +the current \fIerase\fP character (see stty) +.fi \fR +.P +.RE +.RE +.P +If there are no characters before the current character on the current +line, it shall be an error. If there are less than +.IR count +previous characters on the current line, +.IR count +shall be adjusted to the number of previous characters on the line. +.P +If used as a motion command: +.IP " 1." 4 +The text region shall be from the character before the starting cursor +up to and including the +.IR count th +character before the starting cursor. +.IP " 2." 4 +Any text copied to a buffer shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Set to (\c +.IR column +\(mi the number of columns occupied by +.IR count +characters ending with the previous current column). +.SS "Move Down" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR +.br +\fB[\fIcount\fB]\fR -J +.br +\fB[\fIcount\fB]\fR -M +.br +\fB[\fIcount\fB]\fR -N +.br +\fB[\fIcount\fB]\fR j +.br +\fB[\fIcount\fB]\fR +.br +\fB[\fIcount\fB]\fR + +.fi \fR +.P +.RE +.RE +.P +If there are less than +.IR count +lines after the current line in the edit buffer, it shall be an error. +.P +If used as a motion command: +.IP " 1." 4 +The text region shall include the starting line and the next +.IR count +\(mi 1 lines. +.IP " 2." 4 +Any text copied to a buffer shall be in line mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Set to +.IR "current line" + +.IR count . +.P +.IR "Current column" : +Set to non-\c + +for the +, +\(hyM, +and +.BR + +commands; otherwise, unchanged. +.SS "Clear and Redisplay" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +-L +.fi \fR +.P +.RE +.RE +.P +If in open mode, clear the screen and redisplay the current line. +Otherwise, clear and redisplay the screen. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Move Up" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR -P +.br +\fB[\fIcount\fB]\fR k +.br +\fB[\fIcount\fB]\fR \(mi +.fi \fR +.P +.RE +.RE +.P +If there are less than +.IR count +lines before the current line in the edit buffer, it shall be an +error. +.P +If used as a motion command: +.IP " 1." 4 +The text region shall include the starting line and the previous +.IR count +lines. +.IP " 2." 4 +Any text copied to a buffer shall be in line mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Set to +.IR "current line" +\(mi +.IR count . +.P +.IR "Current column" : +Set to non-\c + +for the +.BR \(mi +command; otherwise, unchanged. +.SS "Redraw Screen" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +-R +.fi \fR +.P +.RE +.RE +.P +If any lines have been deleted from the display screen and flagged as +deleted on the terminal using the +.BR @ +convention (see the beginning of the EXTENDED DESCRIPTION section), +they shall be redisplayed to match the contents of the edit buffer. +.P +It is unspecified whether lines flagged with +.BR @ +because they do not fit on the terminal display shall be affected. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Scroll Backward" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR -U +.fi \fR +.P +.RE +.RE +.P +If the current line is the first line of the edit buffer, it shall be +an error. +.P +If no +.IR count +is specified, +.IR count +shall default to the +.IR count +associated with the previous +\(hyD +or +\(hyU +command. If there was no previous +\(hyD +or +\(hyU +command, +.IR count +shall default to the value of the +.BR scroll +edit option. +.P +.IR "Current line" : +If +.IR count +is greater than the current line, set to 1; otherwise, set to the +current line \(mi +.IR count . +.P +.IR "Current column" : +Set to non-\c +. +.SS "Scroll Backward by Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR -Y +.fi \fR +.P +.RE +.RE +.P +Display the line +.IR count +lines before the first line currently displayed. +.P +If the current line is the first line of the edit buffer, it shall be +an error. If this calculation would result in a line that is before the +first line of the edit buffer, the first line of the display shall +display some portion of the first line of the edit buffer. +.P +.IR "Current line" : +Unchanged if the previous current character is displayed; otherwise, +set to the first line displayed. +.P +.IR "Current column" : +Unchanged. +.SS "Edit the Alternate File" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +-^ +.fi \fR +.P +.RE +.RE +This command shall be equivalent to the +.IR ex +.BR edit +command, with the alternate pathname as its argument. +.SS "Terminate Command or Input Mode" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB + +.fi \fR +.P +.RE +.RE +.P +If a partial +.IR vi +command (as defined by at least one, non-\c +.IR count +character) has been entered, discard the +.IR count +and the command character(s). +.P +Otherwise, if no command characters have been entered, and the + +was the result of a map expansion, the terminal shall be alerted and +the + +character shall be discarded, but it shall not be an error. +.P +Otherwise, it shall be an error. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Search for tagstring" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +-] +.fi \fR +.P +.RE +.RE +.P +If the current character is not a word or +, +it shall be an error. +.P +This command shall be equivalent to the +.IR ex +.BR tag +command, with the argument to that command defined as follows. +.P +If the current character is a +: +.IP " 1." 4 +Skip all + +characters after the cursor up to the end of the line. +.IP " 2." 4 +If the end of the line is reached, it shall be an error. +.P +Then, the argument to the +.IR ex +.BR tag +command shall be the current character and all subsequent characters, +up to the first non-word character or the end of the line. +.SS "Move Cursor Forward" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR +.br +\fB[\fIcount\fB]\fR l\fR (ell)\fR +.fi \fR +.P +.RE +.RE +.P +If there are less than +.IR count +non-\c + +characters after the cursor on the current line, +.IR count +shall be adjusted to the number of non-\c + +characters after the cursor on the line. +.P +If used as a motion command: +.IP " 1." 4 +If the current or +.IR count th +character after the cursor is the last non-\c + +in the line, the text region shall be comprised of the current +character up to and including the last non-\c + +in the line. Otherwise, the text region shall be from the current +character up to, but not including, the +.IR count th +character after the cursor. +.IP " 2." 4 +Any text copied to a buffer shall be in character mode. +.P +If not used as a motion command: +.P +If there are no non-\c + +characters after the current character on the current line, it shall be +an error. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Set to the last column that displays any portion of the +.IR count th +character after the current character. +.SS "Replace Text with Results from Shell Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR ! \fImotion shell-commands\fR +.fi \fR +.P +.RE +.RE +.P +If the motion command is the +.BR ! +command repeated: +.IP " 1." 4 +If the edit buffer is empty and no +.IR count +was supplied, the command shall be the equivalent of the +.IR ex +.BR :read +.BR ! +command, with the text input, and no text shall be copied to any +buffer. +.IP " 2." 4 +Otherwise: +.RS 4 +.IP " a." 4 +If there are less than +.IR count +\(mi1 lines after the current line in the edit buffer, it shall be an +error. +.IP " b." 4 +The text region shall be from the current line up to and including the +next +.IR count +\(mi1 lines. +.RE +.P +Otherwise, the text region shall be the lines in which any character of +the text region specified by the motion command appear. +.P +Any text copied to a buffer shall be in line mode. +.P +This command shall be equivalent to the +.IR ex +.BR ! +command for the specified lines. +.SS "Move Cursor to End-of-Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR $ +.fi \fR +.P +.RE +.RE +.P +It shall be an error if there are less than (\c +.IR count +\(mi1) lines after the current line in the edit buffer. +.P +If used as a motion command: +.IP " 1." 4 +If +.IR count +is 1: +.RS 4 +.IP " a." 4 +It shall be an error if the line is empty. +.IP " b." 4 +Otherwise, the text region shall consist of all characters from the +starting cursor to the last non-\c + +in the line, inclusive, and any text copied to a buffer shall be in +character mode. +.RE +.IP " 2." 4 +Otherwise, if the starting cursor position is at or before the first +non-\c + +in the line, the text region shall consist of the current and the next +.IR count +\(mi1 lines, and any text saved to a buffer shall be in line mode. +.IP " 3." 4 +Otherwise, the text region shall consist of all characters from the +starting cursor to the last non-\c + +in the line that is +.IR count +\(mi1 lines forward from the current line, and any text copied to a +buffer shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Set to the +.IR "current line" ++ +.IR count \(mi1. +.P +.IR "Current column" : +The current column is set to the last display line column of the last +non-\c + +in the line, or column position 1 if the line is empty. +.P +The current column shall be adjusted to be on the last display line +column of the last non-\c + +of the current line as subsequent commands change the current line, +until a command changes the current column. +.SS "Move to Matching Character" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +% +.fi \fR +.P +.RE +.RE +.P +If the character at the current position is not a parenthesis, bracket, +or curly brace, search forward in the line to the first one of those +characters. If no such character is found, it shall be an error. +.P +The matching character shall be the parenthesis, bracket, or curly +brace matching the parenthesis, bracket, or curly brace, respectively, +that was at the current position or that was found on the current +line. +.P +Matching shall be determined as follows, for an open parenthesis: +.IP " 1." 4 +Set a counter to 1. +.IP " 2." 4 +Search forwards until a parenthesis is found or the end of the edit +buffer is reached. +.IP " 3." 4 +If the end of the edit buffer is reached, it shall be an error. +.IP " 4." 4 +If an open parenthesis is found, increment the counter by 1. +.IP " 5." 4 +If a close parenthesis is found, decrement the counter by 1. +.IP " 6." 4 +If the counter is zero, the current character is the matching +character. +.P +Matching for a close parenthesis shall be equivalent, except that the +search shall be backwards, from the starting character to the beginning +of the buffer, a close parenthesis shall increment the counter by 1, +and an open parenthesis shall decrement the counter by 1. +.P +Matching for brackets and curly braces shall be equivalent, except that +searching shall be done for open and close brackets or open and close +curly braces. It is implementation-defined whether other characters +are searched for and matched as well. +.P +If used as a motion command: +.IP " 1." 4 +If the matching cursor was after the starting cursor in the edit +buffer, and the starting cursor position was at or before the first +non-\c + +non-\c + +in the starting line, and the matching cursor position was at or after +the last non-\c + +non-\c + +in the matching line, the text region shall consist of the current line +to the matching line, inclusive, and any text copied to a buffer shall +be in line mode. +.IP " 2." 4 +If the matching cursor was before the starting cursor in the edit +buffer, and the starting cursor position was at or after the last +non-\c + +non-\c + +in the starting line, and the matching cursor position was at or before +the first non-\c + +non-\c + +in the matching line, the text region shall consist of the current line +to the matching line, inclusive, and any text copied to a buffer shall +be in line mode. +.IP " 3." 4 +Otherwise, the text region shall consist of the starting character to +the matching character, inclusive, and any text copied to a buffer +shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Set to the line where the matching character is located. +.P +.IR "Current column" : +Set to the last column where any portion of the matching character is +displayed. +.SS "Repeat Substitution" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +& +.fi \fR +.P +.RE +.RE +.P +Repeat the previous substitution command. This command shall be +equivalent to the +.IR ex +.BR & +command with the current line as its addresses, and without +.IR options , +.IR count , +or +.IR flags . +.SS "Return to Previous Context at Beginning of Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\&' \fIcharacter\fR +.fi \fR +.P +.RE +.RE +.P +It shall be an error if there is no line in the edit buffer marked by +.IR character . +.P +If used as a motion command: +.IP " 1." 4 +If the starting cursor is after the marked cursor, then the locations +of the starting cursor and the marked cursor in the edit buffer shall +be logically swapped. +.IP " 2." 4 +The text region shall consist of the starting line up to and including +the marked line, and any text copied to a buffer shall be in line +mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Set to the line referenced by the mark. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Return to Previous Context" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\&` \fIcharacter\fR +.fi \fR +.P +.RE +.RE +.P +It shall be an error if the marked line is no longer in the edit +buffer. If the marked line no longer contains a character in the saved +numbered character position, it shall be as if the marked position is +the first non-\c +. +.P +If used as a motion command: +.IP " 1." 4 +It shall be an error if the marked cursor references the same character +in the edit buffer as the starting cursor. +.IP " 2." 4 +If the starting cursor is after the marked cursor, then the locations +of the starting cursor and the marked cursor in the edit buffer shall +be logically swapped. +.IP " 3." 4 +If the starting line is empty or the starting cursor is at or before +the first non-\c + +non-\c + +of the starting line, and the marked cursor line is empty or the marked +cursor references the first character of the marked cursor line, the +text region shall consist of all lines containing characters from the +starting cursor to the line before the marked cursor line, inclusive, +and any text copied to a buffer shall be in line mode. +.IP " 4." 4 +Otherwise, if the marked cursor line is empty or the marked cursor +references a character at or before the first non-\c + +non-\c + +of the marked cursor line, the region of text shall be from the +starting cursor to the last non-\c + +of the line before the marked cursor line, inclusive, and any text +copied to a buffer shall be in character mode. +.IP " 5." 4 +Otherwise, the region of text shall be from the starting cursor +(inclusive), to the marked cursor (exclusive), and any text copied to a +buffer shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Set to the line referenced by the mark. +.P +.IR "Current column" : +Set to the last column in which any portion of the character referenced +by the mark is displayed. +.SS "Return to Previous Section" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR [[ +.fi \fR +.P +.RE +.RE +.P +Move the cursor backward through the edit buffer to the first character +of the previous section boundary, +.IR count +times. +.P +If used as a motion command: +.IP " 1." 4 +If the starting cursor was at the first character of the starting line +or the starting line was empty, and the first character of the boundary +was the first character of the boundary line, the text region shall +consist of the current line up to and including the line where the +.IR count th +next boundary starts, and any text copied to a buffer shall be in line +mode. +.IP " 2." 4 +If the boundary was the last line of the edit buffer or the last non-\c + +of the last line of the edit buffer, the text region shall consist of +the last character in the edit buffer up to and including the starting +character, and any text saved to a buffer shall be in character mode. +.IP " 3." 4 +Otherwise, the text region shall consist of the starting character up +to but not including the first character in the +.IR count th +next boundary, and any text copied to a buffer shall be in character +mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Set to the line where the +.IR count th +next boundary in the edit buffer starts. +.P +.IR "Current column" : +Set to the last column in which any portion of the first character of +the +.IR count th +next boundary is displayed, or column position 1 if the line is empty. +.SS "Move to Next Section" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR ]] +.fi \fR +.P +.RE +.RE +.P +Move the cursor forward through the edit buffer to the first character +of the next section boundary, +.IR count +times. +.P +If used as a motion command: +.IP " 1." 4 +If the starting cursor was at the first character of the starting line +or the starting line was empty, and the first character of the boundary +was the first character of the boundary line, the text region shall +consist of the current line up to and including the line where the +.IR count th +previous boundary starts, and any text copied to a buffer shall be in +line mode. +.IP " 2." 4 +If the boundary was the first line of the edit buffer, the text region +shall consist of the first character in the edit buffer up to but not +including the starting character, and any text copied to a buffer shall +be in character mode. +.IP " 3." 4 +Otherwise, the text region shall consist of the first character in the +.IR count th +previous section boundary up to but not including the starting +character, and any text copied to a buffer shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Set to the line where the +.IR count th +previous boundary in the edit buffer starts. +.P +.IR "Current column" : +Set to the last column in which any portion of the first character of +the +.IR count th +previous boundary is displayed, or column position 1 if the line is +empty. +.SS "Move to First Non- Position on Current Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\&^ +.fi \fR +.P +.RE +.RE +If used as a motion command: +.IP " 1." 4 +If the line has no non-\c + +non-\c + +characters, or if the cursor is at the first non-\c + +non-\c + +of the line, it shall be an error. +.IP " 2." 4 +If the cursor is before the first non-\c + +non-\c + +of the line, the text region shall be comprised of the current +character, up to, but not including, the first non-\c + +non-\c + +of the line. +.IP " 3." 4 +If the cursor is after the first non-\c + +non-\c + +of the line, the text region shall be from the character before the +starting cursor up to and including the first non-\c + +non-\c + +of the line. +.IP " 4." 4 +Any text copied to a buffer shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Current and Line Above" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR _ +.fi \fR +.P +.RE +.RE +.P +If there are less than +.IR count +\(mi1 lines after the current line in the edit buffer, it shall be an +error. +.P +If used as a motion command: +.IP " 1." 4 +If +.IR count +is less than 2, the text region shall be the current line. +.IP " 2." 4 +Otherwise, the text region shall include the starting line and the next +.IR count +\(mi1 lines. +.IP " 3." 4 +Any text copied to a buffer shall be in line mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Set to current line + +.IR count +\(mi1. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Move Back to Beginning of Sentence" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR ( +.fi \fR +.P +.RE +.RE +.P +Move backward to the beginning of a sentence. This command shall be +equivalent to the +.BR [[ +command, with the exception that sentence boundaries shall be used +instead of section boundaries. +.SS "Move Forward to Beginning of Sentence" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR ) +.fi \fR +.P +.RE +.RE +.P +Move forward to the beginning of a sentence. This command shall be +equivalent to the +.BR ]] +command, with the exception that sentence boundaries shall be used +instead of section boundaries. +.SS "Move Back to Preceding Paragraph" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR { +.fi \fR +.P +.RE +.RE +.P +Move back to the beginning of the preceding paragraph. This command +shall be equivalent to the +.BR [[ +command, with the exception that paragraph boundaries shall be used +instead of section boundaries. +.SS "Move Forward to Next Paragraph" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR } +.fi \fR +.P +.RE +.RE +.P +Move forward to the beginning of the next paragraph. This command +shall be equivalent to the +.BR ]] +command, with the exception that paragraph boundaries shall be used +instead of section boundaries. +.SS "Move to Specific Column Position" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR | +.fi \fR +.P +.RE +.RE +.P +For the purposes of this command, lines that are too long for the +current display and that have been folded shall be treated as having a +single, 1\(mibased, number of columns. +.P +If there are less than +.IR count +columns in which characters from the current line are displayed on the +screen, +.IR count +shall be adjusted to be the last column in which any portion of the +line is displayed on the screen. +.P +If used as a motion command: +.IP " 1." 4 +If the line is empty, or the cursor character is the same as the +character on the +.IR count th +column of the line, it shall be an error. +.IP " 2." 4 +If the cursor is before the +.IR count th +column of the line, the text region shall be comprised of the current +character, up to but not including the character on the +.IR count th +column of the line. +.IP " 3." 4 +If the cursor is after the +.IR count th +column of the line, the text region shall be from the character before +the starting cursor up to and including the character on the +.IR count th +column of the line. +.IP " 4." 4 +Any text copied to a buffer shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Set to the last column in which any portion of the character that is +displayed in the +.IR count +column of the line is displayed. +.SS "Reverse Find Character" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR , +.fi \fR +.P +.RE +.RE +.P +If the last +.BR F , +.BR f , +.BR T , +or +.BR t +command was +.BR F , +.BR f , +.BR T , +or +.BR t , +this command shall be equivalent to an +.BR f , +.BR F , +.BR t , +or +.BR T +command, respectively, with the specified +.IR count +and the same search character. +.P +If there was no previous +.BR F , +.BR f , +.BR T , +or +.BR t +command, it shall be an error. +.SS "Repeat" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR . +.fi \fR +.P +.RE +.RE +.P +Repeat the last +.BR ! , +.BR < , +.BR > , +.BR A , +.BR C , +.BR D , +.BR I , +.BR J , +.BR O , +.BR P , +.BR R , +.BR S , +.BR X , +.BR Y , +.BR a , +.BR c , +.BR d , +.BR i , +.BR o , +.BR p , +.BR r , +.BR s , +.BR x , +.BR y , +or +.BR ~ +command. It shall be an error if none of these commands have been +executed. Commands (other than commands that enter text input mode) +executed as a result of map expansions, shall not change the value of +the last repeatable command. +.P +Repeated commands with associated motion commands shall repeat the +motion command as well; however, any specified +.IR count +shall replace the +.IR count (s) +that were originally specified to the repeated command or its +associated motion command. +.P +If the motion component of the repeated command is +.BR f , +.BR F , +.BR t , +or +.BR T , +the repeated command shall not set the remembered search character for +the +.BR ; +and +.BR , +commands. +.P +If the repeated command is +.BR p +or +.BR P , +and the buffer associated with that command was a numeric buffer named +with a number less than 9, the buffer associated with the repeated +command shall be set to be the buffer named by the name of the previous +buffer logically incremented by 1. +.P +If the repeated character is a text input command, the input text +associated with that command is repeated literally: +.IP " *" 4 +Input characters are neither macro or abbreviation-expanded. +.IP " *" 4 +Input characters are not interpreted in any special way with the +exception that +, +, +and +\(hyT +behave as described in +.IR "Input Mode Commands in vi". +.P +.IR "Current line" : +Set as described for the repeated command. +.P +.IR "Current column" : +Set as described for the repeated command. +.SS "Find Regular Expression" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +/ +.fi \fR +.P +.RE +.RE +.P +If the input line contains no non-\c + +characters, it shall be equivalent to a line containing only the +last regular expression encountered. The enhanced regular expressions +supported by +.IR vi +are described in +.IR "Regular Expressions in ex". +.P +Otherwise, the line shall be interpreted as one or more regular +expressions, optionally followed by an address offset or a +.IR vi +.BR z +command. +.P +If the regular expression is not the last regular expression on the +line, or if a line offset or +.BR z +command is specified, the regular expression shall be terminated by an +unescaped +.BR '/' +character, which shall not be used as part of the regular expression. +If the regular expression is not the first regular expression on the +line, it shall be preceded by zero or more + +characters, a +, +zero or more + +characters, and a leading +.BR '/' +character, which shall not be interpreted as part of the regular +expression. It shall be an error to precede any regular expression with +any characters other than these. +.P +Each search shall begin from the character after the first character of +the last match (or, if it is the first search, after the cursor). If +the +.BR wrapscan +edit option is set, the search shall continue to the character before +the starting cursor character; otherwise, to the end of the edit +buffer. It shall be an error if any search fails to find a match, and +an informational message to this effect shall be displayed. +.P +An optional address offset (see +.IR "Addressing in ex") +can be specified after the last regular expression by including a +trailing +.BR '/' +character after the regular expression and specifying the address +offset. This offset will be from the line containing the match for the +last regular expression specified. It shall be an error if the line +offset would indicate a line address less than 1 or greater than the +last line in the edit buffer. An address offset of zero shall be +supported. It shall be an error to follow the address offset with any +other characters than + +characters. +.P +If not used as a motion command, an optional +.BR z +command (see +.IR "Redraw Window") +can be specified after the last regular expression by including a +trailing +.BR '/' +character after the regular expression, zero or more + +characters, a +.BR 'z' , +zero or more + +characters, an optional new +.BR window +edit option value, zero or more + +characters, and a location character. The effect shall be as if the +.BR z +command was executed after the +.BR / +command. It shall be an error to follow the +.BR z +command with any other characters than + +characters. +.P +The remembered search direction shall be set to forward. +.P +If used as a motion command: +.IP " 1." 4 +It shall be an error if the last match references the same character in +the edit buffer as the starting cursor. +.IP " 2." 4 +If any address offset is specified, the last match shall be adjusted by +the specified offset as described previously. +.IP " 3." 4 +If the starting cursor is after the last match, then the locations of +the starting cursor and the last match in the edit buffer shall be +logically swapped. +.IP " 4." 4 +If any address offset is specified, the text region shall consist of +all lines containing characters from the starting cursor to the last +match line, inclusive, and any text copied to a buffer shall be in line +mode. +.IP " 5." 4 +Otherwise, if the starting line is empty or the starting cursor is at +or before the first non-\c + +non-\c + +of the starting line, and the last match line is empty or the last +match starts at the first character of the last match line, the text +region shall consist of all lines containing characters from the +starting cursor to the line before the last match line, inclusive, and +any text copied to a buffer shall be in line mode. +.IP " 6." 4 +Otherwise, if the last match line is empty or the last match begins at +a character at or before the first non-\c + +non-\c + +of the last match line, the region of text shall be from the current +cursor to the last non-\c + +of the line before the last match line, inclusive, and any text copied +to a buffer shall be in character mode. +.IP " 7." 4 +Otherwise, the region of text shall be from the current cursor +(inclusive), to the first character of the last match (exclusive), and +any text copied to a buffer shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +If a match is found, set to the last matched line plus the address +offset, if any; otherwise, unchanged. +.P +.IR "Current column" : +Set to the last column on which any portion of the first character in +the last matched string is displayed, if a match is found; otherwise, +unchanged. +.SS "Move to First Character in Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +0 \fR(zero)\fR +.fi \fR +.P +.RE +.RE +.P +Move to the first character on the current line. The character +.BR '0' +shall not be interpreted as a command if it is immediately preceded by +a digit. +.P +If used as a motion command: +.IP " 1." 4 +If the cursor character is the first character in the line, it shall be +an error. +.IP " 2." 4 +The text region shall be from the character before the cursor character +up to and including the first character in the line. +.IP " 3." 4 +Any text copied to a buffer shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +The last column in which any portion of the first character in the line +is displayed, or if the line is empty, unchanged. +.SS "Execute an ex Command" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +: +.fi \fR +.P +.RE +.RE +.P +Execute one or more +.IR ex +commands. +.P +If any portion of the screen other than the last line of the screen was +overwritten by any +.IR ex +command (except +.BR shell ), +.IR vi +shall display a message indicating that it is waiting for an input from +the user, and shall then read a character. This action may also be +taken for other, unspecified reasons. +.P +If the next character entered is a +.BR ':' , +another +.IR ex +command shall be accepted and executed. Any other character shall cause +the screen to be refreshed and +.IR vi +shall return to command mode. +.P +.IR "Current line" : +As specified for the +.IR ex +command. +.P +.IR "Current column" : +As specified for the +.IR ex +command. +.SS "Repeat Find" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR ; +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the last +.BR F , +.BR f , +.BR T , +or +.BR t +command, with the specified +.IR count , +and with the same search character used for the last +.BR F , +.BR f , +.BR T , +or +.BR t +command. If there was no previous +.BR F , +.BR f , +.BR T , +or +.BR t +command, it shall be an error. +.SS "Shift Left" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR < \fImotion\fR +.fi \fR +.P +.RE +.RE +.P +If the motion command is the +.BR < +command repeated: +.IP " 1." 4 +If there are less than +.IR count +\(mi1 lines after the current line in the edit buffer, it shall be an +error. +.IP " 2." 4 +The text region shall be from the current line, up to and including the +next +.IR count +\(mi1 lines. +.P +Shift any line in the text region specified by the +.IR count +and motion command one shiftwidth (see the +.IR ex +.BR shiftwidth +option) toward the start of the line, as described by the +.IR ex +.BR < +command. The unshifted lines shall be copied to the unnamed buffer in +line mode. +.P +.IR "Current line" : +If the motion was from the current cursor position toward the end of +the edit buffer, unchanged. Otherwise, set to the first line in the +edit buffer that is part of the text region specified by the motion +command. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Shift Right" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR > \fImotion\fR +.fi \fR +.P +.RE +.RE +.P +If the motion command is the +.BR > +command repeated: +.IP " 1." 4 +If there are less than +.IR count +\(mi1 lines after the current line in the edit buffer, it shall be an +error. +.IP " 2." 4 +The text region shall be from the current line, up to and including the +next +.IR count +\(mi1 lines. +.P +Shift any line with characters in the text region specified by the +.IR count +and motion command one shiftwidth (see the +.IR ex +.BR shiftwidth +option) away from the start of the line, as described by the +.IR ex +.BR > +command. The unshifted lines shall be copied into the unnamed buffer in +line mode. +.P +.IR "Current line" : +If the motion was from the current cursor position toward the end of +the edit buffer, unchanged. Otherwise, set to the first line in the +edit buffer that is part of the text region specified by the +motion command. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Scan Backwards for Regular Expression" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +? +.fi \fR +.P +.RE +.RE +.P +Scan backwards; the +.BR ? +command shall be equivalent to the +.BR / +command (see +.IR "Find Regular Expression") +with the following exceptions: +.IP " 1." 4 +The input prompt shall be a +.BR '?' . +.IP " 2." 4 +Each search shall begin from the character before the first character +of the last match (or, if it is the first search, the character before +the cursor character). +.IP " 3." 4 +The search direction shall be from the cursor toward the beginning of +the edit buffer, and the +.BR wrapscan +edit option shall affect whether the search wraps to the end of the +edit buffer and continues. +.IP " 4." 4 +The remembered search direction shall be set to backward. +.SS "Execute" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +@\fIbuffer\fR +.fi \fR +.P +.RE +.RE +.P +If the +.IR buffer +is specified as +.BR @ , +the last buffer executed shall be used. If no previous buffer has been +executed, it shall be an error. +.P +Behave as if the contents of the named buffer were entered as standard +input. After each line of a line-mode buffer, and all but the last line +of a character mode buffer, behave as if a + +were entered as standard input. +.P +If an error occurs during this process, an error message shall be +written, and no more characters resulting from the execution of this +command shall be processed. +.P +If a +.IR count +is specified, behave as if that count were entered as user input before +the characters from the +.BR @ +buffer were entered. +.P +.IR "Current line" : +As specified for the individual commands. +.P +.IR "Current column" : +As specified for the individual commands. +.SS "Reverse Case" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR ~ +.fi \fR +.P +.RE +.RE +.P +Reverse the case of the current character and the next +.IR count +\(mi1 characters, such that lowercase characters that have uppercase +counterparts shall be changed to uppercase characters, and uppercase +characters that have lowercase counterparts shall be changed to +lowercase characters, as prescribed by the current locale. No other +characters shall be affected by this command. +.P +If there are less than +.IR count +\(mi1 characters after the cursor in the edit buffer, +.IR count +shall be adjusted to the number of characters after the cursor in the +edit buffer minus 1. +.P +For the purposes of this command, the next character after the last +non-\c + +on the line shall be the next character in the edit buffer. +.P +.IR "Current line" : +Set to the line including the (\c +.IR count \(mi1)th +character after the cursor. +.P +.IR "Current column" : +Set to the last column in which any portion of the (\c +.IR count \(mi1)th +character after the cursor is displayed. +.SS "Append" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR a +.fi \fR +.P +.RE +.RE +.P +Enter text input mode after the current cursor position. No characters +already in the edit buffer shall be affected by this command. A +.IR count +shall cause the input text to be appended +.IR count +\(mi1 more times to the end of the input. +.P +.IR "Current line/column" : +As specified for the text input commands (see +.IR "Input Mode Commands in vi"). +.SS "Append at End-of-Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR A +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the +.IR vi +command: +.sp +.RS 4 +.nf +\fB +\fR$\fB [ \fIcount \fB]\fR a +.fi \fR +.P +.RE +.P +(see +.IR "Append"). +.SS "Move Backward to Preceding Word" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR b +.fi \fR +.P +.RE +.RE +.P +With the exception that words are used as the delimiter instead of +bigwords, this command shall be equivalent to the +.BR B +command. +.SS "Move Backward to Preceding Bigword" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR B +.fi \fR +.P +.RE +.RE +.P +If the edit buffer is empty or the cursor is on the first character of +the edit buffer, it shall be an error. If less than +.IR count +bigwords begin between the cursor and the start of the edit buffer, +.IR count +shall be adjusted to the number of bigword beginnings between the +cursor and the start of the edit buffer. +.P +If used as a motion command: +.IP " 1." 4 +The text region shall be from the first character of the +.IR count th +previous bigword beginning up to but not including the cursor +character. +.IP " 2." 4 +Any text copied to a buffer shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Set to the line containing the +.IR "current column" . +.P +.IR "Current column" : +Set to the last column upon which any part of the first character of +the +.IR count th +previous bigword is displayed. +.SS "Change" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB][\fIcount\fB]\fR c \fImotion\fR +.fi \fR +.P +.RE +.RE +.P +If the motion command is the +.BR c +command repeated: +.IP " 1." 4 +The buffer text shall be in line mode. +.IP " 2." 4 +If there are less than +.IR count +\(mi1 lines after the current line in the edit buffer, it shall be an +error. +.IP " 3." 4 +The text region shall be from the current line up to and including the +next +.IR count +\(mi1 lines. +.P +Otherwise, the buffer text mode and text region shall be as specified +by the motion command. +.P +The replaced text shall be copied into +.IR buffer , +if specified, and into the unnamed buffer. If the text to be replaced +contains characters from more than a single line, or the buffer text is +in line mode, the replaced text shall be copied into the numeric +buffers as well. +.P +If the buffer text is in line mode: +.IP " 1." 4 +Any lines that contain characters in the region shall be deleted, and +the editor shall enter text input mode at the beginning of a new line +which shall replace the first line deleted. +.IP " 2." 4 +If the +.BR autoindent +edit option is set, +.BR autoindent +characters equal to the +.BR autoindent +characters on the first line deleted shall be inserted as if entered by +the user. +.P +Otherwise, if characters from more than one line are in the region of +text: +.IP " 1." 4 +The text shall be deleted. +.IP " 2." 4 +Any text remaining in the last line in the text region shall be +appended to the first line in the region, and the last line in the +region shall be deleted. +.IP " 3." 4 +The editor shall enter text input mode after the last character not +deleted from the first line in the text region, if any; otherwise, on +the first column of the first line in the region. +.br +.P +Otherwise: +.IP " 1." 4 +If the glyph for +.BR '$' +is smaller than the region, the end of the region shall be marked with +a +.BR '$' . +.IP " 2." 4 +The editor shall enter text input mode, overwriting the region of +text. +.P +.IR "Current line/column" : +As specified for the text input commands (see +.IR "Input Mode Commands in vi"). +.SS "Change to End-of-Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB][\fIcount\fB]\fR C +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the +.IR vi +command: +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB][\fIcount\fB]\fR c$ +.fi \fR +.P +.RE +.P +See the +.BR c +command. +.SS "Delete" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB][\fIcount\fB]\fR d \fImotion\fR +.fi \fR +.P +.RE +.RE +.P +If the motion command is the +.BR d +command repeated: +.IP " 1." 4 +The buffer text shall be in line mode. +.IP " 2." 4 +If there are less than +.IR count +\(mi1 lines after the current line in the edit buffer, it shall be an +error. +.IP " 3." 4 +The text region shall be from the current line up to and including the +next +.IR count +\(mi1 lines. +.P +Otherwise, the buffer text mode and text region shall be as specified +by the motion command. +.P +If in open mode, and the current line is deleted, and the line remains +on the display, an +.BR '@' +character shall be displayed as the first glyph of that line. +.P +Delete the region of text into +.IR buffer , +if specified, and into the unnamed buffer. If the text to be deleted +contains characters from more than a single line, or the buffer text is +in line mode, the deleted text shall be copied into the numeric +buffers, as well. +.P +.IR "Current line" : +Set to the first text region line that appears in the edit buffer, +unless that line has been deleted, in which case it shall be set to the +last line in the edit buffer, or line 1 if the edit buffer is empty. +.P +.IR "Current column" : +.IP " 1." 4 +If the line is empty, set to column position 1. +.IP " 2." 4 +Otherwise, if the buffer text is in line mode or the motion was from +the cursor toward the end of the edit buffer: +.RS 4 +.IP " a." 4 +If a character from the current line is displayed in the current +column, set to the last column that displays any portion of that +character. +.IP " b." 4 +Otherwise, set to the last column in which any portion of any character +in the line is displayed. +.RE +.IP " 3." 4 +Otherwise, if a character is displayed in the column that began the +text region, set to the last column that displays any portion of that +character. +.IP " 4." 4 +Otherwise, set to the last column in which any portion of any character +in the line is displayed. +.SS "Delete to End-of-Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB]\fR D +.fi \fR +.P +.RE +.RE +.P +Delete the text from the current position to the end of the current +line; equivalent to the +.IR vi +command: +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB]\fR d$ +.fi \fR +.P +.RE +.SS "Move to End-of-Word" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR e +.fi \fR +.P +.RE +.RE +.P +With the exception that words are used instead of bigwords as the +delimiter, this command shall be equivalent to the +.BR E +command. +.SS "Move to End-of-Bigword" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR E +.fi \fR +.P +.RE +.RE +.P +If the edit buffer is empty it shall be an error. If less than +.IR count +bigwords end between the cursor and the end of the edit buffer, +.IR count +shall be adjusted to the number of bigword endings between the cursor +and the end of the edit buffer. +.P +If used as a motion command: +.IP " 1." 4 +The text region shall be from the last character of the +.IR count th +next bigword up to and including the cursor character. +.IP " 2." 4 +Any text copied to a buffer shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Set to the line containing the current column. +.P +.IR "Current column" : +Set to the last column upon which any part of the last character of the +.IR count th +next bigword is displayed. +.SS "Find Character in Current Line (Forward)" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR f \fIcharacter\fR +.fi \fR +.P +.RE +.RE +.P +It shall be an error if +.IR count +occurrences of the character do not occur after the cursor in the +line. +.P +If used as a motion command: +.IP " 1." 4 +The text range shall be from the cursor character up to and including +the +.IR count th +occurrence of the specified character after the cursor. +.IP " 2." 4 +Any text copied to a buffer shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Set to the last column in which any portion of the +.IR count th +occurrence of the specified character after the cursor appears in the +line. +.SS "Find Character in Current Line (Reverse)" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR F \fIcharacter\fR +.fi \fR +.P +.RE +.RE +.P +It shall be an error if +.IR count +occurrences of the character do not occur before the cursor in the +line. +.P +If used as a motion command: +.IP " 1." 4 +The text region shall be from the +.IR count th +occurrence of the specified character before the cursor, up to, but not +including the cursor character. +.IP " 2." 4 +Any text copied to a buffer shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Set to the last column in which any portion of the +.IR count th +occurrence of the specified character before the cursor appears in the +line. +.SS "Move to Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR G +.fi \fR +.P +.RE +.RE +.P +If +.IR count +is not specified, it shall default to the last line of the edit buffer. +If +.IR count +is greater than the last line of the edit buffer, it shall be an +error. +.P +If used as a motion command: +.IP " 1." 4 +The text region shall be from the cursor line up to and including the +specified line. +.IP " 2." 4 +Any text copied to a buffer shall be in line mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Set to +.IR count +if +.IR count +is specified; otherwise, the last line. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Move to Top of Screen" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR H +.fi \fR +.P +.RE +.RE +.P +If the beginning of the line +.IR count +greater than the first line of which any portion appears on the display +does not exist, it shall be an error. +.P +If used as a motion command: +.IP " 1." 4 +If in open mode, the text region shall be the current line. +.IP " 2." 4 +Otherwise, the text region shall be from the starting line up to and +including (the first line of the display + +.IR count +\(mi1). +.IP " 3." 4 +Any text copied to a buffer shall be in line mode. +.P +If not used as a motion command: +.P +If in open mode, this command shall set the current column to non-\c + +and do nothing else. +.P +Otherwise, it shall set the current line and current column as +follows. +.P +.IR "Current line" : +Set to (the first line of the display + +.IR count +\(mi1). +.P +.IR "Current column" : +Set to non-\c +. +.SS "Insert Before Cursor" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR i +.fi \fR +.P +.RE +.RE +.P +Enter text input mode before the current cursor position. No characters +already in the edit buffer shall be affected by this command. A +.IR count +shall cause the input text to be appended +.IR count +\(mi1 more times to the end of the input. +.P +.IR "Current line/column" : +As specified for the text input commands (see +.IR "Input Mode Commands in vi"). +.SS "Insert at Beginning of Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR I +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the +.IR vi +command ^[\c +.IR count ]\c +.BR i . +.SS "Join" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR J +.fi \fR +.P +.RE +.RE +.P +If the current line is the last line in the edit buffer, it shall be an +error. +.P +This command shall be equivalent to the +.IR ex +.BR join +command with no addresses, and an +.IR ex +command +.IR count +value of 1 if +.IR count +was not specified or if a +.IR count +of 1 was specified, and an +.IR ex +command +.IR count +value of +.IR count +\(mi1 for any other value of +.IR count , +except that the current line and column shall be set as follows. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +The last column in which any portion of the character following the +last character in the initial line is displayed, or the last non-\c + +in the line if no characters were appended. +.SS "Move to Bottom of Screen" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR L +.fi \fR +.P +.RE +.RE +.P +If the beginning of the line +.IR count +less than the last line of which any portion appears on the display +does not exist, it shall be an error. +.P +If used as a motion command: +.IP " 1." 4 +If in open mode, the text region shall be the current line. +.IP " 2." 4 +Otherwise, the text region shall include all lines from the starting +cursor line to (the last line of the display \(mi(\c +.IR count +\(mi1)). +.IP " 3." 4 +Any text copied to a buffer shall be in line mode. +.P +If not used as a motion command: +.IP " 1." 4 +If in open mode, this command shall set the current column to non-\c + +and do nothing else. +.IP " 2." 4 +Otherwise, it shall set the current line and current column as follows. +.P +.IR "Current line" : +Set to (the last line of the display \(mi(\c +.IR count +\(mi1)). +.P +.IR "Current column" : +Set to non-\c +. +.SS "Mark Position" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +m \fIletter\fR +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the +.IR ex +.BR mark +command with the specified character as an argument. +.SS "Move to Middle of Screen" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +M +.fi \fR +.P +.RE +.RE +.P +The middle line of the display shall be calculated as follows: +.sp +.RS 4 +.nf +\fB +(the top line of the display) + (((number of lines displayed) +1) /2) \(mi1 +.fi \fR +.P +.RE +.P +If used as a motion command: +.IP " 1." 4 +If in open mode, the text region shall be the current line. +.IP " 2." 4 +Otherwise, the text region shall include all lines from the starting +cursor line up to and including the middle line of the display. +.IP " 3." 4 +Any text copied to a buffer shall be in line mode. +.P +If not used as a motion command: +.P +If in open mode, this command shall set the current column to non-\c + +and do nothing else. +.P +Otherwise, it shall set the current line and current column as +follows. +.P +.IR "Current line" : +Set to the middle line of the display. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Repeat Regular Expression Find (Forward)" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +n +.fi \fR +.P +.RE +.RE +.P +If the remembered search direction was forward, the +.BR n +command shall be equivalent to the +.IR vi +.BR / +command with no characters entered by the user. Otherwise, it shall be +equivalent to the +.IR vi +.BR ? +command with no characters entered by the user. +.P +If the +.BR n +command is used as a motion command for the +.BR ! +command, the editor shall not enter text input mode on the last line on +the screen, and shall behave as if the user entered a single +.BR '!' +character as the text input. +.SS "Repeat Regular Expression Find (Reverse)" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +N +.fi \fR +.P +.RE +.RE +.P +Scan for the next match of the last pattern given to +.BR / +or +.BR ? , +but in the reverse direction; this is the reverse of +.BR n . +.P +If the remembered search direction was forward, the +.BR N +command shall be equivalent to the +.IR vi +.BR ? +command with no characters entered by the user. Otherwise, it shall be +equivalent to the +.IR vi +.BR / +command with no characters entered by the user. If the +.BR N +command is used as a motion command for the +.BR ! +command, the editor shall not enter text input mode on the last line on +the screen, and shall behave as if the user entered a single +.BR ! +character as the text input. +.SS "Insert Empty Line Below" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +o +.fi \fR +.P +.RE +.RE +.P +Enter text input mode in a new line appended after the current line. A +.IR count +shall cause the input text to be appended +.IR count +\(mi1 more times to the end of the already added text, each time +starting on a new, appended line. +.P +.IR "Current line/column" : +As specified for the text input commands (see +.IR "Input Mode Commands in vi"). +.SS "Insert Empty Line Above" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +O +.fi \fR +.P +.RE +.RE +.P +Enter text input mode in a new line inserted before the current line. A +.IR count +shall cause the input text to be appended +.IR count +\(mi1 more times to the end of the already added text, each time +starting on a new, appended line. +.P +.IR "Current line/column" : +As specified for the text input commands (see +.IR "Input Mode Commands in vi"). +.SS "Put from Buffer Following" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB]\fR p +.fi \fR +.P +.RE +.RE +.P +If no +.IR buffer +is specified, the unnamed buffer shall be used. +.P +If the buffer text is in line mode, the text shall be appended below +the current line, and each line of the buffer shall become a new line +in the edit buffer. A +.IR count +shall cause the buffer text to be appended +.IR count +\(mi1 more times to the end of the already added text, each time +starting on a new, appended line. +.P +If the buffer text is in character mode, the text shall be appended +into the current line after the cursor, and each line of the buffer +other than the first and last shall become a new line in the edit +buffer. A +.IR count +shall cause the buffer text to be appended +.IR count +\(mi1 more times to the end of the already added text, each time +starting after the last added character. +.P +.IR "Current line" : +If the buffer text is in line mode, set the line to line +1; otherwise, +unchanged. +.P +.IR "Current column" : +If the buffer text is in line mode: +.IP " 1." 4 +If there is a non-\c + +in the first line of the buffer, set to the last column on which any +portion of the first non-\c + +in the line is displayed. +.IP " 2." 4 +If there is no non-\c + +in the first line of the buffer, set to the last column on which any +portion of the last non-\c + +in the first line of the buffer is displayed. +.P +If the buffer text is in character mode: +.IP " 1." 4 +If the text in the buffer is from more than a single line, then set to +the last column on which any portion of the first character from the +buffer is displayed. +.IP " 2." 4 +Otherwise, if the buffer is the unnamed buffer, set to the last column +on which any portion of the last character from the buffer is +displayed. +.IP " 3." 4 +Otherwise, set to the first column on which any portion of the first +character from the buffer is displayed. +.SS "Put from Buffer Before" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB]\fR P +.fi \fR +.P +.RE +.RE +.P +If no +.IR buffer +is specified, the unnamed buffer shall be used. +.P +If the buffer text is in line mode, the text shall be inserted above +the current line, and each line of the buffer shall become a new line +in the edit buffer. A +.IR count +shall cause the buffer text to be appended +.IR count +\(mi1 more times to the end of the already added text, each time +starting on a new, appended line. +.P +If the buffer text is in character mode, the text shall be inserted +into the current line before the cursor, and each line of the buffer +other than the first and last shall become a new line in the edit +buffer. A +.IR count +shall cause the buffer text to be appended +.IR count +\(mi1 more times to the end of the already added text, each time +starting after the last added character. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +If the buffer text is in line mode: +.IP " 1." 4 +If there is a non-\c + +in the first line of the buffer, set to the last column on which any +portion of that character is displayed. +.IP " 2." 4 +If there is no non-\c + +in the first line of the buffer, set to the last column on which any +portion of the last non-\c + +in the first line of the buffer is displayed. +.P +If the buffer text is in character mode: +.IP " 1." 4 +If the text in the buffer is from more than a single line, then set to +the last column on which any portion of the first character from the +buffer is displayed. +.IP " 2." 4 +Otherwise, if the buffer is the unnamed buffer, set to the last column +on which any portion of the last character from the buffer is displayed. +.IP " 3." 4 +Otherwise, set to the first column on which any portion of the first +character from the buffer is displayed. +.SS "Enter ex Mode" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +Q +.fi \fR +.P +.RE +.RE +.P +Leave visual or open mode and enter +.IR ex +command mode. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "Replace Character" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR r \fIcharacter\fR +.fi \fR +.P +.RE +.RE +.P +Replace the +.IR count +characters at and after the cursor with the specified character. If +there are less than +.IR count +non-\c + +characters at and after the cursor on the line, it shall be an error. +.P +If character is +\(hyV, +any next character other than the + +shall be stripped of any special meaning and used as a literal +character. +.P +If character is +, +no replacement shall be made and the current line and current column +shall be unchanged. +.P +If character is + +or +, +.IR count +new lines shall be appended to the current line. All but the last of +these lines shall be empty. +.IR count +characters at and after the cursor shall be discarded, and any +remaining characters after the cursor in the current line shall be +moved to the last of the new lines. If the +.BR autoindent +edit option is set, they shall be preceded by the same number of +.BR autoindent +characters found on the line from which the command was executed. +.P +.IR "Current line" : +Unchanged unless the replacement character is a + +or +, +in which case it shall be set to line + +.IR count . +.P +.IR "Current column" : +Set to the last column position on which a portion of the last replaced +character is displayed, or if the replacement character caused new +lines to be created, set to non-\c +. +.SS "Replace Characters" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +R +.fi \fR +.P +.RE +.RE +.P +Enter text input mode at the current cursor position possibly +replacing text on the current line. A +.IR count +shall cause the input text to be appended +.IR count +\(mi1 more times to the end of the input. +.P +.IR "Current line/column" : +As specified for the text input commands (see +.IR "Input Mode Commands in vi"). +.SS "Substitute Character" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB][\fIcount\fB]\fR s +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the +.IR vi +command: +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB][\fIcount\fB]\fR c +.fi \fR +.P +.RE +.SS "Substitute Lines" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB][\fIcount\fB]\fR S +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the +.IR vi +command: +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB][\fIcount\fB]\fR c_ +.fi \fR +.P +.RE +.SS "Move Cursor to Before Character (Forward)" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR t \fIcharacter\fR +.fi \fR +.P +.RE +.RE +.P +It shall be an error if +.IR count +occurrences of the character do not occur after the cursor in the +line. +.P +If used as a motion command: +.IP " 1." 4 +The text region shall be from the cursor up to but not including the +.IR count th +occurrence of the specified character after the cursor. +.IP " 2." 4 +Any text copied to a buffer shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Set to the last column in which any portion of the character before the +.IR count th +occurrence of the specified character after the cursor appears in the +line. +.SS "Move Cursor to After Character (Reverse)" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR T \fIcharacter\fR +.fi \fR +.P +.RE +.RE +.P +It shall be an error if +.IR count +occurrences of the character do not occur before the cursor in the +line. +.P +If used as a motion command: +.IP " 1." 4 +If the character before the cursor is the specified character, it shall +be an error. +.IP " 2." 4 +The text region shall be from the character before the cursor up to but +not including the +.IR count th +occurrence of the specified character before the cursor. +.IP " 3." 4 +Any text copied to a buffer shall be in character mode. +.P +If not used as a motion command: +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Set to the last column in which any portion of the character after the +.IR count th +occurrence of the specified character before the cursor appears in the +line. +.SS "Undo" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +u +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the +.IR ex +.BR undo +command except that the current line and current column shall be set as +follows: +.P +.IR "Current line" : +Set to the first line added or changed if any; otherwise, move to the +line preceding any deleted text if one exists; otherwise, move to line 1. +.P +.IR "Current column" : +If undoing an +.IR ex +command, set to the first non-\c +. +.P +Otherwise, if undoing a text input command: +.IP " 1." 4 +If the command was a +.BR C , +.BR c , +.BR O , +.BR o , +.BR R , +.BR S , +or +.BR s +command, the current column shall be set to the value it held when the +text input command was entered. +.IP " 2." 4 +Otherwise, set to the last column in which any portion of the first +character after the deleted text is displayed, or, if no non-\c + +characters follow the text deleted from this line, set to the last column +in which any portion of the last non-\c + +in the line is displayed, or 1 if the line is empty. +.P +Otherwise, if a single line was modified (that is, not added or +deleted) by the +.BR u +command: +.IP " 1." 4 +If text was added or changed, set to the last column in which any +portion of the first character added or changed is displayed. +.IP " 2." 4 +If text was deleted, set to the last column in which any portion of the +first character after the deleted text is displayed, or, if no non-\c + +characters follow the deleted text, set to the last column in which any +portion of the last non-\c + +in the line is displayed, or 1 if the line is empty. +.P +Otherwise, set to non-\c +. +.SS "Undo Current Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +U +.fi \fR +.P +.RE +.RE +.P +Restore the current line to its state immediately before the most +recent time that it became the current line. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Set to the first column in the line in which any portion of the first +character in the line is displayed. +.SS "Move to Beginning of Word" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR w +.fi \fR +.P +.RE +.RE +.P +With the exception that words are used as the delimiter instead of +bigwords, this command shall be equivalent to the +.BR W +command. +.SS "Move to Beginning of Bigword" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR W +.fi \fR +.P +.RE +.RE +.P +If the edit buffer is empty, it shall be an error. If there are less +than +.IR count +bigwords between the cursor and the end of the edit buffer, +.IR count +shall be adjusted to move the cursor to the last bigword in the edit +buffer. +.P +If used as a motion command: +.IP " 1." 4 +If the associated command is +.BR c , +.IR count +is 1, and the cursor is on a +, +the region of text shall be the current character and no further action +shall be taken. +.IP " 2." 4 +If there are less than +.IR count +bigwords between the cursor and the end of the edit buffer, then the +command shall succeed, and the region of text shall include the last +character of the edit buffer. +.IP " 3." 4 +If there are + +characters or an end-of-line that precede the +.IR count th +bigword, and the associated command is +.BR c , +the region of text shall be up to and including the last character +before the preceding + +characters or end-of-line. +.IP " 4." 4 +If there are + +characters or an end-of-line that precede the bigword, and the associated +command is +.BR d +or +.BR y , +the region of text shall be up to and including the last + +before the start of the bigword or end-of-line. +.IP " 5." 4 +Any text copied to a buffer shall be in character mode. +.P +If not used as a motion command: +.IP " 1." 4 +If the cursor is on the last character of the edit buffer, it shall be +an error. +.P +.IR "Current line" : +Set to the line containing the current column. +.P +.IR "Current column" : +Set to the last column in which any part of the first character of the +.IR count th +next bigword is displayed. +.SS "Delete Character at Cursor" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB][\fIcount\fB]\fR x +.fi \fR +.P +.RE +.RE +.P +Delete the +.IR count +characters at and after the current character into +.IR buffer , +if specified, and into the unnamed buffer. +.P +If the line is empty, it shall be an error. If there are less than +.IR count +non-\c + +characters at and after the cursor on the current line, +.IR count +shall be adjusted to the number of non-\c + +characters at and after the cursor. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +If the line is empty, set to column position 1. Otherwise, if there +were +.IR count +or less non-\c + +characters at and after the cursor on the current line, set to the last +column that displays any part of the last non-\c + +of the line. Otherwise, unchanged. +.SS "Delete Character Before Cursor" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB][\fIcount\fB]\fR X +.fi \fR +.P +.RE +.RE +.P +Delete the +.IR count +characters before the current character into +.IR buffer , +if specified, and into the unnamed buffer. +.P +If there are no characters before the current character on the current +line, it shall be an error. If there are less than +.IR count +previous characters on the current line, +.IR count +shall be adjusted to the number of previous characters on the line. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Set to (current column \(mi the width of the deleted characters). +.SS "Yank" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB][\fIcount\fB]\fR y \fImotion\fR +.fi \fR +.P +.RE +.RE +.P +Copy (yank) the region of text into +.IR buffer , +if specified, and into the unnamed buffer. +.P +If the motion command is the +.BR y +command repeated: +.IP " 1." 4 +The buffer shall be in line mode. +.IP " 2." 4 +If there are less than +.IR count +\(mi1 lines after the current line in the edit buffer, it shall be an +error. +.IP " 3." 4 +The text region shall be from the current line up to and including the +next +.IR count +\(mi1 lines. +.P +Otherwise, the buffer text mode and text region shall be as specified +by the motion command. +.P +.IR "Current line" : +If the motion was from the current cursor position toward the end of +the edit buffer, unchanged. Otherwise, set to the first line in the +edit buffer that is part of the text region specified by the +motion command. +.P +.IR "Current column" : +.IP " 1." 4 +If the motion was from the current cursor position toward the end of +the edit buffer, unchanged. +.IP " 2." 4 +Otherwise, if the current line is empty, set to column position 1. +.IP " 3." 4 +Otherwise, set to the last column that displays any part of the first +character in the file that is part of the text region specified by the +motion command. +.SS "Yank Current Line" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB][\fIcount\fB]\fR Y +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the +.IR vi +command: +.sp +.RS 4 +.nf +\fB +\fB[\fIbuffer\fB][\fIcount\fB]\fR y_ +.fi \fR +.P +.RE +.SS "Redraw Window" +.P +If in open mode, the +.BR z +command shall have the Synopsis: +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIcount\fB]\fR z +.fi \fR +.P +.RE +.RE +.P +If +.IR count +is not specified, it shall default to the +.BR window +edit option \(mi1. The +.BR z +command shall be equivalent to the +.IR ex +.BR z +command, with a type character of +.BR = +and a +.IR count +of +.IR count +\(mi2, except that the current line and current column shall be set as +follows, and the +.BR window +edit option shall not be affected. If the calculation for the +.IR count +argument would result in a negative number, the +.IR count +argument to the +.IR ex +.BR z +command shall be zero. A blank line shall be written after the last +line is written. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.P +If not in open mode, the +.BR z +command shall have the following Synopsis: +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +\fB[\fIline\fB]\fR z \fB[\fIcount\fB] \fIcharacter\fR +.fi \fR +.P +.RE +.RE +.P +If +.IR line +is not specified, it shall default to the current line. If +.IR line +is specified, but is greater than the number of lines in the edit +buffer, it shall default to the number of lines in the edit buffer. +.P +If +.IR count +is specified, the value of the +.BR window +edit option shall be set to +.IR count +(as described in the +.IR ex +.BR window +command), and the screen shall be redrawn. +.P +.IR line +shall be placed as specified by the following characters: +.IP ",\ " 6 +.br +Place the beginning of the line on the first line of the display. +.IP "\fR.\fP" 6 +Place the beginning of the line in the center of the display. The +middle line of the display shall be calculated as described for the +.BR M +command. +.IP "\fR\(mi\fP" 6 +Place an unspecified portion of the line on the last line of the +display. +.IP "\fR+\fP" 6 +If +.IR line +was specified, equivalent to the + +case. If +.IR line +was not specified, display a screen where the first line of the display +shall be (current last line) +1. If there are no lines after the last +line in the display, it shall be an error. +.IP "\fR^\fP" 6 +If +.IR line +was specified, display a screen where the last line of the display +shall contain an unspecified portion of the first line of a display +that had an unspecified portion of the specified line on the last line +of the display. If this calculation results in a line before the +beginning of the edit buffer, display the first screen of the edit +buffer. +.RS 6 +.P +Otherwise, display a screen where the last line of the display shall +contain an unspecified portion of (current first line \(mi1). If this +calculation results in a line before the beginning of the edit buffer, +it shall be an error. +.RE +.br +.P +.IR "Current line" : +If +.IR line +and the +.BR '^' +character were specified: +.IP " 1." 4 +If the first screen was displayed as a result of the command attempting +to display lines before the beginning of the edit buffer: if the first +screen was already displayed, unchanged; otherwise, set to (current +first line \(mi1). +.IP " 2." 4 +Otherwise, set to the last line of the display. +.P +If +.IR line +and the +.BR '\(pl' +character were specified, set to the first line of the display. +.P +Otherwise, if +.IR line +was specified, set to +.IR line . +.P +Otherwise, unchanged. +.P +.IR "Current column" : +Set to non-\c +. +.SS "Exit" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +ZZ +.fi \fR +.P +.RE +.RE +.P +This command shall be equivalent to the +.IR ex +.BR xit +command with no addresses, trailing +.BR ! , +or filename (see the +.IR ex +.BR xit +command). +.SS "Input Mode Commands in vi" +.P +In text input mode, the current line shall consist of zero or more of +the following categories, plus the terminating +: +.IP " 1." 4 +Characters preceding the text input entry point +.RS 4 +.P +Characters in this category shall not be modified during text input +mode. +.RE +.IP " 2." 4 +.BR autoindent +characters +.RS 4 +.P +.BR autoindent +characters shall be automatically inserted into each line that is +created in text input mode, either as a result of entering a + +or + +while in text input mode, or as an effect of the command itself; for +example, +.BR O +or +.BR o +(see the +.IR ex +.BR autoindent +command), as if entered by the user. +.P +It shall be possible to erase +.BR autoindent +characters with the +\(hyD +command; it is unspecified whether they can be erased by +\(hyH, +\(hyU, +and +\(hyW +characters. Erasing any +.BR autoindent +character turns the glyph into erase-columns and deletes the character +from the edit buffer, but does not change its representation on the +screen. +.RE +.IP " 3." 4 +Text input characters +.RS 4 +.P +Text input characters are the characters entered by the user. Erasing +any text input character turns the glyph into erase-columns and deletes +the character from the edit buffer, but does not change its +representation on the screen. +.P +Each text input character entered by the user (that does not have a +special meaning) shall be treated as follows: +.IP " a." 4 +The text input character shall be appended to the last character in the +edit buffer from the first, second, or third categories. +.IP " b." 4 +If there are no erase-columns on the screen, the text input command was +the +.BR R +command, and characters in the fifth category from the original line +follow the cursor, the next such character shall be deleted from the +edit buffer. If the +.BR slowopen +edit option is not set, the corresponding glyph on the screen shall +become erase-columns. +.IP " c." 4 +If there are erase-columns on the screen, as many columns as they +occupy, or as are necessary, shall be overwritten to display the text +input character. (If only part of a multi-column glyph is overwritten, +the remainder shall be left on the screen, and continue to be treated +as erase-columns; it is unspecified whether the remainder of the glyph +is modified in any way.) +.IP " d." 4 +If additional display line columns are needed to display the text input +character: +.RS 4 +.IP " i." 5 +If the +.BR slowopen +edit option is set, the text input characters shall be displayed on +subsequent display line columns, overwriting any characters displayed +in those columns. +.IP ii. 5 +Otherwise, any characters currently displayed on or after the column on +the display line where the text input character is to be displayed +shall be pushed ahead the number of display line columns necessary to +display the rest of the text input character. +.RE +.RE +.IP " 4." 4 +Erase-columns +.RS 4 +.P +Erase-columns are not logically part of the edit buffer, appearing only +on the screen, and may be overwritten on the screen by subsequent text +input characters. When text input mode ends, all erase-columns shall no +longer appear on the screen. +.P +Erase-columns are initially the region of text specified by the +.BR c +command (see +.IR "Change"); +however, erasing +.BR autoindent +or text input characters causes the glyphs of the erased characters to +be treated as erase-columns. +.RE +.IP " 5." 4 +Characters following the text region for the +.BR c +command, or the text input entry point for all other commands +.RS 4 +.P +Characters in this category shall not be modified during text input +mode, except as specified in category 3.b. for the +.BR R +text input command, or as + +characters deleted when a + +or + +is entered. +.RE +.P +It is unspecified whether it is an error to attempt to erase past the +beginning of a line that was created by the entry of a + +or + +during text input mode. If it is not an error, the editor shall behave +as if the erasing character was entered immediately after the last text +input character entered on the previous line, and all of the non-\c + +characters on the current line shall be treated as erase-columns. +.P +When text input mode is entered, or after a text input mode character +is entered (except as specified for the special characters below), the +cursor shall be positioned as follows: +.IP " 1." 4 +On the first column that displays any part of the first erase-column, +if one exists +.IP " 2." 4 +Otherwise, if the +.BR slowopen +edit option is set, on the first display line column after the last +character in the first, second, or third categories, if one exists +.IP " 3." 4 +Otherwise, the first column that displays any part of the first +character in the fifth category, if one exists +.IP " 4." 4 +Otherwise, the display line column after the last character in the +first, second, or third categories, if one exists +.IP " 5." 4 +Otherwise, on column position 1 +.P +The characters that are updated on the screen during text input mode +are unspecified, other than that the last text input character shall +always be updated, and, if the +.BR slowopen +edit option is not set, the current cursor character shall always be +updated. +.P +The following specifications are for command characters entered during +text input mode. +.SS "NUL" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +NUL +.fi \fR +.P +.RE +.RE +.P +If the first character of the text input is a NUL, the most recently +input text shall be input as if entered by the user, and then text +input mode shall be exited. The text shall be input literally; that is, +characters are neither macro or abbreviation expanded, nor are any +characters interpreted in any special manner. It is unspecified whether +implementations shall support more than 256 bytes of remembered input +text. +.SS "-D" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +-D +.fi \fR +.P +.RE +.RE +.P +The +\(hyD +character shall have no special meaning when in text input +mode for a line-oriented command (see +.IR "Command Descriptions in vi"). +.P +This command need not be supported on block-mode terminals. +.P +If the cursor does not follow an +.BR autoindent +character, or an +.BR autoindent +character and a +.BR '0' +or +.BR '^' +character: +.IP " 1." 4 +If the cursor is in column position 1, the +\(hyD +character shall be discarded and no further action taken. +.IP " 2." 4 +Otherwise, the +\(hyD +character shall have no special meaning. +.P +If the last input character was a +.BR '0' , +the cursor shall be moved to column position 1. +.P +Otherwise, if the last input character was a +.BR '^' , +the cursor shall be moved to column position 1. In addition, the +.BR autoindent +level for the next input line shall be derived from the same line from +which the +.BR autoindent +level for the current input line was derived. +.P +Otherwise, the cursor shall be moved back to the column after the +previous shiftwidth (see the +.IR ex +.BR shiftwidth +command) boundary. +.P +All of the glyphs on columns between the starting cursor position and +(inclusively) the ending cursor position shall become erase-columns as +described in +.IR "Input Mode Commands in vi". +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Set to 1 if the +\(hyD +was preceded by a +.BR '^' +or +.BR '0' ; +otherwise, set to (column \(mi1) \(mi((column \(mi2) % +.BR shiftwidth ). +.SS "-H" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +-H +.fi \fR +.P +.RE +.RE +.P +If in text input mode for a line-oriented command, and there are no +characters to erase, text input mode shall be terminated, no further +action shall be done for this command, and the current line and column +shall be unchanged. +.P +If there are characters other than +.BR autoindent +characters that have been input on the current line before the cursor, +the cursor shall move back one character. +.P +Otherwise, if there are +.BR autoindent +characters on the current line before the cursor, it is +implementation-defined whether the +\(hyH +command is an error or if the cursor moves back one +.BR autoindent +character. +.P +Otherwise, if the cursor is in column position 1 and there are previous +lines that have been input, it is implementation-defined whether the +\(hyH +command is an error or if it is equivalent to entering +\(hyH +after the last input character on the previous input line. +.P +Otherwise, it shall be an error. +.P +All of the glyphs on columns between the starting cursor position and +(inclusively) the ending cursor position shall become erase-columns as +described in +.IR "Input Mode Commands in vi". +.P +The current erase character (see +.IR stty ) +shall cause an equivalent action to the +\(hyH +command, unless the previously inserted character was a +, +in which case it shall be as if the literal current erase character had +been inserted instead of the +. +.P +.IR "Current line" : +Unchanged, unless previously input lines are erased, in which case it +shall be set to line \(mi1. +.P +.IR "Current column" : +Set to the first column that displays any portion of the character +backed up over. +.SS "" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB + +.br + +.br +-J +.br +-M +.fi \fR +.P +.RE +.RE +.P +If input was part of a line-oriented command, text input mode shall be +terminated and the command shall continue execution with the input +provided. +.P +Otherwise, terminate the current line. If there are no characters other +than +.BR autoindent +characters on the line, all characters on the line shall be discarded. +Otherwise, it is unspecified whether the +.BR autoindent +characters in the line are modified by entering these characters. +.P +Continue text input mode on a new line appended after the current line. +If the +.BR slowopen +edit option is set, the lines on the screen below the current line +shall not be pushed down, but the first of them shall be cleared and +shall appear to be overwritten. Otherwise, the lines of the screen +below the current line shall be pushed down. +.P +If the +.BR autoindent +edit option is set, an appropriate number of +.BR autoindent +characters shall be added as a prefix to the line as described by the +.IR ex +.BR autoindent +edit option. +.P +All columns after the cursor that are erase-columns (as described in +.IR "Input Mode Commands in vi") +shall be discarded. +.P +If the +.BR autoindent +edit option is set, all + +characters immediately following the cursor shall be discarded. +.P +All remaining characters after the cursor shall be transferred to the +new line, positioned after any +.BR autoindent +characters. +.P +.IR "Current line" : +Set to current line +1. +.P +.IR "Current column" : +Set to the first column that displays any portion of the first +character after the +.BR autoindent +characters on the new line, if any, or the first column position after +the last +.BR autoindent +character, if any, or column position 1. +.SS "-T" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +-T +.fi \fR +.P +.RE +.RE +.P +The +\(hyT +character shall have no special meaning when in text input mode for a +line-oriented command (see +.IR "Command Descriptions in vi"). +.P +This command need not be supported on block-mode terminals. +.P +Behave as if the user entered the minimum number of + +characters necessary to move the cursor forward to the column position +after the next +.BR shiftwidth +(see the +.IR ex +.BR shiftwidth +command) boundary. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Set to +.IR column ++ +.BR shiftwidth +\(mi ((column \(mi1) % +.BR shiftwidth ). +.SS "-U" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +-U +.fi \fR +.P +.RE +.RE +.P +If there are characters other than +.BR autoindent +characters that have been input on the current line before the cursor, +the cursor shall move to the first character input after the +.BR autoindent +characters. +.P +Otherwise, if there are +.BR autoindent +characters on the current line before the cursor, it is +implementation-defined whether the +\(hyU +command is an error or if the cursor moves to the first column position +on the line. +.P +Otherwise, if the cursor is in column position 1 and there are previous +lines that have been input, it is implementation-defined whether the +\(hyU +command is an error or if it is equivalent to entering +\(hyU +after the last input character on the previous input line. +.P +Otherwise, it shall be an error. +.P +All of the glyphs on columns between the starting cursor position and +(inclusively) the ending cursor position shall become erase-columns as +described in +.IR "Input Mode Commands in vi". +.P +The current +.IR kill +character (see +.IR stty ) +shall cause an equivalent action to the +\(hyU +command, unless the previously inserted character was a +, +in which case it shall be as if the literal current +.IR kill +character had been inserted instead of the +. +.P +.IR "Current line" : +Unchanged, unless previously input lines are erased, in which case it +shall be set to line \(mi1. +.P +.IR "Current column" : +Set to the first column that displays any portion of the last character +backed up over. +.SS "-V" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +-V +.br +-Q +.fi \fR +.P +.RE +.RE +.P +Allow the entry of any subsequent character, other than +\(hyJ +or the +, +as a literal character, removing any special meaning that it may have +to the editor in text input mode. If a +\(hyV +or +\(hyQ +is entered before a +\(hyJ +or +, +the +\(hyV +or +\(hyQ +character shall be discarded, and the +\(hyJ +or + +shall behave as described in the + +command character during input mode. +.P +For purposes of the display only, the editor shall behave as if a +.BR '^' +character was entered, and the cursor shall be positioned as if +overwriting the +.BR '^' +character. When a subsequent character is entered, the editor shall +behave as if that character was entered instead of the original +\(hyV +or +\(hyQ +character. +.P +.IR "Current line" : +Unchanged. +.P +.IR "Current column" : +Unchanged. +.SS "-W" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB +-W +.fi \fR +.P +.RE +.RE +.P +If there are characters other than +.BR autoindent +characters that have been input on the current line before the cursor, +the cursor shall move back over the last word preceding the cursor +(including any + +characters between the end of the last word and the current cursor); the +cursor shall not move to before the first character after the end of any +.BR autoindent +characters. +.P +Otherwise, if there are +.BR autoindent +characters on the current line before the cursor, it is +implementation-defined whether the +\(hyW +command is an error or if the cursor moves to the first column position +on the line. +.P +Otherwise, if the cursor is in column position 1 and there are previous +lines that have been input, it is implementation-defined whether the +\(hyW +command is an error or if it is equivalent to entering +\(hyW +after the last input character on the previous input line. +.P +Otherwise, it shall be an error. +.P +All of the glyphs on columns between the starting cursor position and +(inclusively) the ending cursor position shall become erase-columns as +described in +.IR "Input Mode Commands in vi". +.P +.IR "Current line" : +Unchanged, unless previously input lines are erased, in which case it +shall be set to line \(mi1. +.P +.IR "Current column" : +Set to the first column that displays any portion of the last character +backed up over. +.SS "" +.IP "\fISynopsis\fR:" 10 +.sp -1v +.RS 10 +.sp +.RS 4 +.nf +\fB + +.fi \fR +.P +.RE +.RE +.P +If input was part of a line-oriented command: +.IP " 1." 4 +If +.IR interrupt +was entered, text input mode shall be terminated and the editor shall +return to command mode. The terminal shall be alerted. +.IP " 2." 4 +If + +was entered, text input mode shall be terminated and the command shall +continue execution with the input provided. +.P +Otherwise, terminate text input mode and return to command mode. +.P +Any +.BR autoindent +characters entered on newly created lines that have no other non-\c + +characters shall be deleted. +.P +Any leading +.BR autoindent +and + +characters on newly created lines shall be rewritten to be the minimum +number of + +characters possible. +.P +The screen shall be redisplayed as necessary to match the contents of +the edit buffer. +.P +.IR "Current line" : +Unchanged. +.br +.P +.IR "Current column" : +.IP " 1." 4 +If there are text input characters on the current line, the column +shall be set to the last column where any portion of the last text +input character is displayed. +.IP " 2." 4 +Otherwise, if a character is displayed in the current column, +unchanged. +.IP " 3." 4 +Otherwise, set to column position 1. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +When any error is encountered and the standard input is not a terminal +device file, +.IR vi +shall not write the file or return to command or text input mode, and +shall terminate with a non-zero exit status. +.P +Otherwise, when an unrecoverable error is encountered it shall be +equivalent to a SIGHUP asynchronous event. +.P +Otherwise, when an error is encountered, the editor shall behave as +specified in +.IR "Command Descriptions in vi". +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +See the RATIONALE for +.IR "\fIex\fR\^" +for more information on +.IR vi . +Major portions of the +.IR vi +utility specification point to +.IR ex +to avoid inadvertent divergence. While +.IR ex +and +.IR vi +have historically been implemented as a single utility, this is not +required by POSIX.1\(hy2008. +.P +It is recognized that portions of +.IR vi +would be difficult, if not impossible, to implement satisfactorily on a +block-mode terminal, or a terminal without any form of cursor +addressing, thus it is not a mandatory requirement that such features +should work on all terminals. It is the intention, however, that a +.IR vi +implementation should provide the full set of capabilities on all +terminals capable of supporting them. +.P +Historically, +.IR vi +exited immediately if the standard input was not a terminal. POSIX.1\(hy2008 +permits, but does not require, this behavior. An end-of-file condition +is not equivalent to an end-of-file character. A common end-of-file +character, +\(hyD, +is historically a +.IR vi +command. +.P +The text in the STDOUT section reflects the usage of the verb +.IR display +in this section; some implementations of +.IR vi +use standard output to write to the terminal, but POSIX.1\(hy2008 does not +require that to be the case. +.P +Historically, implementations reverted to open mode if the terminal was +incapable of supporting full visual mode. POSIX.1\(hy2008 requires this +behavior. Historically, the open mode of +.IR vi +behaved roughly equivalently to the visual mode, with the exception +that only a single line from the edit buffer (one ``buffer line'') was +kept current at any time. This line was normally displayed on the +next-to-last line of a terminal with cursor addressing (and the last +line performed its normal visual functions for line-oriented commands +and messages). In addition, some few commands behaved differently in +open mode than in visual mode. POSIX.1\(hy2008 requires conformance to historical +practice. +.P +Historically, +.IR ex +and +.IR vi +implementations have expected text to proceed in the usual +European/Latin order of left to right, top to bottom. There is no +requirement in POSIX.1\(hy2008 that this be the case. The specification was +deliberately written using words like ``before'', ``after'', ``first'', +and ``last'' in order to permit implementations to support the natural +text order of the language. +.P +Historically, lines past the end of the edit buffer were marked with +single + +(\c +.BR '~' ) +characters; that is, if the one-based display was 20 lines in length, +and the last line of the file was on line one, then lines 2-20 would +contain only a single +.BR '~' +character. +.P +Historically, the +.IR vi +editor attempted to display only complete lines at the bottom of the +screen (it did display partial lines at the top of the screen). If a +line was too long to fit in its entirety at the bottom of the screen, +the screen lines where the line would have been displayed were +displayed as single +.BR '@' +characters, instead of displaying part of the line. POSIX.1\(hy2008 permits, but +does not require, this behavior. Implementations are encouraged to +attempt always to display a complete line at the bottom of the screen +when doing scrolling or screen positioning by buffer lines. +.P +Historically, lines marked with +.BR '@' +were also used to minimize output to dumb terminals over slow lines; +that is, changes local to the cursor were updated, but changes to lines +on the screen that were not close to the cursor were simply marked with +an +.BR '@' +sign instead of being updated to match the current text. POSIX.1\(hy2008 permits, +but does not require this feature because it is used ever less +frequently as terminals become smarter and connections are faster. +.SS "Initialization in ex and vi" +.P +Historically, +.IR vi +always had a line in the edit buffer, even if the edit buffer was +``empty''. For example: +.IP " 1." 4 +The +.IR ex +command +.BR = +executed from visual mode wrote ``1'' when the buffer was empty. +.IP " 2." 4 +Writes from visual mode of an empty edit buffer wrote files of a single +character (a +), +while writes from +.IR ex +mode of an empty edit buffer wrote empty files. +.IP " 3." 4 +Put and read commands into an empty edit buffer left an empty line at +the top of the edit buffer. +.P +For consistency, POSIX.1\(hy2008 does not permit any of these behaviors. +.P +Historically, +.IR vi +did not always return the terminal to its original modes; for example, +ICRNL was modified if it was not originally set. POSIX.1\(hy2008 does not permit +this behavior. +.SS "Command Descriptions in vi" +.P +Motion commands are among the most complicated aspects of +.IR vi +to describe. With some exceptions, the text region and buffer type +effect of a motion command on a +.IR vi +command are described on a case-by-case basis. The descriptions of text +regions in POSIX.1\(hy2008 are not intended to imply direction; that is, an +inclusive region from line +.IR n +to line +.IR n +5 +is identical to a region from line +.IR n +5 +to line +.IR n . +This is of more than academic interest\(emmovements to marks can be in +either direction, and, if the +.BR wrapscan +option is set, so can movements to search points. Historically, lines +are always stored into buffers in text order; that is, from the start +of the edit buffer to the end. POSIX.1\(hy2008 requires conformance to historical +practice. +.P +Historically, command counts were applied to any associated motion, and +were multiplicative to any supplied motion count. For example, +.BR 2cw +is the same as +.BR c2w , +and +.BR 2c3w +is the same as +.BR c6w . +POSIX.1\(hy2008 requires this behavior. Historically, +.IR vi +commands that used bigwords, words, paragraphs, and sentences as +objects treated groups of empty lines, or lines that contained only + +characters, inconsistently. Some commands treated them as a single entity, +while others treated each line separately. For example, the +.BR w , +.BR W , +and +.BR B +commands treated groups of empty lines as individual words; that is, +the command would move the cursor to each new empty line. The +.BR e +and +.BR E +commands treated groups of empty lines as a single word; that is, the +first use would move past the group of lines. The +.BR b +command would just beep at the user, or if done from the start of the +line as a motion command, fail in unexpected ways. If the lines +contained only (or ended with) + +characters, the +.BR w +and +.BR W +commands would just beep at the user, the +.BR E +and +.BR e +commands would treat the group as a single word, and the +.BR B +and +.BR b +commands would treat the lines as individual words. For consistency and +simplicity of specification, POSIX.1\(hy2008 requires that all +.IR vi +commands treat groups of empty or blank lines as a single entity, and +that movement through lines ending with + +characters be consistent with other movements. +.P +Historically, +.IR vi +documentation indicated that any number of double-quotes were skipped +after punctuation marks at sentence boundaries; however, +implementations only skipped single-quotes. POSIX.1\(hy2008 requires both to be +skipped. +.P +Historically, the first and last characters in the edit buffer were +word boundaries. This historical practice is required by POSIX.1\(hy2008. +.P +Historically, +.IR vi +attempted to update the minimum number of columns on the screen +possible, which could lead to misleading information being displayed. +POSIX.1\(hy2008 makes no requirements other than that the current character being +entered is displayed correctly, leaving all other decisions in this +area up to the implementation. +.P +Historically, lines were arbitrarily folded between columns of any +characters that required multiple column positions on the screen, with +the exception of tabs, which terminated at the right-hand margin. POSIX.1\(hy2008 +permits the former and requires the latter. Implementations that do not +arbitrarily break lines between columns of characters that occupy +multiple column positions should not permit the cursor to rest on a +column that does not contain any part of a character. +.P +The historical +.IR vi +had a problem in that all movements were by buffer lines, not by +display or screen lines. This is often the right thing to do; for +example, single line movements, such as +.BR j +or +.BR k , +should work on buffer lines. Commands like +.BR dj , +or +.BR j. , +where +.BR . +is a change command, only make sense for buffer lines. It is not, +however, the right thing to do for screen motion or scrolling commands +like +\(hyD, +\(hyF, +and +.BR H . +If the window is fairly small, using buffer lines in these cases can +result in completely random motion; for example, +.BR 1 \c +\c +.BR \(hyD +can result in a completely changed screen, without any overlap. This is +clearly not what the user wanted. The problem is even worse in the case +of the +.BR H , +.BR L , +and +.BR M +commands\(emas they position the cursor at the first non-\c + +of the line, they may all refer to the same location in large lines, +and will result in no movement at all. +.P +In addition, if the line is larger than the screen, using buffer +lines can make it impossible to display parts of the line\(emthere are +not any commands that do not display the beginning of the line in +historical +.IR vi , +and if both the beginning and end of the line cannot be on the screen +at the same time, the user suffers. Finally, the page and half-page +scrolling commands historically moved to the first non-\c + +in the new line. If the line is approximately the same size as the +screen, this is inadequate because the cursor before and after a +\(hyD +command will refer to the same location on the screen. +.P +Implementations of +.IR ex +and +.IR vi +exist that do not have these problems because the relevant commands (\c +\(hyB, +\(hyD, +\(hyF, +\(hyU, +\(hyY, +\(hyE, +.BR H , +.BR L , +and +.BR M) +operate on display (screen) lines, not (edit) buffer lines. +.P +POSIX.1\(hy2008 does not permit this behavior by default because the standard +developers believed that users would find it too confusing. However, +historical practice has been relaxed. For example, +.IR ex +and +.IR vi +historically attempted, albeit sometimes unsuccessfully, to never put +part of a line on the last lines of a screen; for example, if a line +would not fit in its entirety, no part of the line was displayed, and +the screen lines corresponding to the line contained single +.BR '@' +characters. This behavior is permitted, but not required by POSIX.1\(hy2008, so +that it is possible for implementations to support long lines in small +screens more reasonably without changing the commands to be oriented to +the display (instead of oriented to the buffer). POSIX.1\(hy2008 also permits +implementations to refuse to edit any edit buffer containing a line +that will not fit on the screen in its entirety. +.P +The display area (for example, the value of the +.BR window +edit option) has historically been ``grown'', or expanded, to display +new text when local movements are done in displays where the number of +lines displayed is less than the maximum possible. Expansion has +historically been the first choice, when the target line is less than +the maximum possible expansion value away. Scrolling has historically +been the next choice, done when the target line is less than half a +display away, and otherwise, the screen was redrawn. There were +exceptions, however, in that +.IR ex +commands generally always caused the screen to be redrawn. POSIX.1\(hy2008 does +not specify a standard behavior because there may be external issues, +such as connection speed, the number of characters necessary to redraw +as opposed to scroll, or terminal capabilities that implementations +will have to accommodate. +.P +The current line in POSIX.1\(hy2008 maps one-to-one to a buffer line in the +file. The current column does not. There are two different column +values that are described by POSIX.1\(hy2008. The first is the current column +value as set by many of the +.IR vi +commands. This value is remembered for the lifetime of the editor. The +second column value is the actual position on the screen where the +cursor rests. The two are not always the same. For example, when the +cursor is backed by a multi-column character, the actual cursor +position on the screen has historically been the last column of the +character in command mode, and the first column of the character in +input mode. +.P +Commands that set the current line, but that do not set the current +cursor value (for example, +.BR j +and +.BR k ) +attempt to get as close as possible to the remembered column position, +so that the cursor tends to restrict itself to a vertical column as the +user moves around in the edit buffer. POSIX.1\(hy2008 requires conformance to +historical practice, requiring that the display location of the cursor +on the display line be adjusted from the current column value as +necessary to support this historical behavior. +.P +Historically, only a single line (and for some terminals, a single line +minus 1 column) of characters could be entered by the user for the +line-oriented commands; that is, +.BR : , +.BR ! , +.BR / , +or +.BR ? . +POSIX.1\(hy2008 permits, but does not require, this limitation. +.P +Historically, ``soft'' errors in +.IR vi +caused the terminal to be alerted, but no error message was displayed. +As a general rule, no error message was displayed for errors in command +execution in +.IR vi , +when the error resulted from the user attempting an invalid or +impossible action, or when a searched-for object was not found. +Examples of soft errors included +.BR h +at the left margin, +\(hyB +or +.BR [[ +at the beginning of the file, +.BR 2G +at the end of the file, and so on. In addition, errors such as +.BR % , +.BR ]] , +.BR } , +.BR ) , +.BR N , +.BR n , +.BR f , +.BR F , +.BR t , +and +.BR T +failing to find the searched-for object were soft as well. Less +consistently, +.BR / +and +.BR ? +displayed an error message if the pattern was not found, +.BR / , +.BR ? , +.BR N , +and +.BR n +displayed an error message if no previous regular expression had been +specified, and +.BR ; +did not display an error message if no previous +.BR f , +.BR F , +.BR t , +or +.BR T +command had occurred. Also, behavior in this area might reasonably be +based on a runtime evaluation of the speed of a network connection. +Finally, some implementations have provided error messages for soft +errors in order to assist naive users, based on the value of a verbose +edit option. POSIX.1\(hy2008 does not list specific errors for which an error +message shall be displayed. Implementations should conform to +historical practice in the absence of any strong reason to diverge. +.SS "Page Backwards" +.P +The +\(hyB +and +\(hyF +commands historically considered it an error to attempt to page past +the beginning or end of the file, whereas the +\(hyD +and +\(hyU +commands simply moved to the beginning or end of the file. For +consistency, POSIX.1\(hy2008 requires the latter behavior for all four commands. +All four commands still consider it an error if the current line is at +the beginning (\c +\(hyB, +\(hyU) +or end (\c +\(hyF, +\(hyD) +of the file. Historically, the +\(hyB +and +\(hyF +commands skip two lines in order to include overlapping lines when a +single command is entered. This makes less sense in the presence of a +.IR count , +as there will be, by definition, no overlapping lines. The actual +calculation used by historical implementations of the +.IR vi +editor for +\(hyB +was: +.sp +.RS 4 +.nf +\fB +((current first line) \(mi count x (window edit option)) +2 +.fi \fR +.P +.RE +.P +and for +\(hyF +was: +.sp +.RS 4 +.nf +\fB +((current first line) + count x (window edit option)) \(mi2 +.fi \fR +.P +.RE +.P +This calculation does not work well when intermixing commands with and +without counts; for example, +.BR 3\c +\(hyF +is not equivalent to entering the +\(hyF +command three times, and is not reversible by entering the +\(hyB +command three times. For consistency with other +.IR vi +commands that take counts, POSIX.1\(hy2008 requires a different calculation. +.SS "Scroll Forward" +.P +The 4BSD and System V implementations of +.IR vi +differed on the initial value used by the +.BR scroll +command. 4BSD used: +.sp +.RS 4 +.nf +\fB +((window edit option) +1) /2 +.fi \fR +.P +.RE +.P +while System V used the value of the +.BR scroll +edit option. The System V version is specified by POSIX.1\(hy2008 because the +standard developers believed that it was more intuitive and permitted +the user a method of setting the scroll value initially without also +setting the number of lines that are displayed. +.SS "Scroll Forward by Line" +.P +Historically, the +\(hyE +and +\(hyY +commands considered it an error if the last and first lines, +respectively, were already on the screen. POSIX.1\(hy2008 requires conformance to +historical practice. Historically, the +\(hyE +and +\(hyY +commands had no effect in open mode. For simplicity and consistency of +specification, POSIX.1\(hy2008 requires that they behave as usual, albeit with a +single line screen. +.SS "Clear and Redisplay" +.P +The historical +\(hyL +command refreshed the screen exactly as it was supposed to be currently +displayed, replacing any +.BR '@' +characters for lines that had been deleted but not updated on the +screen with refreshed +.BR '@' +characters. The intent of the +\(hyL +command is to refresh when the screen has been accidentally +overwritten; for example, by a +.BR write +command from another user, or modem noise. +.SS "Redraw Screen" +.P +The historical +\(hyR +command redisplayed only when necessary to update lines that had been +deleted but not updated on the screen and that were flagged with +.BR '@' +characters. There is no requirement that the screen be in any way +refreshed if no lines of this form are currently displayed. POSIX.1\(hy2008 +permits implementations to extend this command to refresh lines on the +screen flagged with +.BR '@' +characters because they are too long to be displayed in the current +framework; however, the current line and column need not be modified. +.SS "Search for tagstring" +.P +Historically, the first non-\c + +at or after the cursor was the first character, and all subsequent +characters that were word characters, up to the end of the line, were +included. For example, with the cursor on the leading + +or on the +.BR '#' +character in the text +.BR \(dq#bar@\(dq , +the tag was +.BR \(dq#bar\(dq . +On the character +.BR 'b' +it was +.BR \(dqbar\(dq , +and on the +.BR 'a' +it was +.BR \(dqar\(dq . +POSIX.1\(hy2008 requires this behavior. +.SS "Replace Text with Results from Shell Command" +.P +Historically, the +.BR < , +.BR > , +and +.BR ! +commands considered most cursor motions other than line-oriented +motions an error; for example, the command +.BR ">/foo" +succeeded, while the command +.BR ">l" +failed, even though the text region described by the two commands might +be identical. For consistency, all three commands only consider entire +lines and not partial lines, and the region is defined as any line that +contains a character that was specified by the motion. +.SS "Move to Matching Character" +.P +Other matching characters have been left implementation-defined in +order to allow extensions such as matching +.BR '<' +and +.BR '>' +for searching HTML, or +.BR #ifdef , +.BR #else , +and +.BR #endif +for searching C source. +.SS "Repeat Substitution" +.P +POSIX.1\(hy2008 requires that any +.BR c +and +.BR g +flags specified to the previous substitute command be ignored; however, +the +.BR r +flag may still apply, if supported by the implementation. +.SS "Return to Previous (Context or Section)" +.P +The +.BR [[ , +.BR ]] , +.BR ( , +.BR ) , +.BR { , +and +.BR } +commands are all affected by ``section boundaries'', but in some +historical implementations not all of the commands recognize the same +section boundaries. This is a bug, not a feature, and a unique +section-boundary algorithm was not described for each command. One +special case that is preserved is that the sentence command moves to +the end of the last line of the edit buffer while the other commands go +to the beginning, in order to preserve the traditional character cut +semantics of the sentence command. Historically, +.IR vi +section boundaries at the beginning and end of the edit buffer were the +first non-\c + +on the first and last lines of the edit buffer if one exists; +otherwise, the last character of the first and last lines of the edit +buffer if one exists. To increase consistency with other section +locations, this has been simplified by POSIX.1\(hy2008 to the first character of +the first and last lines of the edit buffer, or the first and the last +lines of the edit buffer if they are empty. +.P +Sentence boundaries were problematic in the historical +.IR vi . +They were not only the boundaries as defined for the section and +paragraph commands, but they were the first non-\c + +that occurred after those boundaries, as well. Historically, the +.IR vi +section commands were documented as taking an optional window size as a +.IR count +preceding the command. This was not implemented in historical versions, +so POSIX.1\(hy2008 requires that the +.IR count +repeat the command, for consistency with other +.IR vi +commands. +.SS "Repeat" +.P +Historically, mapped commands other than text input commands could not +be repeated using the +.BR period +command. POSIX.1\(hy2008 requires conformance to historical practice. +.P +The restrictions on the interpretation of special characters (for +example, +\(hyH) +in the repetition of text input mode commands is intended to match +historical practice. For example, given the input sequence: +.sp +.RS 4 +.nf +\fB +iab-H-H-Hdef +.fi \fR +.P +.RE +.P +the user should be informed of an error when the sequence is first +entered, but not during a command repetition. The character +\(hyT +is specifically exempted from this restriction. Historical +implementations of +.IR vi +ignored +\(hyT +characters that were input in the original command during command +repetition. POSIX.1\(hy2008 prohibits this behavior. +.SS "Find Regular Expression" +.P +Historically, commands did not affect the line searched to or from if +the motion command was a search (\c +.BR / , +.BR ? , +.BR N , +.BR n ) +and the final position was the start/end of the line. There were some +special cases and +.IR vi +was not consistent. POSIX.1\(hy2008 does not permit this behavior, for +consistency. Historical implementations permitted but were unable to +handle searches as motion commands that wrapped (that is, due to the +edit option +.BR wrapscan ) +to the original location. POSIX.1\(hy2008 requires that this behavior be treated +as an error. +.P +Historically, the syntax +.BR \(dq/RE/0\(dq +was used to force the command to cut text in line mode. POSIX.1\(hy2008 requires +conformance to historical practice. +.P +Historically, in open mode, a +.BR z +specified to a search command redisplayed the current line instead of +displaying the current screen with the current line highlighted. For +consistency and simplicity of specification, POSIX.1\(hy2008 does not permit this +behavior. +.P +Historically, trailing +.BR z +commands were permitted and ignored if entered as part of a search used +as a motion command. For consistency and simplicity of specification, +POSIX.1\(hy2008 does not permit this behavior. +.SS "Execute an ex Command" +.P +Historically, +.IR vi +implementations restricted the commands that could be entered on the +colon command line (for example, +.BR append +and +.BR change ), +and some other commands were known to cause them to fail +catastrophically. For consistency, POSIX.1\(hy2008 does not permit these +restrictions. When executing an +.IR ex +command by entering +.BR : , +it is not possible to enter a + +as part of the command because it is considered the end of the command. +A different approach is to enter +.IR ex +command mode by using the +.IR vi +.BR Q +command (and later resuming visual mode with the +.IR ex +.BR vi +command). In +.IR ex +command mode, the single-line limitation does not exist. So, for +example, the following is valid: +.sp +.RS 4 +.nf +\fB +Q +s/break here/break\e +here/ +vi +.fi \fR +.P +.RE +.P +POSIX.1\(hy2008 requires that, if the +.IR ex +command overwrites any part of the screen that would be erased by a +refresh, +.IR vi +pauses for a character from the user. Historically, this character +could be any character; for example, a character input by the user +before the message appeared, or even a mapped character. This is +probably a bug, but implementations that have tried to be more rigorous +by requiring that the user enter a specific character, or that the user +enter a character after the message was displayed, have been forced by +user indignation back into historical behavior. POSIX.1\(hy2008 requires +conformance to historical practice. +.SS "Shift Left (Right)" +.P +Refer to the Rationale for the +.BR ! +and +.BR / +commands. Historically, the +.BR < +and +.BR > +commands sometimes moved the cursor to the first non-\c + +(for example if the command was repeated or with +.BR _ +as the motion command), and sometimes left it unchanged. POSIX.1\(hy2008 does not +permit this inconsistency, requiring instead that the cursor always +move to the first non-\c +. +Historically, the +.BR < +and +.BR > +commands did not support buffer arguments, although some +implementations allow the specification of an optional buffer. This +behavior is neither required nor disallowed by POSIX.1\(hy2008. +.SS "Execute" +.P +Historically, buffers could execute other buffers, and loops, infinite +and otherwise, were possible. POSIX.1\(hy2008 requires conformance to historical +practice. The *\c +.IR buffer +syntax of +.IR ex +is not required in +.IR vi , +because it is not historical practice and has been used in some +.IR vi +implementations to support additional scripting languages. +.SS "Reverse Case" +.P +Historically, the +.BR ~ +command ignored any associated +.IR count , +and acted only on the characters in the current line. For consistency +with other +.IR vi +commands, POSIX.1\(hy2008 requires that an associated +.IR count +act on the next +.IR count +characters, and that the command move to subsequent lines if warranted +by +.IR count , +to make it possible to modify large pieces of text in a reasonably +efficient manner. There exist +.IR vi +implementations that optionally require an associated motion command +for the +.BR ~ +command. Implementations supporting this functionality are encouraged +to base it on the +.BR tildedop +edit option and handle the text regions and cursor positioning +identically to the +.BR yank +command. +.SS "Append" +.P +Historically, +.IR count s +specified to the +.BR A , +.BR a , +.BR I , +and +.BR i +commands repeated the input of the first line +.IR count +times, and did not repeat the subsequent lines of the input text. POSIX.1\(hy2008 +requires that the entire text input be repeated +.IR count +times. +.SS "Move Backward to Preceding Word" +.P +Historically, +.IR vi +became confused if word commands were used as motion commands in empty +files. POSIX.1\(hy2008 requires that this be an error. Historical implementations +of +.IR vi +had a large number of bugs in the word movement commands, and they +varied greatly in behavior in the presence of empty lines, ``words'' +made up of a single character, and lines containing only + +characters. For consistency and simplicity of specification, POSIX.1\(hy2008 does +not permit this behavior. +.SS "Change to End-of-Line" +.P +Some historical implementations of the +.BR C +command did not behave as described by POSIX.1\(hy2008 when the +.BR $ +key was remapped because they were implemented by pushing the +.BR $ +key onto the input queue and reprocessing it. POSIX.1\(hy2008 does not permit +this behavior. Historically, the +.BR C , +.BR S , +and +.BR s +commands did not copy replaced text into the numeric buffers. For +consistency and simplicity of specification, POSIX.1\(hy2008 requires that they +behave like their respective +.BR c +commands in all respects. +.SS "Delete" +.P +Historically, lines in open mode that were deleted were scrolled up, +and an +.BR @ +glyph written over the beginning of the line. In the case of terminals +that are incapable of the necessary cursor motions, the editor erased +the deleted line from the screen. POSIX.1\(hy2008 requires conformance to +historical practice; that is, if the terminal cannot display the +.BR '@' +character, the line cannot remain on the screen. +.SS "Delete to End-of-Line" +.P +Some historical implementations of the +.BR D +command did not behave as described by POSIX.1\(hy2008 when the +.BR $ +key was remapped because they were implemented by pushing the +.BR $ +key onto the input queue and reprocessing it. POSIX.1\(hy2008 does not permit +this behavior. +.SS "Join" +.P +An historical oddity of +.IR vi +is that the commands +.BR J , +.BR 1J , +and +.BR 2J +are all equivalent. POSIX.1\(hy2008 requires conformance to historical practice. +The +.IR vi +.BR J +command is specified in terms of the +.IR ex +.BR join +command with an +.IR ex +command +.IR count +value. The address correction for a +.IR count +that is past the end of the edit buffer is necessary for historical +compatibility for both +.IR ex +and +.IR vi . +.SS "Mark Position" +.P +Historical practice is that only lowercase letters, plus backquote and +single-quote, could be used to mark a cursor position. POSIX.1\(hy2008 requires +conformance to historical practice, but encourages implementations to +support other characters as marks as well. +.SS "Repeat Regular Expression Find (Forward and Reverse)" +.P +Historically, the +.BR N +and +.BR n +commands could not be used as motion components for the +.BR c +command. With the exception of the +.BR cN +command, which worked if the search crossed a line boundary, the text +region would be discarded, and the user would not be in text input +mode. For consistency and simplicity of specification, POSIX.1\(hy2008 does not +permit this behavior. +.SS "Insert Empty Line (Below and Above)" +.P +Historically, counts to the +.BR O +and +.BR o +commands were used as the number of physical lines to open, if the +terminal was dumb and the +.BR slowopen +option was not set. This was intended to minimize traffic over slow +connections and repainting for dumb terminals. POSIX.1\(hy2008 does not permit +this behavior, requiring that a +.IR count +to the open command behave as for other text input commands. This +change to historical practice was made for consistency, and because a +superset of the functionality is provided by the +.BR slowopen +edit option. +.SS "Put from Buffer (Following and Before)" +.P +Historically, +.IR count s +to the +.BR p +and +.BR P +commands were ignored if the buffer was a line mode buffer, but were +(mostly) implemented as described in POSIX.1\(hy2008 if the buffer was a +character mode buffer. Because implementations exist that do not have +this limitation, and because pasting lines multiple times is generally +useful, POSIX.1\(hy2008 requires that +.IR count +be supported for all +.BR p +and +.BR P +commands. +.P +Historical implementations of +.IR vi +were widely known to have major problems in the +.BR p +and +.BR P +commands, particularly when unusual regions of text were copied into +the edit buffer. The standard developers viewed these as bugs, and they +are not permitted for consistency and simplicity of specification. +.P +Historically, a +.BR P +or +.BR p +command (or an +.IR ex +.BR put +command executed from open or visual mode) executed in an empty file, +left an empty line as the first line of the file. For consistency and +simplicity of specification, POSIX.1\(hy2008 does not permit this behavior. +.SS "Replace Character" +.P +Historically, the +.BR r +command did not correctly handle the +.IR erase +and +.IR "word erase" +characters as arguments, nor did it handle an associated +.IR count +greater than 1 with a + +argument, for which it replaced +.IR count +characters with a single +. +POSIX.1\(hy2008 does not permit these inconsistencies. +.P +Historically, the +.BR r +command permitted the +\(hyV +escaping of entered characters, such as + +and the +; +however, it required two leading +\(hyV +characters instead of one. POSIX.1\(hy2008 requires that this be changed for +consistency with the other text input commands of +.IR vi . +.P +Historically, it is an error to enter the +.BR r +command if there are less than +.IR count +characters at or after the cursor in the line. While a reasonable and +unambiguous extension would be to permit the +.BR r +command on empty lines, it would require that too large a +.IR count +be adjusted to match the number of characters at or after the cursor +for consistency, which is sufficiently different from historical +practice to be avoided. POSIX.1\(hy2008 requires conformance to historical +practice. +.SS "Replace Characters" +.P +Historically, if there were +.BR autoindent +characters in the line on which the +.BR R +command was run, and +.BR autoindent +was set, the first + +would be properly indented and no characters would be replaced by the +. +Each additional + +would replace +.IR n +characters, where +.IR n +was the number of characters that were needed to indent the rest of the +line to the proper indentation level. This behavior is a bug and is not +permitted by POSIX.1\(hy2008. +.SS "Undo" +.P +Historical practice for cursor positioning after undoing commands was +mixed. In most cases, when undoing commands that affected a single +line, the cursor was moved to the start of added or changed text, or +immediately after deleted text. However, if the user had moved from the +line being changed, the column was either set to the first non-\c +, +returned to the origin of the command, or remained unchanged. When +undoing commands that affected multiple lines or entire lines, the +cursor was moved to the first character in the first line restored. As +an example of how inconsistent this was, a search, followed by an +.BR o +text input command, followed by an +.BR undo +would return the cursor to the location where the +.BR o +command was entered, but a +.BR cw +command followed by an +.BR o +command followed by an +.BR undo +would return the cursor to the first non-\c + +of the line. POSIX.1\(hy2008 requires the most useful of these behaviors, and +discards the least useful, in the interest of consistency and +simplicity of specification. +.SS "Yank" +.P +Historically, the +.BR yank +command did not move to the end of the motion if the motion was in the +forward direction. It moved to the end of the motion if the motion was +in the backward direction, except for the +.BR _ +command, or for the +.BR G +and +.BR ' +commands when the end of the motion was on the current line. This was +further complicated by the fact that for a number of motion commands, +the +.BR yank +command moved the cursor but did not update the screen; for example, a +subsequent command would move the cursor from the end of the motion, +even though the cursor on the screen had not reflected the cursor +movement for the +.BR yank +command. POSIX.1\(hy2008 requires that all +.BR yank +commands associated with backward motions move the cursor to the end of +the motion for consistency, and specifically, to make +.BR ' +commands as motions consistent with search patterns as motions. +.SS "Yank Current Line" +.P +Some historical implementations of the +.BR Y +command did not behave as described by POSIX.1\(hy2008 when the +.BR '_' +key was remapped because they were implemented by pushing the +.BR '_' +key onto the input queue and reprocessing it. POSIX.1\(hy2008 does not permit +this behavior. +.SS "Redraw Window" +.P +Historically, the +.BR z +command always redrew the screen. This is permitted but not required by +POSIX.1\(hy2008, because of the frequent use of the +.BR z +command in macros such as +.BR "map n nz." +for screen positioning, instead of its use to change the screen size. +The standard developers believed that expanding or scrolling the screen +offered a better interface for users. The ability to redraw the screen +is preserved if the optional new window size is specified, and in the +\(hyL +and +\(hyR +commands. +.P +The semantics of +.BR z^ +are confusing at best. Historical practice is that the screen before +the screen that ended with the specified line is displayed. POSIX.1\(hy2008 +requires conformance to historical practice. +.P +Historically, the +.BR z +command would not display a partial line at the top or bottom of the +screen. If the partial line would normally have been displayed at the +bottom of the screen, the command worked, but the partial line was +replaced with +.BR '@' +characters. If the partial line would normally have been displayed at +the top of the screen, the command would fail. For consistency and +simplicity of specification, POSIX.1\(hy2008 does not permit this behavior. +.P +Historically, the +.BR z +command with a line specification of 1 ignored the command. For +consistency and simplicity of specification, POSIX.1\(hy2008 does not permit this +behavior. +.P +Historically, the +.BR z +command did not set the cursor column to the first non-\c + +for the character if the first screen was to be displayed, and was +already displayed. For consistency and simplicity of specification, +POSIX.1\(hy2008 does not permit this behavior. +.SS "Input Mode Commands in vi" +.P +Historical implementations of +.IR vi +did not permit the user to erase more than a single line of input, +or to use normal erase characters such as +.IR "line erase" , +.IR worderase , +and +.IR erase +to erase +.BR autoindent +characters. As there exist implementations of +.IR vi +that do not have these limitations, both behaviors are permitted, but +only historical practice is required. In the case of these extensions, +.IR vi +is required to pause at the +.BR autoindent +and previous line boundaries. +.P +Historical implementations of +.IR vi +updated only the portion of the screen where the current cursor +character was displayed. For example, consider the +.IR vi +input keystrokes: +.sp +.RS 4 +.nf +\fB +iabcd0C +.fi \fR +.P +.RE +.P +Historically, the + +would overwrite the characters +.BR \(dqabcd\(dq +when it was displayed. Other implementations replace only the +.BR 'a' +character with the +, +and then push the rest of the characters ahead of the cursor. Both +implementations have problems. The historical implementation is +probably visually nicer for the above example; however, for the +keystrokes: +.sp +.RS 4 +.nf +\fB +iabcd0R +.fi \fR +.P +.RE +.P +the historical implementation results in the string +.BR \(dqbcd\(dq +disappearing and then magically reappearing when the + +character is entered. POSIX.1\(hy2008 requires the former behavior when +overwriting erase-columns\(emthat is, overwriting characters that are no +longer logically part of the edit buffer\(emand the latter behavior +otherwise. +.P +Historical implementations of +.IR vi +discarded the +\(hyD +and +\(hyT +characters when they were entered at places where their command +functionality was not appropriate. POSIX.1\(hy2008 requires that the +\(hyT +functionality always be available, and that +\(hyD +be treated as any other key when not operating on +.BR autoindent +characters. +.SS "NUL" +.P +Some historical implementations of +.IR vi +limited the number of characters entered using the NUL input character +to 256 bytes. POSIX.1\(hy2008 permits this limitation; however, implementations +are encouraged to remove this limit. +.SS "\(hyD" +.P +See also Rationale for the input mode command +. +The hidden assumptions in the +\(hyD +command (and in the +.IR vi +.BR autoindent +specification in general) is that + +characters take up a single column on the screen and that + +characters are comprised of an integral number of + +characters. +.SS "" +.P +Implementations are permitted to rewrite +.BR autoindent +characters in the line when +, +, +\(hyD, +and +\(hyT +are entered, or when the +.BR shift +commands are used, because historical implementations have both done so +and found it necessary to do so. For example, a +\(hyD +when the cursor is preceded by a single +, +with +.BR tabstop +set to 8, and +.BR shiftwidth +set to 3, will result in the + +being replaced by several + +characters. +.SS "\(hyT" +.P +See also the Rationale for the input mode command +. +Historically, +\(hyT +only worked if no non-\c + +characters had yet been input in the current input line. In addition, +the characters inserted by +\(hyT +were treated as +.BR autoindent +characters, and could not be erased using normal user erase characters. +Because implementations exist that do not have these limitations, and +as moving to a column boundary is generally useful, POSIX.1\(hy2008 requires that +both limitations be removed. +.SS "\(hyV" +.P +Historically, +.IR vi +used +.BR ^V , +regardless of the value of the literal-next character of the terminal. +POSIX.1\(hy2008 requires conformance to historical practice. +.P +The uses described for +\(hyV +can also be accomplished with +\(hyQ, +which is useful on terminals that use +\(hyV +for the down-arrow function. However, most historical implementations +use +\(hyQ +for the +.IR termios +START character, so the editor will generally not receive the +\(hyQ +unless +.BR "stty ixon" +mode is set to off. (In addition, some historical implementations of +.IR vi +explicitly set +.BR ixon +mode to on, so it was difficult for the user to set it to off.) Any of +the command characters described in POSIX.1\(hy2008 can be made ineffective by +their selection as +.IR termios +control characters, using the +.IR stty +utility or other methods described in the System Interfaces volume of POSIX.1\(hy2008. +.SS "" +.P +Historically, SIGINT alerted the terminal when used to end input +mode. This behavior is permitted, but not required, by POSIX.1\(hy2008. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIed\fR\^", +.IR "\fIex\fR\^", +.IR "\fIstty\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/wait.1p b/man-pages-posix-2013/man1p/wait.1p new file mode 100644 index 0000000..6c7fe6b --- /dev/null +++ b/man-pages-posix-2013/man1p/wait.1p @@ -0,0 +1,346 @@ +'\" et +.TH WAIT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\(em await process completion +.SH SYNOPSIS +.LP +.nf +wait \fB[\fIpid\fR...\fB]\fR +.fi +.SH DESCRIPTION +When an asynchronous list (see +.IR "Section 2.9.3.1" ", " "Examples") +is started by the shell, the process ID of the last command in each +element of the asynchronous list shall become known in the current +shell execution environment; see +.IR "Section 2.12" ", " "Shell Execution Environment". +.P +If the +.IR wait +utility is invoked with no operands, it shall wait until all process +IDs known to the invoking shell have terminated and exit with a zero +exit status. +.P +If one or more +.IR pid +operands are specified that represent known process IDs, the +.IR wait +utility shall wait until all of them have terminated. If one or more +.IR pid +operands are specified that represent unknown process IDs, +.IR wait +shall treat them as if they were known process IDs that exited with +exit status 127. The exit status returned by the +.IR wait +utility shall be the exit status of the process requested by the last +.IR pid +operand. +.P +The known process IDs are applicable only for invocations of +.IR wait +in the current shell execution environment. +.SH OPTIONS +None. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIpid\fR" 10 +One of the following: +.RS 10 +.IP " 1." 4 +The unsigned decimal integer process ID of a command, for which the +utility is to wait for the termination. +.IP " 2." 4 +A job control job ID (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.204" ", " "Job Control Job ID") +that identifies a background process group to be waited for. The job +control job ID notation is applicable only for invocations of +.IR wait +in the current shell execution environment; see +.IR "Section 2.12" ", " "Shell Execution Environment". +The exit status of +.IR wait +shall be determined by the last command in the pipeline. +.RS 4 +.TP 10 +.BR Note: +The job control job ID type of +.IR pid +is only available on systems supporting the User Portability Utilities +option. +.P +.RE +.RE +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR wait : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +If one or more operands were specified, all of them have terminated or +were not known by the invoking shell, and the status of the last +operand specified is known, then the exit status of +.IR wait +shall be the exit status information of the command indicated by the +last operand specified. If the process terminated abnormally due to +the receipt of a signal, the exit status shall be greater than 128 and +shall be distinct from the exit status generated by other signals, but +the exact value is unspecified. (See the +.IR kill +.BR \(mil +option.) Otherwise, the +.IR wait +utility shall exit with one of the following values: +.IP "\0\0\0\00" 8 +The +.IR wait +utility was invoked with no operands and all process IDs known by the +invoking shell have terminated. +.IP "1\(hy126" 8 +The +.IR wait +utility detected an error. +.IP "\0\0127" 8 +The command identified by the last +.IR pid +operand specified is unknown. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +On most implementations, +.IR wait +is a shell built-in. If it is called in a subshell or separate utility +execution environment, such as one of the following: +.sp +.RS 4 +.nf +\fB +(wait) +nohup wait ... +find . \(miexec wait ... \e; +.fi \fR +.P +.RE +.P +it returns immediately because there are no known process IDs to wait +for in those environments. +.P +Historical implementations of interactive shells have discarded the +exit status of terminated background processes before each shell +prompt. Therefore, the status of background processes was usually lost +unless it terminated while +.IR wait +was waiting for it. This could be a serious problem when a job that +was expected to run for a long time actually terminated quickly with a +syntax or initialization error because the exit status returned was +usually zero if the requested process ID was not found. This volume of POSIX.1\(hy2008 requires +the implementation to keep the status of terminated jobs available +until the status is requested, so that scripts like: +.sp +.RS 4 +.nf +\fB +j1& +p1=$! +j2& +wait $p1 +echo Job 1 exited with status $? +wait $! +echo Job 2 exited with status $? +.fi \fR +.P +.RE +.P +work without losing status on any of the jobs. The shell is allowed to +discard the status of any process if it determines that the application +cannot get the process ID for that process from the shell. It is also +required to remember only +{CHILD_MAX} +number of processes in this way. Since the only way to get the process +ID from the shell is by using the +.BR '!' +shell parameter, the shell is allowed to discard the status of an +asynchronous list if +.BR \(dq$!\(dq +was not referenced before another asynchronous list was started. (This +means that the shell only has to keep the status of the last +asynchronous list started if the application did not reference +.BR \(dq$!\(dq . +If the implementation of the shell is smart enough to determine that a +reference to +.BR \(dq$!\(dq +was not saved anywhere that the application can retrieve it later, it +can use this information to trim the list of saved information. Note +also that a successful call to +.IR wait +with no operands discards the exit status of all asynchronous lists.) +.P +If the exit status of +.IR wait +is greater than 128, there is no way for the application to know if the +waited-for process exited with that value or was killed by a signal. +Since most utilities exit with small values, there is seldom any +ambiguity. Even in the ambiguous cases, most applications just need to +know that the asynchronous job failed; it does not matter whether it +detected an error and failed or was killed and did not complete its job +normally. +.SH EXAMPLES +Although the exact value used when a process is terminated by a signal +is unspecified, if it is known that a signal terminated a process, a +script can still reliably determine which signal by using +.IR kill +as shown by the following script: +.sp +.RS 4 +.nf +\fB +sleep 1000& +pid=$! +kill \(mikill $pid +wait $pid +echo $pid was terminated by a SIG$(kill \(mil $?) signal. +.fi \fR +.P +.RE +.P +If the following sequence of commands is run in less than 31 seconds: +.sp +.RS 4 +.nf +\fB +sleep 257 | sleep 31 & +jobs \(mil %% +.fi \fR +.P +.RE +.P +either of the following commands returns the exit status of the second +.IR sleep +in the pipeline: +.sp +.RS 4 +.nf +\fB +wait \fI\fP +wait %% +.fi \fR +.P +.RE +.SH RATIONALE +The description of +.IR wait +does not refer to the +\fIwaitpid\fR() +function from the System Interfaces volume of POSIX.1\(hy2008 because that would needlessly overspecify this +interface. However, the wording means that +.IR wait +is required to wait for an explicit process when it is given an +argument so that the status information of other processes is not +consumed. Historical implementations use the +\fIwait\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008 until +\fIwait\fR() +returns the requested process ID or finds that the requested process +does not exist. Because this means that a shell script could not +reliably get the status of all background children if a second +background job was ever started before the first job finished, it is +recommended that the +.IR wait +utility use a method such as the functionality provided by the +\fIwaitpid\fR() +function. +.P +The ability to wait for multiple +.IR pid +operands was adopted from the KornShell. +.P +This new functionality was added because it is needed to determine the +exit status of any asynchronous list accurately. The only +compatibility problem that this change creates is for a script like +.sp +.RS 4 +.nf +\fB +while sleep 60 do + job& echo Job started $(date) as $! done +.fi \fR +.P +.RE +.P +which causes the shell to monitor all of the jobs started until the +script terminates or runs out of memory. This would not be a problem +if the loop did not reference +.BR \(dq$!\(dq +or if the script would occasionally +.IR wait +for jobs it started. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIkill\fR\^", +.IR "\fIsh\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.204" ", " "Job Control Job ID", +.IR "Chapter 8" ", " "Environment Variables" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIwait\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/wc.1p b/man-pages-posix-2013/man1p/wc.1p new file mode 100644 index 0000000..2de8551 --- /dev/null +++ b/man-pages-posix-2013/man1p/wc.1p @@ -0,0 +1,264 @@ +'\" et +.TH WC "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +wc +\(em word, line, and byte or character count +.SH SYNOPSIS +.LP +.nf +wc \fB[\fR\(mic|\(mim\fB] [\fR\(milw\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR wc +utility shall read one or more input files and, by default, write the +number of + +characters, words, and bytes contained in each input file to the standard +output. +.P +The utility also shall write a total count for all named files, if more +than one input file is specified. +.P +The +.IR wc +utility shall consider a +.IR word +to be a non-zero-length string of characters delimited by white space. +.SH OPTIONS +The +.IR wc +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(mic\fP" 10 +Write to the standard output the number of bytes in each input file. +.IP "\fB\(mil\fP" 10 +Write to the standard output the number of + +characters in each input file. +.IP "\fB\(mim\fP" 10 +Write to the standard output the number of characters in each input +file. +.IP "\fB\(miw\fP" 10 +Write to the standard output the number of words in each input file. +.P +When any option is specified, +.IR wc +shall report only the information requested by the specified options. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an input file. If no +.IR file +operands are specified, the standard input shall be used. +.SH STDIN +The standard input shall be used if no +.IR file +operands are specified, and shall be used if a +.IR file +operand is +.BR '\(mi' +and the implementation treats the +.BR '\(mi' +as meaning standard input. +Otherwise, the standard input shall not be used. +See the INPUT FILES section. +.SH "INPUT FILES" +The input files may be of any type. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR wc : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files) and which +characters are defined as white-space characters. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +By default, the standard output shall contain an entry for each input +file of the form: +.sp +.RS 4 +.nf +\fB +"%d %d %d %s\en", <\fInewlines\fR>, <\fIwords\fR>, <\fIbytes\fR>, <\fIfile\fR> +.fi \fR +.P +.RE +.P +If the +.BR \(mim +option is specified, the number of characters shall replace the +<\fIbytes\fP> field in this format. +.P +If any options are specified and the +.BR \(mil +option is not specified, the number of + +characters shall not be written. +.P +If any options are specified and the +.BR \(miw +option is not specified, the number of words shall not be written. +.P +If any options are specified and neither +.BR \(mic +nor +.BR \(mim +is specified, the number of bytes or characters shall not be written. +.P +If no input +.IR file +operands are specified, no name shall be written and no + +characters preceding the pathname shall be written. +.P +If more than one input +.IR file +operand is specified, an additional line shall be written, of the same +format as the other lines, except that the word +.BR total +(in the POSIX locale) shall be written instead of a pathname and the +total of each column shall be written as appropriate. Such an +additional line, if any, is written at the end of the output. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.BR \(mim +option is not a switch, but an option at the same level as +.BR \(mic . +Thus, to produce the full default output with character counts instead +of bytes, the command required is: +.sp +.RS 4 +.nf +\fB +wc \(mimlw +.fi \fR +.P +.RE +.SH EXAMPLES +None. +.SH RATIONALE +The output file format pseudo-\c +\fIprintf\fR() +string differs from the System V version of +.IR wc : +.sp +.RS 4 +.nf +\fB +"%7d%7d%7d %s\en" +.fi \fR +.P +.RE +.P +which produces possibly ambiguous and unparsable results for very large +files, as it assumes no number shall exceed six digits. +.P +Some historical implementations use only +, +, +and + +as word separators. The equivalent of the ISO\ C standard +\fIisspace\fR() +function is more appropriate. +.P +The +.BR \(mic +option stands for ``character'' count, even though it counts bytes. +This stems from the sometimes erroneous historical view that bytes and +characters are the same size. Due to international requirements, the +.BR \(mim +option (reminiscent of ``multi-byte'') was added to obtain actual +character counts. +.P +Early proposals only specified the results when input files were text +files. The current specification more closely matches historical +practice. (Bytes, words, and + +characters are counted separately and the results are written when an +end-of-file is detected.) +.P +Historical implementations of the +.IR wc +utility only accepted one argument to specify the options +.BR \(mic , +.BR \(mil , +and +.BR \(miw . +Some of them also had multiple occurrences of an option cause the +corresponding count to be written multiple times and had the order of +specification of the options affect the order of the fields on output, +but did not document either of these. Because common usage either +specifies no options or only one option, and because none of this was +documented, the changes required by this volume of POSIX.1\(hy2008 should not break many +historical applications (and do not break any historical conforming +applications). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcksum\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/what.1p b/man-pages-posix-2013/man1p/what.1p new file mode 100644 index 0000000..b8fbf3e --- /dev/null +++ b/man-pages-posix-2013/man1p/what.1p @@ -0,0 +1,193 @@ +'\" et +.TH WHAT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +what +\(em identify SCCS files (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +what \fB[\fR\(mis\fB] \fIfile\fR... +.fi +.SH DESCRIPTION +The +.IR what +utility shall search the given files for all occurrences of the pattern +that +.IR get +(see +.IR "\fIget\fR\^") +substitutes for the %\fBZ\fP% keyword (\c +.BR \(dq@(#)\(dq ) +and shall write to standard output what follows until the first +occurrence of one of the following: +.sp +.RS 4 +.nf +\fB +\&" > newline \e NUL +.fi \fR +.P +.RE +.SH OPTIONS +The +.IR what +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option shall be supported: +.IP "\fB\(mis\fP" 10 +Quit after finding the first occurrence of the pattern in each file. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile\fR" 10 +A pathname of a file to search. +.SH STDIN +Not used. +.SH "INPUT FILES" +The input files shall be of any file type. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR what : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The standard output shall consist of the following for each +.IR file +operand: +.sp +.RS 4 +.nf +\fB +"%s:\en\et%s\en", <\fIpathname\fR>, <\fIidentification string\fR> +.fi \fR +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP 0 6 +Any matches were found. +.IP 1 6 +Otherwise. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR what +utility is intended to be used in conjunction with the SCCS command +.IR get , +which automatically inserts identifying information, but it can also be +used where the information is inserted by any other means. +.P +When the string +.BR \(dq@(#)\(dq +is included in a library routine in a shared library, it might not be +found in an +.BR a.out +file using that library routine. +.SH EXAMPLES +If the C-language program in file +.BR f.c +contains: +.sp +.RS 4 +.nf +\fB +char ident[] = "@(#)identification information"; +.fi \fR +.P +.RE +.P +and +.BR f.c +is compiled to yield +.BR f.o +and +.BR a.out , +then the command: +.sp +.RS 4 +.nf +\fB +what f.c f.o a.out +.fi \fR +.P +.RE +.P +writes: +.sp +.RS 4 +.nf +\fB +f.c: + identification information + ... +f.o: + identification information + ... +a.out: + identification information + ... +.fi \fR +.P +.RE +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIget\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/who.1p b/man-pages-posix-2013/man1p/who.1p new file mode 100644 index 0000000..1bdfeb1 --- /dev/null +++ b/man-pages-posix-2013/man1p/who.1p @@ -0,0 +1,315 @@ +'\" et +.TH WHO "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +who +\(em display who is on the system +.SH SYNOPSIS +.LP +.nf +who \fB[\fR\(mimTu\fB] [\fR\(miabdHlprt\fB] [\fIfile\fB]\fR +.P +who \fB[\fR\(mimu\fB] \fR\(mis\fB [\fR\(mibHlprt\fB] [\fIfile\fB]\fR +.P +who \(miq \fB[\fIfile\fB]\fR +.P +who am i +.P +who am I +.fi +.SH DESCRIPTION +The +.IR who +utility shall list various pieces of information about accessible +users. The domain of accessibility is implementation-defined. +.P +Based on the options given, +.IR who +can also list the user's name, terminal line, login time, elapsed time +since activity occurred on the line, and the process ID of the command +interpreter for each current system user. +.SH OPTIONS +The +.IR who +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported. The metavariables, such as +<\fIline\fP>, refer to fields described in the STDOUT section. +.IP "\fB\(mia\fP" 10 +Process the implementation-defined database or named file with the +.BR \(mib , +.BR \(mid , +.BR \(mil , +.BR \(mip , +.BR \(mir , +.BR \(mit , +.BR \(miT +and +.BR \(miu +options turned on. +.IP "\fB\(mib\fP" 10 +Write the time and date of the last system reboot. The system reboot +time is the time at which the implementation is able to commence +running processes. +.IP "\fB\(mid\fP" 10 +Write a list of all processes that have expired and not been respawned +by the +.IR init +system process. The <\fIexit\fP> field shall appear for dead processes +and contain the termination and exit values of the dead process. This +can be useful in determining why a process terminated. +.IP "\fB\(miH\fP" 10 +Write column headings above the regular output. +.IP "\fB\(mil\fP" 10 +(The letter ell.) List only those lines on which the system is waiting +for someone to login. The <\fIname\fP> field shall be +.BR LOGIN +in such cases. Other fields shall be the same as for user entries +except that the <\fIstate\fP> field does not exist. +.IP "\fB\(mim\fP" 10 +Output only information about the current terminal. +.IP "\fB\(mip\fP" 10 +List any other process that is currently active and has been previously +spawned by +.IR init . +.IP "\fB\(miq\fP" 10 +(Quick.) List only the names and the number of users currently logged +on. When this option is used, all other options shall be ignored. +.IP "\fB\(mir\fP" 10 +Write the current +.IR run-level +of the +.IR init +process. +.IP "\fB\(mis\fP" 10 +List only the <\fIname\fR>, <\fIline\fR>, and <\fItime\fR> fields. +This is the default case. +.IP "\fB\(mit\fP" 10 +Indicate the last change to the system clock. +.IP "\fB\(miT\fP" 10 +Show the state of each terminal, as described in the STDOUT section. +.IP "\fB\(miu\fP" 10 +Write ``idle time'' for each displayed user in addition to any other +information. The idle time is the time since any activity occurred on +the user's terminal. The method of determining this is unspecified. +This option shall list only those users who are currently logged in. +The <\fIname\fP> is the user's login name. The <\fIline\fP> is the name +of the line as found in the directory +.BR /dev . +The <\fItime\fP> is the time that the user logged in. The +<\fIactivity\fP> is the number of hours and minutes since activity last +occurred on that particular line. A dot indicates that the terminal has +seen activity in the last minute and is therefore ``current''. If more +than twenty-four hours have elapsed or the line has not been used since +boot time, the entry shall be marked <\fIold\fP>. This field is useful +when trying to determine whether a person is working at the terminal or +not. The <\fIpid\fP> is the process ID of the user's login process. +.SH OPERANDS +The following operands shall be supported: +.IP "\fBam\ i\fR,\ \fBam\ I\fR" 10 +In the POSIX locale, limit the output to describing the invoking user, +equivalent to the +.BR \(mim +option. The +.BR am +and +.BR i +or +.BR I +must be separate arguments. +.IP "\fIfile\fR" 10 +Specify a pathname of a file to substitute for the +implementation-defined database of logged-on users that +.IR who +uses by default. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR who : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILC_TIME\fP" 10 +Determine the locale used for the format and contents of the date and +time strings. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITZ\fP" 10 +Determine the timezone used when writing date and time information. If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR who +utility shall write its default format to the standard output in an +implementation-defined format, subject only to the requirement of +containing the information described above. +.P +XSI-conformant systems shall write the default information to the +standard output in the following general format: +.sp +.RS 4 +.nf +\fB +<\fIname\fR>\fB[\fR<\fIstate\fR>\fB]\fR<\fIline\fR><\fItime\fR>\fB[\fR<\fIactivity\fR>\fB][\fR<\fIpid\fR>\fB][\fR<\fIcomment\fR>\fB][\fR<\fIexit\fR>\fB]\fR +.fi \fR +.P +.RE +.P +For the +.BR \(mib +option, <\fIline\fP> shall be +.BR \(dqsystem boot\(dq . +The <\fIname\fP> is unspecified. +.P +The following format shall be used for the +.BR \(miT +option: +.sp +.RS 4 +.nf +\fB +"%s %c %s %s\en" <\fIname\fR>, <\fIterminal state\fR>, <\fIterminal name\fR>, + <\fItime of login\fR> +.fi \fR +.P +.RE +.P +where <\fIterminal\ state\fP> is one of the following characters: +.IP "\fR+\fR" 8 +The terminal allows write access to other users. +.IP "\fR\(mi\fR" 8 +The terminal denies write access to other users. +.IP "\fR?\fR" 8 +The terminal write-access state cannot be determined. +.IP "\fR\fR" 8 +This entry is not associated with a terminal. +.P +In the POSIX locale, the <\fItime\ of\ login\fP> shall be equivalent in +format to the output of: +.sp +.RS 4 +.nf +\fB +date +"%b %e %H:%M" +.fi \fR +.P +.RE +.P +If the +.BR \(miu +option is used with +.BR \(miT , +the idle time shall be added to the end of the previous format in an +unspecified format. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The name +.IR init +used for the system process is the most commonly used on historical +systems, but it may vary. +.P +The ``domain of accessibility'' referred to is a broad concept that +permits interpretation either on a very secure basis or even to allow a +network-wide implementation like the historical +.IR rwho . +.SH EXAMPLES +None. +.SH RATIONALE +Due to differences between historical implementations, the base options +provided were a compromise to allow users to work with those +functions. The standard developers also considered removing all the +options, but felt that these options offered users valuable +functionality. Additional options to match historical systems are +available on XSI-conformant systems. +.P +It is recognized that the +.IR who +command may be of limited usefulness, especially in a multi-level +secure environment. The standard developers considered, however, that +having some standard method of determining the ``accessibility'' of +other users would aid user portability. +.P +No format was specified for the default +.IR who +output for systems not supporting the XSI option. In such a +user-oriented command, designed only for human use, this was not +considered to be a deficiency. +.P +The format of the terminal name is unspecified, but the descriptions of +.IR ps , +.IR talk , +and +.IR write +require that they use the same format. +.P +It is acceptable for an implementation to produce no output for +an invocation of +.IR who +.BR mil . +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImesg\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/write.1p b/man-pages-posix-2013/man1p/write.1p new file mode 100644 index 0000000..c2f1a75 --- /dev/null +++ b/man-pages-posix-2013/man1p/write.1p @@ -0,0 +1,232 @@ +'\" et +.TH WRITE "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +write +\(em write to another user +.SH SYNOPSIS +.LP +.nf +write \fIuser_name \fB[\fIterminal\fB]\fR +.fi +.SH DESCRIPTION +The +.IR write +utility shall read lines from the standard input and write them +to the terminal of the specified user. When first invoked, it shall +write the message: +.sp +.RS 4 +.nf +\fB +\fBMessage from \fIsender-login-id\fR (\fIsending-terminal\fR) \fB[\fIdate\fB]\fR... +.fi \fR +.P +.RE +.P +to +.IR user_name . +When it has successfully completed the connection, the sender's +terminal shall be alerted twice to indicate that what the sender is +typing is being written to the recipient's terminal. +.P +If the recipient wants to reply, this can be accomplished by typing: +.sp +.RS 4 +.nf +\fB +write \fIsender-login-id \fB[\fIsending-terminal\fB]\fR +.fi \fR +.P +.RE +.P +upon receipt of the initial message. Whenever a line of input as +delimited by an NL, EOF, or EOL special character (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface") +is accumulated while in canonical input mode, the accumulated data shall +be written on the other user's terminal. Characters shall be processed +as follows: +.IP " *" 4 +Typing + +shall write the + +character to the recipient's terminal. +.IP " *" 4 +Typing the erase and kill characters shall affect the sender's terminal +in the manner described by the +.BR termios +interface in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface". +.IP " *" 4 +Typing the interrupt or end-of-file characters shall cause +.IR write +to write an appropriate message (\c +.BR \(dqEOT\en\(dq +in the POSIX locale) to the recipient's terminal and exit. +.IP " *" 4 +Typing characters from +.IR LC_CTYPE +classifications +.BR print +or +.BR space +shall cause those characters to be sent to the recipient's terminal. +.IP " *" 4 +When and only when the +.IR stty +.BR iexten +local mode is enabled, the existence and processing of additional +special control characters and multi-byte or single-byte functions is +implementation-defined. +.IP " *" 4 +Typing other non-printable characters shall cause +implementation-defined sequences of printable characters to be +written to the recipient's terminal. +.P +To write to a user who is logged in more than once, the +.IR terminal +argument can be used to indicate which terminal to write to; otherwise, +the recipient's terminal is selected in an implementation-defined +manner and an informational message is written to the sender's standard +output, indicating which terminal was chosen. +.P +Permission to be a recipient of a +.IR write +message can be denied or granted by use of the +.IR mesg +utility. However, a user's privilege may further constrain the domain +of accessibility of other users' terminals. The +.IR write +utility shall fail when the user lacks appropriate privileges to +perform the requested action. +.SH OPTIONS +None. +.SH OPERANDS +.br +The following operands shall be supported: +.IP "\fIuser_name\fR" 10 +Login name of the person to whom the message shall be written. The +application shall ensure that this operand is of the form returned by +the +.IR who +utility. +.IP "\fIterminal\fR" 10 +Terminal identification in the same format provided by the +.IR who +utility. +.SH STDIN +Lines to be copied to the recipient's terminal are read from standard +input. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR write : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). If the +recipient's locale does not use an +.IR LC_CTYPE +equivalent to the sender's, the results are undefined. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error and +informative messages written to standard output. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +If an interrupt signal is received, +.IR write +shall write an appropriate message on the recipient's terminal and +exit with a status of zero. It shall take the standard action for all +other signals. +.SH STDOUT +An informational message shall be written to standard output if a +recipient is logged in more than once. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The recipient's terminal is used for output. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +The addressed user is not logged on or the addressed user denies +permission. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR talk +utility is considered by some users to be a more usable utility on +full-screen terminals. +.SH EXAMPLES +None. +.SH RATIONALE +The +.IR write +utility was included in this volume of POSIX.1\(hy2008 since it can be implemented on all +terminal types. The standard developers considered the +.IR talk +utility, which cannot be implemented on certain terminals, to be a +``better'' communications interface. Both of these programs are in +widespread use on historical implementations. Therefore, the standard +developers decided that both utilities should be specified. +.P +The format of the terminal name is unspecified, but the descriptions of +.IR ps , +.IR talk , +.IR who , +and +.IR write +require that they all use or accept the same format. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImesg\fR\^", +.IR "\fItalk\fR\^", +.IR "\fIwho\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Chapter 11" ", " "General Terminal Interface" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/xargs.1p b/man-pages-posix-2013/man1p/xargs.1p new file mode 100644 index 0000000..507e93d --- /dev/null +++ b/man-pages-posix-2013/man1p/xargs.1p @@ -0,0 +1,749 @@ +'\" et +.TH XARGS "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +xargs +\(em construct argument lists and invoke utility +.SH SYNOPSIS +.LP +.nf +xargs \fB[\fR\(miptx\fB] [\fR\(miE \fIeofstr\fB] [\fR\(miI \fIreplstr\fR|\(miL \fInumber\fR|\(min \fInumber\fB]\fR + \fB[\fR\(mis \fIsize\fB] [\fIutility \fB[\fIargument\fR...\fB]]\fR +.fi +.SH DESCRIPTION +The +.IR xargs +utility shall construct a command line consisting of the +.IR utility +and +.IR argument +operands specified followed by as many arguments read in sequence from +standard input as fit in length and number constraints specified by the +options. The +.IR xargs +utility shall then invoke the constructed command line and wait for its +completion. This sequence shall be repeated until one of the following +occurs: +.IP " *" 4 +An end-of-file condition is detected on standard input. +.IP " *" 4 +An argument consisting of just the logical end-of-file string +(see the +.BR \(miE +.IR eofstr +option) is found on standard input after double-quote processing, + +processing, and +-escape +processing (see next paragraph). All arguments up to but not including +the argument consisting of just the logical end-of-file string shall be +used as arguments in constructed command lines. +.IP " *" 4 +An invocation of a constructed command line returns an exit status of +255. +.P +The application shall ensure that arguments in the standard input are +separated by unquoted + +characters, unescaped + +characters, or + +characters. A string of zero or more non-double-quote (\c +.BR '\&"' ) +characters and non-\c + +characters can be quoted by enclosing them in double-quotes. A string +of zero or more non-\c + +(\c +.BR '\e'' ) +characters and non-\c + +characters can be quoted by enclosing them in + +characters. Any unquoted character can be escaped by preceding it with a +. +The utility named by +.IR utility +shall be executed one or more times until the end-of-file is reached or +the logical end-of file string is found. The results are unspecified if +the utility named by +.IR utility +attempts to read from its standard input. +.P +The generated command line length shall be the sum of the size in bytes +of the utility name and each argument treated as strings, including a +null byte terminator for each of these strings. The +.IR xargs +utility shall limit the command line length such that when the command +line is invoked, the combined argument and environment lists (see the +.IR exec +family of functions in the System Interfaces volume of POSIX.1\(hy2008) shall not exceed +{ARG_MAX}\(mi2\|048 +bytes. Within this constraint, if neither the +.BR \(min +nor the +.BR \(mis +option is specified, the default command line length shall be at least +{LINE_MAX}. +.SH OPTIONS +The +.IR xargs +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\(miE\ \fIeofstr\fR" 10 +Use +.IR eofstr +as the logical end-of-file string. If +.BR \(miE +is not specified, it is unspecified whether the logical end-of-file +string is the + +character (\c +.BR '_' ) +or the end-of-file string capability is disabled. When +.IR eofstr +is the null string, the logical end-of-file string capability shall be +disabled and + +characters shall be taken literally. +.IP "\fB\(miI\ \fIreplstr\fR" 10 +Insert mode: +.IR utility +is executed for each logical line from standard input. Arguments in the +standard input shall be separated only by unescaped + +characters, not by + +characters. Any unquoted unescaped + +characters at the beginning of each line shall be ignored. The resulting +argument shall be inserted in +.IR arguments +in place of each occurrence of +.IR replstr . +At least five arguments in +.IR arguments +can each contain one or more instances of +.IR replstr . +Each of these constructed arguments cannot grow larger than an +implementation-defined limit greater than or equal to 255 bytes. Option +.BR \(mix +shall be forced on. +.IP "\fB\(miL\ \fInumber\fR" 10 +The +.IR utility +shall be executed for each non-empty +.IR number +lines of arguments from standard input. The last invocation of +.IR utility +shall be with fewer lines of arguments if fewer than +.IR number +remain. A line is considered to end with the first + +unless the last character of the line is a +; +a trailing + +signals continuation to the next non-empty line, inclusive. +.IP "\fB\(min\ \fInumber\fR" 10 +Invoke +.IR utility +using as many standard input arguments as possible, up to +.IR number +(a positive decimal integer) arguments maximum. Fewer arguments shall +be used if: +.RS 10 +.IP " *" 4 +The command line length accumulated exceeds the size specified by the +.BR \(mis +option (or +{LINE_MAX} +if there is no +.BR \(mis +option). +.IP " *" 4 +The last iteration has fewer than +.IR number , +but not zero, operands remaining. +.RE +.IP "\fB\(mip\fP" 10 +Prompt mode: the user is asked whether to execute +.IR utility +at each invocation. Trace mode (\c +.BR \(mit ) +is turned on to write the command instance to be executed, followed by +a prompt to standard error. An affirmative response read from +.BR /dev/tty +shall execute the command; otherwise, that particular invocation of +.IR utility +shall be skipped. +.IP "\fB\(mis\ \fIsize\fR" 10 +Invoke +.IR utility +using as many standard input arguments as possible yielding a command +line length less than +.IR size +(a positive decimal integer) bytes. Fewer arguments shall be used if: +.RS 10 +.IP " *" 4 +The total number of arguments exceeds that specified by the +.BR \(min +option. +.IP " *" 4 +The total number of lines exceeds that specified by the +.BR \(miL +option. +.IP " *" 4 +End-of-file is encountered on standard input before +.IR size +bytes are accumulated. +.P +Values of +.IR size +up to at least +{LINE_MAX} +bytes shall be supported, provided that the constraints specified in +the DESCRIPTION are met. It shall not be considered an error if a +value larger than that supported by the implementation or exceeding the +constraints specified in the DESCRIPTION is given; +.IR xargs +shall use the largest value it supports within the constraints. +.RE +.IP "\fB\(mit\fP" 10 +Enable trace mode. Each generated command line shall be written to +standard error just prior to invocation. +.IP "\fB\(mix\fP" 10 +Terminate if a constructed command line will not fit in the +implied or specified size (see the +.BR \(mis +option above). +.SH OPERANDS +The following operands shall be supported: +.IP "\fIutility\fR" 10 +The name of the utility to be invoked, found by search path using the +.IR PATH +environment variable, described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +If +.IR utility +is omitted, the default shall be the +.IR echo +utility. If the +.IR utility +operand names any of the special built-in utilities in +.IR "Section 2.14" ", " "Special Built-In Utilities", +the results are undefined. +.IP "\fIargument\fR" 10 +An initial option or operand for the invocation of +.IR utility . +.SH STDIN +The standard input shall be a text file. The results are unspecified if +an end-of-file condition is detected immediately following an escaped +. +.SH "INPUT FILES" +The file +.BR /dev/tty +shall be used to read responses required by the +.BR \(mip +option. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR xargs : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements used in the extended regular +expression defined for the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files) and the behavior of +character classes used in the extended regular expression defined for +the +.BR yesexpr +locale keyword in the +.IR LC_MESSAGES +category. +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale used to process affirmative responses, and the +locale used to affect the format and contents of diagnostic messages +and prompts written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPATH\fP" 10 +Determine the location of +.IR utility , +as described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used for diagnostic messages and the +.BR \(mit +and +.BR \(mip +options. If the +.BR \(mit +option is specified, the +.IR utility +and its constructed argument list shall be written to standard error, +as it will be invoked, prior to invocation. If +.BR \(mip +is specified, a prompt of the following format shall be written (in the +POSIX locale): +.sp +.RS 4 +.nf +\fB +"?..." +.fi \fR +.P +.RE +.P +at the end of the line of the output from +.BR \(mit . +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\0\0\0\00" 8 +All invocations of +.IR utility +returned exit status zero. +.IP "1\(hy125" 8 +A command line meeting the specified requirements could not be +assembled, one or more of the invocations of +.IR utility +returned a non-zero exit status, or some other error occurred. +.IP "\0\0126" 8 +The utility specified by +.IR utility +was found but could not be invoked. +.IP "\0\0127" 8 +The utility specified by +.IR utility +could not be found. +.SH "CONSEQUENCES OF ERRORS" +If a command line meeting the specified requirements cannot be +assembled, the utility cannot be invoked, an invocation of the utility +is terminated by a signal, or an invocation of the utility exits with +exit status 255, the +.IR xargs +utility shall write a diagnostic message and exit without processing +any remaining input. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The 255 exit status allows a utility being used by +.IR xargs +to tell +.IR xargs +to terminate if it knows no further invocations using the current data +stream will succeed. Thus, +.IR utility +should explicitly +.IR exit +with an appropriate value to avoid accidentally returning with 255. +.P +Note that since input is parsed as lines, + +characters separate arguments, and +, +, +and double-quote characters are used for quoting, if +.IR xargs +is used to bundle the output of commands like +.IR find +.IR dir +.BR \(miprint +or +.IR ls +into commands to be executed, unexpected results are likely if any +filenames contain +, +, +or quoting characters. This can be solved by using find to call a script +that converts each file found into a quoted string that is then piped to +.IR xargs , +but in most cases it is preferable just to have +.IR find +do the argument aggregation itself by using +.BR \(miexec +with a +.BR '+' +terminator instead of +.BR ';' . +Note that the quoting rules used by +.IR xargs +are not the same as in the shell. They were not made consistent here +because existing applications depend on the current rules. An easy (but +inefficient) method that can be used to transform input consisting of +one argument per line into a quoted form that +.IR xargs +interprets correctly is to precede each non-\c + +character with a +. +More efficient alternatives are shown in Example 2 and Example 5 below. +.P +On implementations with a large value for +{ARG_MAX}, +.IR xargs +may produce command lines longer than +{LINE_MAX}. +For invocation of utilities, this is not a problem. If +.IR xargs +is being used to create a text file, users should explicitly set the +maximum command line length with the +.BR \(mis +option. +.P +The +.IR command , +.IR env , +.IR nice , +.IR nohup , +.IR time , +and +.IR xargs +utilities have been specified to use exit code 127 if an error occurs +so that applications can distinguish ``failure to find a utility'' from +``invoked utility exited with an error indication''. The value 127 was +chosen because it is not commonly used for other meanings; most +utilities use small values for ``normal error conditions'' and the +values above 128 can be confused with termination due to receipt of a +signal. The value 126 was chosen in a similar manner to indicate that +the utility could be found, but not invoked. Some scripts produce +meaningful error messages differentiating the 126 and 127 cases. The +distinction between exit codes 126 and 127 is based on KornShell +practice that uses 127 when all attempts to +.IR exec +the utility fail with +.BR [ENOENT] , +and uses 126 when any attempt to +.IR exec +the utility fails for any other reason. +.SH EXAMPLES +.IP " 1." 4 +The following command combines the output of the parenthesized +commands (minus the + +characters) onto one line, which is then appended to the file log. It +assumes that the expansion of +.BR \(dq$0 $*\(dq +does not include any + +or + +characters. +.RS 4 +.sp +.RS 4 +.nf +\fB +(logname; date; printf "'%s'\en$0 $*") | xargs \(miE "" >>log +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +The following command invokes +.IR diff +with successive pairs of arguments originally typed as command line +arguments. It assumes there are no embedded + +characters in the elements of the original argument list. +.RS 4 +.sp +.RS 4 +.nf +\fB +printf "%s\en$@" | sed 's/[^[:alnum:]]/\e\e&/g' | + xargs \(miE "" \(min 2 \(mix diff +.fi \fR +.P +.RE +.RE +.IP " 3." 4 +In the following commands, the user is asked which files in the current +directory (excluding dotfiles) are to be archived. The files are +archived into +.BR arch ; +.IR a , +one at a time or +.IR b , +many at a time. The commands assume that no filenames contain +, +, +, +, +or double-quote characters. +.RS 4 +.sp +.RS 4 +.nf +\fB +a. ls | xargs \(miE "" \(mip \(miL 1 ar \(mir arch +.P +b. ls | xargs \(miE "" \(mip \(miL 1 | xargs \(miE "" ar \(mir arch +.fi \fR +.P +.RE +.RE +.IP " 4." 4 +The following command invokes +.IR command1 +one or more times with multiple arguments, stopping if an invocation of +.IR command1 +has a non-zero exit status. +.RS 4 +.sp +.RS 4 +.nf +\fB +xargs \(miE "" sh \(mic 'command1 "$@" || exit 255' sh < xargs_input +.fi \fR +.P +.RE +.RE +.IP " 5." 4 +On XSI-conformant systems, the following command moves all files +from directory +.BR $1 +to directory +.BR $2 , +and echoes each move command just before doing it. It assumes no +filenames contain + +characters and that neither +.BR $1 +nor +.BR $2 +contains the sequence +.BR \(dq{}\(dq . +.RS 4 +.sp +.RS 4 +.nf +\fB +ls \(miA "$1" | sed \(mie 's/"/"\e\e""/g' \(mie 's/.*/"&"/' | + xargs \(miE "" \(miI {} \(mit mv "$1"/{} "$2"/{} +.fi \fR +.P +.RE +.RE +.SH RATIONALE +The +.IR xargs +utility was usually found only in System V-based systems; BSD systems +included an +.IR apply +utility that provided functionality similar to +.IR xargs +.BR \(min +.IR number . +The SVID lists +.IR xargs +as a software development extension. This volume of POSIX.1\(hy2008 does not share the view that +it is used only for development, and therefore it is not optional. +.P +The classic application of the +.IR xargs +utility is in conjunction with the +.IR find +utility to reduce the number of processes launched by a simplistic use +of the +.IR find +.BR \(miexec +combination. The +.IR xargs +utility is also used to enforce an upper limit on memory required to +launch a process. With this basis in mind, this volume of POSIX.1\(hy2008 selected only the +minimal features required. +.P +Although the 255 exit status is mostly an accident of historical +implementations, it allows a utility being used by +.IR xargs +to tell +.IR xargs +to terminate if it knows no further invocations using the current data +stream shall succeed. Any non-zero exit status from a utility falls +into the 1\(hy125 range when +.IR xargs +exits. There is no statement of how the various non-zero utility exit +status codes are accumulated by +.IR xargs . +The value could be the addition of all codes, their highest value, the +last one received, or a single value such as 1. Since no algorithm is +arguably better than the others, and since many of the standard +utilities say little more (portably) than ``pass/fail'', no new +algorithm was invented. +.P +Several other +.IR xargs +options were removed because simple alternatives already exist within +\&this volume of POSIX.1\(hy2008. For example, the +.BR \(mii +.IR replstr +option can be just as efficiently performed using a shell +.BR for +loop. Since +.IR xargs +calls an +.IR exec +function with each input line, the +.BR \(mii +option does not usually exploit the grouping capabilities of +.IR xargs . +.P +The requirement that +.IR xargs +never produces command lines such that invocation of +.IR utility +is within 2\|048 bytes of hitting the POSIX +.IR exec +{ARG_MAX} +limitations is intended to guarantee that the invoked utility has room +to modify its environment variables and command line arguments and +still be able to invoke another utility. Note that the minimum +{ARG_MAX} +allowed by the System Interfaces volume of POSIX.1\(hy2008 is 4\|096 bytes and the minimum +value allowed by this volume of POSIX.1\(hy2008 is 2\|048 bytes; therefore, +the 2\|048 bytes difference seems reasonable. Note, however, that +.IR xargs +may never be able to invoke a utility if the environment passed in to +.IR xargs +comes close to using +{ARG_MAX} +bytes. +.P +The version of +.IR xargs +required by this volume of POSIX.1\(hy2008 is required to wait for the completion of the invoked +command before invoking another command. This was done because +historical scripts using +.IR xargs +assumed sequential execution. Implementations wanting to provide +parallel operation of the invoked utilities are encouraged to add an +option enabling parallel invocation, but should still wait for +termination of all of the children before +.IR xargs +terminates normally. +.P +The +.BR \(mie +option was omitted from the ISO\ POSIX\(hy2:\|1993 standard in the belief that the +.IR eofstr +option-argument was recognized only when it was on a line by itself and +before quote and escape processing were performed, and that the logical +end-of-file processing was only enabled if a +.BR \(mie +option was specified. In that case, a simple +.IR sed +script could be used to duplicate the +.BR \(mie +functionality. Further investigation revealed that: +.IP " *" 4 +The logical end-of-file string was checked for after quote and escape +processing, making a +.IR sed +script that provided equivalent functionality much more difficult to +write. +.IP " *" 4 +The default was to perform logical end-of-file processing with an + +as the logical end-of-file string. +.P +To correct this misunderstanding, the +.BR \(miE +.IR eofstr +option was adopted from the X/Open Portability Guide. Users should +note that the description of the +.BR \(miE +option matches historical documentation of the +.BR \(mie +option (which was not adopted because it did not support the Utility +Syntax Guidelines), by +saying that if +.IR eofstr +is the null string, logical end-of-file processing is disabled. +Historical implementations of +.IR xargs +actually did not disable logical end-of-file processing; they treated a +null argument found in the input as a logical end-of-file string. (A +null +.IR string +argument could be generated using single or double-quotes (\c +.BR '\^' +or +.BR \(dq\^\(dq ). +Since this behavior was not documented historically, it is considered +to be a bug. +.P +The +.BR \(miI , +.BR \(miL , +and +.BR \(min +options are mutually-exclusive. Some implementations use the last one +specified if more than one is given on a command line; other +implementations treat combinations of the options in different ways. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language", +.IR "\fIdiff\fR\^", +.IR "\fIecho\fR\^", +.IR "\fIfind\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIexec\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/yacc.1p b/man-pages-posix-2013/man1p/yacc.1p new file mode 100644 index 0000000..cd62644 --- /dev/null +++ b/man-pages-posix-2013/man1p/yacc.1p @@ -0,0 +1,1597 @@ +'\" et +.TH YACC "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +yacc +\(em yet another compiler compiler (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +yacc \fB[\fR\(midltv\fB] [\fR\(mib \fIfile_prefix\fB] [\fR\(mip \fIsym_prefix\fB]\fI grammar\fR +.fi +.SH DESCRIPTION +The +.IR yacc +utility shall read a description of a context-free grammar in +.IR grammar +and write C source code, conforming to the ISO\ C standard, to a code file, +and optionally header information into a header file, in the current +directory. The generated source code shall not depend on any undefined, +unspecified, or implementation-defined behavior, except in cases where +it is copied directly from the supplied grammar, or in cases that are +documented by the implementation. The C code shall define a function +and related routines and macros for an automaton that executes a parsing +algorithm meeting the requirements in +.IR "Algorithms". +.P +The form and meaning of the grammar are described in the EXTENDED +DESCRIPTION section. +.P +The C source code and header file shall be produced in a form suitable +as input for the C compiler (see +.IR "\fIc99\fR\^"). +.SH OPTIONS +The +.IR yacc +utility shall conform to the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except for Guideline 9. +.P +The following options shall be supported: +.IP "\fB\(mib\ \fIfile_prefix\fR" 10 +Use +.IR file_prefix +instead of +.BR y +as the prefix for all output filenames. The code file +.BR y.tab.c , +the header file +.BR y.tab.h +(created when +.BR \(mid +is specified), and the description file +.BR y.output +(created when +.BR \(miv +is specified), shall be changed to +.IR file_prefix \c +.BR .tab.c , +.IR file_prefix \c +.BR .tab.h , +and +.IR file_prefix \c +.BR .output , +respectively. +.IP "\fB\(mid\fP" 10 +Write the header file; by default only the code file is written. The +.BR #define +statements associate the token codes assigned by +.IR yacc +with the user-declared token names. This allows source files other +than +.BR y.tab.c +to access the token codes. +.IP "\fB\(mil\fP" 10 +Produce a code file that does not contain any +.BR #line +constructs. If this option is not present, it is unspecified whether +the code file or header file contains +.BR #line +directives. This should only be used after the grammar and the +associated actions are fully debugged. +.IP "\fB\(mip\ \fIsym_prefix\fR" 10 +.br +Use +.IR sym_prefix +instead of +.BR yy +as the prefix for all external names produced by +.IR yacc . +The names affected shall include the functions +\fIyyparse\fR(), +\fIyylex\fR(), +and +\fIyyerror\fR(), +and the variables +.IR yylval , +.IR yychar , +and +.IR yydebug . +(In the remainder of this section, the six symbols cited are referenced +using their default names only as a notational convenience.) Local +names may also be affected by the +.BR \(mip +option; however, the +.BR \(mip +option shall not affect +.BR #define +symbols generated by +.IR yacc . +.IP "\fB\(mit\fP" 10 +Modify conditional compilation directives to permit compilation of +debugging code in the code file. Runtime debugging statements shall +always be contained in the code file, but by default conditional +compilation directives prevent their compilation. +.IP "\fB\(miv\fP" 10 +Write a file containing a description of the parser and a report of +conflicts generated by ambiguities in the grammar. +.br +.SH OPERANDS +The following operand is required: +.IP "\fIgrammar\fR" 10 +A pathname of a file containing instructions, hereafter called +.IR grammar , +for which a parser is to be created. The format for the grammar is +described in the EXTENDED DESCRIPTION section. +.SH STDIN +Not used. +.SH "INPUT FILES" +The file +.IR grammar +shall be a text file formatted as specified in the EXTENDED DESCRIPTION +section. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR yacc : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.P +The +.IR LANG +and +.IR LC_* +variables affect the execution of the +.IR yacc +utility as stated. The +\fImain\fR() +function defined in +.IR "Yacc Library" +shall call: +.sp +.RS 4 +.nf +\fB +setlocale(LC_ALL, "") +.fi \fR +.P +.RE +.P +and thus the program generated by +.IR yacc +shall also be affected by the contents of these variables at runtime. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +If shift/reduce or reduce/reduce conflicts are detected in +.IR grammar , +.IR yacc +shall write a report of those conflicts to the standard error in an +unspecified format. +.P +Standard error shall also be used for diagnostic messages. +.SH "OUTPUT FILES" +The code file, the header file, and the description file shall be text +files. All are described in the following sections. +.SS "Code File" +.P +This file shall contain the C source code for the +\fIyyparse\fR() +function. It shall contain code for the various semantic actions with +macro substitution performed on them as described in the EXTENDED +DESCRIPTION section. It also shall contain a copy of the +.BR #define +statements in the header file. If a +.BR %union +declaration is used, the declaration for YYSTYPE shall also be included +in this file. +.SS "Header File" +.P +The header file shall contain +.BR #define +statements that associate the token numbers with the token names. This +allows source files other than the code file to access the token +codes. If a +.BR %union +declaration is used, the declaration for YYSTYPE and an +.IR "extern YYSTYPE yylval" +declaration shall also be included in this file. +.SS "Description File" +.P +The description file shall be a text file containing a description of +the state machine corresponding to the parser, using an unspecified +format. Limits for internal tables (see +.IR "Limits") +shall also be reported, in an implementation-defined manner. (Some +implementations may use dynamic allocation techniques and have no +specific limit values to report.) +.SH "EXTENDED DESCRIPTION" +The +.IR yacc +command accepts a language that is used to define a grammar for a +target language to be parsed by the tables and code generated by +.IR yacc . +The language accepted by +.IR yacc +as a grammar for the target language is described below using the +.IR yacc +input language itself. +.P +The input +.IR grammar +includes rules describing the input structure of the target language +and code to be invoked when these rules are recognized to provide the +associated semantic action. The code to be executed shall appear as bodies +of text that are intended to be C-language code. These bodies of text +shall not contain C-language trigraphs. The C-language inclusions are +presumed to form a correct function when processed by +.IR yacc +into its output files. The code included in this way shall be executed +during the recognition of the target language. +.P +Given a grammar, the +.IR yacc +utility generates the files described in the OUTPUT FILES section. The +code file can be compiled and linked using +.IR c99 . +If the declaration and programs sections of the grammar file did not +include definitions of +\fImain\fR(), +\fIyylex\fR(), +and +\fIyyerror\fR(), +the compiled output requires linking with externally supplied versions +of those functions. Default versions of +\fImain\fR() +and +\fIyyerror\fR() +are supplied in the +.IR yacc +library and can be linked in by using the +.BR "\(mil\ y" +operand to +.IR c99 . +The +.IR yacc +library interfaces need not support interfaces with other than the +default +.BR yy +symbol prefix. The application provides the lexical analyzer function, +\fIyylex\fR(); +the +.IR lex +utility is specifically designed to generate such a routine. +.SS "Input Language" +.P +The application shall ensure that every specification file consists of +three sections in order: +.IR declarations , +.IR "grammar rules" , +and +.IR programs , +separated by double + +characters (\c +.BR \(dq%%\(dq ). +The declarations and programs sections can be empty. If the latter is +empty, the preceding +.BR \(dq%%\(dq +mark separating it from the rules section can be omitted. +.P +The input is free form text following the structure of the grammar +defined below. +.SS "Lexical Structure of the Grammar" +.P +The +, +, +and + +character shall be ignored, except that the application shall ensure that +they do not appear in names or multi-character reserved symbols. Comments +shall be enclosed in +.BR \(dq/*\ ...\ */\(dq , +and can appear wherever a name is valid. +.P +Names are of arbitrary length, made up of letters, periods (\c +.BR '.' ), +underscores (\c +.BR '_' ), +and non-initial digits. Uppercase and lowercase letters are distinct. +Conforming applications shall not use names beginning in +.BR yy +or +.BR YY +since the +.IR yacc +parser uses such names. Many of the names appear in the final output +of +.IR yacc , +and thus they should be chosen to conform with any additional rules +created by the C compiler to be used. In particular they appear in +.BR #define +statements. +.P +A literal shall consist of a single character enclosed in single-quote +characters. All of the escape sequences supported for character constants +by the ISO\ C standard shall be supported by +.IR yacc . +.P +The relationship with the lexical analyzer is discussed in detail below. +.P +The application shall ensure that the NUL character is not used in +grammar rules or literals. +.SS "Declarations Section" +.P +The declarations section is used to define the symbols used to define +the target language and their relationship with each other. In +particular, much of the additional information required to resolve +ambiguities in the context-free grammar for the target language is +provided here. +.P +Usually +.IR yacc +assigns the relationship between the symbolic names it generates and +their underlying numeric value. The declarations section makes it +possible to control the assignment of these values. +.P +It is also possible to keep semantic information associated with the +tokens currently on the parse stack in a user-defined C-language +.BR union , +if the members of the union are associated with the various names in +the grammar. The declarations section provides for this as well. +.P +The first group of declarators below all take a list of names as +arguments. That list can optionally be preceded by the name of a C +union member (called a +.IR tag +below) appearing within +.BR '<' +and +.BR '>' . +(As an exception to the typographical conventions of the rest of this volume of POSIX.1\(hy2008, +in this case <\fItag\fP> does not represent a metavariable, but the +literal angle bracket characters surrounding a symbol.) The use of +.IR tag +specifies that the tokens named on this line shall be of the same C +type as the union member referenced by +.IR tag . +This is discussed in more detail below. +.P +For lists used to define tokens, the first appearance of a given token +can be followed by a positive integer (as a string of decimal digits). +If this is done, the underlying value assigned to it for lexical +purposes shall be taken to be that number. +.P +The following declares +.IR name +to be a token: +.sp +.RS 4 +.nf +\fB +%token \fB[\fR<\fItag\fR>\fB] \fIname \fB[\fInumber\fB] [\fIname \fB[\fInumber\fB]]\fR... +.fi \fR +.P +.RE +.P +If +.IR tag +is present, the C type for all tokens on this line shall be declared to +be the type referenced by +.IR tag . +If a positive integer, +.IR number , +follows a +.IR name , +that value shall be assigned to the token. +.P +The following declares +.IR name +to be a token, and assigns precedence to it: +.sp +.RS 4 +.nf +\fB +%left \fB[\fR<\fItag\fR>\fB] \fIname \fB[\fInumber\fB] [\fIname \fB[\fInumber\fB]]\fR... +%right \fB[\fR<\fItag\fR>\fB] \fIname \fB[\fInumber\fB] [\fIname \fB[\fInumber\fB]]\fR... +.fi \fR +.P +.RE +.P +One or more lines, each beginning with one of these symbols, can appear +in this section. All tokens on the same line have the same precedence +level and associativity; the lines are in order of increasing +precedence or binding strength. +.BR %left +denotes that the operators on that line are left associative, and +.BR %right +similarly denotes right associative operators. If +.IR tag +is present, it shall declare a C type for +.IR name s +as described for +.BR %token . +.P +The following declares +.IR name +to be a token, and indicates that this cannot be used associatively: +.sp +.RS 4 +.nf +\fB +%nonassoc \fB[\fR<\fItag\fR>\fB] \fIname \fB[\fInumber\fB] [\fIname \fB[\fInumber\fB]]\fR... +.fi \fR +.P +.RE +.P +If the parser encounters associative use of this token it reports an +error. If +.IR tag +is present, it shall declare a C type for +.IR name s +as described for +.BR %token . +.P +The following declares that union member +.IR name s +are non-terminals, and thus it is required to have a +.IR tag +field at its beginning: +.sp +.RS 4 +.nf +\fB +%type <\fItag\fR> \fIname\fR... +.fi \fR +.P +.RE +.P +Because it deals with non-terminals only, assigning a token number or +using a literal is also prohibited. If this construct is present, +.IR yacc +shall perform type checking; if this construct is not present, the +parse stack shall hold only the +.BR int +type. +.P +Every name used in +.IR grammar +not defined by a +.BR %token , +.BR %left , +.BR %right , +or +.BR %nonassoc +declaration is assumed to represent a non-terminal symbol. The +.IR yacc +utility shall report an error for any non-terminal symbol that does not +appear on the left side of at least one grammar rule. +.P +Once the type, precedence, or token number of a name is specified, it +shall not be changed. If the first declaration of a token does not +assign a token number, +.IR yacc +shall assign a token number. Once this assignment is made, the token +number shall not be changed by explicit assignment. +.P +The following declarators do not follow the previous pattern. +.P +The following declares the non-terminal +.IR name +to be the +.IR "start symbol" , +which represents the largest, most general structure described by the +grammar rules: +.sp +.RS 4 +.nf +\fB +%start \fIname\fR +.fi \fR +.P +.RE +.P +By default, it is the left-hand side of the first grammar rule; this +default can be overridden with this declaration. +.P +The following declares the +.IR yacc +value stack to be a union of the various types of values desired. +.sp +.RS 4 +.nf +\fB +%union { \fIbody of union\fR (\fIin C\fR) } +.fi \fR +.P +.RE +.P +The body of the union shall not contain unbalanced curly brace +preprocessing tokens. +.P +By default, the values returned by actions (see below) and the lexical +analyzer shall be of type +.BR int . +The +.IR yacc +utility keeps track of types, and it shall insert corresponding union +member names in order to perform strict type checking of the resulting +parser. +.P +Alternatively, given that at least one <\fItag\fP> construct is used, +the union can be declared in a header file (which shall be included in +the declarations section by using a +.BR #include +construct within +.BR %{ +and +.BR %} ), +and a +.BR typedef +used to define the symbol YYSTYPE to represent this union. The effect +of +.BR %union +is to provide the declaration of YYSTYPE directly from the +.IR yacc +input. +.P +C-language declarations and definitions can appear in the declarations +section, enclosed by the following marks: +.sp +.RS 4 +.nf +\fB +%{ ... %} +.fi \fR +.P +.RE +.P +These statements shall be copied into the code file, and have global +scope within it so that they can be used in the rules and program +sections. The statements shall not contain +.BR \(dq%}\(dq +outside a comment, string literal, or multi-character constant. +.P +The application shall ensure that the declarations section is +terminated by the token +.BR %% . +.SS "Grammar Rules in yacc" +.P +The rules section defines the context-free grammar to be accepted by +the function +.IR yacc +generates, and associates with those rules C-language actions and +additional precedence information. The grammar is described below, and +a formal definition follows. +.P +The rules section is comprised of one or more grammar rules. A grammar +rule has the form: +.sp +.RS 4 +.nf +\fB +A : BODY ; +.fi \fR +.P +.RE +.P +The symbol +.BR A +represents a non-terminal name, and +.BR BODY +represents a sequence of zero or more +.IR name s, +.IR literal s, +and +.IR "semantic action" s +that can then be followed by optional +.IR "precedence rule" s. +Only the names and literals participate in the formation of the +grammar; the semantic actions and precedence rules are used in other +ways. The + +and the + +are +.IR yacc +punctuation. If there are several successive grammar rules with the +same left-hand side, the + +(\c +.BR '|' ) +can be used to avoid rewriting the left-hand side; in this case the + +appears only after the last rule. The BODY part can be empty +(or empty of names and literals) to indicate that the non-terminal +symbol matches the empty string. +.P +The +.IR yacc +utility assigns a unique number to each rule. Rules using the vertical +bar notation are distinct rules. The number assigned to the rule +appears in the description file. +.P +The elements comprising a BODY are: +.IP "\fIname\fR,\ \fIliteral\fR" 10 +These form the rules of the grammar: +.IR name +is either a +.IR token +or a +.IR non-terminal ; +.IR literal +stands for itself (less the lexically required quotation marks). +.IP "\fIsemantic action\fR" 10 +.br +With each grammar rule, the user can associate actions to be performed +each time the rule is recognized in the input process. (Note that the +word ``action'' can also refer to the actions of the parser\(emshift, +reduce, and so on.) +.RS 10 +.P +These actions can return values and can obtain the values returned by +previous actions. These values are kept in objects of type YYSTYPE +(see +.BR %union ). +The result value of the action shall be kept on the parse stack with +the left-hand side of the rule, to be accessed by other reductions as +part of their right-hand side. By using the <\fItag\fP> information +provided in the declarations section, the code generated by +.IR yacc +can be strictly type checked and contain arbitrary information. In +addition, the lexical analyzer can provide the same kinds of values for +tokens, if desired. +.P +An action is an arbitrary C statement and as such can do input or +output, call subprograms, and alter external variables. An action is +one or more C statements enclosed in curly braces +.BR '{' +and +.BR '}' . +The statements shall not contain unbalanced curly brace preprocessing +tokens. +.P +Certain pseudo-variables can be used in the action. These are macros +for access to data structures known internally to +.IR yacc . +.IP $$ 10 +The value of the action can be set by assigning it to $$. If type +checking is enabled and the type of the value to be assigned cannot be +determined, a diagnostic message may be generated. +.IP "$\fInumber\fR" 10 +This refers to the value returned by the component specified by the +token +.IR number +in the right side of a rule, reading from left to right; +.IR number +can be zero or negative. If +.IR number +is zero or negative, it refers to the data associated with the name on +the parser's stack preceding the leftmost symbol of the current rule. +(That is, +.BR \(dq$0\(dq +refers to the name immediately preceding the leftmost name in the +current rule to be found on the parser's stack and +.BR \(dq$\(mi1\(dq +refers to the symbol to +.IR its +left.) If +.IR number +refers to an element past the current point in the rule, or beyond the +bottom of the stack, the result is undefined. If type checking is +enabled and the type of the value to be assigned cannot be determined, +a diagnostic message may be generated. +.IP "$<\fItag\fR>\fInumber\fR" 10 +.br +These correspond exactly to the corresponding symbols without the +.IR tag +inclusion, but allow for strict type checking (and preclude unwanted +type conversions). The effect is that the macro is expanded to use +.IR tag +to select an element from the YYSTYPE union (using +.IR dataname.tag ). +This is particularly useful if +.IR number +is not positive. +.IP "$<\fItag\fR>$" 10 +This imposes on the reference the type of the union member referenced +by +.IR tag . +This construction is applicable when a reference to a left context +value occurs in the grammar, and provides +.IR yacc +with a means for selecting a type. +.P +Actions can occur anywhere in a rule (not just at the end); an +action can access values returned by actions to its left, and in turn +the value it returns can be accessed by actions to its right. An +action appearing in the middle of a rule shall be equivalent to +replacing the action with a new non-terminal symbol and adding an empty +rule with that non-terminal symbol on the left-hand side. The semantic +action associated with the new rule shall be equivalent to the original +action. The use of actions within rules might introduce conflicts that +would not otherwise exist. +.P +By default, the value of a rule shall be the value of the first element +in it. If the first element does not have a type (particularly in the +case of a literal) and type checking is turned on by +.BR %type , +an error message shall result. +.RE +.IP "\fIprecedence\fR" 10 +The keyword +.BR %prec +can be used to change the precedence level associated with a particular +grammar rule. Examples of this are in cases where a unary and binary +operator have the same symbolic representation, but need to be given +different precedences, or where the handling of an ambiguous if-else +construction is necessary. The reserved symbol +.BR %prec +can appear immediately after the body of the grammar rule and can be +followed by a token name or a literal. It shall cause the precedence +of the grammar rule to become that of the following token name or +literal. The action for the rule as a whole can follow +.BR %prec . +.P +If a program section follows, the application shall ensure that the +grammar rules are terminated by +.BR %% . +.SS "Programs Section" +.P +The +.IR programs +section can include the definition of the lexical analyzer +\fIyylex\fR(), +and any other functions; for example, those used in the actions +specified in the grammar rules. It is unspecified whether the programs +section precedes or follows the semantic actions in the output file; +therefore, if the application contains any macro definitions and +declarations intended to apply to the code in the semantic actions, it +shall place them within +.BR \(dq%{\ ...\ %}\(dq +in the declarations section. +.SS "Input Grammar" +.P +The following input to +.IR yacc +yields a parser for the input to +.IR yacc . +This formal syntax takes precedence over the preceding text syntax +description. +.P +The lexical structure is defined less precisely; +.IR "Lexical Structure of the Grammar" +defines most terms. The correspondence between the previous terms and +the tokens below is as follows. +.IP "\fBIDENTIFIER\fR" 12 +This corresponds to the concept of +.IR name , +given previously. It also includes literals as defined previously. +.IP "\fBC_IDENTIFIER\fR" 12 +This is a name, and additionally it is known to be followed by a +. +A literal cannot yield this token. +.IP "\fBNUMBER\fR" 12 +A string of digits (a non-negative decimal integer). +.IP "\fBTYPE\fR,\ \fBLEFT\fR,\ \fBMARK\fR,\ \fBLCURL\fR,\ \fBRCURL\fR" 12 +.br +These correspond directly to +.BR %type , +.BR %left , +.BR %% , +.BR %{ , +and +.BR %} . +.IP "\fB{\ .\|.\|.\ }\fR" 12 +This indicates C-language source code, with the possible inclusion of +.BR '$' +macros as discussed previously. +.sp +.RS 4 +.nf +\fB +/* Grammar for the input to yacc. */ +/* Basic entries. */ +/* The following are recognized by the lexical analyzer. */ +.P +%token IDENTIFIER /* Includes identifiers and literals */ +%token C_IDENTIFIER /* identifier (but not literal) + followed by a :. */ +%token NUMBER /* [0-9][0-9]* */ +.P +/* Reserved words : %type=>TYPE %left=>LEFT, and so on */ +.P +%token LEFT RIGHT NONASSOC TOKEN PREC TYPE START UNION +.P +%token MARK /* The %% mark. */ +%token LCURL /* The %{ mark. */ +%token RCURL /* The %} mark. */ +.P +/* 8-bit character literals stand for themselves; */ +/* tokens have to be defined for multi-byte characters. */ +.P +%start spec +.P +%% +.P +spec : defs MARK rules tail + ; +tail : MARK + { + /* In this action, set up the rest of the file. */ + } + | /* Empty; the second MARK is optional. */ + ; +defs : /* Empty. */ + | defs def + ; +def : START IDENTIFIER + | UNION + { + /* Copy union definition to output. */ + } + | LCURL + { + /* Copy C code to output file. */ + } + RCURL + | rword tag nlist + ; +rword : TOKEN + | LEFT + | RIGHT + | NONASSOC + | TYPE + ; +tag : /* Empty: union tag ID optional. */ + | '<' IDENTIFIER '>' + ; +nlist : nmno + | nlist nmno + ; +nmno : IDENTIFIER /* Note: literal invalid with % type. */ + | IDENTIFIER NUMBER /* Note: invalid with % type. */ + ; +.P +/* Rule section */ +.P +rules : C_IDENTIFIER rbody prec + | rules rule + ; +rule : C_IDENTIFIER rbody prec + | '|' rbody prec + ; +rbody : /* empty */ + | rbody IDENTIFIER + | rbody act + ; +act : '{' + { + /* Copy action, translate $$, and so on. */ + } + '}' + ; +prec : /* Empty */ + | PREC IDENTIFIER + | PREC IDENTIFIER act + | prec ';' + ; +.fi \fR +.P +.RE +.sp +.SS "Conflicts" +.P +The parser produced for an input grammar may contain states in which +conflicts occur. The conflicts occur because the grammar is not +LALR(1). An ambiguous grammar always contains at least one LALR(1) +conflict. The +.IR yacc +utility shall resolve all conflicts, using either default rules or +user-specified precedence rules. +.P +Conflicts are either shift/reduce conflicts or reduce/reduce +conflicts. A shift/reduce conflict is where, for a given state and +lookahead symbol, both a shift action and a reduce action are +possible. A reduce/reduce conflict is where, for a given state and +lookahead symbol, reductions by two different rules are possible. +.P +The rules below describe how to specify what actions to take when a +conflict occurs. Not all shift/reduce conflicts can be successfully +resolved this way because the conflict may be due to something other +than ambiguity, so incautious use of these facilities can cause the +language accepted by the parser to be much different from that which +was intended. The description file shall contain sufficient +information to understand the cause of the conflict. Where ambiguity +is the reason either the default or explicit rules should be adequate +to produce a working parser. +.P +The declared precedences and associativities (see +.IR "Declarations Section") +are used to resolve parsing conflicts as follows: +.IP " 1." 4 +A precedence and associativity is associated with each grammar rule; it +is the precedence and associativity of the last token or literal in the +body of the rule. If the +.BR %prec +keyword is used, it overrides this default. Some grammar rules might +not have both precedence and associativity. +.IP " 2." 4 +If there is a shift/reduce conflict, and both the grammar rule and the +input symbol have precedence and associativity associated with them, +then the conflict is resolved in favor of the action (shift or reduce) +associated with the higher precedence. If the precedences are the +same, then the associativity is used; left associative implies reduce, +right associative implies shift, and non-associative implies an error +in the string being parsed. +.IP " 3." 4 +When there is a shift/reduce conflict that cannot be resolved by rule +2, the shift is done. Conflicts resolved this way are counted in the +diagnostic output described in +.IR "Error Handling". +.IP " 4." 4 +When there is a reduce/reduce conflict, a reduction is done by the +grammar rule that occurs earlier in the input sequence. Conflicts +resolved this way are counted in the diagnostic output described in +.IR "Error Handling". +.P +Conflicts resolved by precedence or associativity shall not be counted +in the shift/reduce and reduce/reduce conflicts reported by +.IR yacc +on either standard error or in the description file. +.SS "Error Handling" +.P +The token +.BR error +shall be reserved for error handling. The name +.BR error +can be used in grammar rules. It indicates places where the parser can +recover from a syntax error. The default value of +.BR error +shall be 256. Its value can be changed using a +.BR %token +declaration. The lexical analyzer should not return the value of +.BR error . +.P +The parser shall detect a syntax error when it is in a state where the +action associated with the lookahead symbol is +.BR error . +A semantic action can cause the parser to initiate error handling by +executing the macro YYERROR. When YYERROR is executed, the semantic +action passes control back to the parser. YYERROR cannot be used +outside of semantic actions. +.P +When the parser detects a syntax error, it normally calls +\fIyyerror\fR() +with the character string +.BR \(dqsyntax\ error\(dq +as its argument. The call shall not be made if the parser is still +recovering from a previous error when the error is detected. The +parser is considered to be recovering from a previous error until the +parser has shifted over at least three normal input symbols since the +last error was detected or a semantic action has executed the macro +.IR yyerrok . +The parser shall not call +\fIyyerror\fR() +when YYERROR is executed. +.P +The macro function YYRECOVERING shall return 1 if a syntax error +has been detected and the parser has not yet fully recovered from it. +Otherwise, zero shall be returned. +.P +When a syntax error is detected by the parser, the parser shall check +if a previous syntax error has been detected. If a previous error was +detected, and if no normal input symbols have been shifted since the +preceding error was detected, the parser checks if the lookahead symbol +is an endmarker (see +.IR "Interface to the Lexical Analyzer"). +If it is, the parser shall return with a non-zero value. Otherwise, +the lookahead symbol shall be discarded and normal parsing shall +resume. +.P +When YYERROR is executed or when the parser detects a syntax error and +no previous error has been detected, or at least one normal input +symbol has been shifted since the previous error was detected, the +parser shall pop back one state at a time until the parse stack is +empty or the current state allows a shift over +.BR error . +If the parser empties the parse stack, it shall return with a non-zero +value. Otherwise, it shall shift over +.BR error +and then resume normal parsing. If the parser reads a lookahead symbol +before the error was detected, that symbol shall still be the lookahead +symbol when parsing is resumed. +.P +The macro +.IR yyerrok +in a semantic action shall cause the parser to act as if it has fully +recovered from any previous errors. The macro +.IR yyclearin +shall cause the parser to discard the current lookahead token. If the +current lookahead token has not yet been read, +.IR yyclearin +shall have no effect. +.P +The macro YYACCEPT shall cause the parser to return with the value +zero. The macro YYABORT shall cause the parser to return with a +non-zero value. +.SS "Interface to the Lexical Analyzer" +.P +The +\fIyylex\fR() +function is an integer-valued function that returns a +.IR "token number" +representing the kind of token read. If there is a value associated +with the token returned by +\fIyylex\fR() +(see the discussion of +.IR tag +above), it shall be assigned to the external variable +.IR yylval . +.P +If the parser and +\fIyylex\fR() +do not agree on these token numbers, reliable communication between +them cannot occur. For (single-byte character) literals, the token is +simply the numeric value of the character in the current character set. +The numbers for other tokens can either be chosen by +.IR yacc , +or chosen by the user. In either case, the +.BR #define +construct of C is used to allow +\fIyylex\fR() +to return these numbers symbolically. The +.BR #define +statements are put into the code file, and the header file if that file +is requested. The set of characters permitted by +.IR yacc +in an identifier is larger than that permitted by C. Token names found +to contain such characters shall not be included in the +.BR #define +declarations. +.P +If the token numbers are chosen by +.IR yacc , +the tokens other than literals shall be assigned numbers greater than +256, although no order is implied. A token can be explicitly assigned a +number by following its first appearance in the declarations section +with a number. Names and literals not defined this way retain their +default definition. All token numbers assigned by +.IR yacc +shall be unique and distinct from the token numbers used for literals +and user-assigned tokens. If duplicate token numbers cause conflicts in +parser generation, +.IR yacc +shall report an error; otherwise, it is unspecified whether the token +assignment is accepted or an error is reported. +.P +The end of the input is marked by a special token called the +.IR endmarker , +which has a token number that is zero or negative. (These values are +invalid for any other token.) All lexical analyzers shall return zero +or negative as a token number upon reaching the end of their input. If +the tokens up to, but excluding, the endmarker form a structure that +matches the start symbol, the parser shall accept the input. If the +endmarker is seen in any other context, it shall be considered an +error. +.SS "Completing the Program" +.P +In addition to +\fIyyparse\fR() +and +\fIyylex\fR(), +the functions +\fIyyerror\fR() +and +\fImain\fR() +are required to make a complete program. The application can supply +\fImain\fR() +and +\fIyyerror\fR(), +or those routines can be obtained from the +.IR yacc +library. +.SS "Yacc Library" +.P +The following functions shall appear only in the +.IR yacc +library accessible through the +.BR "\(mil\ y" +operand to +.IR c99 ; +they can therefore be redefined by a conforming application: +.IP "\fBint\ \fImain\fR(\fBvoid\fR)" 6 +.br +This function shall call +\fIyyparse\fR() +and exit with an unspecified value. Other actions within this function +are unspecified. +.IP "\fBint\ \fIyyerror\fR(\fBconst\ char\fR\ *\fIs\fR)" 6 +.br +This function shall write the NUL-terminated argument to standard +error, followed by a +. +.P +The order of the +.BR "\(mil\ y" +and +.BR "\(mil\ l" +operands given to +.IR c99 +is significant; the application shall either provide its own +\fImain\fR() +function or ensure that +.BR "\(mil\ y" +precedes +.BR "\(mil\ l" . +.SS "Debugging the Parser" +.P +The parser generated by +.IR yacc +shall have diagnostic facilities in it that can be optionally enabled +at either compile time or at runtime (if enabled at compile time). +The compilation of the runtime debugging code is under the control of +YYDEBUG, a preprocessor symbol. If YYDEBUG has a non-zero value, the +debugging code shall be included. If its value is zero, the code shall +not be included. +.P +In parsers where the debugging code has been included, the external +.BR int +.IR yydebug +can be used to turn debugging on (with a non-zero value) and off (zero +value) at runtime. The initial value of +.IR yydebug +shall be zero. +.P +When +.BR \(mit +is specified, the code file shall be built such that, if YYDEBUG is not +already defined at compilation time (using the +.IR c99 +.BR \(miD +YYDEBUG option, for example), YYDEBUG shall be set explicitly to 1. +When +.BR \(mit +is not specified, the code file shall be built such that, if YYDEBUG is +not already defined, it shall be set explicitly to zero. +.P +The format of the debugging output is unspecified but includes at least +enough information to determine the shift and reduce actions, and the +input symbols. It also provides information about error recovery. +.SS "Algorithms" +.P +The parser constructed by +.IR yacc +implements an LALR(1) parsing algorithm as documented in the +literature. It is unspecified whether the parser is table-driven or +direct-coded. +.P +A parser generated by +.IR yacc +shall never request an input symbol from +\fIyylex\fR() +while in a state where the only actions other than the error action are +reductions by a single rule. +.P +The literature of parsing theory defines these concepts. +.SS "Limits" +.P +The +.IR yacc +utility may have several internal tables. The minimum maximums for +these tables are shown in the following table. The exact meaning of +these values is implementation-defined. The implementation shall +define the relationship between these values and between them and any +error messages that the implementation may generate should it run out +of space for any internal structure. An implementation may combine +groups of these resources into a single pool as long as the total +available to the user does not fall below the sum of the sizes +specified by this section. +.br +.sp +.ce 1 +\fBTable: Internal Limits in \fIyacc\fP\fR +.ad l +.TS +center box tab(@); +cB | cB | cB +cB | cB | cB +l | n | lw(3i). +@Minimum +Limit@Maximum@Description +_ +{NTERMS}@126@Number of tokens. +{NNONTERM}@200@Number of non-terminals. +{NPROD}@300@Number of rules. +{NSTATES}@600@Number of states. +{MEMSIZE}@5\|200@T{ +Length of rules. The total length, in names (tokens and +non-terminals), of all the rules of the grammar. The left-hand side is +counted for each rule, even if it is not explicitly repeated, as +specified in +.IR "Grammar Rules in yacc". +T} +{ACTSIZE}@4\|000@T{ +Number of actions. ``Actions'' here (and in the description file) +refer to parser actions (shift, reduce, and so on) not to semantic +actions defined in +.IR "Grammar Rules in yacc". +T} +.TE +.ad b +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If any errors are encountered, the run is aborted and +.IR yacc +exits with a non-zero status. Partial code files and header files +may be produced. The summary information in the description file +shall always be produced if the +.BR \(miv +flag is present. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Historical implementations experience name conflicts on the names +.BR yacc.tmp , +.BR yacc.acts , +.BR yacc.debug , +.BR y.tab.c , +.BR y.tab.h , +and +.BR y.output +if more than one copy of +.IR yacc +is running in a single directory at one time. The +.BR \(mib +option was added to overcome this problem. The related problem of +allowing multiple +.IR yacc +parsers to be placed in the same file was addressed by adding a +.BR \(mip +option to override the previously hard-coded +.BR yy +variable prefix. +.P +The description of the +.BR \(mip +option specifies the minimal set of function and variable names that +cause conflict when multiple parsers are linked together. YYSTYPE does +not need to be changed. Instead, the programmer can use +.BR \(mib +to give the header files for different parsers different names, and +then the file with the +\fIyylex\fR() +for a given parser can include the header for that parser. Names such +as +.IR yyclearerr +do not need to be changed because they are used only in the actions; +they do not have linkage. It is possible that an implementation has +other names, either internal ones for implementing things such as +.IR yyclearerr , +or providing non-standard features that it wants to change with +.BR \(mip . +.P +Unary operators that are the same token as a binary operator in general +need their precedence adjusted. This is handled by the +.BR %prec +advisory symbol associated with the particular grammar rule defining +that unary operator. (See +.IR "Grammar Rules in yacc".) +Applications are not required to use this operator for unary operators, +but the grammars that do not require it are rare. +.SH EXAMPLES +Access to the +.IR yacc +library is obtained with library search operands to +.IR c99 . +To use the +.IR yacc +library +\fImain\fR(): +.sp +.RS 4 +.nf +\fB +c99 y.tab.c \(mil y +.fi \fR +.P +.RE +.P +Both the +.IR lex +library and the +.IR yacc +library contain +\fImain\fR(). +To access the +.IR yacc +\fImain\fR(): +.sp +.RS 4 +.nf +\fB +c99 y.tab.c lex.yy.c \(mil y \(mil l +.fi \fR +.P +.RE +.P +This ensures that the +.IR yacc +library is searched first, so that its +\fImain\fR() +is used. +.P +The historical +.IR yacc +libraries have contained two simple functions that are normally coded +by the application programmer. These functions are similar to the +following code: +.sp +.RS 4 +.nf +\fB +#include +int main(void) +{ + extern int yyparse(); +.P + setlocale(LC_ALL, ""); +.P + /* If the following parser is one created by lex, the + application must be careful to ensure that LC_CTYPE + and LC_COLLATE are set to the POSIX locale. */ + (void) yyparse(); + return (0); +} +.P +#include +.P +int yyerror(const char *msg) +{ + (void) fprintf(stderr, "%s\en", msg); + return (0); +} +.fi \fR +.P +.RE +.SH RATIONALE +The references in +.BR "Referenced Documents" +may be helpful in constructing the parser generator. The referenced DeRemer and Pennello article (along +with the works it references) describes a technique to generate parsers +that conform to this volume of POSIX.1\(hy2008. Work in this area continues to be done, so +implementors should consult current literature before doing any new +implementations. The original Knuth article is the theoretical basis for this +kind of parser, but the tables it generates are impractically large for +reasonable grammars and should not be used. The ``equivalent to'' +wording is intentional to assure that the best tables that are LALR(1) +can be generated. +.P +There has been confusion between the class of grammars, the algorithms +needed to generate parsers, and the algorithms needed to parse the +languages. They are all reasonably orthogonal. In particular, a parser +generator that accepts the full range of LR(1) grammars need not +generate a table any more complex than one that accepts SLR(1) (a +relatively weak class of LR grammars) for a grammar that happens to be +SLR(1). Such an implementation need not recognize the case, either; +table compression can yield the SLR(1) table (or one even smaller than +that) without recognizing that the grammar is SLR(1). +The speed of an LR(1) parser for any class is dependent more upon the +table representation and compression (or the code generation if a +direct parser is generated) than upon the class of grammar that the +table generator handles. +.P +The speed of the parser generator is somewhat dependent upon the class +of grammar it handles. However, the original Knuth article algorithms for +constructing LR parsers were judged by its author to be impractically +slow at that time. Although full LR is more complex than LALR(1), as +computer speeds and algorithms improve, the difference (in terms of +acceptable wall-clock execution time) is becoming less significant. +.P +Potential authors are cautioned that the referenced DeRemer and Pennello article previously cited +identifies a bug (an over-simplification of the computation of LALR(1) +lookahead sets) in some of the LALR(1) algorithm statements that +preceded it to publication. They should take the time to seek out that +paper, as well as current relevant work, particularly Aho's. +.P +The +.BR \(mib +option was added to provide a portable method for permitting +.IR yacc +to work on multiple separate parsers in the same directory. If a +directory contains more than one +.IR yacc +grammar, and both grammars are constructed at the same time (by, for +example, a parallel +.IR make +program), conflict results. While the solution is not historical +practice, it corrects a known deficiency in historical implementations. +Corresponding changes were made to all sections that referenced the +filenames +.BR y.tab.c +(now ``the code file''), +.BR y.tab.h +(now ``the header file''), and +.BR y.output +(now ``the description file''). +.P +The grammar for +.IR yacc +input is based on System V documentation. The textual description shows +there that the +.BR ';' +is required at the end of the rule. The grammar and the implementation +do not require this. (The use of +.BR C_IDENTIFIER +causes a reduce to occur in the right place.) +.P +Also, in that implementation, the constructs such as +.BR %token +can be terminated by a +, +but this is not permitted by the grammar. The keywords such as +.BR %token +can also appear in uppercase, which is again not discussed. In most +places where +.BR '%' +is used, + +can be substituted, and there are alternate spellings for some of the +symbols (for example, +.BR %LEFT +can be +.BR \(dq%<\(dq +or even +.BR \(dq\e<\(dq ). +.P +Historically, <\fItag\fP> can contain any characters except +.BR '>' , +including white space, in the implementation. However, since the +.IR tag +must reference an ISO\ C standard union member, in practice conforming +implementations need to support only the set of characters for ISO\ C standard +identifiers in this context. +.P +Some historical implementations are known to accept actions that are +terminated by a period. Historical implementations often allow +.BR '$' +in names. A conforming implementation does not need to support either +of these behaviors. +.P +Deciding when to use +.BR %prec +illustrates the difficulty in specifying the behavior of +.IR yacc . +There may be situations in which the +.IR grammar +is not, strictly speaking, in error, and yet +.IR yacc +cannot interpret it unambiguously. The resolution of ambiguities in the +grammar can in many instances be resolved by providing additional +information, such as using +.BR %type +or +.BR %union +declarations. It is often easier and it usually yields a smaller parser +to take this alternative when it is appropriate. +.P +The size and execution time of a program produced without the runtime +debugging code is usually smaller and slightly faster in historical +implementations. +.P +Statistics messages from several historical implementations include the +following types of information: +.sp +.RS 4 +.nf +\fB +\fIn\fR/512 terminals, \fIn\fR/300 non-terminals +\fIn\fR/600 grammar rules, \fIn\fR/1\|500 states +\fIn\fR shift/reduce, \fIn\fR reduce/reduce conflicts reported +\fIn\fR/350 working sets used +Memory: states, etc. \fIn\fR/15\|000, parser \fIn\fR/15\|000 +\fIn\fR/600 distinct lookahead sets +\fIn\fR extra closures +\fIn\fR shift entries, \fIn\fR exceptions +\fIn\fR goto entries +\fIn\fR entries saved by goto default +Optimizer space used: input \fIn\fR/15\|000, output \fIn\fR/15\|000 +\fIn\fR table entries, \fIn\fR zero +Maximum spread: \fIn\fR, Maximum offset: \fIn\fR +.fi \fR +.P +.RE +.P +The report of internal tables in the description file is left +implementation-defined because all aspects of these limits are also +implementation-defined. Some implementations may use dynamic +allocation techniques and have no specific limit values to report. +.P +The format of the +.BR y.output +file is not given because specification of the format was not seen to +enhance applications portability. The listing is primarily intended to +help human users understand and debug the parser; use of +.BR y.output +by a conforming application script would be unusual. Furthermore, +implementations have not produced consistent output and no popular +format was apparent. The format selected by the implementation should +be human-readable, in addition to the requirement that it be a text +file. +.P +Standard error reports are not specifically described because they are +seldom of use to conforming applications and there was no reason to +restrict implementations. +.P +Some implementations recognize +.BR \(dq={\(dq +as equivalent to +.BR '{' +because it appears in historical documentation. This construction was +recognized and documented as obsolete as long ago as 1978, in the +referenced \fIYacc: Yet Another Compiler-Compiler\fP. This volume of POSIX.1\(hy2008 chose to leave it as obsolete and omit it. +.P +Multi-byte characters should be recognized by the lexical analyzer and +returned as tokens. They should not be returned as multi-byte +character literals. The token +.BR error +that is used for error recovery is normally assigned the value 256 in +the historical implementation. Thus, the token value 256, which is used +in many multi-byte character sets, is not available for use as the +value of a user-defined token. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIc99\fR\^", +.IR "\fIlex\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man1p/zcat.1p b/man-pages-posix-2013/man1p/zcat.1p new file mode 100644 index 0000000..e5c78cc --- /dev/null +++ b/man-pages-posix-2013/man1p/zcat.1p @@ -0,0 +1,127 @@ +'\" et +.TH ZCAT "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +zcat +\(em expand and concatenate data +.SH SYNOPSIS +.LP +.nf +zcat \fB[\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR zcat +utility shall write to standard output the uncompressed form of files +that have been compressed using the +.IR compress +utility. It is the equivalent of +.IR uncompress +.BR \(mic . +Input files are not affected. +.SH OPTIONS +None. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +The pathname of a file previously processed by the +.IR compress +utility. If +.IR file +already has the +.BR .Z +suffix specified, it is used as submitted. Otherwise, the +.BR .Z +suffix is appended to the filename prior to processing. +.SH STDIN +The standard input shall be used only if no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\(mi' . +.SH "INPUT FILES" +Input files shall be compressed files that are in the format produced by +the +.IR compress +utility. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR zcat : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The compressed files given as input shall be written on standard output +in their uncompressed form. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcompress\fR\^", +.IR "\fIuncompress\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/FD_CLR.3p b/man-pages-posix-2013/man3p/FD_CLR.3p new file mode 100644 index 0000000..499063a --- /dev/null +++ b/man-pages-posix-2013/man3p/FD_CLR.3p @@ -0,0 +1,41 @@ +'\" et +.TH FD_CLR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/_Exit.3p b/man-pages-posix-2013/man3p/_Exit.3p new file mode 100644 index 0000000..67bf8b8 --- /dev/null +++ b/man-pages-posix-2013/man3p/_Exit.3p @@ -0,0 +1,451 @@ +'\" et +.TH _EXIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 to a waiting parent process. +.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 is executing a +\fIwait\fR(), +\fIwaitid\fR(), +or +\fIwaitpid\fR(), +and has neither set its SA_NOCLDWAIT flag nor set SIGCHLD to SIG_IGN, +it shall be notified of termination of the calling process and the +low-order eight bits (that is, bits 0377) of +.IR status +shall be made available to it. If the parent is not waiting, the child's +status shall be made available to it when the parent subsequently +executes +\fIwait\fR(), +\fIwaitid\fR(), +or +\fIwaitpid\fR(). +.RS 4 +.P +The semantics of the +\fIwaitid\fR() +function shall be equivalent to +\fIwait\fR(). +.RE +.IP " *" 4 +If the parent process of the calling process is not executing a +\fIwait\fR(), +\fIwaitid\fR(), +or +\fIwaitpid\fR(), +and has neither set its SA_NOCLDWAIT flag nor set SIGCHLD to SIG_IGN, +the calling process shall be transformed into a \fIzombie process\fP. +A \fIzombie process\fP is an inactive process and it shall be deleted +at some later time when its parent process executes +\fIwait\fR(), +\fIwaitid\fR(), +or +\fIwaitpid\fR(). +.RS 4 +.P +The semantics of the +\fIwaitid\fR() +function shall be equivalent to +\fIwait\fR(). +.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 +Either: +.RS 4 +.P +If the implementation supports the SIGCHLD +signal, a SIGCHLD shall be sent to the parent process. +.P +Or: +.P +If the parent process has set its SA_NOCLDWAIT flag, +or set SIGCHLD to SIG_IGN, the status shall be +discarded, and 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. +.RE +.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\(hy2008. +.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\(hy2008 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\(hy2008, 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\(hy2008, the +signals are sent to the entire process group at the same time. Also, +in this volume of POSIX.1\(hy2008, 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\(hy2008 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/_longjmp.3p b/man-pages-posix-2013/man3p/_longjmp.3p new file mode 100644 index 0000000..9b155d2 --- /dev/null +++ b/man-pages-posix-2013/man3p/_longjmp.3p @@ -0,0 +1,130 @@ +'\" et +.TH _LONGJMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/_tolower.3p b/man-pages-posix-2013/man3p/_tolower.3p new file mode 100644 index 0000000..db6a857 --- /dev/null +++ b/man-pages-posix-2013/man3p/_tolower.3p @@ -0,0 +1,72 @@ +'\" et +.TH _TOLOWER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/_toupper.3p b/man-pages-posix-2013/man3p/_toupper.3p new file mode 100644 index 0000000..bbdceae --- /dev/null +++ b/man-pages-posix-2013/man3p/_toupper.3p @@ -0,0 +1,72 @@ +'\" et +.TH _TOUPPER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/a64l.3p b/man-pages-posix-2013/man3p/a64l.3p new file mode 100644 index 0000000..e5632ae --- /dev/null +++ b/man-pages-posix-2013/man3p/a64l.3p @@ -0,0 +1,159 @@ +'\" et +.TH A64L "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIuuencode\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/abort.3p b/man-pages-posix-2013/man3p/abort.3p new file mode 100644 index 0000000..56caedb --- /dev/null +++ b/man-pages-posix-2013/man3p/abort.3p @@ -0,0 +1,134 @@ +'\" et +.TH ABORT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/abs.3p b/man-pages-posix-2013/man3p/abs.3p new file mode 100644 index 0000000..ebad567 --- /dev/null +++ b/man-pages-posix-2013/man3p/abs.3p @@ -0,0 +1,70 @@ +'\" et +.TH ABS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/accept.3p b/man-pages-posix-2013/man3p/accept.3p new file mode 100644 index 0000000..b4a7a3e --- /dev/null +++ b/man-pages-posix-2013/man3p/accept.3p @@ -0,0 +1,190 @@ +'\" et +.TH ACCEPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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. +.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, \(mi1 shall be returned and +.IR errno +set to indicate the error. +.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 "\fIbind\fR\^(\|)", +.IR "\fIconnect\fR\^(\|)", +.IR "\fIlisten\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/access.3p b/man-pages-posix-2013/man3p/access.3p new file mode 100644 index 0000000..955556d --- /dev/null +++ b/man-pages-posix-2013/man3p/access.3p @@ -0,0 +1,294 @@ +'\" et +.TH ACCESS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 relative to directory file +descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int access(const char *\fIpath\fP, int \fIamode\fP); +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 , +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\(hy2008, +.IR "Section 4.4" ", " "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 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 file descriptor was +opened without O_SEARCH, the function shall check whether directory +searches are permitted using the current permissions of the directory +underlying the file descriptor. If the file descriptor was opened with +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 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 are performed using the effective user and +group IDs instead of the real user 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 \(mi1 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 +.IR fd +was not opened with 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 +\fB +#include +\&... +int result; +const char *pathname = "/tmp/myfile"; +.P +result = access (pathname, F_OK); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +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\(hy2008 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\(hy2008. +.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" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^(\|)", +.IR "\fIfstatat\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.4" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/acos.3p b/man-pages-posix-2013/man3p/acos.3p new file mode 100644 index 0000000..16df697 --- /dev/null +++ b/man-pages-posix-2013/man3p/acos.3p @@ -0,0 +1,120 @@ +'\" et +.TH ACOS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 [\(mi1,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 [\(mi1,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 [\(mi1,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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/acosh.3p b/man-pages-posix-2013/man3p/acosh.3p new file mode 100644 index 0000000..f5cecba --- /dev/null +++ b/man-pages-posix-2013/man3p/acosh.3p @@ -0,0 +1,118 @@ +'\" et +.TH ACOSH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 \(miInf, 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 \(miInf. +.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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/acosl.3p b/man-pages-posix-2013/man3p/acosl.3p new file mode 100644 index 0000000..dfba44b --- /dev/null +++ b/man-pages-posix-2013/man3p/acosl.3p @@ -0,0 +1,38 @@ +'\" et +.TH ACOSL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/aio_cancel.3p b/man-pages-posix-2013/man3p/aio_cancel.3p new file mode 100644 index 0000000..25b8388 --- /dev/null +++ b/man-pages-posix-2013/man3p/aio_cancel.3p @@ -0,0 +1,118 @@ +'\" et +.TH AIO_CANCEL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1. 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/aio_error.3p b/man-pages-posix-2013/man3p/aio_error.3p new file mode 100644 index 0000000..69a04fe --- /dev/null +++ b/man-pages-posix-2013/man3p/aio_error.3p @@ -0,0 +1,117 @@ +'\" et +.TH AIO_ERROR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/aio_fsync.3p b/man-pages-posix-2013/man3p/aio_fsync.3p new file mode 100644 index 0000000..5b2435e --- /dev/null +++ b/man-pages-posix-2013/man3p/aio_fsync.3p @@ -0,0 +1,191 @@ +'\" et +.TH AIO_FSYNC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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 open for writing. +.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" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/aio_read.3p b/man-pages-posix-2013/man3p/aio_read.3p new file mode 100644 index 0000000..2ff7112 --- /dev/null +++ b/man-pages-posix-2013/man3p/aio_read.3p @@ -0,0 +1,208 @@ +'\" et +.TH AIO_READ "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\(mi1 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 \(mi1 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 \(mi1, 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/aio_return.3p b/man-pages-posix-2013/man3p/aio_return.3p new file mode 100644 index 0000000..9bfafbf --- /dev/null +++ b/man-pages-posix-2013/man3p/aio_return.3p @@ -0,0 +1,120 @@ +'\" et +.TH AIO_RETURN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/aio_suspend.3p b/man-pages-posix-2013/man3p/aio_suspend.3p new file mode 100644 index 0000000..fda1d0f --- /dev/null +++ b/man-pages-posix-2013/man3p/aio_suspend.3p @@ -0,0 +1,132 @@ +'\" et +.TH AIO_SUSPEND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/aio_write.3p b/man-pages-posix-2013/man3p/aio_write.3p new file mode 100644 index 0000000..e3bbb1b --- /dev/null +++ b/man-pages-posix-2013/man3p/aio_write.3p @@ -0,0 +1,218 @@ +'\" et +.TH AIO_WRITE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\(mi1 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 \(mi1 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 \(mi1, 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/alarm.3p b/man-pages-posix-2013/man3p/alarm.3p new file mode 100644 index 0000000..00e93c6 --- /dev/null +++ b/man-pages-posix-2013/man3p/alarm.3p @@ -0,0 +1,163 @@ +'\" et +.TH ALARM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/alphasort.3p b/man-pages-posix-2013/man3p/alphasort.3p new file mode 100644 index 0000000..0865014 --- /dev/null +++ b/man-pages-posix-2013/man3p/alphasort.3p @@ -0,0 +1,266 @@ +'\" et +.TH ALPHASORT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1. +.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 +\fB +#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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/asctime.3p b/man-pages-posix-2013/man3p/asctime.3p new file mode 100644 index 0000000..7ef2731 --- /dev/null +++ b/man-pages-posix-2013/man3p/asctime.3p @@ -0,0 +1,197 @@ +'\" et +.TH ASCTIME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +Sun Sep 16 01:03:52 1973\en\e0 +.fi \fR +.P +.RE +.P +using the equivalent of the following algorithm: +.sp +.RS 4 +.nf +\fB +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 \fR +.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}\(mi1990, +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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/asin.3p b/man-pages-posix-2013/man3p/asin.3p new file mode 100644 index 0000000..815fbbc --- /dev/null +++ b/man-pages-posix-2013/man3p/asin.3p @@ -0,0 +1,156 @@ +'\" et +.TH ASIN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 [\(mi1,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 [\(mi\(*p/2,\(*p/2] radians. +.P +For finite values of +.IR x +not in the range [\(mi1,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 [\(mi1,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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/asinh.3p b/man-pages-posix-2013/man3p/asinh.3p new file mode 100644 index 0000000..c19fe56 --- /dev/null +++ b/man-pages-posix-2013/man3p/asinh.3p @@ -0,0 +1,123 @@ +'\" et +.TH ASINH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/asinl.3p b/man-pages-posix-2013/man3p/asinl.3p new file mode 100644 index 0000000..7bdd691 --- /dev/null +++ b/man-pages-posix-2013/man3p/asinl.3p @@ -0,0 +1,38 @@ +'\" et +.TH ASINL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/assert.3p b/man-pages-posix-2013/man3p/assert.3p new file mode 100644 index 0000000..5d3c7ba --- /dev/null +++ b/man-pages-posix-2013/man3p/assert.3p @@ -0,0 +1,92 @@ +'\" et +.TH ASSERT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/atan.3p b/man-pages-posix-2013/man3p/atan.3p new file mode 100644 index 0000000..5860afc --- /dev/null +++ b/man-pages-posix-2013/man3p/atan.3p @@ -0,0 +1,131 @@ +'\" et +.TH ATAN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 [\(mi\(*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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/atan2.3p b/man-pages-posix-2013/man3p/atan2.3p new file mode 100644 index 0000000..643a33c --- /dev/null +++ b/man-pages-posix-2013/man3p/atan2.3p @@ -0,0 +1,239 @@ +'\" et +.TH ATAN2 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 [\(mi\(*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, \(mi\(*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 \(mi0, \(+-\(*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 \(miInf, \(+-\(*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 \(miInf, \(+-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 +\fB +#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 \fR +.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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/atanf.3p b/man-pages-posix-2013/man3p/atanf.3p new file mode 100644 index 0000000..acfc87a --- /dev/null +++ b/man-pages-posix-2013/man3p/atanf.3p @@ -0,0 +1,38 @@ +'\" et +.TH ATANF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/atanh.3p b/man-pages-posix-2013/man3p/atanh.3p new file mode 100644 index 0000000..6ecdf2f --- /dev/null +++ b/man-pages-posix-2013/man3p/atanh.3p @@ -0,0 +1,174 @@ +'\" et +.TH ATANH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 [\(mi1,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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/atanl.3p b/man-pages-posix-2013/man3p/atanl.3p new file mode 100644 index 0000000..c68741c --- /dev/null +++ b/man-pages-posix-2013/man3p/atanl.3p @@ -0,0 +1,38 @@ +'\" et +.TH ATANL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/atexit.3p b/man-pages-posix-2013/man3p/atexit.3p new file mode 100644 index 0000000..144837c --- /dev/null +++ b/man-pages-posix-2013/man3p/atexit.3p @@ -0,0 +1,131 @@ +'\" et +.TH ATEXIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/atof.3p b/man-pages-posix-2013/man3p/atof.3p new file mode 100644 index 0000000..1440493 --- /dev/null +++ b/man-pages-posix-2013/man3p/atof.3p @@ -0,0 +1,85 @@ +'\" et +.TH ATOF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 defers to the ISO\ C standard. +.P +The call +.IR atof ( str ) +shall be equivalent to: +.sp +.RS 4 +.nf +\fB +strtod(\fIstr\fP,(char **)NULL), +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/atoi.3p b/man-pages-posix-2013/man3p/atoi.3p new file mode 100644 index 0000000..5535ea6 --- /dev/null +++ b/man-pages-posix-2013/man3p/atoi.3p @@ -0,0 +1,108 @@ +'\" et +.TH ATOI "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 defers to the ISO\ C standard. +.P +The call +.IR atoi ( str ) +shall be equivalent to: +.sp +.RS 4 +.nf +\fB +(int) strtol(str, (char **)NULL, 10) +.fi \fR +.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 +\fB +#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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/atol.3p b/man-pages-posix-2013/man3p/atol.3p new file mode 100644 index 0000000..65c7bb9 --- /dev/null +++ b/man-pages-posix-2013/man3p/atol.3p @@ -0,0 +1,97 @@ +'\" et +.TH ATOL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 *\fIstr\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\(hy2008 defers to the ISO\ C standard. +.P +The call +.IR atol ( str ) +shall be equivalent to: +.sp +.RS 4 +.nf +\fB +strtol(str, (char **)NULL, 10) +.fi \fR +.P +.RE +.P +The call +.IR atoll ( nptr ) +shall be equivalent to: +.sp +.RS 4 +.nf +\fB +strtoll(nptr, (char **)NULL, 10) +.fi \fR +.P +.RE +.P +except that 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" +The +\fIatol\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 +\fIatol\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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/basename.3p b/man-pages-posix-2013/man3p/basename.3p new file mode 100644 index 0000000..9d81c23 --- /dev/null +++ b/man-pages-posix-2013/man3p/basename.3p @@ -0,0 +1,144 @@ +'\" et +.TH BASENAME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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(). +.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 +\fB +#include +\&... +char *name = "/usr/lib"; +char *base; +.P +base = basename(name); +\&... +.fi \fR +.P +.RE +.SS "Sample Input and Output Strings for basename(\|)" +.P +In the following table, the input string is the value pointed to by +.IR path , +and the output string is the return value of the +\fIbasename\fR() +function. +.TS +center box tab(!); +cB | cB +lf5 | lf5. +Input String!Output String +_ +"/usr/lib"!"lib" +"/usr/"!"usr" +"/"!"/" +"///"!"/" +"//usr//lib//"!"lib" +.TE +.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\(hy2008, +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIbasename\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/bind.3p b/man-pages-posix-2013/man3p/bind.3p new file mode 100644 index 0000000..8af6d9e --- /dev/null +++ b/man-pages-posix-2013/man3p/bind.3p @@ -0,0 +1,290 @@ +'\" et +.TH BIND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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 names 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 +\fB +#define MY_SOCK_PATH "/somepath" +.P +int sfd; +struct sockaddr_un my_addr; +.P +sfd = socket(AF_UNIX, SOCK_STREAM, 0); +if (sfd == \(mi1) + /* Handle error */; +.P +memset(&my_addr, '\e0', 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) \(mi1); +.P +if (bind(sfd, (struct sockaddr *) &my_addr, + sizeof(struct sockaddr_un)) == \(mi1) + /* Handle error */; +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/bsearch.3p b/man-pages-posix-2013/man3p/bsearch.3p new file mode 100644 index 0000000..bff1b94 --- /dev/null +++ b/man-pages-posix-2013/man3p/bsearch.3p @@ -0,0 +1,193 @@ +'\" et +.TH BSEARCH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +#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 \fR +.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 +\fB +((char *)p \(mi (char *(base) % width == 0 +(char *)p >= (char *)base +(char *)p < (char *)base + nel * width +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/btowc.3p b/man-pages-posix-2013/man3p/btowc.3p new file mode 100644 index 0000000..8065db0 --- /dev/null +++ b/man-pages-posix-2013/man3p/btowc.3p @@ -0,0 +1,79 @@ +'\" et +.TH BTOWC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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. +.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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/cabs.3p b/man-pages-posix-2013/man3p/cabs.3p new file mode 100644 index 0000000..1ee6a6d --- /dev/null +++ b/man-pages-posix-2013/man3p/cabs.3p @@ -0,0 +1,64 @@ +'\" et +.TH CABS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/cacos.3p b/man-pages-posix-2013/man3p/cacos.3p new file mode 100644 index 0000000..3a7f79f --- /dev/null +++ b/man-pages-posix-2013/man3p/cacos.3p @@ -0,0 +1,69 @@ +'\" et +.TH CACOS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the complex arc cosine of +.IR z , +with branch cuts outside the interval [\(mi1,\ +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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/cacosh.3p b/man-pages-posix-2013/man3p/cacosh.3p new file mode 100644 index 0000000..ef3866f --- /dev/null +++ b/man-pages-posix-2013/man3p/cacosh.3p @@ -0,0 +1,69 @@ +'\" et +.TH CACOSH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 [\(mi\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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/cacosl.3p b/man-pages-posix-2013/man3p/cacosl.3p new file mode 100644 index 0000000..281ccc2 --- /dev/null +++ b/man-pages-posix-2013/man3p/cacosl.3p @@ -0,0 +1,38 @@ +'\" et +.TH CACOSL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/calloc.3p b/man-pages-posix-2013/man3p/calloc.3p new file mode 100644 index 0000000..aa27402 --- /dev/null +++ b/man-pages-posix-2013/man3p/calloc.3p @@ -0,0 +1,104 @@ +'\" et +.TH CALLOC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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: the value +returned shall be either a null pointer or a unique pointer. +.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 a null pointer or a unique pointer value that can be +successfully passed to +\fIfree\fR() +shall be returned. 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/carg.3p b/man-pages-posix-2013/man3p/carg.3p new file mode 100644 index 0000000..0fbe9dc --- /dev/null +++ b/man-pages-posix-2013/man3p/carg.3p @@ -0,0 +1,69 @@ +'\" et +.TH CARG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +[\(mi\(*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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/casin.3p b/man-pages-posix-2013/man3p/casin.3p new file mode 100644 index 0000000..d5c35b8 --- /dev/null +++ b/man-pages-posix-2013/man3p/casin.3p @@ -0,0 +1,69 @@ +'\" et +.TH CASIN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the complex arc sine of +.IR z , +with branch cuts outside the interval [\(mi1,\ +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 [\(mi\(*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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/casinh.3p b/man-pages-posix-2013/man3p/casinh.3p new file mode 100644 index 0000000..e3cd49b --- /dev/null +++ b/man-pages-posix-2013/man3p/casinh.3p @@ -0,0 +1,70 @@ +'\" et +.TH CASINH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 [\(mi\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 [\(mi\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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/casinl.3p b/man-pages-posix-2013/man3p/casinl.3p new file mode 100644 index 0000000..6305a23 --- /dev/null +++ b/man-pages-posix-2013/man3p/casinl.3p @@ -0,0 +1,38 @@ +'\" et +.TH CASINL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/catan.3p b/man-pages-posix-2013/man3p/catan.3p new file mode 100644 index 0000000..bb01b0a --- /dev/null +++ b/man-pages-posix-2013/man3p/catan.3p @@ -0,0 +1,69 @@ +'\" et +.TH CATAN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the complex arc tangent of +.IR z , +with branch cuts outside the interval [\(mi\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 [\(mi\(*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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/catanh.3p b/man-pages-posix-2013/man3p/catanh.3p new file mode 100644 index 0000000..5135f5c --- /dev/null +++ b/man-pages-posix-2013/man3p/catanh.3p @@ -0,0 +1,70 @@ +'\" et +.TH CATANH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 [\(mi1,\ +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 [\(mi\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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/catanl.3p b/man-pages-posix-2013/man3p/catanl.3p new file mode 100644 index 0000000..b0bfce8 --- /dev/null +++ b/man-pages-posix-2013/man3p/catanl.3p @@ -0,0 +1,38 @@ +'\" et +.TH CATANL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/catclose.3p b/man-pages-posix-2013/man3p/catclose.3p new file mode 100644 index 0000000..45aeb20 --- /dev/null +++ b/man-pages-posix-2013/man3p/catclose.3p @@ -0,0 +1,77 @@ +'\" et +.TH CATCLOSE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/catgets.3p b/man-pages-posix-2013/man3p/catgets.3p new file mode 100644 index 0000000..9a136b0 --- /dev/null +++ b/man-pages-posix-2013/man3p/catgets.3p @@ -0,0 +1,125 @@ +'\" et +.TH CATGETS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/catopen.3p b/man-pages-posix-2013/man3p/catopen.3p new file mode 100644 index 0000000..a53908f --- /dev/null +++ b/man-pages-posix-2013/man3p/catopen.3p @@ -0,0 +1,195 @@ +'\" et +.TH CATOPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 complete name 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\(hy2008, +.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\(hy2008, +.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 ) +\(mi1 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. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcatclose\fR\^(\|)", +.IR "\fIcatgets\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/cbrt.3p b/man-pages-posix-2013/man3p/cbrt.3p new file mode 100644 index 0000000..813f263 --- /dev/null +++ b/man-pages-posix-2013/man3p/cbrt.3p @@ -0,0 +1,81 @@ +'\" et +.TH CBRT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/ccos.3p b/man-pages-posix-2013/man3p/ccos.3p new file mode 100644 index 0000000..727ed37 --- /dev/null +++ b/man-pages-posix-2013/man3p/ccos.3p @@ -0,0 +1,65 @@ +'\" et +.TH CCOS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/ccosh.3p b/man-pages-posix-2013/man3p/ccosh.3p new file mode 100644 index 0000000..d3f3cb2 --- /dev/null +++ b/man-pages-posix-2013/man3p/ccosh.3p @@ -0,0 +1,65 @@ +'\" et +.TH CCOSH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/ccosl.3p b/man-pages-posix-2013/man3p/ccosl.3p new file mode 100644 index 0000000..bebfe75 --- /dev/null +++ b/man-pages-posix-2013/man3p/ccosl.3p @@ -0,0 +1,38 @@ +'\" et +.TH CCOSL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/ceil.3p b/man-pages-posix-2013/man3p/ceil.3p new file mode 100644 index 0000000..7ae4304 --- /dev/null +++ b/man-pages-posix-2013/man3p/ceil.3p @@ -0,0 +1,101 @@ +'\" et +.TH CEIL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/cexp.3p b/man-pages-posix-2013/man3p/cexp.3p new file mode 100644 index 0000000..18a10f8 --- /dev/null +++ b/man-pages-posix-2013/man3p/cexp.3p @@ -0,0 +1,67 @@ +'\" et +.TH CEXP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/cfgetispeed.3p b/man-pages-posix-2013/man3p/cfgetispeed.3p new file mode 100644 index 0000000..20b1192 --- /dev/null +++ b/man-pages-posix-2013/man3p/cfgetispeed.3p @@ -0,0 +1,126 @@ +'\" et +.TH CFGETISPEED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008 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\(hy2008 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/cfgetospeed.3p b/man-pages-posix-2013/man3p/cfgetospeed.3p new file mode 100644 index 0000000..0c53117 --- /dev/null +++ b/man-pages-posix-2013/man3p/cfgetospeed.3p @@ -0,0 +1,75 @@ +'\" et +.TH CFGETOSPEED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/cfsetispeed.3p b/man-pages-posix-2013/man3p/cfsetispeed.3p new file mode 100644 index 0000000..e028f07 --- /dev/null +++ b/man-pages-posix-2013/man3p/cfsetispeed.3p @@ -0,0 +1,94 @@ +'\" et +.TH CFSETISPEED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/cfsetospeed.3p b/man-pages-posix-2013/man3p/cfsetospeed.3p new file mode 100644 index 0000000..be606b0 --- /dev/null +++ b/man-pages-posix-2013/man3p/cfsetospeed.3p @@ -0,0 +1,94 @@ +'\" et +.TH CFSETOSPEED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/chdir.3p b/man-pages-posix-2013/man3p/chdir.3p new file mode 100644 index 0000000..a09c219 --- /dev/null +++ b/man-pages-posix-2013/man3p/chdir.3p @@ -0,0 +1,131 @@ +'\" et +.TH CHDIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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 +\fB +#include +\&... +char *directory = "/tmp"; +int ret; +.P +ret = chdir (directory); +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/chmod.3p b/man-pages-posix-2013/man3p/chmod.3p new file mode 100644 index 0000000..181c01d --- /dev/null +++ b/man-pages-posix-2013/man3p/chmod.3p @@ -0,0 +1,365 @@ +'\" et +.TH CHMOD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 relative to directory file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int chmod(const char *\fIpath\fP, mode_t \fImode\fP); +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 file descriptor was +opened without O_SEARCH, the function shall check whether directory +searches are permitted using the current permissions of the directory +underlying the file descriptor. If the file descriptor was opened with +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 \(mi1 and set +.IR errno +to indicate the error. If \(mi1 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 +.IR fd +was not opened with 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. +.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 +\fB +#include +.P +const char *path; +\&... +chmod(path, S_IRUSR|S_IRGRP|S_IROTH); +.fi \fR +.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 +\fB +#include +.P +const char *path; +\&... +chmod(path, S_IRWXU); +.fi \fR +.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 +\fB +#include +.P +#define CHANGEFILE "/etc/myfile" +\&... +chmod(CHANGEFILE, S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH); +.fi \fR +.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 +\fB +#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 \fR +.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\(hy2008 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/chown.3p b/man-pages-posix-2013/man3p/chown.3p new file mode 100644 index 0000000..5dc8ed6 --- /dev/null +++ b/man-pages-posix-2013/man3p/chown.3p @@ -0,0 +1,323 @@ +'\" et +.TH CHOWN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 relative to directory +file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int chown(const char *\fIpath\fP, uid_t \fIowner\fP, gid_t \fIgroup\fP); +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 )\(mi1 +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 )\(mi1 +or (\c +.BR gid_t )\(mi1, +respectively, the corresponding ID of the file shall not be changed. +If both owner and group are \(mi1, the times need not be updated. +.P +Upon successful completion, +\fIchown\fR() +shall mark for update the last file status change timestamp of the file. +.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 file descriptor was +opened without O_SEARCH, the function shall check whether directory +searches are permitted using the current permissions of the directory +underlying the file descriptor. If the file descriptor was opened with +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 \(mi1 and set +.IR errno +to indicate the error. If \(mi1 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 +.IR fd +was not opened with 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\(hy2008 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/cimag.3p b/man-pages-posix-2013/man3p/cimag.3p new file mode 100644 index 0000000..5f96a6d --- /dev/null +++ b/man-pages-posix-2013/man3p/cimag.3p @@ -0,0 +1,78 @@ +'\" et +.TH CIMAG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +z == creal(z) + cimag(z)*I +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/clearerr.3p b/man-pages-posix-2013/man3p/clearerr.3p new file mode 100644 index 0000000..2460d64 --- /dev/null +++ b/man-pages-posix-2013/man3p/clearerr.3p @@ -0,0 +1,73 @@ +'\" et +.TH CLEARERR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/clock.3p b/man-pages-posix-2013/man3p/clock.3p new file mode 100644 index 0000000..8e5853c --- /dev/null +++ b/man-pages-posix-2013/man3p/clock.3p @@ -0,0 +1,95 @@ +'\" et +.TH CLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 )\(mi1. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +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. +.P +The value returned by +\fIclock\fR() +may wrap around on some implementations. For example, on a machine with +32-bit values for +.BR clock_t , +it wraps after 2\|147 seconds or 36 minutes. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIasctime\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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/clock_getcpuclockid.3p b/man-pages-posix-2013/man3p/clock_getcpuclockid.3p new file mode 100644 index 0000000..4b3eb73 --- /dev/null +++ b/man-pages-posix-2013/man3p/clock_getcpuclockid.3p @@ -0,0 +1,98 @@ +'\" et +.TH CLOCK_GETCPUCLOCKID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/clock_getres.3p b/man-pages-posix-2013/man3p/clock_getres.3p new file mode 100644 index 0000000..58c42f6 --- /dev/null +++ b/man-pages-posix-2013/man3p/clock_getres.3p @@ -0,0 +1,284 @@ +'\" et +.TH CLOCK_GETRES "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/clock_nanosleep.3p b/man-pages-posix-2013/man3p/clock_nanosleep.3p new file mode 100644 index 0000000..000d3b2 --- /dev/null +++ b/man-pages-posix-2013/man3p/clock_nanosleep.3p @@ -0,0 +1,261 @@ +'\" et +.TH CLOCK_NANOSLEEP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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). 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/clock_settime.3p b/man-pages-posix-2013/man3p/clock_settime.3p new file mode 100644 index 0000000..1a03aac --- /dev/null +++ b/man-pages-posix-2013/man3p/clock_settime.3p @@ -0,0 +1,38 @@ +'\" et +.TH CLOCK_SETTIME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/clog.3p b/man-pages-posix-2013/man3p/clog.3p new file mode 100644 index 0000000..3fe3620 --- /dev/null +++ b/man-pages-posix-2013/man3p/clog.3p @@ -0,0 +1,71 @@ +'\" et +.TH CLOG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 [\(mi\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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/close.3p b/man-pages-posix-2013/man3p/close.3p new file mode 100644 index 0000000..98910e8 --- /dev/null +++ b/man-pages-posix-2013/man3p/close.3p @@ -0,0 +1,329 @@ +'\" et +.TH CLOSE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\(mi1 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 \(mi1 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, \(mi1 +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 +\fB +#include +\&... +int pfd; +\&... +close(1); +dup(pfd); +close(pfd); +\&... +.fi \fR +.P +.RE +.P +Incidentally, this is exactly what could be achieved using: +.sp +.RS 4 +.nf +\fB +dup2(pfd, 1); +close(pfd); +.fi \fR +.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 +\fB +#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 \fR +.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 . +.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\(hy2008 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 "\fIexec\fR\^", +.IR "\fIfattach\fR\^(\|)", +.IR "\fIfclose\fR\^(\|)", +.IR "\fIfdetach\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIioctl\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/closedir.3p b/man-pages-posix-2013/man3p/closedir.3p new file mode 100644 index 0000000..3a27757 --- /dev/null +++ b/man-pages-posix-2013/man3p/closedir.3p @@ -0,0 +1,108 @@ +'\" et +.TH CLOSEDIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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 +\fB +\&... + DIR *dir; + struct dirent *dp; +\&... + if ((dir = opendir (".")) == NULL) { +\&... + } +.P + while ((dp = readdir (dir)) != NULL) { +\&... + } +.P + closedir(dir); +\&... +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/closelog.3p b/man-pages-posix-2013/man3p/closelog.3p new file mode 100644 index 0000000..e29a69e --- /dev/null +++ b/man-pages-posix-2013/man3p/closelog.3p @@ -0,0 +1,291 @@ +'\" et +.TH CLOSELOG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +#include +.P +char *ident = "Process demo"; +int logopt = LOG_PID | LOG_CONS; +int facility = LOG_USER; +\&... +openlog(ident, logopt, facility); +.fi \fR +.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 +\fB +#include +.P +int result; +int mask = LOG_MASK (LOG_ERR); +\&... +result = setlogmask(mask); +.fi \fR +.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 +\fB +#include +.P +char *message = "This is a message"; +int priority = LOG_ERR | LOG_USER; +\&... +syslog(priority, message); +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/confstr.3p b/man-pages-posix-2013/man3p/confstr.3p new file mode 100644 index 0000000..01f2f3d --- /dev/null +++ b/man-pages-posix-2013/man3p/confstr.3p @@ -0,0 +1,278 @@ +'\" et +.TH CONFSTR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 +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 +\fB +confstr(_CS_V7_ENV, buf, sizeof(buf)) +.fi \fR +.P +.RE +.P +the string stored in +.IR buf +will contain the +-separated +list of variable=value environment variable pairs required by the +implementation to create 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 +\fB +confstr(_CS_PATH, buf, sizeof(buf)) +.fi \fR +.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, 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\(hy2008, 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 +\fB +confstr(name, (char *)NULL, (size_t)0) +.fi \fR +.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 +\fB +popen("command -p getconf variable", "r"); +.fi \fR +.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\(hy2008. +.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\(hy2008, +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIc99\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/conj.3p b/man-pages-posix-2013/man3p/conj.3p new file mode 100644 index 0000000..f15209f --- /dev/null +++ b/man-pages-posix-2013/man3p/conj.3p @@ -0,0 +1,69 @@ +'\" et +.TH CONJ "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/connect.3p b/man-pages-posix-2013/man3p/connect.3p new file mode 100644 index 0000000..bff7364 --- /dev/null +++ b/man-pages-posix-2013/man3p/connect.3p @@ -0,0 +1,301 @@ +'\" et +.TH CONNECT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/copysign.3p b/man-pages-posix-2013/man3p/copysign.3p new file mode 100644 index 0000000..082437a --- /dev/null +++ b/man-pages-posix-2013/man3p/copysign.3p @@ -0,0 +1,74 @@ +'\" et +.TH COPYSIGN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/cos.3p b/man-pages-posix-2013/man3p/cos.3p new file mode 100644 index 0000000..e4c2fd1 --- /dev/null +++ b/man-pages-posix-2013/man3p/cos.3p @@ -0,0 +1,126 @@ +'\" et +.TH COS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +#include +\&... +double radians = 45 * M_PI / 180; +double result; +\&... +result = cos(radians); +.fi \fR +.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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/cosh.3p b/man-pages-posix-2013/man3p/cosh.3p new file mode 100644 index 0000000..73d8350 --- /dev/null +++ b/man-pages-posix-2013/man3p/cosh.3p @@ -0,0 +1,124 @@ +'\" et +.TH COSH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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. +.P +For IEEE\ Std\ 754\(hy1985 +.BR double , +710.5 < |\fIx\fP| implies that +.IR cosh (\c +.IR x ) +has overflowed. +.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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/cosl.3p b/man-pages-posix-2013/man3p/cosl.3p new file mode 100644 index 0000000..2ee1234 --- /dev/null +++ b/man-pages-posix-2013/man3p/cosl.3p @@ -0,0 +1,38 @@ +'\" et +.TH COSL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/cpow.3p b/man-pages-posix-2013/man3p/cpow.3p new file mode 100644 index 0000000..34eb021 --- /dev/null +++ b/man-pages-posix-2013/man3p/cpow.3p @@ -0,0 +1,68 @@ +'\" et +.TH CPOW "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/cproj.3p b/man-pages-posix-2013/man3p/cproj.3p new file mode 100644 index 0000000..f521162 --- /dev/null +++ b/man-pages-posix-2013/man3p/cproj.3p @@ -0,0 +1,104 @@ +'\" et +.TH CPROJ "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +INFINITY + I * copysign(0.0, cimag(z)) +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/creal.3p b/man-pages-posix-2013/man3p/creal.3p new file mode 100644 index 0000000..0953fd7 --- /dev/null +++ b/man-pages-posix-2013/man3p/creal.3p @@ -0,0 +1,79 @@ +'\" et +.TH CREAL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +z == creal(z) + cimag(z)*I +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/creat.3p b/man-pages-posix-2013/man3p/creat.3p new file mode 100644 index 0000000..e97c847 --- /dev/null +++ b/man-pages-posix-2013/man3p/creat.3p @@ -0,0 +1,104 @@ +'\" et +.TH CREAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +int creat(const char *path, mode_t mode) +{ + return open(path, O_WRONLY|O_CREAT|O_TRUNC, mode); +} +.fi \fR +.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 +\fB +#include +\&... +int fd; +mode_t mode = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH; +char *pathname = "/tmp/file"; +\&... +fd = creat(pathname, mode); +\&... +.fi \fR +.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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/crypt.3p b/man-pages-posix-2013/man3p/crypt.3p new file mode 100644 index 0000000..697bed3 --- /dev/null +++ b/man-pages-posix-2013/man3p/crypt.3p @@ -0,0 +1,155 @@ +'\" et +.TH CRYPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +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 \fR +.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 +\fB +#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 \fR +.P +.RE +.SH "APPLICATION USAGE" +The values returned by this function need not be portable among +XSI-conformant systems. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIencrypt\fR\^(\|)", +.IR "\fIsetkey\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/csin.3p b/man-pages-posix-2013/man3p/csin.3p new file mode 100644 index 0000000..98c185c --- /dev/null +++ b/man-pages-posix-2013/man3p/csin.3p @@ -0,0 +1,65 @@ +'\" et +.TH CSIN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/csinh.3p b/man-pages-posix-2013/man3p/csinh.3p new file mode 100644 index 0000000..9cd401d --- /dev/null +++ b/man-pages-posix-2013/man3p/csinh.3p @@ -0,0 +1,65 @@ +'\" et +.TH CSINH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/csinl.3p b/man-pages-posix-2013/man3p/csinl.3p new file mode 100644 index 0000000..2c78758 --- /dev/null +++ b/man-pages-posix-2013/man3p/csinl.3p @@ -0,0 +1,38 @@ +'\" et +.TH CSINL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/csqrt.3p b/man-pages-posix-2013/man3p/csqrt.3p new file mode 100644 index 0000000..947a09a --- /dev/null +++ b/man-pages-posix-2013/man3p/csqrt.3p @@ -0,0 +1,68 @@ +'\" et +.TH CSQRT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/ctan.3p b/man-pages-posix-2013/man3p/ctan.3p new file mode 100644 index 0000000..67525a0 --- /dev/null +++ b/man-pages-posix-2013/man3p/ctan.3p @@ -0,0 +1,65 @@ +'\" et +.TH CTAN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/ctanh.3p b/man-pages-posix-2013/man3p/ctanh.3p new file mode 100644 index 0000000..f174d10 --- /dev/null +++ b/man-pages-posix-2013/man3p/ctanh.3p @@ -0,0 +1,65 @@ +'\" et +.TH CTANH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/ctanl.3p b/man-pages-posix-2013/man3p/ctanl.3p new file mode 100644 index 0000000..ba2ee73 --- /dev/null +++ b/man-pages-posix-2013/man3p/ctanl.3p @@ -0,0 +1,38 @@ +'\" et +.TH CTANL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/ctermid.3p b/man-pages-posix-2013/man3p/ctermid.3p new file mode 100644 index 0000000..4fd8f2d --- /dev/null +++ b/man-pages-posix-2013/man3p/ctermid.3p @@ -0,0 +1,144 @@ +'\" et +.TH CTERMID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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(). +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 +\fB +#include +\&... +char term[L_ctermid]; +char *ptr; +.P +ptr = ctermid(term); +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/ctime.3p b/man-pages-posix-2013/man3p/ctime.3p new file mode 100644 index 0000000..00681b8 --- /dev/null +++ b/man-pages-posix-2013/man3p/ctime.3p @@ -0,0 +1,173 @@ +'\" et +.TH CTIME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +asctime(localtime(clock)) +.fi \fR +.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() +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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/daylight.3p b/man-pages-posix-2013/man3p/daylight.3p new file mode 100644 index 0000000..e5a0836 --- /dev/null +++ b/man-pages-posix-2013/man3p/daylight.3p @@ -0,0 +1,38 @@ +'\" et +.TH DAYLIGHT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/dbm_clearerr.3p b/man-pages-posix-2013/man3p/dbm_clearerr.3p new file mode 100644 index 0000000..4047ec5 --- /dev/null +++ b/man-pages-posix-2013/man3p/dbm_clearerr.3p @@ -0,0 +1,403 @@ +'\" et +.TH DBM_CLEARERR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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}\(mi4 +bytes (including the terminating null), or pathnames with a last +component longer than +{NAME_MAX}\(mi4 +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 +\fB +for(key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db)) +.fi \fR +.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}\(mi4 +bytes, with the last component of the pathname no greater than +{NAME_MAX}\(mi4 +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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/difftime.3p b/man-pages-posix-2013/man3p/difftime.3p new file mode 100644 index 0000000..7027e44 --- /dev/null +++ b/man-pages-posix-2013/man3p/difftime.3p @@ -0,0 +1,78 @@ +'\" et +.TH DIFFTIME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(mi +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/dirfd.3p b/man-pages-posix-2013/man3p/dirfd.3p new file mode 100644 index 0000000..a3f1b5d --- /dev/null +++ b/man-pages-posix-2013/man3p/dirfd.3p @@ -0,0 +1,130 @@ +'\" et +.TH DIRFD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 and may 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. +.TP +.BR ENOTSUP +The implementation does not support the association of a file +descriptor with a directory. +.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\(hy2008 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 +An implementation that does not support file descriptors referring to +directories may fail with +.BR [ENOTSUP] . +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/dirname.3p b/man-pages-posix-2013/man3p/dirname.3p new file mode 100644 index 0000000..41e8bd5 --- /dev/null +++ b/man-pages-posix-2013/man3p/dirname.3p @@ -0,0 +1,162 @@ +'\" et +.TH DIRNAME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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. Trailing +.BR '/' +characters in the path are not 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 need not be thread-safe. +.SH "RETURN VALUE" +The +\fIdirname\fR() +function shall return a pointer to a string that is the parent +directory of +.IR path . +If +.IR path +is a null pointer or points to an empty string, a pointer to a string +.BR \(dq.\(dq +is returned. +.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(). +.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 +\fB +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 \fR +.P +.RE +.SS "Sample Input and Output Strings for dirname(\|)" +.P +In the following table, the input string is the value pointed to by +.IR path , +and the output string is the return value of the +\fIdirname\fR() +function. +.TS +center tab(!) box; +cB | cB +lf5 | lf5. +Input String!Output String +_ +"/usr/lib"!"/usr" +"/usr/"!"/" +"usr"!"." +"/"!"/" +"."!"." +".."!"." +.TE +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/div.3p b/man-pages-posix-2013/man3p/div.3p new file mode 100644 index 0000000..5dc211d --- /dev/null +++ b/man-pages-posix-2013/man3p/div.3p @@ -0,0 +1,88 @@ +'\" et +.TH DIV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +int quot; /* quotient */ +int rem; /* remainder */ +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/dlclose.3p b/man-pages-posix-2013/man3p/dlclose.3p new file mode 100644 index 0000000..063ab5e --- /dev/null +++ b/man-pages-posix-2013/man3p/dlclose.3p @@ -0,0 +1,141 @@ +'\" et +.TH DLCLOSE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +#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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/dlerror.3p b/man-pages-posix-2013/man3p/dlerror.3p new file mode 100644 index 0000000..dce70ff --- /dev/null +++ b/man-pages-posix-2013/man3p/dlerror.3p @@ -0,0 +1,109 @@ +'\" et +.TH DLERROR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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). +.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 +\fB +\&... +#include +.P +char *errstr; +.P +errstr = dlerror(); +if (errstr != NULL) + printf ("A dynamic linking error occurred: (%s)\en", errstr); +\&... +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/dlopen.3p b/man-pages-posix-2013/man3p/dlopen.3p new file mode 100644 index 0000000..18f854c --- /dev/null +++ b/man-pages-posix-2013/man3p/dlopen.3p @@ -0,0 +1,268 @@ +'\" et +.TH DLOPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/dlsym.3p b/man-pages-posix-2013/man3p/dlsym.3p new file mode 100644 index 0000000..f9c6692 --- /dev/null +++ b/man-pages-posix-2013/man3p/dlsym.3p @@ -0,0 +1,190 @@ +'\" et +.TH DLSYM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +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 \fR +.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 +\fB +fptr = (int (*)(int))dlsym(handle, "my_function"); +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/dprintf.3p b/man-pages-posix-2013/man3p/dprintf.3p new file mode 100644 index 0000000..7007d8e --- /dev/null +++ b/man-pages-posix-2013/man3p/dprintf.3p @@ -0,0 +1,37 @@ +'\" et +.TH DPRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/drand48.3p b/man-pages-posix-2013/man3p/drand48.3p new file mode 100644 index 0000000..72e7546 --- /dev/null +++ b/man-pages-posix-2013/man3p/drand48.3p @@ -0,0 +1,240 @@ +'\" et +.TH DRAND48 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of 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 [\(mi2\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" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIrand\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/dup.3p b/man-pages-posix-2013/man3p/dup.3p new file mode 100644 index 0000000..744f320 --- /dev/null +++ b/man-pages-posix-2013/man3p/dup.3p @@ -0,0 +1,262 @@ +'\" et +.TH DUP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +fcntl(fildes, F_DUPFD, 0); +.fi \fR +.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 \(mi1 without changing the open file description to which +.IR fildes2 +refers. If +.IR fildes +is not a valid file descriptor, +\fIdup2\fR() +shall return \(mi1 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 \(mi1 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, \(mi1 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 +\fB +#include +\&... +int pfd; +\&... +close(1); +dup(pfd); +close(pfd); +\&... +.fi \fR +.P +.RE +.SS "Redirecting Error Messages" +.P +The following example redirects messages from +.IR stderr +to +.IR stdout . +.sp +.RS 4 +.nf +\fB +#include +\&... +dup2(1, 2); +\&... +.fi \fR +.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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/duplocale.3p b/man-pages-posix-2013/man3p/duplocale.3p new file mode 100644 index 0000000..c3e1a74 --- /dev/null +++ b/man-pages-posix-2013/man3p/duplocale.3p @@ -0,0 +1,150 @@ +'\" et +.TH DUPLOCALE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +#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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/encrypt.3p b/man-pages-posix-2013/man3p/encrypt.3p new file mode 100644 index 0000000..d15534a --- /dev/null +++ b/man-pages-posix-2013/man3p/encrypt.3p @@ -0,0 +1,118 @@ +'\" et +.TH ENCRYPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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" +None. +.SH "SEE ALSO" +.IR "\fIcrypt\fR\^(\|)", +.IR "\fIsetkey\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/endgrent.3p b/man-pages-posix-2013/man3p/endgrent.3p new file mode 100644 index 0000000..89e9189 --- /dev/null +++ b/man-pages-posix-2013/man3p/endgrent.3p @@ -0,0 +1,132 @@ +'\" et +.TH ENDGRENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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. When first called, +\fIgetgrent\fR() +shall return a pointer to a +.BR group +structure containing the first entry in the group database. Thereafter, +it shall return a pointer to a +.BR group +structure containing the next 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 to allow repeated searches. +.P +The +\fIendgrent\fR() +function may be called to close the group database when processing is +complete. +.P +These functions need not be thread-safe. +.SH "RETURN VALUE" +When first called, +\fIgetgrent\fR() +shall return a pointer to the first group structure in the group +database. Upon subsequent calls it shall return the next group +structure in the group database. The +\fIgetgrent\fR() +function shall return a null pointer on end-of-file or an error and +.IR errno +may 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(). +.SH ERRORS +The +\fIgetgrent\fR() +function may fail if: +.TP +.BR EINTR +A signal was caught during the operation. +.TP +.BR EIO +An I/O error has occurred. +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/endhostent.3p b/man-pages-posix-2013/man3p/endhostent.3p new file mode 100644 index 0000000..45b54e1 --- /dev/null +++ b/man-pages-posix-2013/man3p/endhostent.3p @@ -0,0 +1,109 @@ +'\" et +.TH ENDHOSTENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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(). +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/endnetent.3p b/man-pages-posix-2013/man3p/endnetent.3p new file mode 100644 index 0000000..b0a3fdb --- /dev/null +++ b/man-pages-posix-2013/man3p/endnetent.3p @@ -0,0 +1,143 @@ +'\" et +.TH ENDNETENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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(). +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/endprotoent.3p b/man-pages-posix-2013/man3p/endprotoent.3p new file mode 100644 index 0000000..7cfaee8 --- /dev/null +++ b/man-pages-posix-2013/man3p/endprotoent.3p @@ -0,0 +1,137 @@ +'\" et +.TH ENDPROTOENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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(). +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/endpwent.3p b/man-pages-posix-2013/man3p/endpwent.3p new file mode 100644 index 0000000..547d930 --- /dev/null +++ b/man-pages-posix-2013/man3p/endpwent.3p @@ -0,0 +1,165 @@ +'\" et +.TH ENDPWENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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. When first called, +\fIgetpwent\fR() +shall return a pointer to a +.BR passwd +structure containing the first entry in the user 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 effectively rewinds the user database to allow repeated +searches. +.P +The +\fIendpwent\fR() +function may be called to close the user database when processing is +complete. +.P +These functions need not be thread-safe. +.SH "RETURN VALUE" +The +\fIgetpwent\fR() +function shall return a null pointer on end-of-file or 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(). +.SH ERRORS +These functions may fail if: +.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 +\fB +#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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/endservent.3p b/man-pages-posix-2013/man3p/endservent.3p new file mode 100644 index 0000000..386a7b3 --- /dev/null +++ b/man-pages-posix-2013/man3p/endservent.3p @@ -0,0 +1,169 @@ +'\" et +.TH ENDSERVENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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(). +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/endutxent.3p b/man-pages-posix-2013/man3p/endutxent.3p new file mode 100644 index 0000000..9739c4a --- /dev/null +++ b/man-pages-posix-2013/man3p/endutxent.3p @@ -0,0 +1,238 @@ +'\" et +.TH ENDUTXENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/environ.3p b/man-pages-posix-2013/man3p/environ.3p new file mode 100644 index 0000000..bf8d9bb --- /dev/null +++ b/man-pages-posix-2013/man3p/environ.3p @@ -0,0 +1,38 @@ +'\" et +.TH ENVIRON "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "Chapter 8" ", " "Environment Variables". +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/erand48.3p b/man-pages-posix-2013/man3p/erand48.3p new file mode 100644 index 0000000..3c6d421 --- /dev/null +++ b/man-pages-posix-2013/man3p/erand48.3p @@ -0,0 +1,38 @@ +'\" et +.TH ERAND48 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/erf.3p b/man-pages-posix-2013/man3p/erf.3p new file mode 100644 index 0000000..0563e1b --- /dev/null +++ b/man-pages-posix-2013/man3p/erf.3p @@ -0,0 +1,151 @@ +'\" et +.TH ERF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of 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\(hy2008 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 +\fB +#include +.P +double +Phi(const double x1, const double x2) +{ + return ( erf(x2*M_SQRT1_2) \(mi erf(x1*M_SQRT1_2) ) / 2; +} +.fi \fR +.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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/erfc.3p b/man-pages-posix-2013/man3p/erfc.3p new file mode 100644 index 0000000..1a9b738 --- /dev/null +++ b/man-pages-posix-2013/man3p/erfc.3p @@ -0,0 +1,143 @@ +'\" et +.TH ERFC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the complementary error function 1.0 \(mi +.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 \(miInf, +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 +Note for IEEE\ Std\ 754\(hy1985 +.BR double , +26.55 < +.IR x +implies +.IR erfc (\c +.IR x ) +has underflowed. +.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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/erff.3p b/man-pages-posix-2013/man3p/erff.3p new file mode 100644 index 0000000..52cd8f9 --- /dev/null +++ b/man-pages-posix-2013/man3p/erff.3p @@ -0,0 +1,40 @@ +'\" et +.TH ERFF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/errno.3p b/man-pages-posix-2013/man3p/errno.3p new file mode 100644 index 0000000..8a3f9b3 --- /dev/null +++ b/man-pages-posix-2013/man3p/errno.3p @@ -0,0 +1,106 @@ +'\" et +.TH ERRNO "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/exec.3p b/man-pages-posix-2013/man3p/exec.3p new file mode 100644 index 0000000..7ef839d --- /dev/null +++ b/man-pages-posix-2013/man3p/exec.3p @@ -0,0 +1,1344 @@ +'\" et +.TH EXEC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +int main (\fIint argc, char *argv\fP[]); +.fi \fR +.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 +\fB +extern char **environ; +.fi \fR +.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\(hy2008, +.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 +\fB +execl(, arg0, file, arg1, ..., (char *)0); +.fi \fR +.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 +\fB +setlocale(LC_ALL, "C") +.fi \fR +.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\(hy2008 shall be inherited in the +new process image from the old process image. All other thread +attributes defined in this volume of POSIX.1\(hy2008 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\(hy2008 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 \(mi1, 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 +\fB +#include +.P +int ret; +\&... +ret = execl ("/bin/ls", "ls", "-1", (char *)0); +.fi \fR +.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 +\fB +#include +.P +int ret; +char *env[] = { "HOME=/usr/home", "LOGNAME=home", (char *)0 }; +\&... +ret = execle ("/bin/ls", "ls", "-l", (char *)0, env); +.fi \fR +.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 +\fB +#include +.P +int ret; +\&... +ret = execlp ("ls", "ls", "-l", (char *)0); +.fi \fR +.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 +\fB +#include +.P +int ret; +char *cmd[] = { "ls", "-l", (char *)0 }; +\&... +ret = execv ("/bin/ls", cmd); +.fi \fR +.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 +\fB +#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 \fR +.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 +\fB +#include +.P +int ret; +char *cmd[] = { "ls", "-l", (char *)0 }; +\&... +ret = execvp ("ls", cmd); +.fi \fR +.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\(hy2008 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 +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 +\fB +main(void) +.fi \fR +.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\(hy2008 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\(hy2008 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 \(mi\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\(hy2008 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\(hy2008 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\(hy2008 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\(hy2008, 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, an +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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/exit.3p b/man-pages-posix-2013/man3p/exit.3p new file mode 100644 index 0000000..bcfb671 --- /dev/null +++ b/man-pages-posix-2013/man3p/exit.3p @@ -0,0 +1,101 @@ +'\" et +.TH EXIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 to a waiting parent process. +.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\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/exp.3p b/man-pages-posix-2013/man3p/exp.3p new file mode 100644 index 0000000..b487627 --- /dev/null +++ b/man-pages-posix-2013/man3p/exp.3p @@ -0,0 +1,187 @@ +'\" et +.TH EXP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 \(miInf, +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 +\fB +#include +.P +double +normal_density (double x) +{ + return exp(\(mix*x/2) / sqrt (2*M_PI); +} +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +Note that for IEEE\ Std\ 754\(hy1985 +.BR double , +709.8 < +.IR x +implies +.IR exp (\c +.IR x ) +has overflowed. The value +.IR x \c +<\ \(mi708.4 +implies +.IR exp (\c +.IR x ) +has underflowed. +.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 "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIlog\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/exp2.3p b/man-pages-posix-2013/man3p/exp2.3p new file mode 100644 index 0000000..56aeb7b --- /dev/null +++ b/man-pages-posix-2013/man3p/exp2.3p @@ -0,0 +1,165 @@ +'\" et +.TH EXP2 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 \(miInf, +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" +For IEEE\ Std\ 754\(hy1985 +.BR double , +1024 <= +.IR x +implies +.IR exp2 (\c +.IR x ) +has overflowed. The value +.IR x \c +<\ \(mi1022 implies +.IR exp (\c +.IR x ) +has underflowed. +.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 "\fIisnan\fR\^(\|)", +.IR "\fIlog\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/expm1.3p b/man-pages-posix-2013/man3p/expm1.3p new file mode 100644 index 0000000..3e0afa4 --- /dev/null +++ b/man-pages-posix-2013/man3p/expm1.3p @@ -0,0 +1,191 @@ +'\" et +.TH EXPM1 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute \fIe\u\s-3x\s+3\d\fR\(mi1.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\(mi1.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 \(miInf, \(mi1 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 )\(mi1.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\(mi1)/\fIx\fR, namely: +.sp +.RS 4 +.nf +\fB +expm1(\fIn\fP * log1p(\fIx\fP))/\fIx\fP +.fi \fR +.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 +For IEEE\ Std\ 754\(hy1985 +.BR double , +709.8 < +.IR x +implies +.IR expm1 (\c +.IR x ) +has overflowed. +.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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fabs.3p b/man-pages-posix-2013/man3p/fabs.3p new file mode 100644 index 0000000..e3ebcb4 --- /dev/null +++ b/man-pages-posix-2013/man3p/fabs.3p @@ -0,0 +1,119 @@ +'\" et +.TH FABS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +norm1(v) = |v[0]| + |v[1]| + ... + |v[n\(mi1]| +.fi \fR +.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 +\fB +#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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/faccessat.3p b/man-pages-posix-2013/man3p/faccessat.3p new file mode 100644 index 0000000..e8368cc --- /dev/null +++ b/man-pages-posix-2013/man3p/faccessat.3p @@ -0,0 +1,39 @@ +'\" et +.TH FACCESSAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fattach.3p b/man-pages-posix-2013/man3p/fattach.3p new file mode 100644 index 0000000..726e7ee --- /dev/null +++ b/man-pages-posix-2013/man3p/fattach.3p @@ -0,0 +1,234 @@ +'\" et +.TH FATTACH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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 +\fB +#include +\&... + int fd; + char *pathname = "/tmp/named-STREAM"; + int ret; +.P + ret = fattach(fd, pathname); +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fchdir.3p b/man-pages-posix-2013/man3p/fchdir.3p new file mode 100644 index 0000000..2277715 --- /dev/null +++ b/man-pages-posix-2013/man3p/fchdir.3p @@ -0,0 +1,101 @@ +'\" et +.TH FCHDIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fchmod.3p b/man-pages-posix-2013/man3p/fchmod.3p new file mode 100644 index 0000000..20c00e3 --- /dev/null +++ b/man-pages-posix-2013/man3p/fchmod.3p @@ -0,0 +1,159 @@ +'\" et +.TH FCHMOD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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 +\fB +#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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fchmodat.3p b/man-pages-posix-2013/man3p/fchmodat.3p new file mode 100644 index 0000000..d8231f0 --- /dev/null +++ b/man-pages-posix-2013/man3p/fchmodat.3p @@ -0,0 +1,38 @@ +'\" et +.TH FCHMODAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fchown.3p b/man-pages-posix-2013/man3p/fchown.3p new file mode 100644 index 0000000..98dbcc0 --- /dev/null +++ b/man-pages-posix-2013/man3p/fchown.3p @@ -0,0 +1,138 @@ +'\" et +.TH FCHOWN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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 +\fB +#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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fchownat.3p b/man-pages-posix-2013/man3p/fchownat.3p new file mode 100644 index 0000000..444c5cc --- /dev/null +++ b/man-pages-posix-2013/man3p/fchownat.3p @@ -0,0 +1,40 @@ +'\" et +.TH FCHOWNAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fclose.3p b/man-pages-posix-2013/man3p/fclose.3p new file mode 100644 index 0000000..c5f6171 --- /dev/null +++ b/man-pages-posix-2013/man3p/fclose.3p @@ -0,0 +1,166 @@ +'\" et +.TH FCLOSE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIclose\fR\^(\|)", +.IR "\fIfmemopen\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIgetrlimit\fR\^(\|)", +.IR "\fIopen_memstream\fR\^(\|)", +.IR "\fIulimit\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fcntl.3p b/man-pages-posix-2013/man3p/fcntl.3p new file mode 100644 index 0000000..5977fe8 --- /dev/null +++ b/man-pages-posix-2013/man3p/fcntl.3p @@ -0,0 +1,690 @@ +'\" et +.TH FCNTL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 the lowest numbered +available (that is, not already open) 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 or process group ID specified to +receive SIGURG signals when out-of-band data is available. Positive +values indicate a process ID; negative values, other than \(mi1, +indicate a process group ID. 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 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 indicate a process ID; negative values, other than +\(mi1, indicate a process group ID. 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 the first 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 \(mi1. +.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 \(mi1 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 \(mi1. +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 \(mi1. +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 \(mi1. +.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 \(mi1. +.IP F_GETLK 12 +Value other than \(mi1. +.IP F_SETLK 12 +Value other than \(mi1. +.IP F_SETLKW 12 +Value other than \(mi1. +.IP F_GETOWN 12 +Value of the socket owner process or process group; this will not be +\(mi1. +.IP F_SETOWN 12 +Value other than \(mi1. +.P +Otherwise, \(mi1 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 . +.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. +.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 +\fB +#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) == \(mi1) { + if (errno == EACCES || errno == EAGAIN) { + printf("Already locked by another process\en"); +.P + /* We can't 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) == \(mi1) + /* Handle error */; + } + exit(EXIT_SUCCESS); +} /* main */ +.fi \fR +.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 +\fB +#include +#include +\&... + int flags; +.P + flags = fcntl(fd, F_GETFD); + if (flags == \(mi1) + /* Handle error */; + flags |= FD_CLOEXEC; + if (fcntl(fd, F_SETFD, flags) == \(mi1) + /* Handle error */;" +.fi \fR +.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\(hy2008 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. +.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\(hy2008 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\(hy2008 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\(hy2008. 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 "\fIopen\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fdatasync.3p b/man-pages-posix-2013/man3p/fdatasync.3p new file mode 100644 index 0000000..728367a --- /dev/null +++ b/man-pages-posix-2013/man3p/fdatasync.3p @@ -0,0 +1,98 @@ +'\" et +.TH FDATASYNC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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 open for writing. +.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" +None. +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fdetach.3p b/man-pages-posix-2013/man3p/fdetach.3p new file mode 100644 index 0000000..198423f --- /dev/null +++ b/man-pages-posix-2013/man3p/fdetach.3p @@ -0,0 +1,174 @@ +'\" et +.TH FDETACH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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 +\fB +#include +\&... + char *pathname = "/tmp/named-STREAM"; + int ret; +.P + ret = fdetach(pathname); +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fdim.3p b/man-pages-posix-2013/man3p/fdim.3p new file mode 100644 index 0000000..44ea76b --- /dev/null +++ b/man-pages-posix-2013/man3p/fdim.3p @@ -0,0 +1,148 @@ +'\" et +.TH FDIM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 \(mi\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 \(mi\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.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fdopen.3p b/man-pages-posix-2013/man3p/fdopen.3p new file mode 100644 index 0000000..cf1779e --- /dev/null +++ b/man-pages-posix-2013/man3p/fdopen.3p @@ -0,0 +1,194 @@ +'\" et +.TH FDOPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fdopendir.3p b/man-pages-posix-2013/man3p/fdopendir.3p new file mode 100644 index 0000000..8e221e4 --- /dev/null +++ b/man-pages-posix-2013/man3p/fdopendir.3p @@ -0,0 +1,314 @@ +'\" et +.TH FDOPENDIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +#include +\&... + DIR *dir; + struct dirent *dp; +\&... + if ((dir = opendir (".")) == NULL) { + perror ("Cannot open ."); + exit (1); + } +.P + while ((dp = readdir (dir)) != NULL) { +\&... +.fi \fR +.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 +\fB +#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] == '.') + 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 \fR +.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\(hy2008 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\(hy2008 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\(hy2008 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/feclearexcept.3p b/man-pages-posix-2013/man3p/feclearexcept.3p new file mode 100644 index 0000000..7daac9c --- /dev/null +++ b/man-pages-posix-2013/man3p/feclearexcept.3p @@ -0,0 +1,69 @@ +'\" et +.TH FECLEAREXCEPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fegetenv.3p b/man-pages-posix-2013/man3p/fegetenv.3p new file mode 100644 index 0000000..f396fe9 --- /dev/null +++ b/man-pages-posix-2013/man3p/fegetenv.3p @@ -0,0 +1,89 @@ +'\" et +.TH FEGETENV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fegetexceptflag.3p b/man-pages-posix-2013/man3p/fegetexceptflag.3p new file mode 100644 index 0000000..7e86259 --- /dev/null +++ b/man-pages-posix-2013/man3p/fegetexceptflag.3p @@ -0,0 +1,94 @@ +'\" et +.TH FEGETEXCEPTFLAG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fegetround.3p b/man-pages-posix-2013/man3p/fegetround.3p new file mode 100644 index 0000000..f3ba4a5 --- /dev/null +++ b/man-pages-posix-2013/man3p/fegetround.3p @@ -0,0 +1,103 @@ +'\" et +.TH FEGETROUND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +#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 \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/feholdexcept.3p b/man-pages-posix-2013/man3p/feholdexcept.3p new file mode 100644 index 0000000..26ee32b --- /dev/null +++ b/man-pages-posix-2013/man3p/feholdexcept.3p @@ -0,0 +1,76 @@ +'\" et +.TH FEHOLDEXCEPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/feof.3p b/man-pages-posix-2013/man3p/feof.3p new file mode 100644 index 0000000..5ffc49f --- /dev/null +++ b/man-pages-posix-2013/man3p/feof.3p @@ -0,0 +1,78 @@ +'\" et +.TH FEOF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/feraiseexcept.3p b/man-pages-posix-2013/man3p/feraiseexcept.3p new file mode 100644 index 0000000..8a9aff3 --- /dev/null +++ b/man-pages-posix-2013/man3p/feraiseexcept.3p @@ -0,0 +1,82 @@ +'\" et +.TH FERAISEEXCEPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 defers to the ISO\ C standard. +.P +The +\fIferaiseexcept\fR() +function shall attempt to raise the supported floating-point exceptions +represented by the argument +.IR excepts . +The order in which these floating-point exceptions are raised is +unspecified. 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/ferror.3p b/man-pages-posix-2013/man3p/ferror.3p new file mode 100644 index 0000000..7228256 --- /dev/null +++ b/man-pages-posix-2013/man3p/ferror.3p @@ -0,0 +1,77 @@ +'\" et +.TH FERROR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fesetenv.3p b/man-pages-posix-2013/man3p/fesetenv.3p new file mode 100644 index 0000000..4fb238c --- /dev/null +++ b/man-pages-posix-2013/man3p/fesetenv.3p @@ -0,0 +1,38 @@ +'\" et +.TH FESETENV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fesetexceptflag.3p b/man-pages-posix-2013/man3p/fesetexceptflag.3p new file mode 100644 index 0000000..c452f55 --- /dev/null +++ b/man-pages-posix-2013/man3p/fesetexceptflag.3p @@ -0,0 +1,38 @@ +'\" et +.TH FESETEXCEPTFLAG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fesetround.3p b/man-pages-posix-2013/man3p/fesetround.3p new file mode 100644 index 0000000..7578f8b --- /dev/null +++ b/man-pages-posix-2013/man3p/fesetround.3p @@ -0,0 +1,38 @@ +'\" et +.TH FESETROUND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fetestexcept.3p b/man-pages-posix-2013/man3p/fetestexcept.3p new file mode 100644 index 0000000..f2b7b1a --- /dev/null +++ b/man-pages-posix-2013/man3p/fetestexcept.3p @@ -0,0 +1,95 @@ +'\" et +.TH FETESTEXCEPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +#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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/feupdateenv.3p b/man-pages-posix-2013/man3p/feupdateenv.3p new file mode 100644 index 0000000..df6c78f --- /dev/null +++ b/man-pages-posix-2013/man3p/feupdateenv.3p @@ -0,0 +1,98 @@ +'\" et +.TH FEUPDATEENV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +#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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fexecve.3p b/man-pages-posix-2013/man3p/fexecve.3p new file mode 100644 index 0000000..b866db7 --- /dev/null +++ b/man-pages-posix-2013/man3p/fexecve.3p @@ -0,0 +1,37 @@ +'\" et +.TH FEXECVE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fflush.3p b/man-pages-posix-2013/man3p/fflush.3p new file mode 100644 index 0000000..3ddfe4a --- /dev/null +++ b/man-pages-posix-2013/man3p/fflush.3p @@ -0,0 +1,214 @@ +'\" et +.TH FFLUSH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +If +.IR stream +is a null pointer, +\fIfflush\fR() +shall perform this flushing action on all streams for which the +behavior is defined above. +.P +For a stream open for reading, 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). +.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 +\fB +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 &= ~ECHO; +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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/ffs.3p b/man-pages-posix-2013/man3p/ffs.3p new file mode 100644 index 0000000..4b41368 --- /dev/null +++ b/man-pages-posix-2013/man3p/ffs.3p @@ -0,0 +1,66 @@ +'\" et +.TH FFS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fgetc.3p b/man-pages-posix-2013/man3p/fgetc.3p new file mode 100644 index 0000000..fbc8008 --- /dev/null +++ b/man-pages-posix-2013/man3p/fgetc.3p @@ -0,0 +1,175 @@ +'\" et +.TH FGETC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fgetpos.3p b/man-pages-posix-2013/man3p/fgetpos.3p new file mode 100644 index 0000000..913d90c --- /dev/null +++ b/man-pages-posix-2013/man3p/fgetpos.3p @@ -0,0 +1,101 @@ +'\" et +.TH FGETPOS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fgets.3p b/man-pages-posix-2013/man3p/fgets.3p new file mode 100644 index 0000000..bad0ccf --- /dev/null +++ b/man-pages-posix-2013/man3p/fgets.3p @@ -0,0 +1,176 @@ +'\" et +.TH FGETS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 \(mi1 +bytes are read, or a + +is read and transferred to +.IR s , +or an end-of-file condition is encountered. The string is then +terminated with a null byte. +.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 \(mi1 without setting +.IR errno . +This example assumes that +.IR sysconf (_SC_LINE_MAX) +will not fail.) +.sp +.RS 4 +.nf +\fB +#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() can't 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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fgetwc.3p b/man-pages-posix-2013/man3p/fgetwc.3p new file mode 100644 index 0000000..3aa1dc7 --- /dev/null +++ b/man-pages-posix-2013/man3p/fgetwc.3p @@ -0,0 +1,174 @@ +'\" et +.TH FGETWC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fgetws.3p b/man-pages-posix-2013/man3p/fgetws.3p new file mode 100644 index 0000000..96e442a --- /dev/null +++ b/man-pages-posix-2013/man3p/fgetws.3p @@ -0,0 +1,121 @@ +'\" et +.TH FGETWS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 \(mi1 +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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fileno.3p b/man-pages-posix-2013/man3p/fileno.3p new file mode 100644 index 0000000..c47a132 --- /dev/null +++ b/man-pages-posix-2013/man3p/fileno.3p @@ -0,0 +1,88 @@ +'\" et +.TH FILENO "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIfileno\fR() +function may fail if: +.TP +.BR EBADF +The +.IR stream +argument is not a valid stream, or the stream is not associated +with a file. +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/flockfile.3p b/man-pages-posix-2013/man3p/flockfile.3p new file mode 100644 index 0000000..4c2293c --- /dev/null +++ b/man-pages-posix-2013/man3p/flockfile.3p @@ -0,0 +1,190 @@ +'\" et +.TH FLOCKFILE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion". +.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 "\fIgetc_unlocked\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/floor.3p b/man-pages-posix-2013/man3p/floor.3p new file mode 100644 index 0000000..569f1d3 --- /dev/null +++ b/man-pages-posix-2013/man3p/floor.3p @@ -0,0 +1,97 @@ +'\" et +.TH FLOOR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fma.3p b/man-pages-posix-2013/man3p/fma.3p new file mode 100644 index 0000000..75ae21e --- /dev/null +++ b/man-pages-posix-2013/man3p/fma.3p @@ -0,0 +1,209 @@ +'\" et +.TH FMA "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fmax.3p b/man-pages-posix-2013/man3p/fmax.3p new file mode 100644 index 0000000..151663a --- /dev/null +++ b/man-pages-posix-2013/man3p/fmax.3p @@ -0,0 +1,78 @@ +'\" et +.TH FMAX "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fmemopen.3p b/man-pages-posix-2013/man3p/fmemopen.3p new file mode 100644 index 0000000..fa3b384 --- /dev/null +++ b/man-pages-posix-2013/man3p/fmemopen.3p @@ -0,0 +1,280 @@ +'\" et +.TH FMEMOPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 either the position of the first null byte in +the buffer or the value of the +.IR size +argument if 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 EINVAL +The +.IR size +argument specifies a buffer size of zero. +.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 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 +\fB +#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 \fR +.P +.RE +.P +This program produces the following output: +.sp +.RS 4 +.nf +\fB +Got f +Got o +Got o +Got b +Got a +Got r +.fi \fR +.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 revision of this standard may mandate specific behavior when the +.IR mode +argument includes +.BR 'b' . +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fmin.3p b/man-pages-posix-2013/man3p/fmin.3p new file mode 100644 index 0000000..f64ddf8 --- /dev/null +++ b/man-pages-posix-2013/man3p/fmin.3p @@ -0,0 +1,78 @@ +'\" et +.TH FMIN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fmod.3p b/man-pages-posix-2013/man3p/fmod.3p new file mode 100644 index 0000000..eedc0b6 --- /dev/null +++ b/man-pages-posix-2013/man3p/fmod.3p @@ -0,0 +1,167 @@ +'\" et +.TH FMOD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 \(mi\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. +.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.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fmtmsg.3p b/man-pages-posix-2013/man3p/fmtmsg.3p new file mode 100644 index 0000000..1cb1c57 --- /dev/null +++ b/man-pages-posix-2013/man3p/fmtmsg.3p @@ -0,0 +1,247 @@ +'\" et +.TH FMTMSG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +fmtmsg(MM_PRINT, "XSI:cat", MM_ERROR, "illegal option", +"refer to cat in user's reference manual", "XSI:cat:001") +.fi \fR +.P +.RE +.P +produces a complete message in the specified message format: +.sp +.RS 4 +.nf +\fB +XSI:cat: ERROR: illegal option +TO FIX: refer to cat in user's reference manual XSI:cat:001 +.fi \fR +.P +.RE +.RE +.IP " 2." 4 +When the environment variable +.IR MSGVERB +is set as follows: +.RS 4 +.sp +.RS 4 +.nf +\fB +MSGVERB=severity:text:action +.fi \fR +.P +.RE +.P +and Example 1 is used, +\fIfmtmsg\fR() +produces: +.sp +.RS 4 +.nf +\fB +ERROR: illegal option +TO FIX: refer to cat in user's reference manual +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fnmatch.3p b/man-pages-posix-2013/man3p/fnmatch.3p new file mode 100644 index 0000000..d7ab403 --- /dev/null +++ b/man-pages-posix-2013/man3p/fnmatch.3p @@ -0,0 +1,196 @@ +'\" et +.TH FNMATCH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.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 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\(hy2008, +.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\(hy2008. 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fopen.3p b/man-pages-posix-2013/man3p/fopen.3p new file mode 100644 index 0000000..65a1f7d --- /dev/null +++ b/man-pages-posix-2013/man3p/fopen.3p @@ -0,0 +1,354 @@ +'\" et +.TH FOPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +names 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 +\fB +#include +\&... +FILE *fp; +\&... +void rgrep(const char *file) +{ +\&... + if ((fp = fopen(file, "r")) == NULL) + return; +\&... +} +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fork.3p b/man-pages-posix-2013/man3p/fork.3p new file mode 100644 index 0000000..c9dcf0e --- /dev/null +++ b/man-pages-posix-2013/man3p/fork.3p @@ -0,0 +1,435 @@ +'\" et +.TH FORK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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. Fork handlers may be established by means of the +\fIpthread_atfork\fR() +function in order to maintain application invariants across +\fIfork\fR() +calls. +.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, \(mi1 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\(hy2008 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\(hy2008 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\(hy2008. +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\(hy2008. +.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\(hy2008, +.IR "Section 4.11" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fpathconf.3p b/man-pages-posix-2013/man3p/fpathconf.3p new file mode 100644 index 0000000..6aa368a --- /dev/null +++ b/man-pages-posix-2013/man3p/fpathconf.3p @@ -0,0 +1,509 @@ +'\" et +.TH FPATHCONF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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 \(mi1 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 \(mi1 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 \(mi1 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 ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.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 +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. +.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 \(mi1 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 \(mi1 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 \(mi1. +.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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIgetconf\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fpclassify.3p b/man-pages-posix-2013/man3p/fpclassify.3p new file mode 100644 index 0000000..6f01154 --- /dev/null +++ b/man-pages-posix-2013/man3p/fpclassify.3p @@ -0,0 +1,73 @@ +'\" et +.TH FPCLASSIFY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fprintf.3p b/man-pages-posix-2013/man3p/fprintf.3p new file mode 100644 index 0000000..63f2c95 --- /dev/null +++ b/man-pages-posix-2013/man3p/fprintf.3p @@ -0,0 +1,1490 @@ +'\" et +.TH FPRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(mi1\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 '\(mi' ), +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 '\(mi' +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 +\fB +printf("%1$d:%2$.*3$d:%4$.*3$d\en", hour, min, precision, sec); +.fi \fR +.P +.RE +.P +The flag characters and their meanings are: +.IP "\fR'\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\(mi\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 '\(mi' ). +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 increases the precision (if necessary) to force the +first digit of the result to be zero. 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 '\(mi' +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"[\(mi]\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"[\(mi]\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[\(mi]inf\(dq +or +.BR \(dq[\(mi]infinity\(dq ; +which style is implementation-defined. A +.BR double +argument representing a NaN shall be converted in one of the styles +\fR"[\(mi]nan(\fIn-char-sequence\fR)"\fR or +.BR \(dq[\(mi]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"[\(mi]\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 \(>=\(mi4, +the conversion shall be with style +.BR f +(or +.BR F ) +and precision +.BR P \(mi(\c +.IR X +1). +.IP -- 4 +Otherwise, the conversion shall be with style +.BR e +(or +.BR E ) +and precision +.BR P \(mi1. +.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"[\(mi]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 +In addition, all forms of +\fIfprintf\fR() +may fail if: +.TP +.BR EINVAL +There are insufficient arguments. +.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 +\fB +printf(format, weekday, month, day, hour, min); +.fi \fR +.P +.RE +.P +For American usage, +.IR format +could be a pointer to the following string: +.sp +.RS 4 +.nf +\fB +"%s, %s %d, %d:%.2d\en" +.fi \fR +.P +.RE +.P +This example would produce the following message: +.sp +.RS 4 +.nf +\fB +Sunday, July 3, 10:02 +.fi \fR +.P +.RE +.P +For German usage, +.IR format +could be a pointer to the following string: +.sp +.RS 4 +.nf +\fB +"%1$s, %3$d. %2$s, %4$d:%5$.2d\en" +.fi \fR +.P +.RE +.P +This definition of +.IR format +would produce the following message: +.sp +.RS 4 +.nf +\fB +Sonntag, 3. Juli, 10:02 +.fi \fR +.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 +\fB +ls \(mil +.fi \fR +.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 +\fB +#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(" %\(mi8.8s", pwd->pw_name); +else + printf(" %\(mi8ld", (long) statbuf.st_uid); +.P +if ((grp = getgrgid(statbuf.st_gid)) != NULL) + printf(" %\(mi8.8s", grp->gr_name); +else + printf(" %\(mi8ld", (long) statbuf.st_gid); +.P +printf("%9jd", (intmax_t) statbuf.st_size); +\&... +.fi \fR +.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 +\fB +#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 \fR +.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 +\fB +#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)) == \(mi1) +{ + 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 \fR +.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 +\fB +#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 +\fB +#include +\&... +long i; +char *keystr; +int elementlen, len; +\&... +while (len < elementlen) { +\&... + printf("%s Element%0*ld\en", keystr, elementlen, i); +\&... +} +.fi \fR +.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 +\fB +#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 \fR +.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 +\fB +#include +#include +#include +#include +\&... +while (!event_complete) { +\&... + if (pause() != \(mi1 || errno != EINTR) + fprintf(stderr, "pause: unknown error: %s\en", strerror(errno)); +} +\&... +.fi \fR +.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 +\fB +#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" }, + { "%^#5n", "disable the grouping separator" }, + { "%^#5.0n", "round off to whole units" }, + { "%^#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 \fR +.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 +\fB +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 \fR +.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 +None. +.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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fputc.3p b/man-pages-posix-2013/man3p/fputc.3p new file mode 100644 index 0000000..280900d --- /dev/null +++ b/man-pages-posix-2013/man3p/fputc.3p @@ -0,0 +1,157 @@ +'\" et +.TH FPUTC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fputs.3p b/man-pages-posix-2013/man3p/fputs.3p new file mode 100644 index 0000000..a9e2453 --- /dev/null +++ b/man-pages-posix-2013/man3p/fputs.3p @@ -0,0 +1,154 @@ +'\" et +.TH FPUTS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +#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 \fR +.P +.RE +.SH "APPLICATION USAGE" +The +\fIputs\fR() +function appends a + +while +\fIfputs\fR() +does not. +.P +This volume of POSIX.1\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fputwc.3p b/man-pages-posix-2013/man3p/fputwc.3p new file mode 100644 index 0000000..cca9f1d --- /dev/null +++ b/man-pages-posix-2013/man3p/fputwc.3p @@ -0,0 +1,162 @@ +'\" et +.TH FPUTWC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fputws.3p b/man-pages-posix-2013/man3p/fputws.3p new file mode 100644 index 0000000..ea418e0 --- /dev/null +++ b/man-pages-posix-2013/man3p/fputws.3p @@ -0,0 +1,113 @@ +'\" et +.TH FPUTWS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 \(mi1, 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\(hy2008 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fread.3p b/man-pages-posix-2013/man3p/fread.3p new file mode 100644 index 0000000..18baec6 --- /dev/null +++ b/man-pages-posix-2013/man3p/fread.3p @@ -0,0 +1,190 @@ +'\" et +.TH FREAD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 reads a single element from the +.IR fp +stream into the array pointed to by +.IR buf . +.sp +.RS 4 +.nf +\fB +#include +\&... +size_t elements_read; +char buf[100]; +FILE *fp; +\&... +elements_read = fread(buf, sizeof(buf), 1, fp); +\&... +.fi \fR +.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 )\(mi1. +.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 +\fB +#include +\&... +size_t bytes_read; +char buf[100]; +FILE *fp; +\&... +bytes_read = fread(buf, 1, sizeof(buf), fp); +\&... +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/free.3p b/man-pages-posix-2013/man3p/free.3p new file mode 100644 index 0000000..5ec34e1 --- /dev/null +++ b/man-pages-posix-2013/man3p/free.3p @@ -0,0 +1,84 @@ +'\" et +.TH FREE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/freeaddrinfo.3p b/man-pages-posix-2013/man3p/freeaddrinfo.3p new file mode 100644 index 0000000..4dcfcbe --- /dev/null +++ b/man-pages-posix-2013/man3p/freeaddrinfo.3p @@ -0,0 +1,504 @@ +'\" et +.TH FREEADDRINFO "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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. In this +.IR hints +structure every member other than +.IR ai_flags , +.IR ai_family , +.IR ai_socktype , +and +.IR ai_protocol +shall be set to zero or a null pointer. 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 +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 (\c +.IR ai_addrlen +shall be 16). 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 is 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 +\fB +#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 = {}; + 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 \fR +.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 +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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/freelocale.3p b/man-pages-posix-2013/man3p/freelocale.3p new file mode 100644 index 0000000..1ef3cea --- /dev/null +++ b/man-pages-posix-2013/man3p/freelocale.3p @@ -0,0 +1,102 @@ +'\" et +.TH FREELOCALE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +#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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/freopen.3p b/man-pages-posix-2013/man3p/freopen.3p new file mode 100644 index 0000000..9132e43 --- /dev/null +++ b/man-pages-posix-2013/man3p/freopen.3p @@ -0,0 +1,361 @@ +'\" et +.TH FREOPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +names 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 +\fB +#include +\&... +FILE *fp; +\&... +fp = freopen ("/tmp/logfile", "a+", stdout); +\&... +.fi \fR +.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 +\fB +{ appl file1; appl file2; } > file3 +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/frexp.3p b/man-pages-posix-2013/man3p/frexp.3p new file mode 100644 index 0000000..d7af0ea --- /dev/null +++ b/man-pages-posix-2013/man3p/frexp.3p @@ -0,0 +1,97 @@ +'\" et +.TH FREXP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fscanf.3p b/man-pages-posix-2013/man3p/fscanf.3p new file mode 100644 index 0000000..8681c90 --- /dev/null +++ b/man-pages-posix-2013/man3p/fscanf.3p @@ -0,0 +1,880 @@ +'\" et +.TH FSCANF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 \(mi1)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 '^' ), +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[^]\(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 '\(mi' +is in the scanlist and is not the first character, nor the second where +the first character is a +.BR '^' , +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 +\fB +int i, n; float x; char name[50]; +n = scanf("%d%f%s", &i, &x, name); +.fi \fR +.P +.RE +.P +with the input line: +.sp +.RS 4 +.nf +\fB +25 54.32E\(mi1 Hamster +.fi \fR +.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 +\fB +int i; float x; char name[50]; +(void) scanf("%2d%f%*d %[0123456789]", &i, &x, name); +.fi \fR +.P +.RE +.P +with input: +.sp +.RS 4 +.nf +\fB +56789 0123 56a72 +.fi \fR +.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 +\fB +float input[3]; fscanf (stdin, "%f %f %f", input, input+1, input+2); +.fi \fR +.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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fseek.3p b/man-pages-posix-2013/man3p/fseek.3p new file mode 100644 index 0000000..93eb0b1 --- /dev/null +++ b/man-pages-posix-2013/man3p/fseek.3p @@ -0,0 +1,250 @@ +'\" et +.TH FSEEK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fsetpos.3p b/man-pages-posix-2013/man3p/fsetpos.3p new file mode 100644 index 0000000..b9a5f45 --- /dev/null +++ b/man-pages-posix-2013/man3p/fsetpos.3p @@ -0,0 +1,172 @@ +'\" et +.TH FSETPOS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fstat.3p b/man-pages-posix-2013/man3p/fstat.3p new file mode 100644 index 0000000..abc8c2b --- /dev/null +++ b/man-pages-posix-2013/man3p/fstat.3p @@ -0,0 +1,192 @@ +'\" et +.TH FSTAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, 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\(hy2008, +.IR "Section 4.8" ", " "File Times Update"), +before writing into the +.BR stat +structure. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \(mi1 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 +\fB +#include +#include +#include +.P +struct stat buffer; +int status; +\&... +fildes = open("/home/cnd/mod1", O_RDWR); +status = fstat(fildes, &buffer); +.fi \fR +.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\(hy2008, +.IR "Section 4.8" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fstatat.3p b/man-pages-posix-2013/man3p/fstatat.3p new file mode 100644 index 0000000..8b6e2a7 --- /dev/null +++ b/man-pages-posix-2013/man3p/fstatat.3p @@ -0,0 +1,493 @@ +'\" et +.TH FSTATAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +.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\(hy2008, +.IR "Section 4.8" ", " "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\(hy2008, 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 file descriptor was +opened without O_SEARCH, the function shall check whether directory +searches are permitted using the current permissions of the directory +underlying the file descriptor. If the file descriptor was opened with +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 \(mi1 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 +.IR fd +was not opened with 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 +\fB +#include +#include +#include +.P +struct stat buffer; +int status; +\&... +status = stat("/home/cnd/mod1", &buffer); +.fi \fR +.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 +\fB +#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's 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's 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 \fR +.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 +\fB +#include +.P +struct stat buffer; +int status; +\&... +status = lstat("/modules/pass1", &buffer); +.fi \fR +.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 +\fIlstat\fR() +function is not required to update the time-related fields if the named +file is not a symbolic link. While the +.IR st_uid , +.IR st_gid , +.IR st_atim , +.IR st_mtim , +and +.IR st_ctim +members of the +.BR stat +structure may apply to a symbolic link, they are not required to do so. +No functions in POSIX.1\(hy2008 are required to maintain any of these time +fields. +.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\(hy2008, +.IR "Section 4.8" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fstatvfs.3p b/man-pages-posix-2013/man3p/fstatvfs.3p new file mode 100644 index 0000000..73184a8 --- /dev/null +++ b/man-pages-posix-2013/man3p/fstatvfs.3p @@ -0,0 +1,233 @@ +'\" et +.TH FSTATVFS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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 +\fB +#include +#include +.P +struct statvfs buffer; +int status; +\&... +fildes = open("/home/cnd/mod1", O_RDWR); +status = fstatvfs(fildes, &buffer); +.fi \fR +.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 +\fB +#include +.P +struct statvfs buffer; +int status; +\&... +status = statvfs("/home/cnd/mod1", &buffer); +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fsync.3p b/man-pages-posix-2013/man3p/fsync.3p new file mode 100644 index 0000000..10f3736 --- /dev/null +++ b/man-pages-posix-2013/man3p/fsync.3p @@ -0,0 +1,152 @@ +'\" et +.TH FSYNC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/ftell.3p b/man-pages-posix-2013/man3p/ftell.3p new file mode 100644 index 0000000..fed666a --- /dev/null +++ b/man-pages-posix-2013/man3p/ftell.3p @@ -0,0 +1,129 @@ +'\" et +.TH FTELL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 \(mi1, 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/ftok.3p b/man-pages-posix-2013/man3p/ftok.3p new file mode 100644 index 0000000..7b30e2e --- /dev/null +++ b/man-pages-posix-2013/man3p/ftok.3p @@ -0,0 +1,193 @@ +'\" et +.TH FTOK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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)\(mi1 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 +\fB +#include +\&... +key_t semkey; +.P +if ((semkey = ftok("/tmp", 'a')) == (key_t) -1) { + perror("IPC error: ftok"); exit(1); +} +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/ftruncate.3p b/man-pages-posix-2013/man3p/ftruncate.3p new file mode 100644 index 0000000..e24175a --- /dev/null +++ b/man-pages-posix-2013/man3p/ftruncate.3p @@ -0,0 +1,161 @@ +'\" et +.TH FTRUNCATE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/ftrylockfile.3p b/man-pages-posix-2013/man3p/ftrylockfile.3p new file mode 100644 index 0000000..5fa236a --- /dev/null +++ b/man-pages-posix-2013/man3p/ftrylockfile.3p @@ -0,0 +1,38 @@ +'\" et +.TH FTRYLOCKFILE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/ftw.3p b/man-pages-posix-2013/man3p/ftw.3p new file mode 100644 index 0000000..2befe8f --- /dev/null +++ b/man-pages-posix-2013/man3p/ftw.3p @@ -0,0 +1,284 @@ +'\" et +.TH FTW "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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 \(mi1 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 +\fB +#include +\&... +if (ftw(".", fn, 10) != 0) { + perror("ftw"); exit(2); +} +.fi \fR +.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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/funlockfile.3p b/man-pages-posix-2013/man3p/funlockfile.3p new file mode 100644 index 0000000..ed048b1 --- /dev/null +++ b/man-pages-posix-2013/man3p/funlockfile.3p @@ -0,0 +1,38 @@ +'\" et +.TH FUNLOCKFILE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/futimens.3p b/man-pages-posix-2013/man3p/futimens.3p new file mode 100644 index 0000000..e270c19 --- /dev/null +++ b/man-pages-posix-2013/man3p/futimens.3p @@ -0,0 +1,383 @@ +'\" et +.TH FUTIMENS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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]); +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 file descriptor was +opened without O_SEARCH, the function shall check whether directory +searches are permitted using the current permissions of the directory +underlying the file descriptor. If the file descriptor was opened with +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 completion, +\fIfutimens\fR() +and +\fIutimensat\fR() +shall mark the last file status change timestamp 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 \(mi1 and set +.IR errno +to indicate the error. If \(mi1 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 +.IR fd +was not opened with 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fwide.3p b/man-pages-posix-2013/man3p/fwide.3p new file mode 100644 index 0000000..b1527aa --- /dev/null +++ b/man-pages-posix-2013/man3p/fwide.3p @@ -0,0 +1,107 @@ +'\" et +.TH FWIDE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fwprintf.3p b/man-pages-posix-2013/man3p/fwprintf.3p new file mode 100644 index 0000000..fb0dc7f --- /dev/null +++ b/man-pages-posix-2013/man3p/fwprintf.3p @@ -0,0 +1,1040 @@ +'\" et +.TH FWPRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(mi1)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. +.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 '\(mi' ), +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 '\(mi' +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 +\fB +wprintf(L"%1$d:%2$.*3$d:%4$.*3$d\en", hour, min, precision, sec); \*? +.fi \fR +.P +.RE +.P +The flag wide characters and their meanings are: +.IP "\fR'\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\(mi\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 '\(mi' ). +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 increases the precision (if necessary) to force the +first digit of the result to be 0. 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 '\(mi' +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"[\(mi]\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"[\(mi]\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[\(mi]inf\(dq +or +.BR \(dq[\(mi]infinity\(dq ; +which style is implementation-defined. A +.BR double +argument representing a NaN shall be converted in one of the styles +.BR \(dq[\(mi]nan\(dq +or \fR"[\(mi]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"[\(mi]\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 \(>=\(mi4, +the conversion shall be with style +.BR f +(or +.BR F ) +and precision +.BR P \(mi(\c +.IR X +1). +.IP -- 4 +Otherwise, the conversion shall be with style +.BR e +(or +.BR E ) +and precision +.BR P \(mi1. +.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"[\(mi]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. +.br +.P +In addition, all forms of +\fIfwprintf\fR() +may fail if: +.TP +.BR EINVAL +There are insufficient arguments. +.br +.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 +\fB +wprintf(format, weekday, month, day, hour, min); +.fi \fR +.P +.RE +.P +For American usage, +.IR format +could be a pointer to the wide-character string: +.sp +.RS 4 +.nf +\fB +L"%s, %s %d, %d:%.2d\en" +.fi \fR +.P +.RE +.P +producing the message: +.sp +.RS 4 +.nf +\fB +Sunday, July 3, 10:02 +.fi \fR +.P +.RE +.P +whereas for German usage, +.IR format +could be a pointer to the wide-character string: +.sp +.RS 4 +.nf +\fB +L"%1$s, %3$d. %2$s, %4$d:%5$.2d\en" +.fi \fR +.P +.RE +.P +producing the message: +.sp +.RS 4 +.nf +\fB +Sonntag, 3. Juli, 10:02 +.fi \fR +.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 "\fIbtowc\fR\^(\|)", +.IR "\fIfputwc\fR\^(\|)", +.IR "\fIfwscanf\fR\^(\|)", +.IR "\fImbrtowc\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fwrite.3p b/man-pages-posix-2013/man3p/fwrite.3p new file mode 100644 index 0000000..5a9a12e --- /dev/null +++ b/man-pages-posix-2013/man3p/fwrite.3p @@ -0,0 +1,121 @@ +'\" et +.TH FWRITE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/fwscanf.3p b/man-pages-posix-2013/man3p/fwscanf.3p new file mode 100644 index 0000000..a9fcd3b --- /dev/null +++ b/man-pages-posix-2013/man3p/fwscanf.3p @@ -0,0 +1,862 @@ +'\" et +.TH FWSCANF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 \(mi1)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. +.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 '^' ), +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[^]\(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 '\(mi' +is in the scanlist and is not the first wide character, nor the second +where the first wide character is a +.BR '^' , +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 matching failure or conversion, EOF shall be returned. +If any error occurs, 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 +\fB +int i, n; float x; char name[50]; +n = wscanf(L"%d%f%s", &i, &x, name); +.fi \fR +.P +.RE +.P +with the input line: +.sp +.RS 4 +.nf +\fB +25 54.32E\(mi1 Hamster +.fi \fR +.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 +\fB +int i; float x; char name[50]; +(void) wscanf(L"%2d%f%*d %[0123456789]", &i, &x, name); +.fi \fR +.P +.RE +.P +with input: +.sp +.RS 4 +.nf +\fB +56789 0123 56a72 +.fi \fR +.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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/gai_strerror.3p b/man-pages-posix-2013/man3p/gai_strerror.3p new file mode 100644 index 0000000..53c7b0d --- /dev/null +++ b/man-pages-posix-2013/man3p/gai_strerror.3p @@ -0,0 +1,96 @@ +'\" et +.TH GAI_STRERROR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getaddrinfo.3p b/man-pages-posix-2013/man3p/getaddrinfo.3p new file mode 100644 index 0000000..97be9cf --- /dev/null +++ b/man-pages-posix-2013/man3p/getaddrinfo.3p @@ -0,0 +1,42 @@ +'\" et +.TH GETADDRINFO "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getc.3p b/man-pages-posix-2013/man3p/getc.3p new file mode 100644 index 0000000..a96e11f --- /dev/null +++ b/man-pages-posix-2013/man3p/getc.3p @@ -0,0 +1,90 @@ +'\" et +.TH GETC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getc_unlocked.3p b/man-pages-posix-2013/man3p/getc_unlocked.3p new file mode 100644 index 0000000..166c155 --- /dev/null +++ b/man-pages-posix-2013/man3p/getc_unlocked.3p @@ -0,0 +1,233 @@ +'\" et +.TH GETC_UNLOCKED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 thread-safe manner. They may only safely be used +within a scope protected by +\fIflockfile\fR() +(or +\fIftrylockfile\fR()) +and +\fIfunlockfile\fR(). +These functions may 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 +\fB +#undef getc_unlocked +#undef putc_unlocked +.fi \fR +.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 +\fB +flockfile(fileptr); +putc_unlocked('1', fileptr); +putc_unlocked('\en', fileptr); +fprintf(fileptr, "Line 2\en"); +funlockfile(fileptr); +.fi \fR +.P +.RE +.br +.P +is permissible, and results in the text sequence: +.sp +.RS 4 +.nf +\fB +1 +Line 2 +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getchar.3p b/man-pages-posix-2013/man3p/getchar.3p new file mode 100644 index 0000000..a6c8ea2 --- /dev/null +++ b/man-pages-posix-2013/man3p/getchar.3p @@ -0,0 +1,74 @@ +'\" et +.TH GETCHAR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getchar_unlocked.3p b/man-pages-posix-2013/man3p/getchar_unlocked.3p new file mode 100644 index 0000000..f2d5130 --- /dev/null +++ b/man-pages-posix-2013/man3p/getchar_unlocked.3p @@ -0,0 +1,38 @@ +'\" et +.TH GETCHAR_UNLOCKED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getcwd.3p b/man-pages-posix-2013/man3p/getcwd.3p new file mode 100644 index 0000000..2cf9a50 --- /dev/null +++ b/man-pages-posix-2013/man3p/getcwd.3p @@ -0,0 +1,292 @@ +'\" et +.TH GETCWD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +#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 \fR +.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\(hy2008. +.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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getdate.3p b/man-pages-posix-2013/man3p/getdate.3p new file mode 100644 index 0000000..698f10b --- /dev/null +++ b/man-pages-posix-2013/man3p/getdate.3p @@ -0,0 +1,399 @@ +'\" et +.TH GETDATE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +%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 \fR +.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 +\fB +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 \fR +.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 +\fB +getdate("freitag den 10. oktober 1986 10.30 Uhr"); +.fi \fR +.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 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getdelim.3p b/man-pages-posix-2013/man3p/getdelim.3p new file mode 100644 index 0000000..92e8255 --- /dev/null +++ b/man-pages-posix-2013/man3p/getdelim.3p @@ -0,0 +1,221 @@ +'\" et +.TH GETDELIM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +The size of the object pointed to by +.IR *lineptr +shall be increased to fit the incoming line, if it isn't already large +enough, including room for the delimiter and a terminating NUL. The +characters read, including any delimiter, shall be stored in the string +pointed to by the +.IR lineptr +argument, 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 characters written into the buffer, +including the delimiter character if one was encountered before EOF, +but excluding the terminating NUL character. If no characters were read, +and 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 +the function shall return \(mi1. If an error occurs, the error indicator +for the stream shall be set, and the function shall return \(mi1 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. +.P +These functions may fail if: +.TP +.BR EOVERFLOW +More than +{SSIZE_MAX} +characters were read without encountering the +.IR delimiter +character. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.sp +.RS 4 +.nf +\fB +#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 \fR +.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\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getegid.3p b/man-pages-posix-2013/man3p/getegid.3p new file mode 100644 index 0000000..62008be --- /dev/null +++ b/man-pages-posix-2013/man3p/getegid.3p @@ -0,0 +1,70 @@ +'\" et +.TH GETEGID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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. +.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 +None. +.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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getenv.3p b/man-pages-posix-2013/man3p/getenv.3p new file mode 100644 index 0000000..99c8cfd --- /dev/null +++ b/man-pages-posix-2013/man3p/getenv.3p @@ -0,0 +1,220 @@ +'\" et +.TH GETENV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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(), +or (if supported) +\fIputenv\fR() +but they shall not be affected by a call to any other function in this volume of POSIX.1\(hy2008. +.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 +\fB +#include +\&... +const char *name = "HOME"; +char *value; +.P +value = getenv(name); +.fi \fR +.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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/geteuid.3p b/man-pages-posix-2013/man3p/geteuid.3p new file mode 100644 index 0000000..4ec16bc --- /dev/null +++ b/man-pages-posix-2013/man3p/geteuid.3p @@ -0,0 +1,70 @@ +'\" et +.TH GETEUID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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. +.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 +None. +.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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getgid.3p b/man-pages-posix-2013/man3p/getgid.3p new file mode 100644 index 0000000..a1901e7 --- /dev/null +++ b/man-pages-posix-2013/man3p/getgid.3p @@ -0,0 +1,70 @@ +'\" et +.TH GETGID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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. +.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 +None. +.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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getgrent.3p b/man-pages-posix-2013/man3p/getgrent.3p new file mode 100644 index 0000000..1ae72e2 --- /dev/null +++ b/man-pages-posix-2013/man3p/getgrent.3p @@ -0,0 +1,38 @@ +'\" et +.TH GETGRENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getgrgid.3p b/man-pages-posix-2013/man3p/getgrgid.3p new file mode 100644 index 0000000..7d4b51e --- /dev/null +++ b/man-pages-posix-2013/man3p/getgrgid.3p @@ -0,0 +1,235 @@ +'\" et +.TH GETGRGID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +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 \(mi1 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. 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(). +.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 \(mi1 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 +\fB +long int initlen = sysconf(_SC_GETGR_R_SIZE_MAX); +size_t len; +if (initlen =\|= \(mi1) + /* 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 \fR +.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 +\fB +#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 \fR +.P +.RE +.SH "APPLICATION USAGE" +Applications wishing to check for error situations should set +.IR errno +to 0 before calling +\fIgetgrgid\fR(). +If +.IR errno +is set on return, an error occurred. +.P +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 \(mi1 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getgrnam.3p b/man-pages-posix-2013/man3p/getgrnam.3p new file mode 100644 index 0000000..aa6ab98 --- /dev/null +++ b/man-pages-posix-2013/man3p/getgrnam.3p @@ -0,0 +1,210 @@ +'\" et +.TH GETGRNAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +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 \(mi1 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. 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(). +.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 \(mi1 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 +\fB +long int initlen = sysconf(_SC_GETGR_R_SIZE_MAX); +size_t len; +if (initlen =\|= \(mi1) + /* 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 \fR +.P +.RE +.SH "APPLICATION USAGE" +Applications wishing to check for error situations should set +.IR errno +to 0 before calling +\fIgetgrnam\fR(). +If +.IR errno +is set on return, an error occurred. +.P +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 \(mi1 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getgroups.3p b/man-pages-posix-2013/man3p/getgroups.3p new file mode 100644 index 0000000..28f14a8 --- /dev/null +++ b/man-pages-posix-2013/man3p/getgroups.3p @@ -0,0 +1,145 @@ +'\" et +.TH GETGROUPS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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 +\fB +#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 \fR +.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\(hy2008. +.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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/gethostent.3p b/man-pages-posix-2013/man3p/gethostent.3p new file mode 100644 index 0000000..835f4d0 --- /dev/null +++ b/man-pages-posix-2013/man3p/gethostent.3p @@ -0,0 +1,38 @@ +'\" et +.TH GETHOSTENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/gethostid.3p b/man-pages-posix-2013/man3p/gethostid.3p new file mode 100644 index 0000000..386d6d1 --- /dev/null +++ b/man-pages-posix-2013/man3p/gethostid.3p @@ -0,0 +1,60 @@ +'\" et +.TH GETHOSTID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/gethostname.3p b/man-pages-posix-2013/man3p/gethostname.3p new file mode 100644 index 0000000..93e4c39 --- /dev/null +++ b/man-pages-posix-2013/man3p/gethostname.3p @@ -0,0 +1,73 @@ +'\" et +.TH GETHOSTNAME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getitimer.3p b/man-pages-posix-2013/man3p/getitimer.3p new file mode 100644 index 0000000..cd48ace --- /dev/null +++ b/man-pages-posix-2013/man3p/getitimer.3p @@ -0,0 +1,167 @@ +'\" et +.TH GETITIMER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getline.3p b/man-pages-posix-2013/man3p/getline.3p new file mode 100644 index 0000000..3081a23 --- /dev/null +++ b/man-pages-posix-2013/man3p/getline.3p @@ -0,0 +1,40 @@ +'\" et +.TH GETLINE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getlogin.3p b/man-pages-posix-2013/man3p/getlogin.3p new file mode 100644 index 0000000..4d42edc --- /dev/null +++ b/man-pages-posix-2013/man3p/getlogin.3p @@ -0,0 +1,225 @@ +'\" et +.TH GETLOGIN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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(). +.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 +\fB +#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 \fR +.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 +\fB +getpwuid(geteuid()) +.fi \fR +.P +.RE +.P +while the information provided by historical implementations of +.IR cuserid (\|) +can be obtained by: +.sp +.RS 4 +.nf +\fB +getpwuid(getuid()) +.fi \fR +.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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getmsg.3p b/man-pages-posix-2013/man3p/getmsg.3p new file mode 100644 index 0000000..b660d1c --- /dev/null +++ b/man-pages-posix-2013/man3p/getmsg.3p @@ -0,0 +1,410 @@ +'\" et +.TH GETMSG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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 \(mi1, 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 \(mi1. 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 \(mi1 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 +\fB +#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 \fR +.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 +\fB +#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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getnameinfo.3p b/man-pages-posix-2013/man3p/getnameinfo.3p new file mode 100644 index 0000000..14f21fa --- /dev/null +++ b/man-pages-posix-2013/man3p/getnameinfo.3p @@ -0,0 +1,234 @@ +'\" et +.TH GETNAMEINFO "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(min +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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getnetbyaddr.3p b/man-pages-posix-2013/man3p/getnetbyaddr.3p new file mode 100644 index 0000000..c7ab1ae --- /dev/null +++ b/man-pages-posix-2013/man3p/getnetbyaddr.3p @@ -0,0 +1,42 @@ +'\" et +.TH GETNETBYADDR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getopt.3p b/man-pages-posix-2013/man3p/getopt.3p new file mode 100644 index 0000000..4abec74 --- /dev/null +++ b/man-pages-posix-2013/man3p/getopt.3p @@ -0,0 +1,445 @@ +'\" et +.TH GETOPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.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 +\fB + \fIargv\fP[optind] \fRis a null pointer\fP +*\fIargv\fP[optind] \fRis not the character\fP \(mi + \fIargv\fP[optind] \fRpoints to the string\fP "\(mi" +.fi \fR +.P +.RE +.P +\fIgetopt\fR() +shall return \(mi1 without changing +.IR optind . +If: +.sp +.RS 4 +.nf +\fB +\fIargv\fP[optind] \fRpoints to the string\fP "\(mi\|\(mi" +.fi \fR +.P +.RE +.P +\fIgetopt\fR() +shall return \(mi1 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. +.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 \(mi1 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 +\fB +#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 'a': + if (bflg) + errflg++; + else + aflg++; + break; + case 'b': + if (aflg) + errflg++; + else + bflg++; + break; + case 'f': + ifile = optarg; + break; + case 'o': + ofile = optarg; + break; + case ':': /* -f or -o without operand */ + fprintf(stderr, + "Option -%c requires an operand\en", optopt); + errflg++; + break; + case '?': + fprintf(stderr, + "Unrecognized option: '-%c'\en", optopt); + errflg++; + } + } + if (errflg) { + fprintf(stderr, "usage: . . . "); + exit(2); + } + for ( ; optind < argc; optind++) { + if (access(argv[optind], R_OK)) { + . . . +} +.fi \fR +.P +.RE +.P +This code accepts any of the following as equivalent: +.sp +.RS 4 +.nf +\fB +cmd \(miao arg path path +cmd \(mia \(mio arg path path +cmd \(mio arg \(mia path path +cmd \(mia \(mio arg \(mi\|\(mi path path +cmd \(mia \(mioarg path path +cmd \(miaoarg path path +.fi \fR +.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 +\fB +#include +#include +\&... +const char *Options = "hdbtl"; +\&... +int dbtype, c; +char *st; +\&... +dbtype = 0; +while ((c = getopt(argc, argv, Options)) != \(mi1) { + if ((st = strchr(Options, c)) != NULL) { + dbtype = st - Options; + break; + } +} +.fi \fR +.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 +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 \(mi1, 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\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIgetopts\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getpeername.3p b/man-pages-posix-2013/man3p/getpeername.3p new file mode 100644 index 0000000..399c22e --- /dev/null +++ b/man-pages-posix-2013/man3p/getpeername.3p @@ -0,0 +1,121 @@ +'\" et +.TH GETPEERNAME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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\(hy2008, +.IR "\fB\fP" +.br +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getpgid.3p b/man-pages-posix-2013/man3p/getpgid.3p new file mode 100644 index 0000000..43e6db2 --- /dev/null +++ b/man-pages-posix-2013/man3p/getpgid.3p @@ -0,0 +1,98 @@ +'\" et +.TH GETPGID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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)\(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getpgrp.3p b/man-pages-posix-2013/man3p/getpgrp.3p new file mode 100644 index 0000000..a2da4c9 --- /dev/null +++ b/man-pages-posix-2013/man3p/getpgrp.3p @@ -0,0 +1,80 @@ +'\" et +.TH GETPGRP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getpid.3p b/man-pages-posix-2013/man3p/getpid.3p new file mode 100644 index 0000000..6f81d0e --- /dev/null +++ b/man-pages-posix-2013/man3p/getpid.3p @@ -0,0 +1,69 @@ +'\" et +.TH GETPID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getpmsg.3p b/man-pages-posix-2013/man3p/getpmsg.3p new file mode 100644 index 0000000..7f0b0a1 --- /dev/null +++ b/man-pages-posix-2013/man3p/getpmsg.3p @@ -0,0 +1,40 @@ +'\" et +.TH GETPMSG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getppid.3p b/man-pages-posix-2013/man3p/getppid.3p new file mode 100644 index 0000000..5cdcab7 --- /dev/null +++ b/man-pages-posix-2013/man3p/getppid.3p @@ -0,0 +1,69 @@ +'\" et +.TH GETPPID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getpriority.3p b/man-pages-posix-2013/man3p/getpriority.3p new file mode 100644 index 0000000..247d18a --- /dev/null +++ b/man-pages-posix-2013/man3p/getpriority.3p @@ -0,0 +1,235 @@ +'\" et +.TH GETPRIORITY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(mi1], 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 \(mi1 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 \(mi1, 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 \(mi{NZERO} to +{NZERO}\(mi1. +Otherwise, \(mi1 shall be returned and +.IR errno +set to indicate the error. +.P +Upon successful completion, +\fIsetpriority\fR() +shall return 0; otherwise, \(mi1 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 +\fB +#include +\&... +int which = PRIO_PROCESS; +id_t pid; +int ret; +.P +pid = getpid(); +ret = getpriority(which, pid); +.fi \fR +.P +.RE +.SS "Using setpriority(\|)" +.P +The following example sets the priority for the current process ID to +\(mi20. +.sp +.RS 4 +.nf +\fB +#include +\&... +int which = PRIO_PROCESS; +id_t pid; +int priority = -20; +int ret; +.P +pid = getpid(); +ret = setpriority(which, pid, priority); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +The +\fIgetpriority\fR() +and +\fIsetpriority\fR() +functions work with an offset nice value (nice value \(mi{NZERO}). The +nice value is in the range [0,2*{NZERO} \(mi1], while the return value +for +\fIgetpriority\fR() +and the third parameter for +\fIsetpriority\fR() +are in the range [\(mi{NZERO},{NZERO} \(mi1]. +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getprotobyname.3p b/man-pages-posix-2013/man3p/getprotobyname.3p new file mode 100644 index 0000000..05d135b --- /dev/null +++ b/man-pages-posix-2013/man3p/getprotobyname.3p @@ -0,0 +1,42 @@ +'\" et +.TH GETPROTOBYNAME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getpwent.3p b/man-pages-posix-2013/man3p/getpwent.3p new file mode 100644 index 0000000..f46fe7d --- /dev/null +++ b/man-pages-posix-2013/man3p/getpwent.3p @@ -0,0 +1,38 @@ +'\" et +.TH GETPWENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getpwnam.3p b/man-pages-posix-2013/man3p/getpwnam.3p new file mode 100644 index 0000000..5d47101 --- /dev/null +++ b/man-pages-posix-2013/man3p/getpwnam.3p @@ -0,0 +1,241 @@ +'\" et +.TH GETPWNAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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. 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(). +.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 \(mi1 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 +\fB +long int initlen = sysconf(_SC_GETPW_R_SIZE_MAX); +size_t len; +if (initlen =\|= \(mi1) + /* 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 \fR +.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 +\fB +#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 \fR +.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 \(mi1 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getpwuid.3p b/man-pages-posix-2013/man3p/getpwuid.3p new file mode 100644 index 0000000..e333a04 --- /dev/null +++ b/man-pages-posix-2013/man3p/getpwuid.3p @@ -0,0 +1,290 @@ +'\" et +.TH GETPWUID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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. 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(). +.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 \(mi1 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 +\fB +long int initlen = sysconf(_SC_GETPW_R_SIZE_MAX); +size_t len; +if (initlen =\|= \(mi1) + /* 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 \fR +.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 +\fB +#include +#include +\&... +uid_t id = 0; +struct passwd *pwd; +.P +pwd = getpwuid(id); +.fi \fR +.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 +\fB +#include +#include +#include +\&... +struct passwd *pws; +pws = getpwuid(geteuid()); +.fi \fR +.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 +\fB +#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 \fR +.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 \(mi1 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getrlimit.3p b/man-pages-posix-2013/man3p/getrlimit.3p new file mode 100644 index 0000000..8ced3f4 --- /dev/null +++ b/man-pages-posix-2013/man3p/getrlimit.3p @@ -0,0 +1,250 @@ +'\" et +.TH GETRLIMIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getrusage.3p b/man-pages-posix-2013/man3p/getrusage.3p new file mode 100644 index 0000000..5635a6f --- /dev/null +++ b/man-pages-posix-2013/man3p/getrusage.3p @@ -0,0 +1,110 @@ +'\" et +.TH GETRUSAGE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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 +\fB +#include +\&... +int who = RUSAGE_SELF; +struct rusage usage; +int ret; +.P +ret = getrusage(who, &usage); +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/gets.3p b/man-pages-posix-2013/man3p/gets.3p new file mode 100644 index 0000000..d97dfda --- /dev/null +++ b/man-pages-posix-2013/man3p/gets.3p @@ -0,0 +1,135 @@ +'\" et +.TH GETS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getservbyname.3p b/man-pages-posix-2013/man3p/getservbyname.3p new file mode 100644 index 0000000..2fe3564 --- /dev/null +++ b/man-pages-posix-2013/man3p/getservbyname.3p @@ -0,0 +1,42 @@ +'\" et +.TH GETSERVBYNAME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getsid.3p b/man-pages-posix-2013/man3p/getsid.3p new file mode 100644 index 0000000..752cc06 --- /dev/null +++ b/man-pages-posix-2013/man3p/getsid.3p @@ -0,0 +1,86 @@ +'\" et +.TH GETSID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getsockname.3p b/man-pages-posix-2013/man3p/getsockname.3p new file mode 100644 index 0000000..c2530fe --- /dev/null +++ b/man-pages-posix-2013/man3p/getsockname.3p @@ -0,0 +1,121 @@ +'\" et +.TH GETSOCKNAME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 +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\(hy2008, +.IR "\fB\fP" +.br +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getsockopt.3p b/man-pages-posix-2013/man3p/getsockopt.3p new file mode 100644 index 0000000..0266a12 --- /dev/null +++ b/man-pages-posix-2013/man3p/getsockopt.3p @@ -0,0 +1,144 @@ +'\" et +.TH GETSOCKOPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getsubopt.3p b/man-pages-posix-2013/man3p/getsubopt.3p new file mode 100644 index 0000000..3cff22e --- /dev/null +++ b/man-pages-posix-2013/man3p/getsubopt.3p @@ -0,0 +1,296 @@ +'\" et +.TH GETSUBOPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 +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 +\fB +#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 'a': + do_all = 1; + break; + case 't': + type = optarg; + break; + case 'o': + subopts = optarg; + while (*subopts != '\0') + { + 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'\en", saved); + abort(); + } + } + break; + default: + abort(); + } +.P + /* Do the real work. */ +.P + return 0; +} +.fi \fR +.P +.RE +.P +If the above example is invoked with: +.sp +.RS 4 +.nf +\fB +program -o ro,rsize=512 +.fi \fR +.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 +\fB +program -o oops +.fi \fR +.P +.RE +.P +it will print: +.sp +.RS 4 +.nf +\fB +"Unknown suboption `oops'" +.fi \fR +.P +.RE +.P +before aborting. +.SH "APPLICATION USAGE" +The value of *\fIvaluep\fR when +\fIgetsubopt\fR() +returns \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/gettimeofday.3p b/man-pages-posix-2013/man3p/gettimeofday.3p new file mode 100644 index 0000000..b0a449a --- /dev/null +++ b/man-pages-posix-2013/man3p/gettimeofday.3p @@ -0,0 +1,77 @@ +'\" et +.TH GETTIMEOFDAY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getuid.3p b/man-pages-posix-2013/man3p/getuid.3p new file mode 100644 index 0000000..6fafbf9 --- /dev/null +++ b/man-pages-posix-2013/man3p/getuid.3p @@ -0,0 +1,85 @@ +'\" et +.TH GETUID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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. +.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 and the real user ID +of the current process to the real user ID of the caller. +.sp +.RS 4 +.nf +\fB +#include +#include +\&... +setreuid(getuid(), getuid()); +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getutxent.3p b/man-pages-posix-2013/man3p/getutxent.3p new file mode 100644 index 0000000..e2d55de --- /dev/null +++ b/man-pages-posix-2013/man3p/getutxent.3p @@ -0,0 +1,42 @@ +'\" et +.TH GETUTXENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getwc.3p b/man-pages-posix-2013/man3p/getwc.3p new file mode 100644 index 0000000..2024fb8 --- /dev/null +++ b/man-pages-posix-2013/man3p/getwc.3p @@ -0,0 +1,80 @@ +'\" et +.TH GETWC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/getwchar.3p b/man-pages-posix-2013/man3p/getwchar.3p new file mode 100644 index 0000000..9096e17 --- /dev/null +++ b/man-pages-posix-2013/man3p/getwchar.3p @@ -0,0 +1,79 @@ +'\" et +.TH GETWCHAR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/glob.3p b/man-pages-posix-2013/man3p/glob.3p new file mode 100644 index 0000000..ad08152 --- /dev/null +++ b/man-pages-posix-2013/man3p/glob.3p @@ -0,0 +1,448 @@ +'\" et +.TH GLOB "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "Section 2.13" ", " "Pattern Matching Notation", +with optional support for rule 3 in the Shell and Utilities volume of POSIX.1\(hy2008, +.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\(hy2008, +.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\(hy2008, +.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\(hy2008, +.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 +\fB +ls -l *.c +.fi \fR +.P +.RE +.P +but for some reason: +.sp +.RS 4 +.nf +\fB +system("ls -l *.c") +.fi \fR +.P +.RE +.P +is not acceptable. The application could obtain approximately the same +result using the sequence: +.sp +.RS 4 +.nf +\fB +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 \fR +.P +.RE +.P +Using the same example: +.sp +.RS 4 +.nf +\fB +ls -l *.c *.h +.fi \fR +.P +.RE +.P +could be approximately simulated using GLOB_APPEND as follows: +.sp +.RS 4 +.nf +\fB +globbuf.gl_offs = 2; +glob("*.c", GLOB_DOOFFS, NULL, &globbuf); +glob("*.h", GLOB_DOOFFS|GLOB_APPEND, NULL, &globbuf); +\&... +.fi \fR +.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 +\fB +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 \fR +.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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/gmtime.3p b/man-pages-posix-2013/man3p/gmtime.3p new file mode 100644 index 0000000..9943ae8 --- /dev/null +++ b/man-pages-posix-2013/man3p/gmtime.3p @@ -0,0 +1,152 @@ +'\" et +.TH GMTIME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "Section 4.15" ", " "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\(hy2008, +.IR "Section 4.15" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/grantpt.3p b/man-pages-posix-2013/man3p/grantpt.3p new file mode 100644 index 0000000..227e71d --- /dev/null +++ b/man-pages-posix-2013/man3p/grantpt.3p @@ -0,0 +1,93 @@ +'\" et +.TH GRANTPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIgrantpt\fR() +function may fail if: +.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. +.TP +.BR EACCES +The corresponding slave pseudo-terminal device could not be accessed. +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/hcreate.3p b/man-pages-posix-2013/man3p/hcreate.3p new file mode 100644 index 0000000..f989f19 --- /dev/null +++ b/man-pages-posix-2013/man3p/hcreate.3p @@ -0,0 +1,211 @@ +'\" et +.TH HCREATE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +#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\(mi>age, + &info_ptr\(mi>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\(mi>key, + ((struct info *)found_item\(mi>data)\(mi>age, + ((struct info *)found_item\(mi>data)\(mi>room); + } else + (void)printf("no such employee %s\en", name_to_find); + } + return 0; +} +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/htonl.3p b/man-pages-posix-2013/man3p/htonl.3p new file mode 100644 index 0000000..cb78329 --- /dev/null +++ b/man-pages-posix-2013/man3p/htonl.3p @@ -0,0 +1,90 @@ +'\" et +.TH HTONL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/hypot.3p b/man-pages-posix-2013/man3p/hypot.3p new file mode 100644 index 0000000..ac67427 --- /dev/null +++ b/man-pages-posix-2013/man3p/hypot.3p @@ -0,0 +1,156 @@ +'\" et +.TH HYPOT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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, \(mi\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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/iconv.3p b/man-pages-posix-2013/man3p/iconv.3p new file mode 100644 index 0000000..a7c14b5 --- /dev/null +++ b/man-pages-posix-2013/man3p/iconv.3p @@ -0,0 +1,235 @@ +'\" et +.TH ICONV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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)\(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/iconv_close.3p b/man-pages-posix-2013/man3p/iconv_close.3p new file mode 100644 index 0000000..dd04975 --- /dev/null +++ b/man-pages-posix-2013/man3p/iconv_close.3p @@ -0,0 +1,74 @@ +'\" et +.TH ICONV_CLOSE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/iconv_open.3p b/man-pages-posix-2013/man3p/iconv_open.3p new file mode 100644 index 0000000..f6d5536 --- /dev/null +++ b/man-pages-posix-2013/man3p/iconv_open.3p @@ -0,0 +1,124 @@ +'\" et +.TH ICONV_OPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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)\(mi1 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/if_freenameindex.3p b/man-pages-posix-2013/man3p/if_freenameindex.3p new file mode 100644 index 0000000..d04be2b --- /dev/null +++ b/man-pages-posix-2013/man3p/if_freenameindex.3p @@ -0,0 +1,72 @@ +'\" et +.TH IF_FREENAMEINDEX "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/if_indextoname.3p b/man-pages-posix-2013/man3p/if_indextoname.3p new file mode 100644 index 0000000..eb34a00 --- /dev/null +++ b/man-pages-posix-2013/man3p/if_indextoname.3p @@ -0,0 +1,82 @@ +'\" et +.TH IF_INDEXTONAME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/if_nameindex.3p b/man-pages-posix-2013/man3p/if_nameindex.3p new file mode 100644 index 0000000..36b3b2c --- /dev/null +++ b/man-pages-posix-2013/man3p/if_nameindex.3p @@ -0,0 +1,82 @@ +'\" et +.TH IF_NAMEINDEX "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/if_nametoindex.3p b/man-pages-posix-2013/man3p/if_nametoindex.3p new file mode 100644 index 0000000..5b44d03 --- /dev/null +++ b/man-pages-posix-2013/man3p/if_nametoindex.3p @@ -0,0 +1,65 @@ +'\" et +.TH IF_NAMETOINDEX "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/ilogb.3p b/man-pages-posix-2013/man3p/ilogb.3p new file mode 100644 index 0000000..386ce58 --- /dev/null +++ b/man-pages-posix-2013/man3p/ilogb.3p @@ -0,0 +1,193 @@ +'\" et +.TH ILOGB "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of 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\(hy2008 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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/imaxabs.3p b/man-pages-posix-2013/man3p/imaxabs.3p new file mode 100644 index 0000000..a78a412 --- /dev/null +++ b/man-pages-posix-2013/man3p/imaxabs.3p @@ -0,0 +1,67 @@ +'\" et +.TH IMAXABS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/imaxdiv.3p b/man-pages-posix-2013/man3p/imaxdiv.3p new file mode 100644 index 0000000..c5bc147 --- /dev/null +++ b/man-pages-posix-2013/man3p/imaxdiv.3p @@ -0,0 +1,76 @@ +'\" et +.TH IMAXDIV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/inet_addr.3p b/man-pages-posix-2013/man3p/inet_addr.3p new file mode 100644 index 0000000..565770e --- /dev/null +++ b/man-pages-posix-2013/man3p/inet_addr.3p @@ -0,0 +1,116 @@ +'\" et +.TH INET_ADDR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 )(\(mi1). +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/inet_ntop.3p b/man-pages-posix-2013/man3p/inet_ntop.3p new file mode 100644 index 0000000..f1d1adc --- /dev/null +++ b/man-pages-posix-2013/man3p/inet_ntop.3p @@ -0,0 +1,200 @@ +'\" et +.TH INET_NTOP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +ddd.ddd.ddd.ddd +.fi \fR +.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 at +least one numeral 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/initstate.3p b/man-pages-posix-2013/man3p/initstate.3p new file mode 100644 index 0000000..99559c4 --- /dev/null +++ b/man-pages-posix-2013/man3p/initstate.3p @@ -0,0 +1,189 @@ +'\" et +.TH INITSTATE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(mi1. The period of this random-number generator is +approximately 16 x (2\s-3\u31\d\s+3\(mi\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. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdrand48\fR\^(\|)", +.IR "\fIrand\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/insque.3p b/man-pages-posix-2013/man3p/insque.3p new file mode 100644 index 0000000..81fd05b --- /dev/null +++ b/man-pages-posix-2013/man3p/insque.3p @@ -0,0 +1,214 @@ +'\" et +.TH INSQUE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +#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 \fR +.P +.RE +.SS "Creating a Circular Linked List" +.P +The following example creates a circular linked list. +.sp +.RS 4 +.nf +\fB +#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 \fR +.P +.RE +.SS "Removing an Element" +.P +The following example removes the element pointed to by +.IR element1 . +.sp +.RS 4 +.nf +\fB +#include +\&... +struct myque element1; +\&... +remque (&element1); +.fi \fR +.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 +\fB +struct qelem { + struct qelem *q_forw; + struct qelem *q_back; +}; +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/ioctl.3p b/man-pages-posix-2013/man3p/ioctl.3p new file mode 100644 index 0000000..122712e --- /dev/null +++ b/man-pages-posix-2013/man3p/ioctl.3p @@ -0,0 +1,1214 @@ +'\" et +.TH IOCTL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 (\(mi1=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 \(mi1. +.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 \(mi1 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 \(mi1 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 \(mi1 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 \(mi1 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 \(mi1 that depends upon the STREAMS device +control function. Otherwise, it shall return \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/isalnum.3p b/man-pages-posix-2013/man3p/isalnum.3p new file mode 100644 index 0000000..2ca7a96 --- /dev/null +++ b/man-pages-posix-2013/man3p/isalnum.3p @@ -0,0 +1,116 @@ +'\" et +.TH ISALNUM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/isalpha.3p b/man-pages-posix-2013/man3p/isalpha.3p new file mode 100644 index 0000000..c750350 --- /dev/null +++ b/man-pages-posix-2013/man3p/isalpha.3p @@ -0,0 +1,115 @@ +'\" et +.TH ISALPHA "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/isascii.3p b/man-pages-posix-2013/man3p/isascii.3p new file mode 100644 index 0000000..844a2d3 --- /dev/null +++ b/man-pages-posix-2013/man3p/isascii.3p @@ -0,0 +1,71 @@ +'\" et +.TH ISASCII "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/isastream.3p b/man-pages-posix-2013/man3p/isastream.3p new file mode 100644 index 0000000..649c0fc --- /dev/null +++ b/man-pages-posix-2013/man3p/isastream.3p @@ -0,0 +1,75 @@ +'\" et +.TH ISASTREAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/isatty.3p b/man-pages-posix-2013/man3p/isatty.3p new file mode 100644 index 0000000..babe7dc --- /dev/null +++ b/man-pages-posix-2013/man3p/isatty.3p @@ -0,0 +1,82 @@ +'\" et +.TH ISATTY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/isblank.3p b/man-pages-posix-2013/man3p/isblank.3p new file mode 100644 index 0000000..91ac531 --- /dev/null +++ b/man-pages-posix-2013/man3p/isblank.3p @@ -0,0 +1,117 @@ +'\" et +.TH ISBLANK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/iscntrl.3p b/man-pages-posix-2013/man3p/iscntrl.3p new file mode 100644 index 0000000..b5ebc3d --- /dev/null +++ b/man-pages-posix-2013/man3p/iscntrl.3p @@ -0,0 +1,115 @@ +'\" et +.TH ISCNTRL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/isdigit.3p b/man-pages-posix-2013/man3p/isdigit.3p new file mode 100644 index 0000000..96fa995 --- /dev/null +++ b/man-pages-posix-2013/man3p/isdigit.3p @@ -0,0 +1,113 @@ +'\" et +.TH ISDIGIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/isfinite.3p b/man-pages-posix-2013/man3p/isfinite.3p new file mode 100644 index 0000000..7ffed3b --- /dev/null +++ b/man-pages-posix-2013/man3p/isfinite.3p @@ -0,0 +1,73 @@ +'\" et +.TH ISFINITE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/isgraph.3p b/man-pages-posix-2013/man3p/isgraph.3p new file mode 100644 index 0000000..f9f03ca --- /dev/null +++ b/man-pages-posix-2013/man3p/isgraph.3p @@ -0,0 +1,116 @@ +'\" et +.TH ISGRAPH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/isgreater.3p b/man-pages-posix-2013/man3p/isgreater.3p new file mode 100644 index 0000000..609d49e --- /dev/null +++ b/man-pages-posix-2013/man3p/isgreater.3p @@ -0,0 +1,101 @@ +'\" et +.TH ISGREATER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/isgreaterequal.3p b/man-pages-posix-2013/man3p/isgreaterequal.3p new file mode 100644 index 0000000..ee329ec --- /dev/null +++ b/man-pages-posix-2013/man3p/isgreaterequal.3p @@ -0,0 +1,101 @@ +'\" et +.TH ISGREATEREQUAL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/isinf.3p b/man-pages-posix-2013/man3p/isinf.3p new file mode 100644 index 0000000..67dff48 --- /dev/null +++ b/man-pages-posix-2013/man3p/isinf.3p @@ -0,0 +1,72 @@ +'\" et +.TH ISINF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/isless.3p b/man-pages-posix-2013/man3p/isless.3p new file mode 100644 index 0000000..76e857e --- /dev/null +++ b/man-pages-posix-2013/man3p/isless.3p @@ -0,0 +1,101 @@ +'\" et +.TH ISLESS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/islessequal.3p b/man-pages-posix-2013/man3p/islessequal.3p new file mode 100644 index 0000000..0b30c95 --- /dev/null +++ b/man-pages-posix-2013/man3p/islessequal.3p @@ -0,0 +1,101 @@ +'\" et +.TH ISLESSEQUAL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/islessgreater.3p b/man-pages-posix-2013/man3p/islessgreater.3p new file mode 100644 index 0000000..e7b953d --- /dev/null +++ b/man-pages-posix-2013/man3p/islessgreater.3p @@ -0,0 +1,106 @@ +'\" et +.TH ISLESSGREATER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/islower.3p b/man-pages-posix-2013/man3p/islower.3p new file mode 100644 index 0000000..97efc15 --- /dev/null +++ b/man-pages-posix-2013/man3p/islower.3p @@ -0,0 +1,169 @@ +'\" et +.TH ISLOWER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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 +\fB +/* 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 \fR +.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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/isnan.3p b/man-pages-posix-2013/man3p/isnan.3p new file mode 100644 index 0000000..9c56483 --- /dev/null +++ b/man-pages-posix-2013/man3p/isnan.3p @@ -0,0 +1,72 @@ +'\" et +.TH ISNAN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/isnormal.3p b/man-pages-posix-2013/man3p/isnormal.3p new file mode 100644 index 0000000..7d874d7 --- /dev/null +++ b/man-pages-posix-2013/man3p/isnormal.3p @@ -0,0 +1,72 @@ +'\" et +.TH ISNORMAL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/isprint.3p b/man-pages-posix-2013/man3p/isprint.3p new file mode 100644 index 0000000..9953947 --- /dev/null +++ b/man-pages-posix-2013/man3p/isprint.3p @@ -0,0 +1,115 @@ +'\" et +.TH ISPRINT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/ispunct.3p b/man-pages-posix-2013/man3p/ispunct.3p new file mode 100644 index 0000000..e65e349 --- /dev/null +++ b/man-pages-posix-2013/man3p/ispunct.3p @@ -0,0 +1,115 @@ +'\" et +.TH ISPUNCT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/isspace.3p b/man-pages-posix-2013/man3p/isspace.3p new file mode 100644 index 0000000..7cb6c43 --- /dev/null +++ b/man-pages-posix-2013/man3p/isspace.3p @@ -0,0 +1,114 @@ +'\" et +.TH ISSPACE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/isunordered.3p b/man-pages-posix-2013/man3p/isunordered.3p new file mode 100644 index 0000000..959a93a --- /dev/null +++ b/man-pages-posix-2013/man3p/isunordered.3p @@ -0,0 +1,87 @@ +'\" et +.TH ISUNORDERED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/isupper.3p b/man-pages-posix-2013/man3p/isupper.3p new file mode 100644 index 0000000..be0e50c --- /dev/null +++ b/man-pages-posix-2013/man3p/isupper.3p @@ -0,0 +1,115 @@ +'\" et +.TH ISUPPER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/iswalnum.3p b/man-pages-posix-2013/man3p/iswalnum.3p new file mode 100644 index 0000000..20bb894 --- /dev/null +++ b/man-pages-posix-2013/man3p/iswalnum.3p @@ -0,0 +1,117 @@ +'\" et +.TH ISWALNUM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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 current locale, 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/iswalpha.3p b/man-pages-posix-2013/man3p/iswalpha.3p new file mode 100644 index 0000000..a39c3a1 --- /dev/null +++ b/man-pages-posix-2013/man3p/iswalpha.3p @@ -0,0 +1,114 @@ +'\" et +.TH ISWALPHA "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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 current locale, 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/iswblank.3p b/man-pages-posix-2013/man3p/iswblank.3p new file mode 100644 index 0000000..2b29770 --- /dev/null +++ b/man-pages-posix-2013/man3p/iswblank.3p @@ -0,0 +1,115 @@ +'\" et +.TH ISWBLANK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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 current locale, 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/iswcntrl.3p b/man-pages-posix-2013/man3p/iswcntrl.3p new file mode 100644 index 0000000..aaba885 --- /dev/null +++ b/man-pages-posix-2013/man3p/iswcntrl.3p @@ -0,0 +1,114 @@ +'\" et +.TH ISWCNTRL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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 current locale, 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/iswctype.3p b/man-pages-posix-2013/man3p/iswctype.3p new file mode 100644 index 0000000..2d83a4b --- /dev/null +++ b/man-pages-posix-2013/man3p/iswctype.3p @@ -0,0 +1,188 @@ +'\" et +.TH ISWCTYPE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 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 +\fB +#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 \fR +.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 +\fB +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 \fR +.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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/iswdigit.3p b/man-pages-posix-2013/man3p/iswdigit.3p new file mode 100644 index 0000000..5e6a646 --- /dev/null +++ b/man-pages-posix-2013/man3p/iswdigit.3p @@ -0,0 +1,114 @@ +'\" et +.TH ISWDIGIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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 current locale, 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/iswgraph.3p b/man-pages-posix-2013/man3p/iswgraph.3p new file mode 100644 index 0000000..15850fa --- /dev/null +++ b/man-pages-posix-2013/man3p/iswgraph.3p @@ -0,0 +1,115 @@ +'\" et +.TH ISWGRAPH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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 current locale, 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/iswlower.3p b/man-pages-posix-2013/man3p/iswlower.3p new file mode 100644 index 0000000..47dca63 --- /dev/null +++ b/man-pages-posix-2013/man3p/iswlower.3p @@ -0,0 +1,114 @@ +'\" et +.TH ISWLOWER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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 current locale, 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/iswprint.3p b/man-pages-posix-2013/man3p/iswprint.3p new file mode 100644 index 0000000..68234d5 --- /dev/null +++ b/man-pages-posix-2013/man3p/iswprint.3p @@ -0,0 +1,114 @@ +'\" et +.TH ISWPRINT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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 current locale, 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/iswpunct.3p b/man-pages-posix-2013/man3p/iswpunct.3p new file mode 100644 index 0000000..cc52b7e --- /dev/null +++ b/man-pages-posix-2013/man3p/iswpunct.3p @@ -0,0 +1,114 @@ +'\" et +.TH ISWPUNCT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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 current locale, 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/iswspace.3p b/man-pages-posix-2013/man3p/iswspace.3p new file mode 100644 index 0000000..098bd49 --- /dev/null +++ b/man-pages-posix-2013/man3p/iswspace.3p @@ -0,0 +1,114 @@ +'\" et +.TH ISWSPACE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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 current locale, 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/iswupper.3p b/man-pages-posix-2013/man3p/iswupper.3p new file mode 100644 index 0000000..625be1a --- /dev/null +++ b/man-pages-posix-2013/man3p/iswupper.3p @@ -0,0 +1,114 @@ +'\" et +.TH ISWUPPER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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 current locale, 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/iswxdigit.3p b/man-pages-posix-2013/man3p/iswxdigit.3p new file mode 100644 index 0000000..98d59c9 --- /dev/null +++ b/man-pages-posix-2013/man3p/iswxdigit.3p @@ -0,0 +1,114 @@ +'\" et +.TH ISWXDIGIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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 current locale, 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/isxdigit.3p b/man-pages-posix-2013/man3p/isxdigit.3p new file mode 100644 index 0000000..8ac1b15 --- /dev/null +++ b/man-pages-posix-2013/man3p/isxdigit.3p @@ -0,0 +1,112 @@ +'\" et +.TH ISXDIGIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/j0.3p b/man-pages-posix-2013/man3p/j0.3p new file mode 100644 index 0000000..c038be0 --- /dev/null +++ b/man-pages-posix-2013/man3p/j0.3p @@ -0,0 +1,112 @@ +'\" et +.TH J0 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/jrand48.3p b/man-pages-posix-2013/man3p/jrand48.3p new file mode 100644 index 0000000..745ecf1 --- /dev/null +++ b/man-pages-posix-2013/man3p/jrand48.3p @@ -0,0 +1,38 @@ +'\" et +.TH JRAND48 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/kill.3p b/man-pages-posix-2013/man3p/kill.3p new file mode 100644 index 0000000..bf47e0e --- /dev/null +++ b/man-pages-posix-2013/man3p/kill.3p @@ -0,0 +1,287 @@ +'\" et +.TH KILL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1, +.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 \(mi1, +.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, \(mi1 +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\(hy2008 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\(hy2008, 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\(hy2008, 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 +Existing implementations vary on the result of a +\fIkill\fR() +with +.IR pid +indicating an inactive process (a terminated process that has not been +waited for by its parent). Some indicate success on such a call +(subject to permission checking), while others give an error of +.BR [ESRCH] . +Since the definition of process lifetime in this volume of POSIX.1\(hy2008 +covers inactive processes, the +.BR [ESRCH] +error as described is inappropriate in this case. In particular, this +means that an application cannot have a parent process check for +termination of a particular child with +\fIkill\fR(). +(Usually this is done with the null signal; this can be done reliably +with +\fIwaitpid\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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/killpg.3p b/man-pages-posix-2013/man3p/killpg.3p new file mode 100644 index 0000000..b578f59 --- /dev/null +++ b/man-pages-posix-2013/man3p/killpg.3p @@ -0,0 +1,95 @@ +'\" et +.TH KILLPG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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(\(mi\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 +\fB +#include +#include +\&... + if (signal(SIGUSR1, SIG_IGN) == SIG_ERR) + /* Handle error */; +.P + if (killpg(getpgrp(), SIGUSR1) == \(mi1) + /* Handle error */;" +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/l64a.3p b/man-pages-posix-2013/man3p/l64a.3p new file mode 100644 index 0000000..0f5e77f --- /dev/null +++ b/man-pages-posix-2013/man3p/l64a.3p @@ -0,0 +1,38 @@ +'\" et +.TH L64A "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/labs.3p b/man-pages-posix-2013/man3p/labs.3p new file mode 100644 index 0000000..f7f92ec --- /dev/null +++ b/man-pages-posix-2013/man3p/labs.3p @@ -0,0 +1,84 @@ +'\" et +.TH LABS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/lchown.3p b/man-pages-posix-2013/man3p/lchown.3p new file mode 100644 index 0000000..9528113 --- /dev/null +++ b/man-pages-posix-2013/man3p/lchown.3p @@ -0,0 +1,174 @@ +'\" et +.TH LCHOWN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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 +\fB +#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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/lcong48.3p b/man-pages-posix-2013/man3p/lcong48.3p new file mode 100644 index 0000000..123c84c --- /dev/null +++ b/man-pages-posix-2013/man3p/lcong48.3p @@ -0,0 +1,39 @@ +'\" et +.TH LCONG48 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/ldexp.3p b/man-pages-posix-2013/man3p/ldexp.3p new file mode 100644 index 0000000..9355f53 --- /dev/null +++ b/man-pages-posix-2013/man3p/ldexp.3p @@ -0,0 +1,151 @@ +'\" et +.TH LDEXP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/ldiv.3p b/man-pages-posix-2013/man3p/ldiv.3p new file mode 100644 index 0000000..986e658 --- /dev/null +++ b/man-pages-posix-2013/man3p/ldiv.3p @@ -0,0 +1,108 @@ +'\" et +.TH LDIV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +long quot; /* Quotient */ +long rem; /* Remainder */ +.fi \fR +.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 +\fB +long long quot; /* Quotient */ +long long rem; /* Remainder */ +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/lfind.3p b/man-pages-posix-2013/man3p/lfind.3p new file mode 100644 index 0000000..37b088b --- /dev/null +++ b/man-pages-posix-2013/man3p/lfind.3p @@ -0,0 +1,39 @@ +'\" et +.TH LFIND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/lgamma.3p b/man-pages-posix-2013/man3p/lgamma.3p new file mode 100644 index 0000000..1714bb1 --- /dev/null +++ b/man-pages-posix-2013/man3p/lgamma.3p @@ -0,0 +1,158 @@ +'\" et +.TH LGAMMA "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of 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\(hy2008 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, \(miInf, 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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/link.3p b/man-pages-posix-2013/man3p/link.3p new file mode 100644 index 0000000..ba58b85 --- /dev/null +++ b/man-pages-posix-2013/man3p/link.3p @@ -0,0 +1,437 @@ +'\" et +.TH LINK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 relative to two directory +file descriptors +.SH SYNOPSIS +.LP +.nf +#include +.P +int link(const char *\fIpath1\fP, const char *\fIpath2\fP); +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 file descriptor was opened without O_SEARCH, the function +shall check whether directory searches are permitted using the current +permissions of the directory underlying the file descriptor. If the +file descriptor was opened with 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 \(mi1 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 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 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 +\fB +#include +.P +char *path1 = "/home/cnd/mod1"; +char *path2 = "/modules/pass1"; +int status; +\&... +status = link (path1, path2); +.fi \fR +.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 +\fB +#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 \fR +.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\(hy2008 +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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/lio_listio.3p b/man-pages-posix-2013/man3p/lio_listio.3p new file mode 100644 index 0000000..5d0dd3f --- /dev/null +++ b/man-pages-posix-2013/man3p/lio_listio.3p @@ -0,0 +1,354 @@ +'\" et +.TH LIO_LISTIO "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\(mi1 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/listen.3p b/man-pages-posix-2013/man3p/listen.3p new file mode 100644 index 0000000..15196c6 --- /dev/null +++ b/man-pages-posix-2013/man3p/listen.3p @@ -0,0 +1,153 @@ +'\" et +.TH LISTEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/llabs.3p b/man-pages-posix-2013/man3p/llabs.3p new file mode 100644 index 0000000..2752bfc --- /dev/null +++ b/man-pages-posix-2013/man3p/llabs.3p @@ -0,0 +1,38 @@ +'\" et +.TH LLABS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/lldiv.3p b/man-pages-posix-2013/man3p/lldiv.3p new file mode 100644 index 0000000..4aa646d --- /dev/null +++ b/man-pages-posix-2013/man3p/lldiv.3p @@ -0,0 +1,38 @@ +'\" et +.TH LLDIV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/llrint.3p b/man-pages-posix-2013/man3p/llrint.3p new file mode 100644 index 0000000..94eaa85 --- /dev/null +++ b/man-pages-posix-2013/man3p/llrint.3p @@ -0,0 +1,147 @@ +'\" et +.TH LLRINT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 \(miInf, 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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/llround.3p b/man-pages-posix-2013/man3p/llround.3p new file mode 100644 index 0000000..0c04972 --- /dev/null +++ b/man-pages-posix-2013/man3p/llround.3p @@ -0,0 +1,149 @@ +'\" et +.TH LLROUND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 \(miInf, 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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/localeconv.3p b/man-pages-posix-2013/man3p/localeconv.3p new file mode 100644 index 0000000..61fbb0e --- /dev/null +++ b/man-pages-posix-2013/man3p/localeconv.3p @@ -0,0 +1,362 @@ +'\" et +.TH LOCALECONV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008 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. +.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!\(mi\(eu.1.230!EUR.1.230 +Netherlands!\(eu 1.234,56!\(eu \(mi1.234,56!EUR 1.234,56 +Norway!kr1.234,56!kr1.234,56\(mi!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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/localtime.3p b/man-pages-posix-2013/man3p/localtime.3p new file mode 100644 index 0000000..3459412 --- /dev/null +++ b/man-pages-posix-2013/man3p/localtime.3p @@ -0,0 +1,276 @@ +'\" et +.TH LOCALTIME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "Section 4.15" ", " "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() +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 +\fB +#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 \fR +.P +.RE +.P +This example writes the current time to +.IR stdout +in a form like this: +.sp +.RS 4 +.nf +\fB +Wed Jun 26 10:32:15 1996 +835810335 secs since the Epoch +.fi \fR +.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 +\fB +#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) =\|= \(mi1) + return \(mi1; + if((tm = localtime(&statbuf.st_mtime)) =\|= NULL) + return \(mi1; + if(strftime(timestr, sizeof(timestr), "%Y-%m-%d %H:%M:%S", tm) =\|= 0) + return \(mi1; + printf("%s: %s.%09ld\en", pathname, timestr, statbuf.st_mtim.tv_nsec); + return 0; +} +.fi \fR +.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 +\fB +#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 \fR +.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\(hy2008, +.IR "Section 4.15" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/lockf.3p b/man-pages-posix-2013/man3p/lockf.3p new file mode 100644 index 0000000..870fb59 --- /dev/null +++ b/man-pages-posix-2013/man3p/lockf.3p @@ -0,0 +1,291 @@ +'\" et +.TH LOCKF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1, 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 +\fB +#include +#include +.P +int fildes; +int status; +\&... +fildes = open("/home/cnd/mod1", O_RDWR); +status = lockf(fildes, F_TLOCK, (off_t)10000); +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/log.3p b/man-pages-posix-2013/man3p/log.3p new file mode 100644 index 0000000..0d68316 --- /dev/null +++ b/man-pages-posix-2013/man3p/log.3p @@ -0,0 +1,151 @@ +'\" et +.TH LOG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 \(miHUGE_VAL, \(miHUGE_VALF, and \(miHUGE_VALL, +respectively. +.P +For finite values of +.IR x +that are less than 0, +or if +.IR x +is \(miInf, +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 \(miInf. +.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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/log10.3p b/man-pages-posix-2013/man3p/log10.3p new file mode 100644 index 0000000..502f3be --- /dev/null +++ b/man-pages-posix-2013/man3p/log10.3p @@ -0,0 +1,149 @@ +'\" et +.TH LOG10 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 \(miHUGE_VAL, \(miHUGE_VALF, and \(miHUGE_VALL, +respectively. +.P +For finite values of +.IR x +that are less than 0, +or if +.IR x +is \(miInf, +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 \(miInf. +.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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/log1p.3p b/man-pages-posix-2013/man3p/log1p.3p new file mode 100644 index 0000000..b8a2e13 --- /dev/null +++ b/man-pages-posix-2013/man3p/log1p.3p @@ -0,0 +1,177 @@ +'\" et +.TH LOG1P "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 \(mi1, a pole error shall occur and +\fIlog1p\fR(), +\fIlog1pf\fR(), +and +\fIlog1pl\fR() +shall return \(miHUGE_VAL, \(miHUGE_VALF, and \(miHUGE_VALL, +respectively. +.P +For finite values of +.IR x +that are less than \(mi1, +or if +.IR x +is \(miInf, +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 \(mi1, +or +.IR x +is \(miInf. +.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 \(mi1. +.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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/log2.3p b/man-pages-posix-2013/man3p/log2.3p new file mode 100644 index 0000000..2f20c80 --- /dev/null +++ b/man-pages-posix-2013/man3p/log2.3p @@ -0,0 +1,148 @@ +'\" et +.TH LOG2 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 \(miHUGE_VAL, \(miHUGE_VALF, and \(miHUGE_VALL, +respectively. +.P +For finite values of +.IR x +that are less than 0, +or if +.IR x +is \(miInf, +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 \(miInf. +.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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/logb.3p b/man-pages-posix-2013/man3p/logb.3p new file mode 100644 index 0000000..1f26022 --- /dev/null +++ b/man-pages-posix-2013/man3p/logb.3p @@ -0,0 +1,163 @@ +'\" et +.TH LOGB "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +1 <= \fIx\fP * FLT_RADIX\s-3\u\(milogb(x)\d\s+3 < FLT_RADIX +.fi \fR +.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 \(miHUGE_VAL, \(miHUGE_VALF, and \(miHUGE_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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/logf.3p b/man-pages-posix-2013/man3p/logf.3p new file mode 100644 index 0000000..700bfb4 --- /dev/null +++ b/man-pages-posix-2013/man3p/logf.3p @@ -0,0 +1,40 @@ +'\" et +.TH LOGF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/longjmp.3p b/man-pages-posix-2013/man3p/longjmp.3p new file mode 100644 index 0000000..1b5b180 --- /dev/null +++ b/man-pages-posix-2013/man3p/longjmp.3p @@ -0,0 +1,146 @@ +'\" et +.TH LONGJMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +As it bypasses the usual function call and return mechanisms, +\fIlongjmp\fR() +shall execute correctly in contexts of interrupts, signals, and any +of their associated functions. However, if +\fIlongjmp\fR() +is invoked from a nested signal handler (that is, from a function +invoked as a result of a signal raised during the handling of another +signal), the behavior 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). +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/lrand48.3p b/man-pages-posix-2013/man3p/lrand48.3p new file mode 100644 index 0000000..10759b7 --- /dev/null +++ b/man-pages-posix-2013/man3p/lrand48.3p @@ -0,0 +1,39 @@ +'\" et +.TH LRAND48 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/lrint.3p b/man-pages-posix-2013/man3p/lrint.3p new file mode 100644 index 0000000..74b5aec --- /dev/null +++ b/man-pages-posix-2013/man3p/lrint.3p @@ -0,0 +1,147 @@ +'\" et +.TH LRINT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 \(miInf, 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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/lround.3p b/man-pages-posix-2013/man3p/lround.3p new file mode 100644 index 0000000..ed2259a --- /dev/null +++ b/man-pages-posix-2013/man3p/lround.3p @@ -0,0 +1,149 @@ +'\" et +.TH LROUND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 \(miInf, 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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/lsearch.3p b/man-pages-posix-2013/man3p/lsearch.3p new file mode 100644 index 0000000..a4d8838 --- /dev/null +++ b/man-pages-posix-2013/man3p/lsearch.3p @@ -0,0 +1,154 @@ +'\" et +.TH LSEARCH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +#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 \fR +.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 +\fB +#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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/lseek.3p b/man-pages-posix-2013/man3p/lseek.3p new file mode 100644 index 0000000..38d3bd5 --- /dev/null +++ b/man-pages-posix-2013/man3p/lseek.3p @@ -0,0 +1,183 @@ +'\" et +.TH LSEEK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 +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 )\(mi1 +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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/lstat.3p b/man-pages-posix-2013/man3p/lstat.3p new file mode 100644 index 0000000..fdfee8c --- /dev/null +++ b/man-pages-posix-2013/man3p/lstat.3p @@ -0,0 +1,38 @@ +'\" et +.TH LSTAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/malloc.3p b/man-pages-posix-2013/man3p/malloc.3p new file mode 100644 index 0000000..f9c0f1f --- /dev/null +++ b/man-pages-posix-2013/man3p/malloc.3p @@ -0,0 +1,99 @@ +'\" et +.TH MALLOC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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: the value returned shall be either +a null pointer or a unique pointer. +.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 a null pointer or a unique pointer that can be +successfully passed to +\fIfree\fR() +shall be returned. 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/mblen.3p b/man-pages-posix-2013/man3p/mblen.3p new file mode 100644 index 0000000..3361050 --- /dev/null +++ b/man-pages-posix-2013/man3p/mblen.3p @@ -0,0 +1,135 @@ +'\" et +.TH MBLEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +mbtowc((wchar_t *)0, \fIs\fP, \fIn\fP); +.fi \fR +.P +.RE +.P +The implementation shall behave as if no function defined in this volume of POSIX.1\(hy2008 +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 \(mi1 (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. +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/mbrlen.3p b/man-pages-posix-2013/man3p/mbrlen.3p new file mode 100644 index 0000000..166e1f0 --- /dev/null +++ b/man-pages-posix-2013/man3p/mbrlen.3p @@ -0,0 +1,158 @@ +'\" et +.TH MBRLEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +mbstate_t internal; +mbrtowc(NULL, s, n, ps != NULL ? ps : &internal); +.fi \fR +.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\(hy2008 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)\(mi2" 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)\(mi1" 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. +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/mbrtowc.3p b/man-pages-posix-2013/man3p/mbrtowc.3p new file mode 100644 index 0000000..4bc37de --- /dev/null +++ b/man-pages-posix-2013/man3p/mbrtowc.3p @@ -0,0 +1,180 @@ +'\" et +.TH MBRTOWC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +mbrtowc(NULL, "", 1, ps) +.fi \fR +.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\(hy2008 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)\(mi2" 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)\(mi1" 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. +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/mbsinit.3p b/man-pages-posix-2013/man3p/mbsinit.3p new file mode 100644 index 0000000..fc02d2f --- /dev/null +++ b/man-pages-posix-2013/man3p/mbsinit.3p @@ -0,0 +1,101 @@ +'\" et +.TH MBSINIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/mbsrtowcs.3p b/man-pages-posix-2013/man3p/mbsrtowcs.3p new file mode 100644 index 0000000..c9afaca --- /dev/null +++ b/man-pages-posix-2013/man3p/mbsrtowcs.3p @@ -0,0 +1,168 @@ +'\" et +.TH MBSRTOWCS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 pointed to by +.IR src +is limited to at most +.IR nmc +bytes (the size of the input buffer). +.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\(hy2008 +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)\(mi1; 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. +.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 "\fIiconv\fR\^(\|)", +.IR "\fImbrtowc\fR\^(\|)", +.IR "\fImbsinit\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/mbstowcs.3p b/man-pages-posix-2013/man3p/mbstowcs.3p new file mode 100644 index 0000000..0c8c54d --- /dev/null +++ b/man-pages-posix-2013/man3p/mbstowcs.3p @@ -0,0 +1,119 @@ +'\" et +.TH MBSTOWCS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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)\(mi1 +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 byte sequence 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 "\fIwctomb\fR\^(\|)", +.IR "\fIwcstombs\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/mbtowc.3p b/man-pages-posix-2013/man3p/mbtowc.3p new file mode 100644 index 0000000..b1488cf --- /dev/null +++ b/man-pages-posix-2013/man3p/mbtowc.3p @@ -0,0 +1,139 @@ +'\" et +.TH MBTOWC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008 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 \(mi1 +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. +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/memccpy.3p b/man-pages-posix-2013/man3p/memccpy.3p new file mode 100644 index 0000000..e286dc3 --- /dev/null +++ b/man-pages-posix-2013/man3p/memccpy.3p @@ -0,0 +1,81 @@ +'\" et +.TH MEMCCPY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/memchr.3p b/man-pages-posix-2013/man3p/memchr.3p new file mode 100644 index 0000000..5cf2c49 --- /dev/null +++ b/man-pages-posix-2013/man3p/memchr.3p @@ -0,0 +1,81 @@ +'\" et +.TH MEMCHR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/memcmp.3p b/man-pages-posix-2013/man3p/memcmp.3p new file mode 100644 index 0000000..283b6a0 --- /dev/null +++ b/man-pages-posix-2013/man3p/memcmp.3p @@ -0,0 +1,82 @@ +'\" et +.TH MEMCMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/memcpy.3p b/man-pages-posix-2013/man3p/memcpy.3p new file mode 100644 index 0000000..1cfb70f --- /dev/null +++ b/man-pages-posix-2013/man3p/memcpy.3p @@ -0,0 +1,74 @@ +'\" et +.TH MEMCPY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/memmove.3p b/man-pages-posix-2013/man3p/memmove.3p new file mode 100644 index 0000000..05275f7 --- /dev/null +++ b/man-pages-posix-2013/man3p/memmove.3p @@ -0,0 +1,83 @@ +'\" et +.TH MEMMOVE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/memset.3p b/man-pages-posix-2013/man3p/memset.3p new file mode 100644 index 0000000..d6fb0e8 --- /dev/null +++ b/man-pages-posix-2013/man3p/memset.3p @@ -0,0 +1,71 @@ +'\" et +.TH MEMSET "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/mkdir.3p b/man-pages-posix-2013/man3p/mkdir.3p new file mode 100644 index 0000000..3eafad1 --- /dev/null +++ b/man-pages-posix-2013/man3p/mkdir.3p @@ -0,0 +1,250 @@ +'\" et +.TH MKDIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 relative to directory file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int mkdir(const char *\fIpath\fP, mode_t \fImode\fP); +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 file descriptor was +opened without O_SEARCH, the function shall check whether directory +searches are permitted using the current permissions of the directory +underlying the file descriptor. If the file descriptor was opened with +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 \(mi1 and set +.IR errno +to indicate the error. If \(mi1 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 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 +\fB +#include +#include +.P +int status; +\&... +status = mkdir("/home/cnd/mod1", S_IRWXU | S_IRWXG | S_IROTH | S_IXOTH); +.fi \fR +.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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/mkdtemp.3p b/man-pages-posix-2013/man3p/mkdtemp.3p new file mode 100644 index 0000000..0a6b2bd --- /dev/null +++ b/man-pages-posix-2013/man3p/mkdtemp.3p @@ -0,0 +1,215 @@ +'\" et +.TH MKDTEMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 uses the contents of +.IR template +to construct a unique directory name. The string provided in +.IR template +shall be a pathname ending with six trailing +.BR 'X' s. +The +\fImkdtemp\fR() +function shall replace each +.BR 'X' +with a character from the portable filename character set. The +characters are chosen such that the resulting name does not duplicate +the name of an existing file at the time of a call to +\fImkdtemp\fR(). +The unique directory name is used to attempt to create the directory +using mode 0700 as modified by the file creation mask. +.P +The +\fImkstemp\fR() +function shall replace the contents of the string pointed to by +.IR template +by a unique pathname, and return a file descriptor for the file open +for reading and writing. The +\fImkstemp\fR() +function shall create the file, and obtain a file descriptor for it, +as if by a call to: +.sp +.RS 4 +.nf +\fB +open(pathname, O_RDWR|O_CREAT|O_EXCL, S_IRUSR|S_IWUSR) +.fi \fR +.P +.RE +.P +The function thus prevents any possible race condition between testing +whether the file exists and opening it for use. The string in +.IR template +should look like a pathname with six trailing +.BR 'X' s; +\fImkstemp\fR() +replaces each +.BR 'X' +with a character from the portable filename character set. The +characters are chosen such that the resulting name does not duplicate +the name of an existing file at the time of a call to +\fImkstemp\fR(). +.SH "RETURN VALUE" +Upon successful completion, the +\fImkdtemp\fR() +function shall return a pointer to the string containing the directory +name if it was created. 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 \(mi1 if no suitable file could be created. +.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 +\fB +#include +\&... +char template[] = "/tmp/fileXXXXXX"; +int fd; +.P +fd = mkstemp(template); +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +It is possible to run out of letters. +.P +The +\fImkdtemp\fR() +and +\fImkstemp\fR() +functions need not check to determine whether the filename part of +.IR template +exceeds the maximum allowable filename length. +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/mkfifo.3p b/man-pages-posix-2013/man3p/mkfifo.3p new file mode 100644 index 0000000..2f7917b --- /dev/null +++ b/man-pages-posix-2013/man3p/mkfifo.3p @@ -0,0 +1,273 @@ +'\" et +.TH MKFIFO "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 relative to directory file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int mkfifo(const char *\fIpath\fP, mode_t \fImode\fP); +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 file descriptor was +opened without O_SEARCH, the function shall check whether directory +searches are permitted using the current permissions of the directory +underlying the file descriptor. If the file descriptor was opened with +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 \(mi1 and set +.IR errno +to indicate the error. If \(mi1 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 +names 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 +.IR fd +was not opened with 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 +\fB +#include +#include +.P +int status; +\&... +status = mkfifo("/home/cnd/mod_done", S_IWUSR | S_IRUSR | + S_IRGRP | S_IROTH); +.fi \fR +.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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/mknod.3p b/man-pages-posix-2013/man3p/mknod.3p new file mode 100644 index 0000000..e05d447 --- /dev/null +++ b/man-pages-posix-2013/man3p/mknod.3p @@ -0,0 +1,336 @@ +'\" et +.TH MKNOD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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); +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 file descriptor was +opened without O_SEARCH, the function shall check whether directory +searches are permitted using the current permissions of the directory +underlying the file descriptor. If the file descriptor was opened with +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 \(mi1 and set +.IR errno +to indicate the error. If \(mi1 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 +names 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 +.IR fd +was not opened with 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 +\fB +#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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/mkstemp.3p b/man-pages-posix-2013/man3p/mkstemp.3p new file mode 100644 index 0000000..64d0fa6 --- /dev/null +++ b/man-pages-posix-2013/man3p/mkstemp.3p @@ -0,0 +1,38 @@ +'\" et +.TH MKSTEMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 directory +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/mktime.3p b/man-pages-posix-2013/man3p/mktime.3p new file mode 100644 index 0000000..f8f673a --- /dev/null +++ b/man-pages-posix-2013/man3p/mktime.3p @@ -0,0 +1,175 @@ +'\" et +.TH MKTIME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 are ignored, and the original values +of the other components are not 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\(hy2008, +.IR "Section 4.15" ", " "Seconds Since the Epoch") +corrected for timezone and any seasonal time adjustments, where the +names in the structure and in the expression correspond. +.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 are 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)\(mi1 +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 +\fB +#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 = \(mi1; + if (mktime(&time_str) == -1) + (void)puts("-unknown-"); + else { + (void)strftime(daybuf, sizeof(daybuf), "%A", &time_str); + (void)puts(daybuf); + } + return 0; +} +.fi \fR +.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\(hy2008, +.IR "Section 4.15" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/mlock.3p b/man-pages-posix-2013/man3p/mlock.3p new file mode 100644 index 0000000..2eb4888 --- /dev/null +++ b/man-pages-posix-2013/man3p/mlock.3p @@ -0,0 +1,168 @@ +'\" et +.TH MLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/mlockall.3p b/man-pages-posix-2013/man3p/mlockall.3p new file mode 100644 index 0000000..df4158a --- /dev/null +++ b/man-pages-posix-2013/man3p/mlockall.3p @@ -0,0 +1,158 @@ +'\" et +.TH MLOCKALL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/mmap.3p b/man-pages-posix-2013/man3p/mmap.3p new file mode 100644 index 0000000..a065f5c --- /dev/null +++ b/man-pages-posix-2013/man3p/mmap.3p @@ -0,0 +1,729 @@ +'\" et +.TH MMAP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +\fIpa\fR=\fImmap\fR(\fIaddr\fP, \fIlen\fP, \fIprot\fP, \fIflags\fP, \fIfildes\fP, \fIoff\fP); +.fi \fR +.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, the mapping established by +\fImmap\fR() +replaces any previous mappings for the pages in the range +[\fIpa\fP,\fIpa\fP+\fIlen\fR) of the process. +.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 +\fB +fildes = open(...) +lseek(fildes, some_offset) +read(fildes, buf, len) +/* Use data in buf. */ +.fi \fR +.P +.RE +.P +becomes: +.sp +.RS 4 +.nf +\fB +fildes = open(...) +address = mmap(0, len, PROT_READ, MAP_PRIVATE, fildes, some_offset) +/* Use data at address. */ +.fi \fR +.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 would overlay existing +mappings in the process, it might be desirable that an implementation +detect this and inform the application. However, the default, portable +(not MAP_FIXED) +operation does not overlay existing mappings. On the other hand, 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\(hy2008 specifies that the new mappings +replace any existing mappings, following existing practice in this +regard. +.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 +MEMLOCK_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 \(mi1 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/modf.3p b/man-pages-posix-2013/man3p/modf.3p new file mode 100644 index 0000000..52c31d9 --- /dev/null +++ b/man-pages-posix-2013/man3p/modf.3p @@ -0,0 +1,107 @@ +'\" et +.TH MODF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +a = modf(x, iptr) ; +x == a+*iptr ; +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/mprotect.3p b/man-pages-posix-2013/man3p/mprotect.3p new file mode 100644 index 0000000..3b4ad01 --- /dev/null +++ b/man-pages-posix-2013/man3p/mprotect.3p @@ -0,0 +1,158 @@ +'\" et +.TH MPROTECT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/mq_close.3p b/man-pages-posix-2013/man3p/mq_close.3p new file mode 100644 index 0000000..6d979e8 --- /dev/null +++ b/man-pages-posix-2013/man3p/mq_close.3p @@ -0,0 +1,90 @@ +'\" et +.TH MQ_CLOSE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/mq_getattr.3p b/man-pages-posix-2013/man3p/mq_getattr.3p new file mode 100644 index 0000000..b6399a8 --- /dev/null +++ b/man-pages-posix-2013/man3p/mq_getattr.3p @@ -0,0 +1,111 @@ +'\" et +.TH MQ_GETATTR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/mq_notify.3p b/man-pages-posix-2013/man3p/mq_notify.3p new file mode 100644 index 0000000..f0895d5 --- /dev/null +++ b/man-pages-posix-2013/man3p/mq_notify.3p @@ -0,0 +1,196 @@ +'\" et +.TH MQ_NOTIFY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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 +\fB +#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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/mq_open.3p b/man-pages-posix-2013/man3p/mq_open.3p new file mode 100644 index 0000000..4c610bb --- /dev/null +++ b/man-pages-posix-2013/man3p/mq_open.3p @@ -0,0 +1,317 @@ +'\" et +.TH MQ_OPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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)\(mi1 +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 )\(mi1 +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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/mq_receive.3p b/man-pages-posix-2013/man3p/mq_receive.3p new file mode 100644 index 0000000..71624f0 --- /dev/null +++ b/man-pages-posix-2013/man3p/mq_receive.3p @@ -0,0 +1,201 @@ +'\" et +.TH MQ_RECEIVE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\(mi1, 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/mq_send.3p b/man-pages-posix-2013/man3p/mq_send.3p new file mode 100644 index 0000000..eb430cc --- /dev/null +++ b/man-pages-posix-2013/man3p/mq_send.3p @@ -0,0 +1,210 @@ +'\" et +.TH MQ_SEND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1, 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}\(mi1. +.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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/mq_setattr.3p b/man-pages-posix-2013/man3p/mq_setattr.3p new file mode 100644 index 0000000..7d3e311 --- /dev/null +++ b/man-pages-posix-2013/man3p/mq_setattr.3p @@ -0,0 +1,112 @@ +'\" et +.TH MQ_SETATTR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/mq_timedreceive.3p b/man-pages-posix-2013/man3p/mq_timedreceive.3p new file mode 100644 index 0000000..02f351c --- /dev/null +++ b/man-pages-posix-2013/man3p/mq_timedreceive.3p @@ -0,0 +1,42 @@ +'\" et +.TH MQ_TIMEDRECEIVE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/mq_timedsend.3p b/man-pages-posix-2013/man3p/mq_timedsend.3p new file mode 100644 index 0000000..483c3e0 --- /dev/null +++ b/man-pages-posix-2013/man3p/mq_timedsend.3p @@ -0,0 +1,41 @@ +'\" et +.TH MQ_TIMEDSEND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/mq_unlink.3p b/man-pages-posix-2013/man3p/mq_unlink.3p new file mode 100644 index 0000000..c3c5efb --- /dev/null +++ b/man-pages-posix-2013/man3p/mq_unlink.3p @@ -0,0 +1,127 @@ +'\" et +.TH MQ_UNLINK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/mrand48.3p b/man-pages-posix-2013/man3p/mrand48.3p new file mode 100644 index 0000000..f295641 --- /dev/null +++ b/man-pages-posix-2013/man3p/mrand48.3p @@ -0,0 +1,38 @@ +'\" et +.TH MRAND48 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/msgctl.3p b/man-pages-posix-2013/man3p/msgctl.3p new file mode 100644 index 0000000..558b1b9 --- /dev/null +++ b/man-pages-posix-2013/man3p/msgctl.3p @@ -0,0 +1,188 @@ +'\" et +.TH MSGCTL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "Section 3.225" ", " "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 +\fB +msg_perm.uid +msg_perm.gid +msg_perm.mode +msg_qbytes +.fi \fR +.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 \(mi1 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\(hy2008, +.IR "Section 3.225" ", " "Message Queue", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/msgget.3p b/man-pages-posix-2013/man3p/msgget.3p new file mode 100644 index 0000000..a3ccdd6 --- /dev/null +++ b/man-pages-posix-2013/man3p/msgget.3p @@ -0,0 +1,164 @@ +'\" et +.TH MSGGET "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "Section 3.225" ", " "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 \(mi1 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\(hy2008, +.IR "Section 3.225" ", " "Message Queue", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/msgrcv.3p b/man-pages-posix-2013/man3p/msgrcv.3p new file mode 100644 index 0000000..ef29b1f --- /dev/null +++ b/man-pages-posix-2013/man3p/msgrcv.3p @@ -0,0 +1,272 @@ +'\" et +.TH MSGRCV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "Section 3.225" ", " "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 +\fB +struct mymsg { + long mtype; /* Message type. */ + char mtext[1]; /* Message text. */ +} +.fi \fR +.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 \(mi1 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 \(mi1 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 \(mi1, 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 +\fB +#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 \fR +.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\(hy2008, +.IR "Section 3.225" ", " "Message Queue", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/msgsnd.3p b/man-pages-posix-2013/man3p/msgsnd.3p new file mode 100644 index 0000000..8c1c5b2 --- /dev/null +++ b/man-pages-posix-2013/man3p/msgsnd.3p @@ -0,0 +1,239 @@ +'\" et +.TH MSGSND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "Section 3.225" ", " "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 +\fB +struct mymsg { + long mtype; /* Message type. */ + char mtext[1]; /* Message text. */ +} +.fi \fR +.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 \(mi1 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 \(mi1, 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 +\fB +#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 \fR +.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\(hy2008, +.IR "Section 3.225" ", " "Message Queue", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/msync.3p b/man-pages-posix-2013/man3p/msync.3p new file mode 100644 index 0000000..833a4ba --- /dev/null +++ b/man-pages-posix-2013/man3p/msync.3p @@ -0,0 +1,191 @@ +'\" et +.TH MSYNC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/munlock.3p b/man-pages-posix-2013/man3p/munlock.3p new file mode 100644 index 0000000..fbb27e7 --- /dev/null +++ b/man-pages-posix-2013/man3p/munlock.3p @@ -0,0 +1,38 @@ +'\" et +.TH MUNLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/munlockall.3p b/man-pages-posix-2013/man3p/munlockall.3p new file mode 100644 index 0000000..b746eda --- /dev/null +++ b/man-pages-posix-2013/man3p/munlockall.3p @@ -0,0 +1,38 @@ +'\" et +.TH MUNLOCKALL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/munmap.3p b/man-pages-posix-2013/man3p/munmap.3p new file mode 100644 index 0000000..e737a96 --- /dev/null +++ b/man-pages-posix-2013/man3p/munmap.3p @@ -0,0 +1,143 @@ +'\" et +.TH MUNMAP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/nan.3p b/man-pages-posix-2013/man3p/nan.3p new file mode 100644 index 0000000..a287256 --- /dev/null +++ b/man-pages-posix-2013/man3p/nan.3p @@ -0,0 +1,112 @@ +'\" et +.TH NAN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 defers to the ISO\ C standard. +.P +The function call \fInan\fR("\fIn-char-sequence\fR") shall be +equivalent to: +.sp +.RS 4 +.nf +\fB +strtod("NAN(\fIn-char-sequence\fP)", (char **) NULL); +.fi \fR +.P +.RE +.P +The function call \fInan\fR("\|") shall be equivalent to: +.sp +.RS 4 +.nf +\fB +strtod("NAN()", (char **) NULL) +.fi \fR +.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 +\fB +strtod("NAN", (char **) NULL) +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/nanosleep.3p b/man-pages-posix-2013/man3p/nanosleep.3p new file mode 100644 index 0000000..5d03044 --- /dev/null +++ b/man-pages-posix-2013/man3p/nanosleep.3p @@ -0,0 +1,145 @@ +'\" et +.TH NANOSLEEP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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 may 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 \(mi1 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\(hy2008 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/nearbyint.3p b/man-pages-posix-2013/man3p/nearbyint.3p new file mode 100644 index 0000000..a913672 --- /dev/null +++ b/man-pages-posix-2013/man3p/nearbyint.3p @@ -0,0 +1,89 @@ +'\" et +.TH NEARBYINT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/newlocale.3p b/man-pages-posix-2013/man3p/newlocale.3p new file mode 100644 index 0000000..32b1fe8 --- /dev/null +++ b/man-pages-posix-2013/man3p/newlocale.3p @@ -0,0 +1,267 @@ +'\" et +.TH NEWLOCALE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 other implementation-defined +.IR LC_*_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\(hy2008, +.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 tok2 : +.sp +.RS 4 +.nf +\fB +#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 \fR +.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 +\fB +#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 \fR +.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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/nextafter.3p b/man-pages-posix-2013/man3p/nextafter.3p new file mode 100644 index 0000000..ce9758a --- /dev/null +++ b/man-pages-posix-2013/man3p/nextafter.3p @@ -0,0 +1,196 @@ +'\" et +.TH NEXTAFTER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/nftw.3p b/man-pages-posix-2013/man3p/nftw.3p new file mode 100644 index 0000000..c571f1e --- /dev/null +++ b/man-pages-posix-2013/man3p/nftw.3p @@ -0,0 +1,358 @@ +'\" et +.TH NFTW "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1. +.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 \(mi1 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 \(mi1 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 +\fB +#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], 'd') != NULL) + flags |= FTW_DEPTH; + if (argc > 2 && strchr(argv[2], 'p') != 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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/nice.3p b/man-pages-posix-2013/man3p/nice.3p new file mode 100644 index 0000000..76e04c6 --- /dev/null +++ b/man-pages-posix-2013/man3p/nice.3p @@ -0,0 +1,122 @@ +'\" et +.TH NICE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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}\(mi1 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 \(mi1 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 \(mi1, check to see whether +.IR errno +is non-zero. +.SH "RETURN VALUE" +Upon successful completion, +\fInice\fR() +shall return the new nice value \(mi{NZERO}. +Otherwise, \(mi1 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, \(mi20, to the nice value of the calling process. +.sp +.RS 4 +.nf +\fB +#include +\&... +int incr = -20; +int ret; +.P +ret = nice(incr); +.fi \fR +.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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/nl_langinfo.3p b/man-pages-posix-2013/man3p/nl_langinfo.3p new file mode 100644 index 0000000..f98b5c6 --- /dev/null +++ b/man-pages-posix-2013/man3p/nl_langinfo.3p @@ -0,0 +1,205 @@ +'\" et +.TH NL_LANGINFO "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +nl_langinfo(ABDAY_1) +.fi \fR +.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 +\fB +nl_langinfo_l(ABDAY_1, loc) +.fi \fR +.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(). +.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 +\fB +#include +#include +\&... +strftime(datestring, sizeof(datestring), nl_langinfo(D_T_FMT), tm); +\&... +.fi \fR +.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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/nrand48.3p b/man-pages-posix-2013/man3p/nrand48.3p new file mode 100644 index 0000000..62ad737 --- /dev/null +++ b/man-pages-posix-2013/man3p/nrand48.3p @@ -0,0 +1,38 @@ +'\" et +.TH NRAND48 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/ntohl.3p b/man-pages-posix-2013/man3p/ntohl.3p new file mode 100644 index 0000000..c7ca169 --- /dev/null +++ b/man-pages-posix-2013/man3p/ntohl.3p @@ -0,0 +1,40 @@ +'\" et +.TH NTOHL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/open.3p b/man-pages-posix-2013/man3p/open.3p new file mode 100644 index 0000000..f56a01b --- /dev/null +++ b/man-pages-posix-2013/man3p/open.3p @@ -0,0 +1,779 @@ +'\" et +.TH OPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 relative to directory file descriptor +.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 that is the +lowest file descriptor not currently open for that process. 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, the file shall be created; 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\(hy2008, +.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 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 file descriptor was +opened without O_SEARCH, the function shall check whether directory +searches are permitted using the current permissions of the directory +underlying the file descriptor. If the file descriptor was opened with +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 lowest numbered unused +file descriptor. Otherwise, these functions shall return \(mi1 and set +.IR errno +to indicate the error. If \(mi1 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. +.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 +names 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 +.IR fd +was not opened with 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 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 +\fB +#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 \fR +.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 +\fB +#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 \fR +.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 +\fB +#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 \fR +.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\(hy2008, 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\(hy2008 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\(hy2008, +.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 +\fB +O_RDONLY | O_WRONLY == O_RDWR +.fi \fR +.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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/open_memstream.3p b/man-pages-posix-2013/man3p/open_memstream.3p new file mode 100644 index 0000000..7e1a648 --- /dev/null +++ b/man-pages-posix-2013/man3p/open_memstream.3p @@ -0,0 +1,189 @@ +'\" et +.TH OPEN_MEMSTREAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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(). +.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 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 +\fB +#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 \fR +.P +.RE +.P +This program produces the following output: +.sp +.RS 4 +.nf +\fB +buf=hello my world, len=14 +buf=good-bye world, len=14 +.fi \fR +.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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/openat.3p b/man-pages-posix-2013/man3p/openat.3p new file mode 100644 index 0000000..a2c718d --- /dev/null +++ b/man-pages-posix-2013/man3p/openat.3p @@ -0,0 +1,38 @@ +'\" et +.TH OPENAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/opendir.3p b/man-pages-posix-2013/man3p/opendir.3p new file mode 100644 index 0000000..1eaac54 --- /dev/null +++ b/man-pages-posix-2013/man3p/opendir.3p @@ -0,0 +1,38 @@ +'\" et +.TH OPENDIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/openlog.3p b/man-pages-posix-2013/man3p/openlog.3p new file mode 100644 index 0000000..7a14430 --- /dev/null +++ b/man-pages-posix-2013/man3p/openlog.3p @@ -0,0 +1,38 @@ +'\" et +.TH OPENLOG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/optarg.3p b/man-pages-posix-2013/man3p/optarg.3p new file mode 100644 index 0000000..ba63b21 --- /dev/null +++ b/man-pages-posix-2013/man3p/optarg.3p @@ -0,0 +1,42 @@ +'\" et +.TH OPTARG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pathconf.3p b/man-pages-posix-2013/man3p/pathconf.3p new file mode 100644 index 0000000..ab1759c --- /dev/null +++ b/man-pages-posix-2013/man3p/pathconf.3p @@ -0,0 +1,38 @@ +'\" et +.TH PATHCONF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pause.3p b/man-pages-posix-2013/man3p/pause.3p new file mode 100644 index 0000000..cbbeb51 --- /dev/null +++ b/man-pages-posix-2013/man3p/pause.3p @@ -0,0 +1,91 @@ +'\" et +.TH PAUSE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pclose.3p b/man-pages-posix-2013/man3p/pclose.3p new file mode 100644 index 0000000..b764d57 --- /dev/null +++ b/man-pages-posix-2013/man3p/pclose.3p @@ -0,0 +1,221 @@ +'\" et +.TH PCLOSE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008 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. +.SH "RETURN VALUE" +Upon successful return, +\fIpclose\fR() +shall return the termination status of the command language +interpreter. Otherwise, +\fIpclose\fR() +shall return \(mi1 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 \(mi1 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 +\fB +popen("command", "r") +.fi \fR +.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 +\fB +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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/perror.3p b/man-pages-posix-2013/man3p/perror.3p new file mode 100644 index 0000000..820f09c --- /dev/null +++ b/man-pages-posix-2013/man3p/perror.3p @@ -0,0 +1,156 @@ +'\" et +.TH PERROR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +#include +#include +\&... +char *bufptr; +size_t szbuf; +\&... +if ((bufptr = malloc(szbuf)) == NULL) { + perror("malloc"); exit(2); +} +\&... +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pipe.3p b/man-pages-posix-2013/man3p/pipe.3p new file mode 100644 index 0000000..b31b682 --- /dev/null +++ b/man-pages-posix-2013/man3p/pipe.3p @@ -0,0 +1,169 @@ +'\" et +.TH PIPE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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. Their integer values shall be the two lowest available at the +time of the +\fIpipe\fR() +call. 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, \(mi1 shall +be returned and +.IR errno +set to indicate the error. +.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 +\fB +#include +#include +\&... +.P +int fildes[2]; +const int BSIZE = 100; +char buf[BSIZE]; +ssize_t nbytes; +int status; +.P +status = pipe(fildes); +if (status == \(mi1 ) { + /* an error occurred */ + ... +} +.P +switch (fork()) { +case \(mi1: /* 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 \fR +.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 "\fIfcntl\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/poll.3p b/man-pages-posix-2013/man3p/poll.3p new file mode 100644 index 0000000..796e431 --- /dev/null +++ b/man-pages-posix-2013/man3p/poll.3p @@ -0,0 +1,388 @@ +'\" et +.TH POLL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1, +\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. +.SH "RETURN VALUE" +Upon successful completion, +\fIpoll\fR() +shall return a non-negative value. A positive value indicates the total +number of file descriptors that have been selected (that is, file +descriptors 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 \(mi1 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 +\fB +#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 \fR +.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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/popen.3p b/man-pages-posix-2013/man3p/popen.3p new file mode 100644 index 0000000..5d6f2cd --- /dev/null +++ b/man-pages-posix-2013/man3p/popen.3p @@ -0,0 +1,312 @@ +'\" et +.TH POPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +execl(\fIshell path\fP, "sh", "-c", \fIcommand\fP, (char *)0); +.fi \fR +.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 +\fB +#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 == \(mi1) { + /* Error reported by pclose() */ + ... +} else { + /* Use macros described under wait() to inspect `status' in order + to determine success/failure of command executed by popen() */ + ... +} +.fi \fR +.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\(hy2008 is +present, use the function call: +.sp +.RS 4 +.nf +\fB +sysconf(_SC_2_VERSION) +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIsh\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_fadvise.3p b/man-pages-posix-2013/man3p/posix_fadvise.3p new file mode 100644 index 0000000..bc6b3fb --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_fadvise.3p @@ -0,0 +1,133 @@ +'\" et +.TH POSIX_FADVISE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_fallocate.3p b/man-pages-posix-2013/man3p/posix_fallocate.3p new file mode 100644 index 0000000..f4fde58 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_fallocate.3p @@ -0,0 +1,160 @@ +'\" et +.TH POSIX_FALLOCATE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_madvise.3p b/man-pages-posix-2013/man3p/posix_madvise.3p new file mode 100644 index 0000000..6a78275 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_madvise.3p @@ -0,0 +1,144 @@ +'\" et +.TH POSIX_MADVISE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_mem_offset.3p b/man-pages-posix-2013/man3p/posix_mem_offset.3p new file mode 100644 index 0000000..f4b3884 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_mem_offset.3p @@ -0,0 +1,125 @@ +'\" et +.TH POSIX_MEM_OFFSET "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1. 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_memalign.3p b/man-pages-posix-2013/man3p/posix_memalign.3p new file mode 100644 index 0000000..605e086 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_memalign.3p @@ -0,0 +1,101 @@ +'\" et +.TH POSIX_MEMALIGN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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; the value returned in +.IR memptr +shall be either a null pointer or a unique pointer. +.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. +.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 +None. +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_openpt.3p b/man-pages-posix-2013/man3p/posix_openpt.3p new file mode 100644 index 0000000..24668b6 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_openpt.3p @@ -0,0 +1,172 @@ +'\" et +.TH POSIX_OPENPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 is 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 master pseudo-terminal device and return a +non-negative integer representing the lowest numbered unused file +descriptor. Otherwise, \(mi1 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 +\fB +#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 \fR +.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 +\fB +mfdp = open("/dev/ptmx", oflag ); +if (mfdp < 0) + return -1; +.fi \fR +.P +.RE +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgrantpt\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIptsname\fR\^(\|)", +.IR "\fIunlockpt\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_spawn.3p b/man-pages-posix-2013/man3p/posix_spawn.3p new file mode 100644 index 0000000..e71ca14 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_spawn.3p @@ -0,0 +1,932 @@ +'\" et +.TH POSIX_SPAWN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +int main(int \fIargc\fP, char *\fIargv\fP[]); +.fi \fR +.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 +\fB +extern char **environ; +.fi \fR +.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\(hy2008, +.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\(hy2008, +.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, all attributes of the +corresponding open file descriptions, including file locks (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. All attributes of +the corresponding open file descriptions, including file locks (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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_spawn_file_actions_addclose.3p b/man-pages-posix-2013/man3p/posix_spawn_file_actions_addclose.3p new file mode 100644 index 0000000..d72ee5e --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_spawn_file_actions_addclose.3p @@ -0,0 +1,328 @@ +'\" et +.TH POSIX_SPAWN_FILE_ACTIONS_ADDCLOSE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +system ("myprog \fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_spawn_file_actions_adddup2.3p b/man-pages-posix-2013/man3p/posix_spawn_file_actions_adddup2.3p new file mode 100644 index 0000000..80e6de3 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_spawn_file_actions_adddup2.3p @@ -0,0 +1,135 @@ +'\" et +.TH POSIX_SPAWN_FILE_ACTIONS_ADDDUP2 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_spawn_file_actions_addopen.3p b/man-pages-posix-2013/man3p/posix_spawn_file_actions_addopen.3p new file mode 100644 index 0000000..e7657f6 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_spawn_file_actions_addopen.3p @@ -0,0 +1,41 @@ +'\" et +.TH POSIX_SPAWN_FILE_ACTIONS_ADDOPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_spawn_file_actions_destroy.3p b/man-pages-posix-2013/man3p/posix_spawn_file_actions_destroy.3p new file mode 100644 index 0000000..0039435 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_spawn_file_actions_destroy.3p @@ -0,0 +1,109 @@ +'\" et +.TH POSIX_SPAWN_FILE_ACTIONS_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.br +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_spawnattr_destroy.3p b/man-pages-posix-2013/man3p/posix_spawnattr_destroy.3p new file mode 100644 index 0000000..4643049 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_spawnattr_destroy.3p @@ -0,0 +1,151 @@ +'\" et +.TH POSIX_SPAWNATTR_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_spawnattr_getflags.3p b/man-pages-posix-2013/man3p/posix_spawnattr_getflags.3p new file mode 100644 index 0000000..e8c2f62 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_spawnattr_getflags.3p @@ -0,0 +1,129 @@ +'\" et +.TH POSIX_SPAWNATTR_GETFLAGS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_spawnattr_getpgroup.3p b/man-pages-posix-2013/man3p/posix_spawnattr_getpgroup.3p new file mode 100644 index 0000000..536077a --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_spawnattr_getpgroup.3p @@ -0,0 +1,114 @@ +'\" et +.TH POSIX_SPAWNATTR_GETPGROUP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_spawnattr_getschedparam.3p b/man-pages-posix-2013/man3p/posix_spawnattr_getschedparam.3p new file mode 100644 index 0000000..74c0412 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_spawnattr_getschedparam.3p @@ -0,0 +1,119 @@ +'\" et +.TH POSIX_SPAWNATTR_GETSCHEDPARAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_spawnattr_getschedpolicy.3p b/man-pages-posix-2013/man3p/posix_spawnattr_getschedpolicy.3p new file mode 100644 index 0000000..8f1262c --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_spawnattr_getschedpolicy.3p @@ -0,0 +1,118 @@ +'\" et +.TH POSIX_SPAWNATTR_GETSCHEDPOLICY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_spawnattr_getsigdefault.3p b/man-pages-posix-2013/man3p/posix_spawnattr_getsigdefault.3p new file mode 100644 index 0000000..6aef458 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_spawnattr_getsigdefault.3p @@ -0,0 +1,119 @@ +'\" et +.TH POSIX_SPAWNATTR_GETSIGDEFAULT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_spawnattr_getsigmask.3p b/man-pages-posix-2013/man3p/posix_spawnattr_getsigmask.3p new file mode 100644 index 0000000..0a43b27 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_spawnattr_getsigmask.3p @@ -0,0 +1,117 @@ +'\" et +.TH POSIX_SPAWNATTR_GETSIGMASK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_spawnattr_init.3p b/man-pages-posix-2013/man3p/posix_spawnattr_init.3p new file mode 100644 index 0000000..a088a07 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_spawnattr_init.3p @@ -0,0 +1,39 @@ +'\" et +.TH POSIX_SPAWNATTR_INIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_spawnattr_setflags.3p b/man-pages-posix-2013/man3p/posix_spawnattr_setflags.3p new file mode 100644 index 0000000..43afdb4 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_spawnattr_setflags.3p @@ -0,0 +1,39 @@ +'\" et +.TH POSIX_SPAWNATTR_SETFLAGS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_spawnattr_setpgroup.3p b/man-pages-posix-2013/man3p/posix_spawnattr_setpgroup.3p new file mode 100644 index 0000000..cac176e --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_spawnattr_setpgroup.3p @@ -0,0 +1,39 @@ +'\" et +.TH POSIX_SPAWNATTR_SETPGROUP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_spawnattr_setschedparam.3p b/man-pages-posix-2013/man3p/posix_spawnattr_setschedparam.3p new file mode 100644 index 0000000..e90734c --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_spawnattr_setschedparam.3p @@ -0,0 +1,41 @@ +'\" et +.TH POSIX_SPAWNATTR_SETSCHEDPARAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_spawnattr_setschedpolicy.3p b/man-pages-posix-2013/man3p/posix_spawnattr_setschedpolicy.3p new file mode 100644 index 0000000..7aed806 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_spawnattr_setschedpolicy.3p @@ -0,0 +1,41 @@ +'\" et +.TH POSIX_SPAWNATTR_SETSCHEDPOLICY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_spawnattr_setsigdefault.3p b/man-pages-posix-2013/man3p/posix_spawnattr_setsigdefault.3p new file mode 100644 index 0000000..c239cec --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_spawnattr_setsigdefault.3p @@ -0,0 +1,41 @@ +'\" et +.TH POSIX_SPAWNATTR_SETSIGDEFAULT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_spawnattr_setsigmask.3p b/man-pages-posix-2013/man3p/posix_spawnattr_setsigmask.3p new file mode 100644 index 0000000..585a103 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_spawnattr_setsigmask.3p @@ -0,0 +1,41 @@ +'\" et +.TH POSIX_SPAWNATTR_SETSIGMASK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_spawnp.3p b/man-pages-posix-2013/man3p/posix_spawnp.3p new file mode 100644 index 0000000..13db80e --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_spawnp.3p @@ -0,0 +1,42 @@ +'\" et +.TH POSIX_SPAWNP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_attr_destroy.3p b/man-pages-posix-2013/man3p/posix_trace_attr_destroy.3p new file mode 100644 index 0000000..a17d322 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_attr_destroy.3p @@ -0,0 +1,125 @@ +'\" et +.TH POSIX_TRACE_ATTR_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_attr_getclockres.3p b/man-pages-posix-2013/man3p/posix_trace_attr_getclockres.3p new file mode 100644 index 0000000..0806982 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_attr_getclockres.3p @@ -0,0 +1,190 @@ +'\" et +.TH POSIX_TRACE_ATTR_GETCLOCKRES "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_attr_getinherited.3p b/man-pages-posix-2013/man3p/posix_trace_attr_getinherited.3p new file mode 100644 index 0000000..ed4c3a0 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_attr_getinherited.3p @@ -0,0 +1,277 @@ +'\" et +.TH POSIX_TRACE_ATTR_GETINHERITED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_attr_getlogsize.3p b/man-pages-posix-2013/man3p/posix_trace_attr_getlogsize.3p new file mode 100644 index 0000000..35eb2ca --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_attr_getlogsize.3p @@ -0,0 +1,265 @@ +'\" et +.TH POSIX_TRACE_ATTR_GETLOGSIZE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_attr_getname.3p b/man-pages-posix-2013/man3p/posix_trace_attr_getname.3p new file mode 100644 index 0000000..c18693e --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_attr_getname.3p @@ -0,0 +1,40 @@ +'\" et +.TH POSIX_TRACE_ATTR_GETNAME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_attr_getstreamfullpolicy.3p b/man-pages-posix-2013/man3p/posix_trace_attr_getstreamfullpolicy.3p new file mode 100644 index 0000000..24a7b0c --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_attr_getstreamfullpolicy.3p @@ -0,0 +1,40 @@ +'\" et +.TH POSIX_TRACE_ATTR_GETSTREAMFULLPOLICY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_attr_getstreamsize.3p b/man-pages-posix-2013/man3p/posix_trace_attr_getstreamsize.3p new file mode 100644 index 0000000..97dccee --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_attr_getstreamsize.3p @@ -0,0 +1,41 @@ +'\" et +.TH POSIX_TRACE_ATTR_GETSTREAMSIZE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_attr_init.3p b/man-pages-posix-2013/man3p/posix_trace_attr_init.3p new file mode 100644 index 0000000..9603b4f --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_attr_init.3p @@ -0,0 +1,39 @@ +'\" et +.TH POSIX_TRACE_ATTR_INIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_attr_setinherited.3p b/man-pages-posix-2013/man3p/posix_trace_attr_setinherited.3p new file mode 100644 index 0000000..ac33c81 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_attr_setinherited.3p @@ -0,0 +1,43 @@ +'\" et +.TH POSIX_TRACE_ATTR_SETINHERITED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_attr_setlogsize.3p b/man-pages-posix-2013/man3p/posix_trace_attr_setlogsize.3p new file mode 100644 index 0000000..c5b7ab1 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_attr_setlogsize.3p @@ -0,0 +1,44 @@ +'\" et +.TH POSIX_TRACE_ATTR_SETLOGSIZE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_attr_setname.3p b/man-pages-posix-2013/man3p/posix_trace_attr_setname.3p new file mode 100644 index 0000000..23b93fb --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_attr_setname.3p @@ -0,0 +1,40 @@ +'\" et +.TH POSIX_TRACE_ATTR_SETNAME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_attr_setstreamfullpolicy.3p b/man-pages-posix-2013/man3p/posix_trace_attr_setstreamfullpolicy.3p new file mode 100644 index 0000000..81c52aa --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_attr_setstreamfullpolicy.3p @@ -0,0 +1,40 @@ +'\" et +.TH POSIX_TRACE_ATTR_SETSTREAMFULLPOLICY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_attr_setstreamsize.3p b/man-pages-posix-2013/man3p/posix_trace_attr_setstreamsize.3p new file mode 100644 index 0000000..d08dec9 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_attr_setstreamsize.3p @@ -0,0 +1,41 @@ +'\" et +.TH POSIX_TRACE_ATTR_SETSTREAMSIZE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_clear.3p b/man-pages-posix-2013/man3p/posix_trace_clear.3p new file mode 100644 index 0000000..37669b6 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_clear.3p @@ -0,0 +1,125 @@ +'\" et +.TH POSIX_TRACE_CLEAR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_close.3p b/man-pages-posix-2013/man3p/posix_trace_close.3p new file mode 100644 index 0000000..30d87d1 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_close.3p @@ -0,0 +1,173 @@ +'\" et +.TH POSIX_TRACE_CLOSE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_create.3p b/man-pages-posix-2013/man3p/posix_trace_create.3p new file mode 100644 index 0000000..5426601 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_create.3p @@ -0,0 +1,450 @@ +'\" et +.TH POSIX_TRACE_CREATE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_event.3p b/man-pages-posix-2013/man3p/posix_trace_event.3p new file mode 100644 index 0000000..2210a16 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_event.3p @@ -0,0 +1,178 @@ +'\" et +.TH POSIX_TRACE_EVENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_eventid_equal.3p b/man-pages-posix-2013/man3p/posix_trace_eventid_equal.3p new file mode 100644 index 0000000..959708c --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_eventid_equal.3p @@ -0,0 +1,225 @@ +'\" et +.TH POSIX_TRACE_EVENTID_EQUAL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_eventid_open.3p b/man-pages-posix-2013/man3p/posix_trace_eventid_open.3p new file mode 100644 index 0000000..1f95039 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_eventid_open.3p @@ -0,0 +1,41 @@ +'\" et +.TH POSIX_TRACE_EVENTID_OPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_eventset_add.3p b/man-pages-posix-2013/man3p/posix_trace_eventset_add.3p new file mode 100644 index 0000000..90598e5 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_eventset_add.3p @@ -0,0 +1,155 @@ +'\" et +.TH POSIX_TRACE_EVENTSET_ADD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_eventtypelist_getnext_id.3p b/man-pages-posix-2013/man3p/posix_trace_eventtypelist_getnext_id.3p new file mode 100644 index 0000000..bb2340a --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_eventtypelist_getnext_id.3p @@ -0,0 +1,109 @@ +'\" et +.TH POSIX_TRACE_EVENTTYPELIST_GETNEXT_ID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_flush.3p b/man-pages-posix-2013/man3p/posix_trace_flush.3p new file mode 100644 index 0000000..023c4cf --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_flush.3p @@ -0,0 +1,40 @@ +'\" et +.TH POSIX_TRACE_FLUSH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_get_attr.3p b/man-pages-posix-2013/man3p/posix_trace_get_attr.3p new file mode 100644 index 0000000..2ad5e72 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_get_attr.3p @@ -0,0 +1,138 @@ +'\" et +.TH POSIX_TRACE_GET_ATTR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_get_filter.3p b/man-pages-posix-2013/man3p/posix_trace_get_filter.3p new file mode 100644 index 0000000..1e92c37 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_get_filter.3p @@ -0,0 +1,143 @@ +'\" et +.TH POSIX_TRACE_GET_FILTER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_get_status.3p b/man-pages-posix-2013/man3p/posix_trace_get_status.3p new file mode 100644 index 0000000..df67bdd --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_get_status.3p @@ -0,0 +1,40 @@ +'\" et +.TH POSIX_TRACE_GET_STATUS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_getnext_event.3p b/man-pages-posix-2013/man3p/posix_trace_getnext_event.3p new file mode 100644 index 0000000..581ed23 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_getnext_event.3p @@ -0,0 +1,265 @@ +'\" et +.TH POSIX_TRACE_GETNEXT_EVENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_open.3p b/man-pages-posix-2013/man3p/posix_trace_open.3p new file mode 100644 index 0000000..651daa6 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_open.3p @@ -0,0 +1,41 @@ +'\" et +.TH POSIX_TRACE_OPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_set_filter.3p b/man-pages-posix-2013/man3p/posix_trace_set_filter.3p new file mode 100644 index 0000000..100175c --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_set_filter.3p @@ -0,0 +1,40 @@ +'\" et +.TH POSIX_TRACE_SET_FILTER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_shutdown.3p b/man-pages-posix-2013/man3p/posix_trace_shutdown.3p new file mode 100644 index 0000000..834f182 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_shutdown.3p @@ -0,0 +1,40 @@ +'\" et +.TH POSIX_TRACE_SHUTDOWN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_start.3p b/man-pages-posix-2013/man3p/posix_trace_start.3p new file mode 100644 index 0000000..4f7b14a --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_start.3p @@ -0,0 +1,103 @@ +'\" et +.TH POSIX_TRACE_START "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_timedgetnext_event.3p b/man-pages-posix-2013/man3p/posix_trace_timedgetnext_event.3p new file mode 100644 index 0000000..7d37ac6 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_timedgetnext_event.3p @@ -0,0 +1,44 @@ +'\" et +.TH POSIX_TRACE_TIMEDGETNEXT_EVENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_trid_eventid_open.3p b/man-pages-posix-2013/man3p/posix_trace_trid_eventid_open.3p new file mode 100644 index 0000000..1021014 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_trid_eventid_open.3p @@ -0,0 +1,41 @@ +'\" et +.TH POSIX_TRACE_TRID_EVENTID_OPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_trace_trygetnext_event.3p b/man-pages-posix-2013/man3p/posix_trace_trygetnext_event.3p new file mode 100644 index 0000000..6e55b78 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_trygetnext_event.3p @@ -0,0 +1,43 @@ +'\" et +.TH POSIX_TRACE_TRYGETNEXT_EVENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_typed_mem_get_info.3p b/man-pages-posix-2013/man3p/posix_typed_mem_get_info.3p new file mode 100644 index 0000000..218ffbb --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_typed_mem_get_info.3p @@ -0,0 +1,142 @@ +'\" et +.TH POSIX_TYPED_MEM_GET_INFO "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/posix_typed_mem_open.3p b/man-pages-posix-2013/man3p/posix_typed_mem_open.3p new file mode 100644 index 0000000..8b27a8f --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_typed_mem_open.3p @@ -0,0 +1,275 @@ +'\" et +.TH POSIX_TYPED_MEM_OPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 is 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 that is the +lowest numbered file descriptor not currently open for that process. +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 lowest +numbered unused file descriptor. Otherwise, it shall return \(mi1 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 "\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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pow.3p b/man-pages-posix-2013/man3p/pow.3p new file mode 100644 index 0000000..e91ba28 --- /dev/null +++ b/man-pages-posix-2013/man3p/pow.3p @@ -0,0 +1,315 @@ +'\" et +.TH POW "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 \(mi1, and +.IR y +is \(+-Inf, 1.0 shall be returned. +.P +For |\fIx\fP| < 1, if +.IR y +is \(miInf, +Inf shall be returned. +.P +For |\fIx\fP| > 1, if +.IR y +is \(miInf, +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 \(miInf, \(mi0 shall be returned. +.P +For +.IR y +< 0 and not an odd integer, if +.IR x +is \(miInf, +0 shall be returned. +.P +For +.IR y +an odd integer > 0, if +.IR x +is \(miInf, \(miInf shall be returned. +.P +For +.IR y +> 0 and not an odd integer, if +.IR x +is \(miInf, +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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pread.3p b/man-pages-posix-2013/man3p/pread.3p new file mode 100644 index 0000000..8f6ff64 --- /dev/null +++ b/man-pages-posix-2013/man3p/pread.3p @@ -0,0 +1,38 @@ +'\" et +.TH PREAD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/printf.3p b/man-pages-posix-2013/man3p/printf.3p new file mode 100644 index 0000000..743c4be --- /dev/null +++ b/man-pages-posix-2013/man3p/printf.3p @@ -0,0 +1,38 @@ +'\" et +.TH PRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pselect.3p b/man-pages-posix-2013/man3p/pselect.3p new file mode 100644 index 0000000..5a74faa --- /dev/null +++ b/man-pages-posix-2013/man3p/pselect.3p @@ -0,0 +1,504 @@ +'\" et +.TH PSELECT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 +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, \(mi1 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 before any of the selected events occurred +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 +\fB +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 \fR +.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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/psiginfo.3p b/man-pages-posix-2013/man3p/psiginfo.3p new file mode 100644 index 0000000..723d9cd --- /dev/null +++ b/man-pages-posix-2013/man3p/psiginfo.3p @@ -0,0 +1,175 @@ +'\" et +.TH PSIGINFO "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 print 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 print a message out on +.IR stderr +associated with a signal number. If +.IR message +is not null and is not the empty string, then the string pointed to by +the +.IR message +argument shall be printed first, followed by a +, +a +, +and the signal description string indicated by +.IR signum , +or by the signal associated with +.IR pinfo . +If the +.IR message +argument is null or points to an empty string, then only the signal +description shall be printed. For +\fIpsiginfo\fR(), +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\(hy2008, 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_atfork.3p b/man-pages-posix-2013/man3p/pthread_atfork.3p new file mode 100644 index 0000000..20dafcb --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_atfork.3p @@ -0,0 +1,237 @@ +'\" et +.TH PTHREAD_ATFORK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +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" +None. +.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" +None. +.SH "SEE ALSO" +.IR "\fIatexit\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfork\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_attr_destroy.3p b/man-pages-posix-2013/man3p/pthread_attr_destroy.3p new file mode 100644 index 0000000..430cfb6 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_attr_destroy.3p @@ -0,0 +1,237 @@ +'\" et +.TH PTHREAD_ATTR_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_attr_getdetachstate.3p b/man-pages-posix-2013/man3p/pthread_attr_getdetachstate.3p new file mode 100644 index 0000000..9a04312 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_attr_getdetachstate.3p @@ -0,0 +1,173 @@ +'\" et +.TH PTHREAD_ATTR_GETDETACHSTATE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +#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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_attr_getguardsize.3p b/man-pages-posix-2013/man3p/pthread_attr_getguardsize.3p new file mode 100644 index 0000000..21bde70 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_attr_getguardsize.3p @@ -0,0 +1,215 @@ +'\" et +.TH PTHREAD_ATTR_GETGUARDSIZE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +#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 \fR +.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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_attr_getinheritsched.3p b/man-pages-posix-2013/man3p/pthread_attr_getinheritsched.3p new file mode 100644 index 0000000..4dfc74c --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_attr_getinheritsched.3p @@ -0,0 +1,159 @@ +'\" et +.TH PTHREAD_ATTR_GETINHERITSCHED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_attr_getschedparam.3p b/man-pages-posix-2013/man3p/pthread_attr_getschedparam.3p new file mode 100644 index 0000000..d7e14e6 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_attr_getschedparam.3p @@ -0,0 +1,150 @@ +'\" et +.TH PTHREAD_ATTR_GETSCHEDPARAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_attr_getschedpolicy.3p b/man-pages-posix-2013/man3p/pthread_attr_getschedpolicy.3p new file mode 100644 index 0000000..044f606 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_attr_getschedpolicy.3p @@ -0,0 +1,133 @@ +'\" et +.TH PTHREAD_ATTR_GETSCHEDPOLICY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_attr_getscope.3p b/man-pages-posix-2013/man3p/pthread_attr_getscope.3p new file mode 100644 index 0000000..f003b5b --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_attr_getscope.3p @@ -0,0 +1,132 @@ +'\" et +.TH PTHREAD_ATTR_GETSCOPE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_attr_getstack.3p b/man-pages-posix-2013/man3p/pthread_attr_getstack.3p new file mode 100644 index 0000000..d545375 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_attr_getstack.3p @@ -0,0 +1,201 @@ +'\" et +.TH PTHREAD_ATTR_GETSTACK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_attr_getstacksize.3p b/man-pages-posix-2013/man3p/pthread_attr_getstacksize.3p new file mode 100644 index 0000000..bd1427d --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_attr_getstacksize.3p @@ -0,0 +1,119 @@ +'\" et +.TH PTHREAD_ATTR_GETSTACKSIZE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_attr_init.3p b/man-pages-posix-2013/man3p/pthread_attr_init.3p new file mode 100644 index 0000000..a15e4a1 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_attr_init.3p @@ -0,0 +1,38 @@ +'\" et +.TH PTHREAD_ATTR_INIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_attr_setdetachstate.3p b/man-pages-posix-2013/man3p/pthread_attr_setdetachstate.3p new file mode 100644 index 0000000..51bc552 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_attr_setdetachstate.3p @@ -0,0 +1,38 @@ +'\" et +.TH PTHREAD_ATTR_SETDETACHSTATE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_attr_setguardsize.3p b/man-pages-posix-2013/man3p/pthread_attr_setguardsize.3p new file mode 100644 index 0000000..9c07af5 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_attr_setguardsize.3p @@ -0,0 +1,39 @@ +'\" et +.TH PTHREAD_ATTR_SETGUARDSIZE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_attr_setinheritsched.3p b/man-pages-posix-2013/man3p/pthread_attr_setinheritsched.3p new file mode 100644 index 0000000..f259b7a --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_attr_setinheritsched.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_ATTR_SETINHERITSCHED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_attr_setschedparam.3p b/man-pages-posix-2013/man3p/pthread_attr_setschedparam.3p new file mode 100644 index 0000000..dfb4fe9 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_attr_setschedparam.3p @@ -0,0 +1,39 @@ +'\" et +.TH PTHREAD_ATTR_SETSCHEDPARAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_attr_setschedpolicy.3p b/man-pages-posix-2013/man3p/pthread_attr_setschedpolicy.3p new file mode 100644 index 0000000..3f9e446 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_attr_setschedpolicy.3p @@ -0,0 +1,39 @@ +'\" et +.TH PTHREAD_ATTR_SETSCHEDPOLICY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_attr_setscope.3p b/man-pages-posix-2013/man3p/pthread_attr_setscope.3p new file mode 100644 index 0000000..721f267 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_attr_setscope.3p @@ -0,0 +1,39 @@ +'\" et +.TH PTHREAD_ATTR_SETSCOPE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_attr_setstack.3p b/man-pages-posix-2013/man3p/pthread_attr_setstack.3p new file mode 100644 index 0000000..a6ef250 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_attr_setstack.3p @@ -0,0 +1,39 @@ +'\" et +.TH PTHREAD_ATTR_SETSTACK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_attr_setstacksize.3p b/man-pages-posix-2013/man3p/pthread_attr_setstacksize.3p new file mode 100644 index 0000000..676ac3e --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_attr_setstacksize.3p @@ -0,0 +1,38 @@ +'\" et +.TH PTHREAD_ATTR_SETSTACKSIZE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_barrier_destroy.3p b/man-pages-posix-2013/man3p/pthread_barrier_destroy.3p new file mode 100644 index 0000000..124b447 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_barrier_destroy.3p @@ -0,0 +1,168 @@ +'\" et +.TH PTHREAD_BARRIER_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +Only the object referenced by +.IR barrier +may be used for performing synchronization. The result of referring to +copies of that object in calls to +\fIpthread_barrier_destroy\fR() +or +\fIpthread_barrier_wait\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_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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_barrier_wait.3p b/man-pages-posix-2013/man3p/pthread_barrier_wait.3p new file mode 100644 index 0000000..48735fe --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_barrier_wait.3p @@ -0,0 +1,112 @@ +'\" et +.TH PTHREAD_BARRIER_WAIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "Section 3.287" ", " "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\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion", +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_barrierattr_destroy.3p b/man-pages-posix-2013/man3p/pthread_barrierattr_destroy.3p new file mode 100644 index 0000000..b83baf9 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_barrierattr_destroy.3p @@ -0,0 +1,113 @@ +'\" et +.TH PTHREAD_BARRIERATTR_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_barrierattr_getpshared.3p b/man-pages-posix-2013/man3p/pthread_barrierattr_getpshared.3p new file mode 100644 index 0000000..3592976 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_barrierattr_getpshared.3p @@ -0,0 +1,141 @@ +'\" et +.TH PTHREAD_BARRIERATTR_GETPSHARED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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. If the +.IR process-shared +attribute is PTHREAD_PROCESS_PRIVATE, the barrier shall only be +operated upon by +threads created within the same process as the thread that initialized +the barrier; if threads of different processes attempt to operate on +such a barrier, the behavior is undefined. 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_barrierattr_init.3p b/man-pages-posix-2013/man3p/pthread_barrierattr_init.3p new file mode 100644 index 0000000..e9ac123 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_barrierattr_init.3p @@ -0,0 +1,38 @@ +'\" et +.TH PTHREAD_BARRIERATTR_INIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_barrierattr_setpshared.3p b/man-pages-posix-2013/man3p/pthread_barrierattr_setpshared.3p new file mode 100644 index 0000000..7f853cb --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_barrierattr_setpshared.3p @@ -0,0 +1,39 @@ +'\" et +.TH PTHREAD_BARRIERATTR_SETPSHARED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_cancel.3p b/man-pages-posix-2013/man3p/pthread_cancel.3p new file mode 100644 index 0000000..2b417a3 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_cancel.3p @@ -0,0 +1,121 @@ +'\" et +.TH PTHREAD_CANCEL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_cleanup_pop.3p b/man-pages-posix-2013/man3p/pthread_cleanup_pop.3p new file mode 100644 index 0000000..19c80c6 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_cleanup_pop.3p @@ -0,0 +1,335 @@ +'\" et +.TH PTHREAD_CLEANUP_POP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +These functions may be implemented as macros. 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 +\fB +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 = \(mi1; + /* + * 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 \fR +.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 +\fB +#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 \fR +.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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_cond_broadcast.3p b/man-pages-posix-2013/man3p/pthread_cond_broadcast.3p new file mode 100644 index 0000000..dd92468 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_cond_broadcast.3p @@ -0,0 +1,238 @@ +'\" et +.TH PTHREAD_COND_BROADCAST "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +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 \fR +.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\(hy2008, +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_cond_destroy.3p b/man-pages-posix-2013/man3p/pthread_cond_destroy.3p new file mode 100644 index 0000000..ec8e263 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_cond_destroy.3p @@ -0,0 +1,236 @@ +'\" et +.TH PTHREAD_COND_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +Only +.IR cond +itself may be used for performing synchronization. The result of +referring to copies of +.IR cond +in calls to +\fIpthread_cond_wait\fR(), +\fIpthread_cond_timedwait\fR(), +\fIpthread_cond_signal\fR(), +\fIpthread_cond_broadcast\fR(), +and +\fIpthread_cond_destroy\fR() +is undefined. +.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 +\fB +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(&rp->notbusy); + free(ep); +} +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_cond_signal.3p b/man-pages-posix-2013/man3p/pthread_cond_signal.3p new file mode 100644 index 0000000..c9af451 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_cond_signal.3p @@ -0,0 +1,38 @@ +'\" et +.TH PTHREAD_COND_SIGNAL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_cond_timedwait.3p b/man-pages-posix-2013/man3p/pthread_cond_timedwait.3p new file mode 100644 index 0000000..8dc4ba4 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_cond_timedwait.3p @@ -0,0 +1,459 @@ +'\" et +.TH PTHREAD_COND_TIMEDWAIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 in the case of +.BR [ETIMEDOUT] , +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 +\fB +clock_gettime(CLOCK_REALTIME, &now) +reltime = sleep_til_this_absolute_time -now; +cond_relative_timed_wait(c, m, &reltime); +.fi \fR +.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 +\fB +(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 \fR +.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\(hy2008, +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_condattr_destroy.3p b/man-pages-posix-2013/man3p/pthread_condattr_destroy.3p new file mode 100644 index 0000000..ff58ec9 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_condattr_destroy.3p @@ -0,0 +1,141 @@ +'\" et +.TH PTHREAD_CONDATTR_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_condattr_getclock.3p b/man-pages-posix-2013/man3p/pthread_condattr_getclock.3p new file mode 100644 index 0000000..40d71ed --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_condattr_getclock.3p @@ -0,0 +1,133 @@ +'\" et +.TH PTHREAD_CONDATTR_GETCLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_condattr_getpshared.3p b/man-pages-posix-2013/man3p/pthread_condattr_getpshared.3p new file mode 100644 index 0000000..9fa1907 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_condattr_getpshared.3p @@ -0,0 +1,132 @@ +'\" et +.TH PTHREAD_CONDATTR_GETPSHARED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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. If the +.IR process-shared +attribute is PTHREAD_PROCESS_PRIVATE, the condition variable +shall only be operated upon by threads created within the same process +as the thread that initialized the condition variable; if threads of +differing processes attempt to operate on such a condition variable, +the behavior is undefined. 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_condattr_init.3p b/man-pages-posix-2013/man3p/pthread_condattr_init.3p new file mode 100644 index 0000000..a6d63fb --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_condattr_init.3p @@ -0,0 +1,38 @@ +'\" et +.TH PTHREAD_CONDATTR_INIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_condattr_setclock.3p b/man-pages-posix-2013/man3p/pthread_condattr_setclock.3p new file mode 100644 index 0000000..b68bbc0 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_condattr_setclock.3p @@ -0,0 +1,39 @@ +'\" et +.TH PTHREAD_CONDATTR_SETCLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_condattr_setpshared.3p b/man-pages-posix-2013/man3p/pthread_condattr_setpshared.3p new file mode 100644 index 0000000..c2f85a2 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_condattr_setpshared.3p @@ -0,0 +1,39 @@ +'\" et +.TH PTHREAD_CONDATTR_SETPSHARED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_create.3p b/man-pages-posix-2013/man3p/pthread_create.3p new file mode 100644 index 0000000..69bec24 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_create.3p @@ -0,0 +1,234 @@ +'\" et +.TH PTHREAD_CREATE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 return value 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\(hy2008, +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_detach.3p b/man-pages-posix-2013/man3p/pthread_detach.3p new file mode 100644 index 0000000..6d37157 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_detach.3p @@ -0,0 +1,119 @@ +'\" et +.TH PTHREAD_DETACH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_equal.3p b/man-pages-posix-2013/man3p/pthread_equal.3p new file mode 100644 index 0000000..a3ff5f1 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_equal.3p @@ -0,0 +1,86 @@ +'\" et +.TH PTHREAD_EQUAL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_exit.3p b/man-pages-posix-2013/man3p/pthread_exit.3p new file mode 100644 index 0000000..afad1a6 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_exit.3p @@ -0,0 +1,127 @@ +'\" et +.TH PTHREAD_EXIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_getconcurrency.3p b/man-pages-posix-2013/man3p/pthread_getconcurrency.3p new file mode 100644 index 0000000..4a1c9bd --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_getconcurrency.3p @@ -0,0 +1,140 @@ +'\" et +.TH PTHREAD_GETCONCURRENCY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_getcpuclockid.3p b/man-pages-posix-2013/man3p/pthread_getcpuclockid.3p new file mode 100644 index 0000000..37bd8d7 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_getcpuclockid.3p @@ -0,0 +1,78 @@ +'\" et +.TH PTHREAD_GETCPUCLOCKID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_getschedparam.3p b/man-pages-posix-2013/man3p/pthread_getschedparam.3p new file mode 100644 index 0000000..1d36dd7 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_getschedparam.3p @@ -0,0 +1,193 @@ +'\" et +.TH PTHREAD_GETSCHEDPARAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_getspecific.3p b/man-pages-posix-2013/man3p/pthread_getspecific.3p new file mode 100644 index 0000000..e8d6b4c --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_getspecific.3p @@ -0,0 +1,151 @@ +'\" et +.TH PTHREAD_GETSPECIFIC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_join.3p b/man-pages-posix-2013/man3p/pthread_join.3p new file mode 100644 index 0000000..5ba8bf3 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_join.3p @@ -0,0 +1,230 @@ +'\" et +.TH PTHREAD_JOIN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +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 \fR +.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\(hy2008 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\(hy2008, +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_key_create.3p b/man-pages-posix-2013/man3p/pthread_key_create.3p new file mode 100644 index 0000000..9fd2bc8 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_key_create.3p @@ -0,0 +1,261 @@ +'\" et +.TH PTHREAD_KEY_CREATE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +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 \fR +.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 +\fB +static pthread_key_t key; +.P +func() +{ + void *ptr; +.P + /* KEY NOT INITIALIZED!!! THIS WON'T WORK!!! */ + if ((ptr = pthread_getspecific(key)) == NULL && + pthread_setspecific(key, NULL) != 0) { + pthread_key_create(&key, NULL); + ... + } +} +.fi \fR +.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 +\fB +pthread_getspecific(key, &old); +new = allocate(); +destructor(old); +pthread_setspecific(key, new); +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_key_delete.3p b/man-pages-posix-2013/man3p/pthread_key_delete.3p new file mode 100644 index 0000000..4eca083 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_key_delete.3p @@ -0,0 +1,139 @@ +'\" et +.TH PTHREAD_KEY_DELETE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_kill.3p b/man-pages-posix-2013/man3p/pthread_kill.3p new file mode 100644 index 0000000..fa06e14 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_kill.3p @@ -0,0 +1,97 @@ +'\" et +.TH PTHREAD_KILL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIkill\fR\^(\|)", +.IR "\fIpthread_self\fR\^(\|)", +.IR "\fIraise\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_mutex_consistent.3p b/man-pages-posix-2013/man3p/pthread_mutex_consistent.3p new file mode 100644 index 0000000..177bbd9 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_mutex_consistent.3p @@ -0,0 +1,120 @@ +'\" et +.TH PTHREAD_MUTEX_CONSISTENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_mutex_destroy.3p b/man-pages-posix-2013/man3p/pthread_mutex_destroy.3p new file mode 100644 index 0000000..c8b22d6 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_mutex_destroy.3p @@ -0,0 +1,455 @@ +'\" et +.TH PTHREAD_MUTEX_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 is referenced +(for example, while being used in a +\fIpthread_cond_timedwait\fR() +or +\fIpthread_cond_wait\fR()) +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 +Only +.IR mutex +itself may be used for performing synchronization. The result of +referring to copies of +.IR mutex +in calls to +\fIpthread_mutex_lock\fR(), +\fIpthread_mutex_trylock\fR(), +\fIpthread_mutex_unlock\fR(), +and +\fIpthread_mutex_destroy\fR() +is undefined. +.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\(hy2008 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\(hy2008 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\(hy2008 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 +\fB +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 \fR +.P +.RE +.P +With static initialization, the same routine could be coded as +follows: +.sp +.RS 4 +.nf +\fB +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 \fR +.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. For +example, consider the following code: +.sp +.RS 4 +.nf +\fB +struct obj { +pthread_mutex_t om; + int refcnt; + ... +}; +.P +obj_done(struct obj *op) +{ + pthread_mutex_lock(&op->om); + if (-\|-op->refcnt == 0) { + pthread_mutex_unlock(&op->om); +(A) pthread_mutex_destroy(&op->om); +(B) free(op); + } else +(C) pthread_mutex_unlock(&op->om); +} +.fi \fR +.P +.RE +.P +In this case +.IR obj +is reference counted and +\fIobj_done\fR() +is called whenever a reference to the object is dropped. +Implementations are required to allow an object to be destroyed and +freed and potentially unmapped (for example, lines A and B) immediately +after the object is unlocked (line C). +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_mutex_getprioceiling.3p b/man-pages-posix-2013/man3p/pthread_mutex_getprioceiling.3p new file mode 100644 index 0000000..03093eb --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_mutex_getprioceiling.3p @@ -0,0 +1,151 @@ +'\" et +.TH PTHREAD_MUTEX_GETPRIOCEILING "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_mutex_init.3p b/man-pages-posix-2013/man3p/pthread_mutex_init.3p new file mode 100644 index 0000000..d898454 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_mutex_init.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_MUTEX_INIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_mutex_lock.3p b/man-pages-posix-2013/man3p/pthread_mutex_lock.3p new file mode 100644 index 0000000..a453a0b --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_mutex_lock.3p @@ -0,0 +1,309 @@ +'\" et +.TH PTHREAD_MUTEX_LOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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. +.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\(hy2008, +.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\(hy2008, +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_mutex_setprioceiling.3p b/man-pages-posix-2013/man3p/pthread_mutex_setprioceiling.3p new file mode 100644 index 0000000..53ae3ef --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_mutex_setprioceiling.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_MUTEX_SETPRIOCEILING "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_mutex_timedlock.3p b/man-pages-posix-2013/man3p/pthread_mutex_timedlock.3p new file mode 100644 index 0000000..4c1b9cf --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_mutex_timedlock.3p @@ -0,0 +1,195 @@ +'\" et +.TH PTHREAD_MUTEX_TIMEDLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "Section 4.11" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_mutex_trylock.3p b/man-pages-posix-2013/man3p/pthread_mutex_trylock.3p new file mode 100644 index 0000000..fcdf1c9 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_mutex_trylock.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_MUTEX_TRYLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_mutexattr_destroy.3p b/man-pages-posix-2013/man3p/pthread_mutexattr_destroy.3p new file mode 100644 index 0000000..1c6bdc9 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_mutexattr_destroy.3p @@ -0,0 +1,364 @@ +'\" et +.TH PTHREAD_MUTEXATTR_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 without changing the existing functions. Thus, they +provide for future extensibility of this volume of POSIX.1\(hy2008 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\(hy2008. 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\(hy2008 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 +\fB +/* 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 \fR +.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 +\fB +/* 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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_mutexattr_getprioceiling.3p b/man-pages-posix-2013/man3p/pthread_mutexattr_getprioceiling.3p new file mode 100644 index 0000000..12b41f4 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_mutexattr_getprioceiling.3p @@ -0,0 +1,123 @@ +'\" et +.TH PTHREAD_MUTEXATTR_GETPRIOCEILING "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_mutexattr_getprotocol.3p b/man-pages-posix-2013/man3p/pthread_mutexattr_getprotocol.3p new file mode 100644 index 0000000..d3ab83c --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_mutexattr_getprotocol.3p @@ -0,0 +1,197 @@ +'\" et +.TH PTHREAD_MUTEXATTR_GETPROTOCOL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_mutexattr_getpshared.3p b/man-pages-posix-2013/man3p/pthread_mutexattr_getpshared.3p new file mode 100644 index 0000000..1c2d107 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_mutexattr_getpshared.3p @@ -0,0 +1,130 @@ +'\" et +.TH PTHREAD_MUTEXATTR_GETPSHARED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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. If the +.IR process-shared +attribute is PTHREAD_PROCESS_PRIVATE, the mutex shall only be operated +upon by threads created within the same process as the thread that +initialized the mutex; if threads of differing processes attempt to +operate on such a mutex, the behavior is undefined. 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_mutexattr_getrobust.3p b/man-pages-posix-2013/man3p/pthread_mutexattr_getrobust.3p new file mode 100644 index 0000000..5196d9c --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_mutexattr_getrobust.3p @@ -0,0 +1,160 @@ +'\" et +.TH PTHREAD_MUTEXATTR_GETROBUST "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 acquires +the mutex may be notified about the termination by the return value +.BR [EOWNERDEAD] . +The notified thread can then attempt to mark the state protected by the +mutex as consistent again by a call to +\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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_mutexattr_gettype.3p b/man-pages-posix-2013/man3p/pthread_mutexattr_gettype.3p new file mode 100644 index 0000000..778792d --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_mutexattr_gettype.3p @@ -0,0 +1,135 @@ +'\" et +.TH PTHREAD_MUTEXATTR_GETTYPE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_mutexattr_init.3p b/man-pages-posix-2013/man3p/pthread_mutexattr_init.3p new file mode 100644 index 0000000..8af996b --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_mutexattr_init.3p @@ -0,0 +1,38 @@ +'\" et +.TH PTHREAD_MUTEXATTR_INIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_mutexattr_setprioceiling.3p b/man-pages-posix-2013/man3p/pthread_mutexattr_setprioceiling.3p new file mode 100644 index 0000000..e70d436 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_mutexattr_setprioceiling.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_MUTEXATTR_SETPRIOCEILING "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_mutexattr_setprotocol.3p b/man-pages-posix-2013/man3p/pthread_mutexattr_setprotocol.3p new file mode 100644 index 0000000..dccf9a3 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_mutexattr_setprotocol.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_MUTEXATTR_SETPROTOCOL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_mutexattr_setpshared.3p b/man-pages-posix-2013/man3p/pthread_mutexattr_setpshared.3p new file mode 100644 index 0000000..d89560e --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_mutexattr_setpshared.3p @@ -0,0 +1,39 @@ +'\" et +.TH PTHREAD_MUTEXATTR_SETPSHARED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_mutexattr_setrobust.3p b/man-pages-posix-2013/man3p/pthread_mutexattr_setrobust.3p new file mode 100644 index 0000000..f889f91 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_mutexattr_setrobust.3p @@ -0,0 +1,39 @@ +'\" et +.TH PTHREAD_MUTEXATTR_SETROBUST "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_mutexattr_settype.3p b/man-pages-posix-2013/man3p/pthread_mutexattr_settype.3p new file mode 100644 index 0000000..332df5c --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_mutexattr_settype.3p @@ -0,0 +1,38 @@ +'\" et +.TH PTHREAD_MUTEXATTR_SETTYPE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_once.3p b/man-pages-posix-2013/man3p/pthread_once.3p new file mode 100644 index 0000000..316b1e9 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_once.3p @@ -0,0 +1,175 @@ +'\" et +.TH PTHREAD_ONCE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +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" +None. +.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 +\fB +static int random_is_initialized = 0; +extern int initialize_random(); +.P +int random_function() +{ + if (random_is_initialized == 0) { + initialize_random(); + random_is_initialized = 1; + } + ... /* Operations performed after initialization. */ +} +.fi \fR +.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, a +simple initialization flag is not sufficient; the flag needs to be +protected against modification by multiple threads simultaneously +calling into the library. Protecting the flag requires the use of a +mutex; however, mutexes have to be initialized before they are used. +Ensuring that the mutex is only initialized once requires a recursive +solution to this problem. +.P +The use of +\fIpthread_once\fR() +not only supplies an implementation-guaranteed means of dynamic +initialization, it provides an aid to the reliable construction of +multi-threaded and realtime systems. The preceding example then +becomes: +.sp +.RS 4 +.nf +\fB +#include +static pthread_once_t random_is_initialized = PTHREAD_ONCE_INIT; +extern int initialize_random(); +.P +int random_function() +{ + (void) pthread_once(&random_is_initialized, initialize_random); + ... /* Operations performed after initialization. */ +} +.fi \fR +.P +.RE +.P +Note that a +.BR pthread_once_t +cannot be an array because some compilers do not accept the construct +\fB&\fP. +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_rwlock_destroy.3p b/man-pages-posix-2013/man3p/pthread_rwlock_destroy.3p new file mode 100644 index 0000000..acc1dd4 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_rwlock_destroy.3p @@ -0,0 +1,195 @@ +'\" et +.TH PTHREAD_RWLOCK_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +Only the object referenced by +.IR rwlock +may be used for performing synchronization. The result of referring to +copies of that object in calls to +\fIpthread_rwlock_destroy\fR(), +\fIpthread_rwlock_rdlock\fR(), +\fIpthread_rwlock_timedrdlock\fR(), +\fIpthread_rwlock_timedwrlock\fR(), +\fIpthread_rwlock_tryrdlock\fR(), +\fIpthread_rwlock_trywrlock\fR(), +\fIpthread_rwlock_unlock\fR(), +or +\fIpthread_rwlock_wrlock\fR() +is undefined. +.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\(hy2008, +.IR "Section 3.287" ", " "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_rwlockr_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\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_rwlock_rdlock.3p b/man-pages-posix-2013/man3p/pthread_rwlock_rdlock.3p new file mode 100644 index 0000000..6aa04e7 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_rwlock_rdlock.3p @@ -0,0 +1,182 @@ +'\" et +.TH PTHREAD_RWLOCK_RDLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "Section 3.287" ", " "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\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion", +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_rwlock_timedrdlock.3p b/man-pages-posix-2013/man3p/pthread_rwlock_timedrdlock.3p new file mode 100644 index 0000000..5ad394f --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_rwlock_timedrdlock.3p @@ -0,0 +1,148 @@ +'\" et +.TH PTHREAD_RWLOCK_TIMEDRDLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "Section 3.287" ", " "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\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion", +.IR "Section 4.11" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_rwlock_timedwrlock.3p b/man-pages-posix-2013/man3p/pthread_rwlock_timedwrlock.3p new file mode 100644 index 0000000..3cc9dbe --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_rwlock_timedwrlock.3p @@ -0,0 +1,141 @@ +'\" et +.TH PTHREAD_RWLOCK_TIMEDWRLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "Section 3.287" ", " "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\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion", +.IR "Section 4.11" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_rwlock_tryrdlock.3p b/man-pages-posix-2013/man3p/pthread_rwlock_tryrdlock.3p new file mode 100644 index 0000000..ef9a3b7 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_rwlock_tryrdlock.3p @@ -0,0 +1,38 @@ +'\" et +.TH PTHREAD_RWLOCK_TRYRDLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_rwlock_trywrlock.3p b/man-pages-posix-2013/man3p/pthread_rwlock_trywrlock.3p new file mode 100644 index 0000000..30313d2 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_rwlock_trywrlock.3p @@ -0,0 +1,133 @@ +'\" et +.TH PTHREAD_RWLOCK_TRYWRLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 acquires the write lock if no other thread (reader +or writer) holds the read-write lock +.IR rwlock . +Otherwise, the thread shall block until it can acquire the lock. The +calling thread may deadlock if at the time the call is made it holds +the read-write lock (whether a read or write lock). +.P +Implementations may favor writers over readers to avoid +writer starvation. +.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\(hy2008, +.IR "Section 3.287" ", " "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\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion", +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_rwlock_unlock.3p b/man-pages-posix-2013/man3p/pthread_rwlock_unlock.3p new file mode 100644 index 0000000..5583dc5 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_rwlock_unlock.3p @@ -0,0 +1,119 @@ +'\" et +.TH PTHREAD_RWLOCK_UNLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_rwlock_wrlock.3p b/man-pages-posix-2013/man3p/pthread_rwlock_wrlock.3p new file mode 100644 index 0000000..c6a2940 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_rwlock_wrlock.3p @@ -0,0 +1,38 @@ +'\" et +.TH PTHREAD_RWLOCK_WRLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_rwlockattr_destroy.3p b/man-pages-posix-2013/man3p/pthread_rwlockattr_destroy.3p new file mode 100644 index 0000000..330812b --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_rwlockattr_destroy.3p @@ -0,0 +1,115 @@ +'\" et +.TH PTHREAD_RWLOCKATTR_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_rwlockattr_getpshared.3p b/man-pages-posix-2013/man3p/pthread_rwlockattr_getpshared.3p new file mode 100644 index 0000000..aae565c --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_rwlockattr_getpshared.3p @@ -0,0 +1,124 @@ +'\" et +.TH PTHREAD_RWLOCKATTR_GETPSHARED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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. If the +.IR process-shared +attribute is PTHREAD_PROCESS_PRIVATE, the +read-write lock shall only be operated upon by threads created within +the same process as the thread that initialized the read-write lock; if +threads of differing processes attempt to operate on such a read-write +lock, the behavior is undefined. 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_rwlockattr_init.3p b/man-pages-posix-2013/man3p/pthread_rwlockattr_init.3p new file mode 100644 index 0000000..31736b5 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_rwlockattr_init.3p @@ -0,0 +1,38 @@ +'\" et +.TH PTHREAD_RWLOCKATTR_INIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_rwlockattr_setpshared.3p b/man-pages-posix-2013/man3p/pthread_rwlockattr_setpshared.3p new file mode 100644 index 0000000..929fbac --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_rwlockattr_setpshared.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_RWLOCKATTR_SETPSHARED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_self.3p b/man-pages-posix-2013/man3p/pthread_self.3p new file mode 100644 index 0000000..d63a03b --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_self.3p @@ -0,0 +1,67 @@ +'\" et +.TH PTHREAD_SELF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_setcancelstate.3p b/man-pages-posix-2013/man3p/pthread_setcancelstate.3p new file mode 100644 index 0000000..c7663d6 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_setcancelstate.3p @@ -0,0 +1,153 @@ +'\" et +.TH PTHREAD_SETCANCELSTATE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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" +None. +.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" +None. +.SH "SEE ALSO" +.IR "\fIpthread_cancel\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_setconcurrency.3p b/man-pages-posix-2013/man3p/pthread_setconcurrency.3p new file mode 100644 index 0000000..8b517b0 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_setconcurrency.3p @@ -0,0 +1,38 @@ +'\" et +.TH PTHREAD_SETCONCURRENCY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_setschedparam.3p b/man-pages-posix-2013/man3p/pthread_setschedparam.3p new file mode 100644 index 0000000..d59b83b --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_setschedparam.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_SETSCHEDPARAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_setschedprio.3p b/man-pages-posix-2013/man3p/pthread_setschedprio.3p new file mode 100644 index 0000000..5b936ac --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_setschedprio.3p @@ -0,0 +1,115 @@ +'\" et +.TH PTHREAD_SETSCHEDPRIO "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_setspecific.3p b/man-pages-posix-2013/man3p/pthread_setspecific.3p new file mode 100644 index 0000000..3ea1e51 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_setspecific.3p @@ -0,0 +1,38 @@ +'\" et +.TH PTHREAD_SETSPECIFIC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_sigmask.3p b/man-pages-posix-2013/man3p/pthread_sigmask.3p new file mode 100644 index 0000000..7c70fb4 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_sigmask.3p @@ -0,0 +1,248 @@ +'\" et +.TH PTHREAD_SIGMASK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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 +\fB +#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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_spin_destroy.3p b/man-pages-posix-2013/man3p/pthread_spin_destroy.3p new file mode 100644 index 0000000..6b74c45 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_spin_destroy.3p @@ -0,0 +1,155 @@ +'\" et +.TH PTHREAD_SPIN_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +If the Thread Process-Shared Synchronization option is supported and +the value of +.IR pshared +is PTHREAD_PROCESS_PRIVATE, +or if the option is not supported, the spin lock shall only be operated +upon by threads created within the same process as the thread that +initialized the spin lock. If threads of differing processes attempt to +operate on such a spin lock, the behavior is undefined. +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_spin_lock.3p b/man-pages-posix-2013/man3p/pthread_spin_lock.3p new file mode 100644 index 0000000..8daf932 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_spin_lock.3p @@ -0,0 +1,114 @@ +'\" et +.TH PTHREAD_SPIN_LOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "Section 3.287" ", " "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\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion", +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_spin_unlock.3p b/man-pages-posix-2013/man3p/pthread_spin_unlock.3p new file mode 100644 index 0000000..d0c4c9e --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_spin_unlock.3p @@ -0,0 +1,98 @@ +'\" et +.TH PTHREAD_SPIN_UNLOCK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pthread_testcancel.3p b/man-pages-posix-2013/man3p/pthread_testcancel.3p new file mode 100644 index 0000000..14e255c --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_testcancel.3p @@ -0,0 +1,38 @@ +'\" et +.TH PTHREAD_TESTCANCEL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/ptsname.3p b/man-pages-posix-2013/man3p/ptsname.3p new file mode 100644 index 0000000..e3032bf --- /dev/null +++ b/man-pages-posix-2013/man3p/ptsname.3p @@ -0,0 +1,86 @@ +'\" et +.TH PTSNAME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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. 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(). +.SH ERRORS +No errors are defined. +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/putc.3p b/man-pages-posix-2013/man3p/putc.3p new file mode 100644 index 0000000..de09fc5 --- /dev/null +++ b/man-pages-posix-2013/man3p/putc.3p @@ -0,0 +1,78 @@ +'\" et +.TH PUTC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/putc_unlocked.3p b/man-pages-posix-2013/man3p/putc_unlocked.3p new file mode 100644 index 0000000..f4db2ca --- /dev/null +++ b/man-pages-posix-2013/man3p/putc_unlocked.3p @@ -0,0 +1,38 @@ +'\" et +.TH PUTC_UNLOCKED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/putchar.3p b/man-pages-posix-2013/man3p/putchar.3p new file mode 100644 index 0000000..7a59c4c --- /dev/null +++ b/man-pages-posix-2013/man3p/putchar.3p @@ -0,0 +1,65 @@ +'\" et +.TH PUTCHAR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/putchar_unlocked.3p b/man-pages-posix-2013/man3p/putchar_unlocked.3p new file mode 100644 index 0000000..97e28b8 --- /dev/null +++ b/man-pages-posix-2013/man3p/putchar_unlocked.3p @@ -0,0 +1,38 @@ +'\" et +.TH PUTCHAR_UNLOCKED "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/putenv.3p b/man-pages-posix-2013/man3p/putenv.3p new file mode 100644 index 0000000..6b2b177 --- /dev/null +++ b/man-pages-posix-2013/man3p/putenv.3p @@ -0,0 +1,159 @@ +'\" et +.TH PUTENV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +#include +\&... +static char *var = "HOME=/usr/home"; +int ret; +.P +ret = putenv(var); +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/putmsg.3p b/man-pages-posix-2013/man3p/putmsg.3p new file mode 100644 index 0000000..ff4ec56 --- /dev/null +++ b/man-pages-posix-2013/man3p/putmsg.3p @@ -0,0 +1,361 @@ +'\" et +.TH PUTMSG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1. +.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 \(mi1 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 +\fB +#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 \fR +.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 +\fB +#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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/puts.3p b/man-pages-posix-2013/man3p/puts.3p new file mode 100644 index 0000000..df4434a --- /dev/null +++ b/man-pages-posix-2013/man3p/puts.3p @@ -0,0 +1,145 @@ +'\" et +.TH PUTS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +#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 \fR +.P +.RE +.SH "APPLICATION USAGE" +The +\fIputs\fR() +function appends a +, +while +\fIfputs\fR() +does not. +.P +This volume of POSIX.1\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pututxline.3p b/man-pages-posix-2013/man3p/pututxline.3p new file mode 100644 index 0000000..ac93ce1 --- /dev/null +++ b/man-pages-posix-2013/man3p/pututxline.3p @@ -0,0 +1,38 @@ +'\" et +.TH PUTUTXLINE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/putwc.3p b/man-pages-posix-2013/man3p/putwc.3p new file mode 100644 index 0000000..5b52e09 --- /dev/null +++ b/man-pages-posix-2013/man3p/putwc.3p @@ -0,0 +1,80 @@ +'\" et +.TH PUTWC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/putwchar.3p b/man-pages-posix-2013/man3p/putwchar.3p new file mode 100644 index 0000000..4ad1398 --- /dev/null +++ b/man-pages-posix-2013/man3p/putwchar.3p @@ -0,0 +1,66 @@ +'\" et +.TH PUTWCHAR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/pwrite.3p b/man-pages-posix-2013/man3p/pwrite.3p new file mode 100644 index 0000000..0713f73 --- /dev/null +++ b/man-pages-posix-2013/man3p/pwrite.3p @@ -0,0 +1,39 @@ +'\" et +.TH PWRITE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/qsort.3p b/man-pages-posix-2013/man3p/qsort.3p new file mode 100644 index 0000000..eeeaf94 --- /dev/null +++ b/man-pages-posix-2013/man3p/qsort.3p @@ -0,0 +1,113 @@ +'\" et +.TH QSORT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +((char *)p \(mi (char *)base) % width == 0 +(char *)p >= (char *)base +(char *)p < (char *)base + nel * width +.fi \fR +.P +.RE +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIalphasort\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/raise.3p b/man-pages-posix-2013/man3p/raise.3p new file mode 100644 index 0000000..03a87e3 --- /dev/null +++ b/man-pages-posix-2013/man3p/raise.3p @@ -0,0 +1,93 @@ +'\" et +.TH RAISE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +pthread_kill(pthread_self(), sig); +.fi \fR +.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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/rand.3p b/man-pages-posix-2013/man3p/rand.3p new file mode 100644 index 0000000..ca9234b --- /dev/null +++ b/man-pages-posix-2013/man3p/rand.3p @@ -0,0 +1,225 @@ +'\" et +.TH RAND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008 +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 +\fB +#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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/random.3p b/man-pages-posix-2013/man3p/random.3p new file mode 100644 index 0000000..3dfd9ca --- /dev/null +++ b/man-pages-posix-2013/man3p/random.3p @@ -0,0 +1,38 @@ +'\" et +.TH RANDOM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/read.3p b/man-pages-posix-2013/man3p/read.3p new file mode 100644 index 0000000..d411ce5 --- /dev/null +++ b/man-pages-posix-2013/man3p/read.3p @@ -0,0 +1,626 @@ +'\" et +.TH READ "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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 \(mi1 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 +\(mi1 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 pointer. 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 \(mi1 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 pointer shall remain unchanged. +.TP +.BR ESPIPE +The file is a pipe, FIFO, or socket. +.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 +\fB +#include +#include +\&... +char buf[20]; +size_t nbytes; +ssize_t bytes_read; +int fd; +\&... +nbytes = sizeof(buf); +bytes_read = read(fd, buf, nbytes); +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +This volume of POSIX.1\(hy2008 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 +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\(hy2008 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\(hy2008 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\(hy2008, 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\(hy2008. 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\(hy2008 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 \(mi1 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 \(mi1 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 \(mi1 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 \(mi1. +.P +This volume of POSIX.1\(hy2008 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/readdir.3p b/man-pages-posix-2013/man3p/readdir.3p new file mode 100644 index 0000000..4456a2a --- /dev/null +++ b/man-pages-posix-2013/man3p/readdir.3p @@ -0,0 +1,373 @@ +'\" et +.TH READDIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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. +.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 +\fB +#include +#include +#include +#include +.P +static void lookup(const char *arg) +{ + DIR *dirp; + struct dirent *dp; +.P + if ((dirp = opendir(".")) == NULL) { + perror("couldn't open '.'"); + 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 \fR +.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 +\fB +int derror (\fIdirp\fP) +DIR *\fIdirp\fP; +.P +void clearderr (\fIdirp\fP) +DIR *\fIdirp\fP; +.fi \fR +.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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/readlink.3p b/man-pages-posix-2013/man3p/readlink.3p new file mode 100644 index 0000000..6bdf98f --- /dev/null +++ b/man-pages-posix-2013/man3p/readlink.3p @@ -0,0 +1,255 @@ +'\" et +.TH READLINK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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); +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 file descriptor was +opened without O_SEARCH, the function shall check whether directory +searches are permitted using the current permissions of the directory +underlying the file descriptor. If the file descriptor was opened with +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 \(mi1, 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 +.IR fd +was not opened with 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 +\fB +#include +.P +char buf[1024]; +ssize_t len; +\&... +if ((len = readlink("/modules/pass1", buf, sizeof(buf)-1)) != -1) + buf[len] = '\e0'; +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/readv.3p b/man-pages-posix-2013/man3p/readv.3p new file mode 100644 index 0000000..a700b02 --- /dev/null +++ b/man-pages-posix-2013/man3p/readv.3p @@ -0,0 +1,150 @@ +'\" et +.TH READV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1]. +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 +\fB +#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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/realloc.3p b/man-pages-posix-2013/man3p/realloc.3p new file mode 100644 index 0000000..2eedf89 --- /dev/null +++ b/man-pages-posix-2013/man3p/realloc.3p @@ -0,0 +1,176 @@ +'\" et +.TH REALLOC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 returned pointer shall not be 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 +.IR errno +set to an implementation-defined value. +.IP " *" 4 +A unique pointer that can be successfully passed to +\fIfree\fR() +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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/realpath.3p b/man-pages-posix-2013/man3p/realpath.3p new file mode 100644 index 0000000..6a0c902 --- /dev/null +++ b/man-pages-posix-2013/man3p/realpath.3p @@ -0,0 +1,254 @@ +'\" et +.TH REALPATH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +#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 \fR +.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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/recv.3p b/man-pages-posix-2013/man3p/recv.3p new file mode 100644 index 0000000..9ec4726 --- /dev/null +++ b/man-pages-posix-2013/man3p/recv.3p @@ -0,0 +1,220 @@ +'\" et +.TH RECV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/recvfrom.3p b/man-pages-posix-2013/man3p/recvfrom.3p new file mode 100644 index 0000000..1323ba8 --- /dev/null +++ b/man-pages-posix-2013/man3p/recvfrom.3p @@ -0,0 +1,243 @@ +'\" et +.TH RECVFROM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/recvmsg.3p b/man-pages-posix-2013/man3p/recvmsg.3p new file mode 100644 index 0000000..855481b --- /dev/null +++ b/man-pages-posix-2013/man3p/recvmsg.3p @@ -0,0 +1,278 @@ +'\" et +.TH RECVMSG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/regcomp.3p b/man-pages-posix-2013/man3p/regcomp.3p new file mode 100644 index 0000000..06466af --- /dev/null +++ b/man-pages-posix-2013/man3p/regcomp.3p @@ -0,0 +1,873 @@ +'\" et +.TH REGCOMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.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\(hy2008, +.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 '^' ), +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 \(mi1] +shall be filled with \(mi1. 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 \(mi1. 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 \(mi1, then the pointers in +.IR pmatch [\c +.IR i ] +shall also be \(mi1. +.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\(hy2008, +.IR "Chapter 9" ", " "Regular Expressions"). +.IP " 2." 4 +A + +(\c +.BR '^' ) +in +.IR pattern , +when used to specify expression anchoring (see the Base Definitions volume of POSIX.1\(hy2008, +.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 +\fB +#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 \fR +.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 +\fB +(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 \fR +.P +.RE +.SH "APPLICATION USAGE" +An application could use: +.sp +.RS 4 +.nf +\fB +regerror(code,preg,(char *)NULL,(size_t)0) +.fi \fR +.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\(hy2008, +.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 \(mi>\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 \(mii +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\(hy2008). +.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\(hy2008, +.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\(hy2008, +.IR "Chapter 9" ", " "Regular Expressions", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/remainder.3p b/man-pages-posix-2013/man3p/remainder.3p new file mode 100644 index 0000000..70a121e --- /dev/null +++ b/man-pages-posix-2013/man3p/remainder.3p @@ -0,0 +1,145 @@ +'\" et +.TH REMAINDER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 defers to the ISO\ C standard. +.P +These functions shall return the floating-point remainder +.IR r =\c +.IR x \(mi\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\(mi\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 \(mi\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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/remove.3p b/man-pages-posix-2013/man3p/remove.3p new file mode 100644 index 0000000..a06a78e --- /dev/null +++ b/man-pages-posix-2013/man3p/remove.3p @@ -0,0 +1,97 @@ +'\" et +.TH REMOVE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +#include +.P +int status; +\&... +status = remove("/home/cnd/old_mods"); +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/remque.3p b/man-pages-posix-2013/man3p/remque.3p new file mode 100644 index 0000000..3cc5221 --- /dev/null +++ b/man-pages-posix-2013/man3p/remque.3p @@ -0,0 +1,38 @@ +'\" et +.TH REMQUE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/remquo.3p b/man-pages-posix-2013/man3p/remquo.3p new file mode 100644 index 0000000..54b48fb --- /dev/null +++ b/man-pages-posix-2013/man3p/remquo.3p @@ -0,0 +1,161 @@ +'\" et +.TH REMQUO "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/rename.3p b/man-pages-posix-2013/man3p/rename.3p new file mode 100644 index 0000000..c189d77 --- /dev/null +++ b/man-pages-posix-2013/man3p/rename.3p @@ -0,0 +1,549 @@ +'\" et +.TH RENAME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 relative to directory file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int rename(const char *\fIold\fP, const char *\fInew\fP); +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\(hy2008 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 processes 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 file descriptor was opened without O_SEARCH, the function +shall check whether directory searches are permitted using the current +permissions of the directory underlying the file descriptor. If the +file descriptor was opened with 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 \(mi1, +.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 \(mi1 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\(hy2008, +.IR "Section 4.2" ", " "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\(hy2008, +.IR "Section 4.2" ", " "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 +.IR oldfd +or +.IR newfd +was not opened with 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 +\fB +#include +.P +int status; +\&... +status = rename("/home/cnd/mod1", "/home/cnd/mod2"); +.fi \fR +.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 +\fB +rename("x", "x"); +.fi \fR +.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\(hy2008, +.IR "Section 4.2" ", " "Directory Protection", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/rewind.3p b/man-pages-posix-2013/man3p/rewind.3p new file mode 100644 index 0000000..8ab54b5 --- /dev/null +++ b/man-pages-posix-2013/man3p/rewind.3p @@ -0,0 +1,100 @@ +'\" et +.TH REWIND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 defers to the ISO\ C standard. +.P +The call: +.sp +.RS 4 +.nf +\fB +rewind(stream) +.fi \fR +.P +.RE +.P +shall be equivalent to: +.sp +.RS 4 +.nf +\fB +(void) fseek(stream, 0L, SEEK_SET) +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/rewinddir.3p b/man-pages-posix-2013/man3p/rewinddir.3p new file mode 100644 index 0000000..ca2f2dd --- /dev/null +++ b/man-pages-posix-2013/man3p/rewinddir.3p @@ -0,0 +1,91 @@ +'\" et +.TH REWINDDIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/rint.3p b/man-pages-posix-2013/man3p/rint.3p new file mode 100644 index 0000000..4a97551 --- /dev/null +++ b/man-pages-posix-2013/man3p/rint.3p @@ -0,0 +1,130 @@ +'\" et +.TH RINT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/rmdir.3p b/man-pages-posix-2013/man3p/rmdir.3p new file mode 100644 index 0000000..614afa0 --- /dev/null +++ b/man-pages-posix-2013/man3p/rmdir.3p @@ -0,0 +1,267 @@ +'\" et +.TH RMDIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 shall be returned, and +.IR errno +set to indicate the error. If \(mi1 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\(hy2008, +.IR "Section 4.2" ", " "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 +\fB +#include +.P +int status; +\&... +status = rmdir("/home/cnd/mod1"); +.fi \fR +.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\(hy2008, +.IR "Section 4.2" ", " "Directory Protection", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/round.3p b/man-pages-posix-2013/man3p/round.3p new file mode 100644 index 0000000..70cbb2f --- /dev/null +++ b/man-pages-posix-2013/man3p/round.3p @@ -0,0 +1,88 @@ +'\" et +.TH ROUND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/scalbln.3p b/man-pages-posix-2013/man3p/scalbln.3p new file mode 100644 index 0000000..bb6684c --- /dev/null +++ b/man-pages-posix-2013/man3p/scalbln.3p @@ -0,0 +1,172 @@ +'\" et +.TH SCALBLN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/scandir.3p b/man-pages-posix-2013/man3p/scandir.3p new file mode 100644 index 0000000..9b74e5d --- /dev/null +++ b/man-pages-posix-2013/man3p/scandir.3p @@ -0,0 +1,40 @@ +'\" et +.TH SCANDIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/scanf.3p b/man-pages-posix-2013/man3p/scanf.3p new file mode 100644 index 0000000..489ae6b --- /dev/null +++ b/man-pages-posix-2013/man3p/scanf.3p @@ -0,0 +1,38 @@ +'\" et +.TH SCANF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sched_get_priority_max.3p b/man-pages-posix-2013/man3p/sched_get_priority_max.3p new file mode 100644 index 0000000..a13261a --- /dev/null +++ b/man-pages-posix-2013/man3p/sched_get_priority_max.3p @@ -0,0 +1,93 @@ +'\" et +.TH SCHED_GET_PRIORITY_MAX "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sched_getparam.3p b/man-pages-posix-2013/man3p/sched_getparam.3p new file mode 100644 index 0000000..50c354f --- /dev/null +++ b/man-pages-posix-2013/man3p/sched_getparam.3p @@ -0,0 +1,98 @@ +'\" et +.TH SCHED_GETPARAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sched_getscheduler.3p b/man-pages-posix-2013/man3p/sched_getscheduler.3p new file mode 100644 index 0000000..ff248f3 --- /dev/null +++ b/man-pages-posix-2013/man3p/sched_getscheduler.3p @@ -0,0 +1,98 @@ +'\" et +.TH SCHED_GETSCHEDULER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sched_rr_get_interval.3p b/man-pages-posix-2013/man3p/sched_rr_get_interval.3p new file mode 100644 index 0000000..494a867 --- /dev/null +++ b/man-pages-posix-2013/man3p/sched_rr_get_interval.3p @@ -0,0 +1,86 @@ +'\" et +.TH SCHED_RR_GET_INTERVAL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sched_setparam.3p b/man-pages-posix-2013/man3p/sched_setparam.3p new file mode 100644 index 0000000..f3056d0 --- /dev/null +++ b/man-pages-posix-2013/man3p/sched_setparam.3p @@ -0,0 +1,157 @@ +'\" et +.TH SCHED_SETPARAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sched_setscheduler.3p b/man-pages-posix-2013/man3p/sched_setscheduler.3p new file mode 100644 index 0000000..2d6bf0a --- /dev/null +++ b/man-pages-posix-2013/man3p/sched_setscheduler.3p @@ -0,0 +1,182 @@ +'\" et +.TH SCHED_SETSCHEDULER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sched_yield.3p b/man-pages-posix-2013/man3p/sched_yield.3p new file mode 100644 index 0000000..affc53c --- /dev/null +++ b/man-pages-posix-2013/man3p/sched_yield.3p @@ -0,0 +1,67 @@ +'\" et +.TH SCHED_YIELD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/seed48.3p b/man-pages-posix-2013/man3p/seed48.3p new file mode 100644 index 0000000..876b529 --- /dev/null +++ b/man-pages-posix-2013/man3p/seed48.3p @@ -0,0 +1,39 @@ +'\" et +.TH SEED48 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/seekdir.3p b/man-pages-posix-2013/man3p/seekdir.3p new file mode 100644 index 0000000..5428a14 --- /dev/null +++ b/man-pages-posix-2013/man3p/seekdir.3p @@ -0,0 +1,117 @@ +'\" et +.TH SEEKDIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/select.3p b/man-pages-posix-2013/man3p/select.3p new file mode 100644 index 0000000..f63c3ad --- /dev/null +++ b/man-pages-posix-2013/man3p/select.3p @@ -0,0 +1,40 @@ +'\" et +.TH SELECT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sem_close.3p b/man-pages-posix-2013/man3p/sem_close.3p new file mode 100644 index 0000000..e7c0e31 --- /dev/null +++ b/man-pages-posix-2013/man3p/sem_close.3p @@ -0,0 +1,102 @@ +'\" et +.TH SEM_CLOSE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sem_destroy.3p b/man-pages-posix-2013/man3p/sem_destroy.3p new file mode 100644 index 0000000..0f54616 --- /dev/null +++ b/man-pages-posix-2013/man3p/sem_destroy.3p @@ -0,0 +1,93 @@ +'\" et +.TH SEM_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sem_getvalue.3p b/man-pages-posix-2013/man3p/sem_getvalue.3p new file mode 100644 index 0000000..bd5f1b3 --- /dev/null +++ b/man-pages-posix-2013/man3p/sem_getvalue.3p @@ -0,0 +1,90 @@ +'\" et +.TH SEM_GETVALUE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sem_init.3p b/man-pages-posix-2013/man3p/sem_init.3p new file mode 100644 index 0000000..cc2445c --- /dev/null +++ b/man-pages-posix-2013/man3p/sem_init.3p @@ -0,0 +1,146 @@ +'\" et +.TH SEM_INIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +Only +.IR sem +itself may be used for performing synchronization. The result of +referring to copies of +.IR sem +in calls to +\fIsem_wait\fR(), +\fIsem_timedwait\fR(), +\fIsem_trywait\fR(), +\fIsem_post\fR(), +and +\fIsem_destroy\fR() +is undefined. +.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. The use of the semaphore by threads other than those +created in the same process is undefined. +.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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sem_open.3p b/man-pages-posix-2013/man3p/sem_open.3p new file mode 100644 index 0000000..ece10ec --- /dev/null +++ b/man-pages-posix-2013/man3p/sem_open.3p @@ -0,0 +1,296 @@ +'\" et +.TH SEM_OPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sem_post.3p b/man-pages-posix-2013/man3p/sem_post.3p new file mode 100644 index 0000000..f731e7d --- /dev/null +++ b/man-pages-posix-2013/man3p/sem_post.3p @@ -0,0 +1,104 @@ +'\" et +.TH SEM_POST "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 +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\(hy2008, +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sem_timedwait.3p b/man-pages-posix-2013/man3p/sem_timedwait.3p new file mode 100644 index 0000000..ee894bf --- /dev/null +++ b/man-pages-posix-2013/man3p/sem_timedwait.3p @@ -0,0 +1,231 @@ +'\" et +.TH SEM_TIMEDWAIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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 +\fB +#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 \fR +.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\(hy2008, +.IR "Section 3.287" ", " "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\(hy2008, +.IR "Section 3.287" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sem_trywait.3p b/man-pages-posix-2013/man3p/sem_trywait.3p new file mode 100644 index 0000000..5dfbf15 --- /dev/null +++ b/man-pages-posix-2013/man3p/sem_trywait.3p @@ -0,0 +1,127 @@ +'\" et +.TH SEM_TRYWAIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "Section 3.287" ", " "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\(hy2008, +.IR "Section 3.287" ", " "Priority Inversion", +.IR "Section 4.11" ", " "Memory Synchronization", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sem_unlink.3p b/man-pages-posix-2013/man3p/sem_unlink.3p new file mode 100644 index 0000000..4e14310 --- /dev/null +++ b/man-pages-posix-2013/man3p/sem_unlink.3p @@ -0,0 +1,133 @@ +'\" et +.TH SEM_UNLINK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sem_wait.3p b/man-pages-posix-2013/man3p/sem_wait.3p new file mode 100644 index 0000000..0346657 --- /dev/null +++ b/man-pages-posix-2013/man3p/sem_wait.3p @@ -0,0 +1,38 @@ +'\" et +.TH SEM_WAIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/semctl.3p b/man-pages-posix-2013/man3p/semctl.3p new file mode 100644 index 0000000..c71c238 --- /dev/null +++ b/man-pages-posix-2013/man3p/semctl.3p @@ -0,0 +1,336 @@ +'\" et +.TH SEMCTL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "Section 4.16" ", " "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 +\fB +union semun { + int val; + struct semid_ds *buf; + unsigned short *array; +} arg; +.fi \fR +.P +.RE +.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 +\fB +sem_perm.uid +sem_perm.gid +sem_perm.mode +.fi \fR +.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 \(mi1 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\(hy2008, +.IR "Section 4.16" ", " "Semaphore", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/semget.3p b/man-pages-posix-2013/man3p/semget.3p new file mode 100644 index 0000000..7c15c14 --- /dev/null +++ b/man-pages-posix-2013/man3p/semget.3p @@ -0,0 +1,196 @@ +'\" et +.TH SEMGET "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "Section 4.16" ", " "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 \(mi1 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\(hy2008, +.IR "Section 4.16" ", " "Semaphore", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/semop.3p b/man-pages-posix-2013/man3p/semop.3p new file mode 100644 index 0000000..e07ba49 --- /dev/null +++ b/man-pages-posix-2013/man3p/semop.3p @@ -0,0 +1,480 @@ +'\" et +.TH SEMOP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "Section 4.16" ", " "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 \(mi1 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 \(mi1 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 \(mi1 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 +\fB +#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 \fR +.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 +\fB +#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", 'a')) == (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 \fR +.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\(hy2008, +.IR "Section 4.16" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/send.3p b/man-pages-posix-2013/man3p/send.3p new file mode 100644 index 0000000..a38fae1 --- /dev/null +++ b/man-pages-posix-2013/man3p/send.3p @@ -0,0 +1,224 @@ +'\" et +.TH SEND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 +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, \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sendmsg.3p b/man-pages-posix-2013/man3p/sendmsg.3p new file mode 100644 index 0000000..c826fe0 --- /dev/null +++ b/man-pages-posix-2013/man3p/sendmsg.3p @@ -0,0 +1,323 @@ +'\" et +.TH SENDMSG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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 \(mi1 +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, \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sendto.3p b/man-pages-posix-2013/man3p/sendto.3p new file mode 100644 index 0000000..1ce82ef --- /dev/null +++ b/man-pages-posix-2013/man3p/sendto.3p @@ -0,0 +1,314 @@ +'\" et +.TH SENDTO "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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 \(mi1 +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, \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/setbuf.3p b/man-pages-posix-2013/man3p/setbuf.3p new file mode 100644 index 0000000..32fb1a0 --- /dev/null +++ b/man-pages-posix-2013/man3p/setbuf.3p @@ -0,0 +1,121 @@ +'\" et +.TH SETBUF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 defers to the ISO\ C standard. +.P +Except that it returns no value, the function call: +.sp +.RS 4 +.nf +\fB +setbuf(stream, buf) +.fi \fR +.P +.RE +.P +shall be equivalent to: +.sp +.RS 4 +.nf +\fB +setvbuf(stream, buf, _IOFBF, BUFSIZ) +.fi \fR +.P +.RE +.P +if +.IR buf +is not a null pointer, or to: +.sp +.RS 4 +.nf +\fB +setvbuf(stream, buf, _IONBF, BUFSIZ) +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/setegid.3p b/man-pages-posix-2013/man3p/setegid.3p new file mode 100644 index 0000000..6a388ca --- /dev/null +++ b/man-pages-posix-2013/man3p/setegid.3p @@ -0,0 +1,94 @@ +'\" et +.TH SETEGID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/setenv.3p b/man-pages-posix-2013/man3p/setenv.3p new file mode 100644 index 0000000..180025e --- /dev/null +++ b/man-pages-posix-2013/man3p/setenv.3p @@ -0,0 +1,167 @@ +'\" et +.TH SETENV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 +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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/seteuid.3p b/man-pages-posix-2013/man3p/seteuid.3p new file mode 100644 index 0000000..af9f09e --- /dev/null +++ b/man-pages-posix-2013/man3p/seteuid.3p @@ -0,0 +1,93 @@ +'\" et +.TH SETEUID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/setgid.3p b/man-pages-posix-2013/man3p/setgid.3p new file mode 100644 index 0000000..9223c8d --- /dev/null +++ b/man-pages-posix-2013/man3p/setgid.3p @@ -0,0 +1,101 @@ +'\" et +.TH SETGID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/setgrent.3p b/man-pages-posix-2013/man3p/setgrent.3p new file mode 100644 index 0000000..f993735 --- /dev/null +++ b/man-pages-posix-2013/man3p/setgrent.3p @@ -0,0 +1,38 @@ +'\" et +.TH SETGRENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sethostent.3p b/man-pages-posix-2013/man3p/sethostent.3p new file mode 100644 index 0000000..9e35f60 --- /dev/null +++ b/man-pages-posix-2013/man3p/sethostent.3p @@ -0,0 +1,38 @@ +'\" et +.TH SETHOSTENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/setitimer.3p b/man-pages-posix-2013/man3p/setitimer.3p new file mode 100644 index 0000000..59d19b3 --- /dev/null +++ b/man-pages-posix-2013/man3p/setitimer.3p @@ -0,0 +1,39 @@ +'\" et +.TH SETITIMER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/setjmp.3p b/man-pages-posix-2013/man3p/setjmp.3p new file mode 100644 index 0000000..ca5b6f8 --- /dev/null +++ b/man-pages-posix-2013/man3p/setjmp.3p @@ -0,0 +1,104 @@ +'\" et +.TH SETJMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/setkey.3p b/man-pages-posix-2013/man3p/setkey.3p new file mode 100644 index 0000000..3aa615c --- /dev/null +++ b/man-pages-posix-2013/man3p/setkey.3p @@ -0,0 +1,98 @@ +'\" et +.TH SETKEY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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" +None. +.SH "SEE ALSO" +.IR "\fIcrypt\fR\^(\|)", +.IR "\fIencrypt\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/setlocale.3p b/man-pages-posix-2013/man3p/setlocale.3p new file mode 100644 index 0000000..bb4f94d --- /dev/null +++ b/man-pages-posix-2013/man3p/setlocale.3p @@ -0,0 +1,441 @@ +'\" et +.TH SETLOCALE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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 +\fB +setlocale(LC_ALL, ""); +.fi \fR +.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\(hy2008, +.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\(hy2008 calls +\fIsetlocale\fR(). +.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(). +.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 +\fB +setlocale(LC_ALL, "De"); +setlocale(LC_COLLATE, "Fr@dict"); +.fi \fR +.P +.RE +.P +Internationalized programs can initiate language operation according +to environment variable settings (see the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables") +by calling +\fIsetlocale\fR() +as follows: +.sp +.RS 4 +.nf +\fB +setlocale(LC_ALL, ""); +.fi \fR +.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 +\fB +char *setlocale(int \fIcategory\fP, const char *\fIlocale\fP); +.fi \fR +.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 +\fB +setlocale({LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, \e + LC_NUMERIC, LC_TIME},(char *) NULL); +.fi \fR +.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 +\fB +setlocale(LC_ALL, "fr_FR.ISO-8859-1"); +.fi \fR +.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 "\fInl_langinfo\fR\^(\|)", +.IR "\fIperror\fR\^(\|)", +.IR "\fIpsiginfo\fR\^(\|)", +.IR "\fIsetlocale\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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/setlogmask.3p b/man-pages-posix-2013/man3p/setlogmask.3p new file mode 100644 index 0000000..8968918 --- /dev/null +++ b/man-pages-posix-2013/man3p/setlogmask.3p @@ -0,0 +1,38 @@ +'\" et +.TH SETLOGMASK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/setnetent.3p b/man-pages-posix-2013/man3p/setnetent.3p new file mode 100644 index 0000000..a85c2a7 --- /dev/null +++ b/man-pages-posix-2013/man3p/setnetent.3p @@ -0,0 +1,37 @@ +'\" et +.TH SETNETENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/setpgid.3p b/man-pages-posix-2013/man3p/setpgid.3p new file mode 100644 index 0000000..c50508c --- /dev/null +++ b/man-pages-posix-2013/man3p/setpgid.3p @@ -0,0 +1,201 @@ +'\" et +.TH SETPGID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/setpgrp.3p b/man-pages-posix-2013/man3p/setpgrp.3p new file mode 100644 index 0000000..29367c1 --- /dev/null +++ b/man-pages-posix-2013/man3p/setpgrp.3p @@ -0,0 +1,85 @@ +'\" et +.TH SETPGRP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/setpriority.3p b/man-pages-posix-2013/man3p/setpriority.3p new file mode 100644 index 0000000..d7e1b59 --- /dev/null +++ b/man-pages-posix-2013/man3p/setpriority.3p @@ -0,0 +1,38 @@ +'\" et +.TH SETPRIORITY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/setprotoent.3p b/man-pages-posix-2013/man3p/setprotoent.3p new file mode 100644 index 0000000..53c5e7a --- /dev/null +++ b/man-pages-posix-2013/man3p/setprotoent.3p @@ -0,0 +1,38 @@ +'\" et +.TH SETPROTOENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/setpwent.3p b/man-pages-posix-2013/man3p/setpwent.3p new file mode 100644 index 0000000..958cbe1 --- /dev/null +++ b/man-pages-posix-2013/man3p/setpwent.3p @@ -0,0 +1,38 @@ +'\" et +.TH SETPWENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/setregid.3p b/man-pages-posix-2013/man3p/setregid.3p new file mode 100644 index 0000000..29fe9e7 --- /dev/null +++ b/man-pages-posix-2013/man3p/setregid.3p @@ -0,0 +1,135 @@ +'\" et +.TH SETREGID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1, the real group ID shall not be changed; if +.IR egid +is \(mi1, 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 \(mi1), 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, \(mi1 +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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/setreuid.3p b/man-pages-posix-2013/man3p/setreuid.3p new file mode 100644 index 0000000..6d7982f --- /dev/null +++ b/man-pages-posix-2013/man3p/setreuid.3p @@ -0,0 +1,141 @@ +'\" et +.TH SETREUID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1, 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 \(mi1), 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, \(mi1 +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 +\fB +#include +#include +\&... +setreuid(getuid(), getuid()); +\&... +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/setrlimit.3p b/man-pages-posix-2013/man3p/setrlimit.3p new file mode 100644 index 0000000..00c2a17 --- /dev/null +++ b/man-pages-posix-2013/man3p/setrlimit.3p @@ -0,0 +1,38 @@ +'\" et +.TH SETRLIMIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/setservent.3p b/man-pages-posix-2013/man3p/setservent.3p new file mode 100644 index 0000000..df868c9 --- /dev/null +++ b/man-pages-posix-2013/man3p/setservent.3p @@ -0,0 +1,38 @@ +'\" et +.TH SETSERVENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/setsid.3p b/man-pages-posix-2013/man3p/setsid.3p new file mode 100644 index 0000000..4eb4e0e --- /dev/null +++ b/man-pages-posix-2013/man3p/setsid.3p @@ -0,0 +1,111 @@ +'\" et +.TH SETSID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/setsockopt.3p b/man-pages-posix-2013/man3p/setsockopt.3p new file mode 100644 index 0000000..cff6e9f --- /dev/null +++ b/man-pages-posix-2013/man3p/setsockopt.3p @@ -0,0 +1,165 @@ +'\" et +.TH SETSOCKOPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/setstate.3p b/man-pages-posix-2013/man3p/setstate.3p new file mode 100644 index 0000000..c3e0fae --- /dev/null +++ b/man-pages-posix-2013/man3p/setstate.3p @@ -0,0 +1,38 @@ +'\" et +.TH SETSTATE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/setuid.3p b/man-pages-posix-2013/man3p/setuid.3p new file mode 100644 index 0000000..4bdd011 --- /dev/null +++ b/man-pages-posix-2013/man3p/setuid.3p @@ -0,0 +1,255 @@ +'\" et +.TH SETUID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 +shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIsetuid\fR() +function shall fail, return \(mi1, 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/setutxent.3p b/man-pages-posix-2013/man3p/setutxent.3p new file mode 100644 index 0000000..d0cc57e --- /dev/null +++ b/man-pages-posix-2013/man3p/setutxent.3p @@ -0,0 +1,38 @@ +'\" et +.TH SETUTXENT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/setvbuf.3p b/man-pages-posix-2013/man3p/setvbuf.3p new file mode 100644 index 0000000..ab401c6 --- /dev/null +++ b/man-pages-posix-2013/man3p/setvbuf.3p @@ -0,0 +1,124 @@ +'\" et +.TH SETVBUF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/shm_open.3p b/man-pages-posix-2013/man3p/shm_open.3p new file mode 100644 index 0000000..7857174 --- /dev/null +++ b/man-pages-posix-2013/man3p/shm_open.3p @@ -0,0 +1,400 @@ +'\" et +.TH SHM_OPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 is 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 that is the +lowest numbered file descriptor not currently open for that process. +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 lowest +numbered unused file descriptor. Otherwise, it shall return \(mi1 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 +\fB +#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 == \(mi1) + /* Handle error */; +.P +if (ftruncate(fd, sizeof(struct region)) == \(mi1) + /* 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 \fR +.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\(hy2008 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\(hy2008 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 "\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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/shm_unlink.3p b/man-pages-posix-2013/man3p/shm_unlink.3p new file mode 100644 index 0000000..6d19b3b --- /dev/null +++ b/man-pages-posix-2013/man3p/shm_unlink.3p @@ -0,0 +1,139 @@ +'\" et +.TH SHM_UNLINK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 shall be returned and +.IR errno +set to indicate the error. If \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/shmat.3p b/man-pages-posix-2013/man3p/shmat.3p new file mode 100644 index 0000000..99855ef --- /dev/null +++ b/man-pages-posix-2013/man3p/shmat.3p @@ -0,0 +1,152 @@ +'\" et +.TH SHMAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "Section 3.342" ", " "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 \(mi((\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 \(mi1, 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 \(mi((\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\(hy2008, +.IR "Section 3.342" ", " "Shared Memory Object", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/shmctl.3p b/man-pages-posix-2013/man3p/shmctl.3p new file mode 100644 index 0000000..18de0ba --- /dev/null +++ b/man-pages-posix-2013/man3p/shmctl.3p @@ -0,0 +1,190 @@ +'\" et +.TH SHMCTL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "Section 3.342" ", " "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 +\fB +shm_perm.uid +shm_perm.gid +shm_perm.mode \fRLow-order nine bits.\fP +.fi \fR +.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 \(mi1 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\(hy2008, +.IR "Section 3.342" ", " "Shared Memory Object", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/shmdt.3p b/man-pages-posix-2013/man3p/shmdt.3p new file mode 100644 index 0000000..0ad0c16 --- /dev/null +++ b/man-pages-posix-2013/man3p/shmdt.3p @@ -0,0 +1,105 @@ +'\" et +.TH SHMDT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "Section 3.342" ", " "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 \(mi1, 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\(hy2008, +.IR "Section 3.342" ", " "Shared Memory Object", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/shmget.3p b/man-pages-posix-2013/man3p/shmget.3p new file mode 100644 index 0000000..ca1281e --- /dev/null +++ b/man-pages-posix-2013/man3p/shmget.3p @@ -0,0 +1,183 @@ +'\" et +.TH SHMGET "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "Section 3.342" ", " "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 \(mi1 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 shall +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\(hy2008, +.IR "Section 3.342" ", " "Shared Memory Object", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/shutdown.3p b/man-pages-posix-2013/man3p/shutdown.3p new file mode 100644 index 0000000..2fe1a0f --- /dev/null +++ b/man-pages-posix-2013/man3p/shutdown.3p @@ -0,0 +1,126 @@ +'\" et +.TH SHUTDOWN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sigaction.3p b/man-pages-posix-2013/man3p/sigaction.3p new file mode 100644 index 0000000..5d68eb2 --- /dev/null +++ b/man-pages-posix-2013/man3p/sigaction.3p @@ -0,0 +1,676 @@ +'\" et +.TH SIGACTION "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +void func(int \fIsigno\fP); +.fi \fR +.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 +\fB +void func(int \fIsigno\fP, siginfo_t *\fIinfo\fP, void *\fIcontext\fP); +.fi \fR +.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 set, and +.IR sig +equals SIGCHLD, 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] . +Otherwise, terminating child processes shall be transformed into zombie +processes, unless SIGCHLD is set to SIG_IGN. +.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, \(mi1 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. +.TP +.BR ENOTSUP +The SA_SIGINFO bit flag is set in the +.IR sa_flags +field of the +.BR sigaction +structure. +.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, 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 +\fB +#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) == \(mi1) + /* Handle error */; +.P + /* Further code */ +} +.fi \fR +.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\(hy2008, 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\(hy2008 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\(hy2008 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\(hy2008. The BSD declaration would be: +.sp +.RS 4 +.nf +\fB +void handler(int \fIsig\fP, int \fIcode\fP, struct sigcontext *\fIscp\fP, + char *\fIaddr\fP); +.fi \fR +.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\(hy2008, +.IR "Section B.2.4.2" ", " "Signal Generation and Delivery". +.SH RATIONALE +Although this volume of POSIX.1\(hy2008 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\(hy2008. +.P +This volume of POSIX.1\(hy2008 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\(hy2008 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 "\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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sigaddset.3p b/man-pages-posix-2013/man3p/sigaddset.3p new file mode 100644 index 0000000..367b4c7 --- /dev/null +++ b/man-pages-posix-2013/man3p/sigaddset.3p @@ -0,0 +1,103 @@ +'\" et +.TH SIGADDSET "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sigaltstack.3p b/man-pages-posix-2013/man3p/sigaltstack.3p new file mode 100644 index 0000000..5e7574f --- /dev/null +++ b/man-pages-posix-2013/man3p/sigaltstack.3p @@ -0,0 +1,181 @@ +'\" et +.TH SIGALTSTACK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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 +\fB +#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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sigdelset.3p b/man-pages-posix-2013/man3p/sigdelset.3p new file mode 100644 index 0000000..14817a0 --- /dev/null +++ b/man-pages-posix-2013/man3p/sigdelset.3p @@ -0,0 +1,104 @@ +'\" et +.TH SIGDELSET "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sigemptyset.3p b/man-pages-posix-2013/man3p/sigemptyset.3p new file mode 100644 index 0000000..6e0cd07 --- /dev/null +++ b/man-pages-posix-2013/man3p/sigemptyset.3p @@ -0,0 +1,118 @@ +'\" et +.TH SIGEMPTYSET "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008. Although it is outside the scope of +\&this volume of POSIX.1\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sigfillset.3p b/man-pages-posix-2013/man3p/sigfillset.3p new file mode 100644 index 0000000..72016b6 --- /dev/null +++ b/man-pages-posix-2013/man3p/sigfillset.3p @@ -0,0 +1,73 @@ +'\" et +.TH SIGFILLSET "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 are included. +.SH "RETURN VALUE" +Upon successful completion, +\fIsigfillset\fR() +shall return 0; otherwise, it shall return \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sighold.3p b/man-pages-posix-2013/man3p/sighold.3p new file mode 100644 index 0000000..2812e82 --- /dev/null +++ b/man-pages-posix-2013/man3p/sighold.3p @@ -0,0 +1,255 @@ +'\" et +.TH SIGHOLD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 and set +.IR errno +to +.BR [EINTR] . +.P +For all other functions, upon successful completion, 0 shall be returned. +Otherwise, \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/siginterrupt.3p b/man-pages-posix-2013/man3p/siginterrupt.3p new file mode 100644 index 0000000..78b25c3 --- /dev/null +++ b/man-pages-posix-2013/man3p/siginterrupt.3p @@ -0,0 +1,99 @@ +'\" et +.TH SIGINTERRUPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +int siginterrupt(int sig, int flag) { + int ret; + struct sigaction act; +.P + (void) sigaction(sig, NULL, &act); + if (flag) + act.sa_flags &= ~SA_RESTART; + else + act.sa_flags |= SA_RESTART; + ret = sigaction(sig, &act, NULL); + return ret; +} +.fi \fR +.P +.RE +.SH "RETURN VALUE" +Upon successful completion, +\fIsiginterrupt\fR() +shall return 0; otherwise, \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sigismember.3p b/man-pages-posix-2013/man3p/sigismember.3p new file mode 100644 index 0000000..55faf9f --- /dev/null +++ b/man-pages-posix-2013/man3p/sigismember.3p @@ -0,0 +1,105 @@ +'\" et +.TH SIGISMEMBER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/siglongjmp.3p b/man-pages-posix-2013/man3p/siglongjmp.3p new file mode 100644 index 0000000..a69f582 --- /dev/null +++ b/man-pages-posix-2013/man3p/siglongjmp.3p @@ -0,0 +1,106 @@ +'\" et +.TH SIGLONGJMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/signal.3p b/man-pages-posix-2013/man3p/signal.3p new file mode 100644 index 0000000..8a25dff --- /dev/null +++ b/man-pages-posix-2013/man3p/signal.3p @@ -0,0 +1,218 @@ +'\" et +.TH SIGNAL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 defers to the ISO\ C standard. +.P +Use of this function is unspecified in a multi-threaded process. +.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 +\fB +signal(\fIsig\fP, SIG_DFL); +.fi \fR +.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 +\fB +(*func)(sig); +.fi \fR +.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 +\fB +signal(\fIsig\fP, SIG_IGN); +.fi \fR +.P +.RE +.P +is executed for some signals, and the equivalent of: +.sp +.RS 4 +.nf +\fB +signal(\fIsig\fP, SIG_DFL); +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/signbit.3p b/man-pages-posix-2013/man3p/signbit.3p new file mode 100644 index 0000000..889a631 --- /dev/null +++ b/man-pages-posix-2013/man3p/signbit.3p @@ -0,0 +1,70 @@ +'\" et +.TH SIGNBIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/signgam.3p b/man-pages-posix-2013/man3p/signgam.3p new file mode 100644 index 0000000..3ac9cb5 --- /dev/null +++ b/man-pages-posix-2013/man3p/signgam.3p @@ -0,0 +1,38 @@ +'\" et +.TH SIGNGAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sigpause.3p b/man-pages-posix-2013/man3p/sigpause.3p new file mode 100644 index 0000000..727f324 --- /dev/null +++ b/man-pages-posix-2013/man3p/sigpause.3p @@ -0,0 +1,38 @@ +'\" et +.TH SIGPAUSE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sigpending.3p b/man-pages-posix-2013/man3p/sigpending.3p new file mode 100644 index 0000000..9a1d63a --- /dev/null +++ b/man-pages-posix-2013/man3p/sigpending.3p @@ -0,0 +1,72 @@ +'\" et +.TH SIGPENDING "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sigprocmask.3p b/man-pages-posix-2013/man3p/sigprocmask.3p new file mode 100644 index 0000000..5b5e70d --- /dev/null +++ b/man-pages-posix-2013/man3p/sigprocmask.3p @@ -0,0 +1,39 @@ +'\" et +.TH SIGPROCMASK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sigqueue.3p b/man-pages-posix-2013/man3p/sigqueue.3p new file mode 100644 index 0000000..b3dd2b4 --- /dev/null +++ b/man-pages-posix-2013/man3p/sigqueue.3p @@ -0,0 +1,188 @@ +'\" et +.TH SIGQUEUE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, const 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 \(mi1 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\(hy2008 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sigrelse.3p b/man-pages-posix-2013/man3p/sigrelse.3p new file mode 100644 index 0000000..49d3192 --- /dev/null +++ b/man-pages-posix-2013/man3p/sigrelse.3p @@ -0,0 +1,40 @@ +'\" et +.TH SIGRELSE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sigsetjmp.3p b/man-pages-posix-2013/man3p/sigsetjmp.3p new file mode 100644 index 0000000..a1882fc --- /dev/null +++ b/man-pages-posix-2013/man3p/sigsetjmp.3p @@ -0,0 +1,155 @@ +'\" et +.TH SIGSETJMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sigsuspend.3p b/man-pages-posix-2013/man3p/sigsuspend.3p new file mode 100644 index 0000000..22efe90 --- /dev/null +++ b/man-pages-posix-2013/man3p/sigsuspend.3p @@ -0,0 +1,128 @@ +'\" et +.TH SIGSUSPEND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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 +\fB +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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sigtimedwait.3p b/man-pages-posix-2013/man3p/sigtimedwait.3p new file mode 100644 index 0000000..f0ecfd1 --- /dev/null +++ b/man-pages-posix-2013/man3p/sigtimedwait.3p @@ -0,0 +1,366 @@ +'\" et +.TH SIGTIMEDWAIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 if the +.IR info +argument is NULL. If the +.IR info +argument is non-NULL, the +\fIsigwaitinfo\fR() +function shall be equivalent to +\fIsigwait\fR(), +except that 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 \(mi1 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\(hy2008. 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\(hy2008 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\(hy2008. 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sigwait.3p b/man-pages-posix-2013/man3p/sigwait.3p new file mode 100644 index 0000000..1fe7ad5 --- /dev/null +++ b/man-pages-posix-2013/man3p/sigwait.3p @@ -0,0 +1,145 @@ +'\" et +.TH SIGWAIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 +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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sigwaitinfo.3p b/man-pages-posix-2013/man3p/sigwaitinfo.3p new file mode 100644 index 0000000..cb4cd78 --- /dev/null +++ b/man-pages-posix-2013/man3p/sigwaitinfo.3p @@ -0,0 +1,38 @@ +'\" et +.TH SIGWAITINFO "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sin.3p b/man-pages-posix-2013/man3p/sin.3p new file mode 100644 index 0000000..53a0a97 --- /dev/null +++ b/man-pages-posix-2013/man3p/sin.3p @@ -0,0 +1,160 @@ +'\" et +.TH SIN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +#include +\&... +double radians = 45.0 * M_PI / 180; +double result; +\&... +result = sin(radians); +.fi \fR +.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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sinh.3p b/man-pages-posix-2013/man3p/sinh.3p new file mode 100644 index 0000000..4137556 --- /dev/null +++ b/man-pages-posix-2013/man3p/sinh.3p @@ -0,0 +1,145 @@ +'\" et +.TH SINH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sinl.3p b/man-pages-posix-2013/man3p/sinl.3p new file mode 100644 index 0000000..1872e03 --- /dev/null +++ b/man-pages-posix-2013/man3p/sinl.3p @@ -0,0 +1,38 @@ +'\" et +.TH SINL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sleep.3p b/man-pages-posix-2013/man3p/sleep.3p new file mode 100644 index 0000000..467d9d9 --- /dev/null +++ b/man-pages-posix-2013/man3p/sleep.3p @@ -0,0 +1,224 @@ +'\" et +.TH SLEEP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +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\(hy2008 permits either +approach. +.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\(hy2008, 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\(hy2008 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" +None. +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/snprintf.3p b/man-pages-posix-2013/man3p/snprintf.3p new file mode 100644 index 0000000..58d1182 --- /dev/null +++ b/man-pages-posix-2013/man3p/snprintf.3p @@ -0,0 +1,39 @@ +'\" et +.TH SNPRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sockatmark.3p b/man-pages-posix-2013/man3p/sockatmark.3p new file mode 100644 index 0000000..26b231d --- /dev/null +++ b/man-pages-posix-2013/man3p/sockatmark.3p @@ -0,0 +1,149 @@ +'\" et +.TH SOCKATMARK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 +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 +\fB +#include +.P +int sockatmark(int s) +{ + int val; + if (ioctl(s,SIOCATMARK,&val)==\(mi1) + return(\(mi1); + return(val); +} +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/socket.3p b/man-pages-posix-2013/man3p/socket.3p new file mode 100644 index 0000000..da1fc88 --- /dev/null +++ b/man-pages-posix-2013/man3p/socket.3p @@ -0,0 +1,182 @@ +'\" et +.TH SOCKET "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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. +.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 \(mi1 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 "\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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/socketpair.3p b/man-pages-posix-2013/man3p/socketpair.3p new file mode 100644 index 0000000..8b3ddef --- /dev/null +++ b/man-pages-posix-2013/man3p/socketpair.3p @@ -0,0 +1,170 @@ +'\" et +.TH SOCKETPAIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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]. +.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, +\(mi1 shall be returned and +.IR errno +set to indicate the error. +.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 "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sprintf.3p b/man-pages-posix-2013/man3p/sprintf.3p new file mode 100644 index 0000000..72c9e14 --- /dev/null +++ b/man-pages-posix-2013/man3p/sprintf.3p @@ -0,0 +1,38 @@ +'\" et +.TH SPRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sqrt.3p b/man-pages-posix-2013/man3p/sqrt.3p new file mode 100644 index 0000000..f1a8c3a --- /dev/null +++ b/man-pages-posix-2013/man3p/sqrt.3p @@ -0,0 +1,136 @@ +'\" et +.TH SQRT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of 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\(hy2008 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 +< \(mi0, 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 \(miInf, 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 < \(mi0, +or +.IR x +is \(miInf. +.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 +\fB +#include +\&... +double x = 9.0; +double result; +\&... +result = sqrt(x); +.fi \fR +.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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/srand.3p b/man-pages-posix-2013/man3p/srand.3p new file mode 100644 index 0000000..1d03553 --- /dev/null +++ b/man-pages-posix-2013/man3p/srand.3p @@ -0,0 +1,38 @@ +'\" et +.TH SRAND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/srand48.3p b/man-pages-posix-2013/man3p/srand48.3p new file mode 100644 index 0000000..e645ce7 --- /dev/null +++ b/man-pages-posix-2013/man3p/srand48.3p @@ -0,0 +1,39 @@ +'\" et +.TH SRAND48 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/srandom.3p b/man-pages-posix-2013/man3p/srandom.3p new file mode 100644 index 0000000..26a0b0b --- /dev/null +++ b/man-pages-posix-2013/man3p/srandom.3p @@ -0,0 +1,38 @@ +'\" et +.TH SRANDOM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sscanf.3p b/man-pages-posix-2013/man3p/sscanf.3p new file mode 100644 index 0000000..117c217 --- /dev/null +++ b/man-pages-posix-2013/man3p/sscanf.3p @@ -0,0 +1,38 @@ +'\" et +.TH SSCANF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/stat.3p b/man-pages-posix-2013/man3p/stat.3p new file mode 100644 index 0000000..5f7a2b4 --- /dev/null +++ b/man-pages-posix-2013/man3p/stat.3p @@ -0,0 +1,38 @@ +'\" et +.TH STAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/statvfs.3p b/man-pages-posix-2013/man3p/statvfs.3p new file mode 100644 index 0000000..429e2d0 --- /dev/null +++ b/man-pages-posix-2013/man3p/statvfs.3p @@ -0,0 +1,38 @@ +'\" et +.TH STATVFS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/stdin.3p b/man-pages-posix-2013/man3p/stdin.3p new file mode 100644 index 0000000..f89bc60 --- /dev/null +++ b/man-pages-posix-2013/man3p/stdin.3p @@ -0,0 +1,129 @@ +'\" et +.TH STDIN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/stpcpy.3p b/man-pages-posix-2013/man3p/stpcpy.3p new file mode 100644 index 0000000..08ae046 --- /dev/null +++ b/man-pages-posix-2013/man3p/stpcpy.3p @@ -0,0 +1,38 @@ +'\" et +.TH STPCPY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/stpncpy.3p b/man-pages-posix-2013/man3p/stpncpy.3p new file mode 100644 index 0000000..13c37a9 --- /dev/null +++ b/man-pages-posix-2013/man3p/stpncpy.3p @@ -0,0 +1,38 @@ +'\" et +.TH STPNCPY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strcasecmp.3p b/man-pages-posix-2013/man3p/strcasecmp.3p new file mode 100644 index 0000000..1f23c8c --- /dev/null +++ b/man-pages-posix-2013/man3p/strcasecmp.3p @@ -0,0 +1,135 @@ +'\" et +.TH STRCASECMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strcat.3p b/man-pages-posix-2013/man3p/strcat.3p new file mode 100644 index 0000000..8f0a8d8 --- /dev/null +++ b/man-pages-posix-2013/man3p/strcat.3p @@ -0,0 +1,78 @@ +'\" et +.TH STRCAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strchr.3p b/man-pages-posix-2013/man3p/strchr.3p new file mode 100644 index 0000000..3add32f --- /dev/null +++ b/man-pages-posix-2013/man3p/strchr.3p @@ -0,0 +1,71 @@ +'\" et +.TH STRCHR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strcmp.3p b/man-pages-posix-2013/man3p/strcmp.3p new file mode 100644 index 0000000..8f67c8e --- /dev/null +++ b/man-pages-posix-2013/man3p/strcmp.3p @@ -0,0 +1,125 @@ +'\" et +.TH STRCMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +#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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strcoll.3p b/man-pages-posix-2013/man3p/strcoll.3p new file mode 100644 index 0000000..7c7b896 --- /dev/null +++ b/man-pages-posix-2013/man3p/strcoll.3p @@ -0,0 +1,170 @@ +'\" et +.TH STRCOLL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +#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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strcpy.3p b/man-pages-posix-2013/man3p/strcpy.3p new file mode 100644 index 0000000..6e0c352 --- /dev/null +++ b/man-pages-posix-2013/man3p/strcpy.3p @@ -0,0 +1,178 @@ +'\" et +.TH STRCPY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +#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 \fR +.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 +\fB +#include +\&... +static char permstring[11]; +\&... +strcpy(permstring, "----------"); +\&... +.fi \fR +.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 +\fB +#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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strcspn.3p b/man-pages-posix-2013/man3p/strcspn.3p new file mode 100644 index 0000000..cf87337 --- /dev/null +++ b/man-pages-posix-2013/man3p/strcspn.3p @@ -0,0 +1,73 @@ +'\" et +.TH STRCSPN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strdup.3p b/man-pages-posix-2013/man3p/strdup.3p new file mode 100644 index 0000000..f2009c0 --- /dev/null +++ b/man-pages-posix-2013/man3p/strdup.3p @@ -0,0 +1,119 @@ +'\" et +.TH STRDUP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfree\fR\^(\|)", +.IR "\fIwcsdup\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strerror.3p b/man-pages-posix-2013/man3p/strerror.3p new file mode 100644 index 0000000..815b318 --- /dev/null +++ b/man-pages-posix-2013/man3p/strerror.3p @@ -0,0 +1,307 @@ +'\" et +.TH STRERROR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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. +.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\(hy2008 +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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strfmon.3p b/man-pages-posix-2013/man3p/strfmon.3p new file mode 100644 index 0000000..cbd1796 --- /dev/null +++ b/man-pages-posix-2013/man3p/strfmon.3p @@ -0,0 +1,326 @@ +'\" et +.TH STRFMON "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 '\(mi' +are used (for example, in many locales, the empty string if positive and +.BR '\(mi' +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\(mi\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 '\(mi' +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 '^' +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, \(mi1 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, \(mi123.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 +\fB +%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 +%^#5n [ $ 123.45] \fRDisable the grouping separator\fP + [-$ 123.45] + [ $ 3456.78] +.P +%^#5.0n [ $ 123] \fRRound off to whole units\fP + [-$ 123] + [ $ 3457] +.P +%^#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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strftime.3p b/man-pages-posix-2013/man3p/strftime.3p new file mode 100644 index 0000000..c74625c --- /dev/null +++ b/man-pages-posix-2013/man3p/strftime.3p @@ -0,0 +1,996 @@ +'\" et +.TH STRFTIME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 minus-sign character (\c +.BR '\(mi' ) +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 '\(mi' +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 '\(mi' +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\(hy2008, +.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 \(mi6. +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 \(mi7 +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\(hy2008, +.IR .) +.IP "\fRX\fR" 8 +Replaced by the locale's appropriate time representation. (See +the Base Definitions volume of POSIX.1\(hy2008, +.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 \(mihhmm ), +or by no characters if no timezone is determinable. For example, +.BR \(dq\(mi0430\(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\(hy2008, +.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 +\fB +#include +#include +#include +\&... +struct tm *tm; +char datestring[256]; +\&... +setlocale (LC_ALL, ""); +\&... +strftime (datestring, sizeof(datestring), nl_langinfo (D_T_FMT), tm); +\&... +.fi \fR +.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 +\fB +printf("%2d", x = 1000); +.fi \fR +.P +.RE +.P +prints +.BR \(dq1000\(dq , +but: +.sp +.RS 4 +.nf +\fB +scanf(%2d", &x); +.fi \fR +.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 '\(mi' +sign; a six-digit, 0-filled year; a +.BR '\(mi' ; +a two-digit, leading 0-filled month; another +.BR '\(mi' ; +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 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 '\(mi' +sign. +(All of these specifiers can also provide a leading +.BR '\(mi' +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 +minus-sign 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 minus-sign (\c +.BR '\(mi' ) +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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strlen.3p b/man-pages-posix-2013/man3p/strlen.3p new file mode 100644 index 0000000..ca0ce28 --- /dev/null +++ b/man-pages-posix-2013/man3p/strlen.3p @@ -0,0 +1,125 @@ +'\" et +.TH STRLEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 the 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 an integer containing the smaller of either the +length of the string pointed to by +.IR s +or +.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 +\fB +#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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strncasecmp.3p b/man-pages-posix-2013/man3p/strncasecmp.3p new file mode 100644 index 0000000..f21e972 --- /dev/null +++ b/man-pages-posix-2013/man3p/strncasecmp.3p @@ -0,0 +1,41 @@ +'\" et +.TH STRNCASECMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strncat.3p b/man-pages-posix-2013/man3p/strncat.3p new file mode 100644 index 0000000..59b6b93 --- /dev/null +++ b/man-pages-posix-2013/man3p/strncat.3p @@ -0,0 +1,78 @@ +'\" et +.TH STRNCAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strncmp.3p b/man-pages-posix-2013/man3p/strncmp.3p new file mode 100644 index 0000000..a354df2 --- /dev/null +++ b/man-pages-posix-2013/man3p/strncmp.3p @@ -0,0 +1,82 @@ +'\" et +.TH STRNCMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strncpy.3p b/man-pages-posix-2013/man3p/strncpy.3p new file mode 100644 index 0000000..014b76e --- /dev/null +++ b/man-pages-posix-2013/man3p/strncpy.3p @@ -0,0 +1,116 @@ +'\" et +.TH STRNCPY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strndup.3p b/man-pages-posix-2013/man3p/strndup.3p new file mode 100644 index 0000000..395a927 --- /dev/null +++ b/man-pages-posix-2013/man3p/strndup.3p @@ -0,0 +1,38 @@ +'\" et +.TH STRNDUP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strnlen.3p b/man-pages-posix-2013/man3p/strnlen.3p new file mode 100644 index 0000000..1d3f09a --- /dev/null +++ b/man-pages-posix-2013/man3p/strnlen.3p @@ -0,0 +1,38 @@ +'\" et +.TH STRNLEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strpbrk.3p b/man-pages-posix-2013/man3p/strpbrk.3p new file mode 100644 index 0000000..8b6775a --- /dev/null +++ b/man-pages-posix-2013/man3p/strpbrk.3p @@ -0,0 +1,71 @@ +'\" et +.TH STRPBRK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strptime.3p b/man-pages-posix-2013/man3p/strptime.3p new file mode 100644 index 0000000..cfcf6cb --- /dev/null +++ b/man-pages-posix-2013/man3p/strptime.3p @@ -0,0 +1,442 @@ +'\" et +.TH STRPTIME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 , +.BR F , +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 '\(mi' +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 '\(mi' +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 '\(mi' +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 Data-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 +\fB +#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 = \(mi1; /* Not set by strptime(); tells mktime() + to determine whether daylight saving time + is in effect */ +t = mktime(&tm); +if (t == \(mi1) + /* Handle error */; +printf("seconds since the Epoch: %ld\en", (long) t);" +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strrchr.3p b/man-pages-posix-2013/man3p/strrchr.3p new file mode 100644 index 0000000..4f46b23 --- /dev/null +++ b/man-pages-posix-2013/man3p/strrchr.3p @@ -0,0 +1,97 @@ +'\" et +.TH STRRCHR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +#include +\&... +const char *name; +char *basename; +\&... +basename = strrchr(name, '/') + 1; +\&... +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strsignal.3p b/man-pages-posix-2013/man3p/strsignal.3p new file mode 100644 index 0000000..4896279 --- /dev/null +++ b/man-pages-posix-2013/man3p/strsignal.3p @@ -0,0 +1,104 @@ +'\" et +.TH STRSIGNAL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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(). +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strspn.3p b/man-pages-posix-2013/man3p/strspn.3p new file mode 100644 index 0000000..02f2561 --- /dev/null +++ b/man-pages-posix-2013/man3p/strspn.3p @@ -0,0 +1,69 @@ +'\" et +.TH STRSPN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strstr.3p b/man-pages-posix-2013/man3p/strstr.3p new file mode 100644 index 0000000..df547ea --- /dev/null +++ b/man-pages-posix-2013/man3p/strstr.3p @@ -0,0 +1,74 @@ +'\" et +.TH STRSTR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strtod.3p b/man-pages-posix-2013/man3p/strtod.3p new file mode 100644 index 0000000..421c17c --- /dev/null +++ b/man-pages-posix-2013/man3p/strtod.3p @@ -0,0 +1,341 @@ +'\" et +.TH STRTOD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 '\(mi' +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 '\(mi' +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 '\(mi' +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 +\fB +n-char-sequence: + digit + nondigit + n-char-sequence digit + n-char-sequence nondigit +.fi \fR +.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 minus-sign, 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 +locales, other implementation-defined subject sequences 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 +\fB +int +what_kind_of_number (char *s) +{ + char *endp; + double d; + long l; +.P + d = strtod(s, &endp); + if (s != endp && *endp == `\e0') + printf("It's a float with value %g\en", d); + else + { + l = strtol(s, &endp, 0); + if (s != endp && *endp == `\e0') + printf("It's an integer with value %ld\en", 1); + else + return 1; + } + return 0; +} +.fi \fR +.P +.RE +.P +If the function is called with: +.sp +.RS 4 +.nf +\fB +what_kind_of_number ("0x10") +.fi \fR +.P +.RE +.P +an ISO/IEC\ 9899:\|1990 standard-compliant library will result in the function printing: +.sp +.RS 4 +.nf +\fB +It's an integer with value 16 +.fi \fR +.P +.RE +.P +With the ISO/IEC\ 9899:\|1999 standard, the result is: +.sp +.RS 4 +.nf +\fB +It's a float with value 16 +.fi \fR +.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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strtoimax.3p b/man-pages-posix-2013/man3p/strtoimax.3p new file mode 100644 index 0000000..c26cad2 --- /dev/null +++ b/man-pages-posix-2013/man3p/strtoimax.3p @@ -0,0 +1,123 @@ +'\" et +.TH STRTOIMAX "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strtok.3p b/man-pages-posix-2013/man3p/strtok.3p new file mode 100644 index 0000000..531e309 --- /dev/null +++ b/man-pages-posix-2013/man3p/strtok.3p @@ -0,0 +1,241 @@ +'\" et +.TH STRTOK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \fIs1\fP, const char *restrict \fIs2\fP); +char *strtok_r(char *restrict \fIs\fP, const char *restrict \fIsep\fP, + char **restrict \fIlasts\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\(hy2008 defers to the ISO\ C standard. +.P +A sequence of calls to +\fIstrtok\fR() +breaks the string pointed to by +.IR s1 +into a sequence of tokens, each of which is delimited by a byte from +the string pointed to by +.IR s2 . +The first call in the sequence has +.IR s1 +as its first argument, and is followed by calls with a null pointer as +their first argument. The separator string pointed to by +.IR s2 +may be different from call to call. +.P +The first call in the sequence searches the string pointed to by +.IR s1 +for the first byte that is +.IR not +contained in the current separator string pointed to by +.IR s2 . +If no such byte is found, then there are no tokens in the string +pointed to by +.IR s1 +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 s1 , +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\(hy2008 +calls +\fIstrtok\fR(). +.P +The +\fIstrtok\fR() +function need not be thread-safe. +.P +The +\fIstrtok_r\fR() +function considers the null-terminated string +.IR s +as a sequence of zero or more text tokens separated by spans of one or +more characters from the separator string +.IR sep . +The argument +.IR lasts +points to a user-provided pointer which points to stored information +necessary for +\fIstrtok_r\fR() +to continue scanning the same string. +.P +In the first call to +\fIstrtok_r\fR(), +.IR s +points to a null-terminated string, +.IR sep +to a null-terminated string of separator characters, and the value +pointed to by +.IR lasts +is ignored. The +\fIstrtok_r\fR() +function shall return a pointer to the first character of the first +token, write a null character into +.IR s +immediately following the returned token, and update the pointer to +which +.IR lasts +points. +.P +In subsequent calls, +.IR s +is a null pointer and +.IR lasts +shall be unchanged from the previous call so that subsequent calls +shall move through the string +.IR s , +returning successive tokens until no tokens remain. The separator +string +.IR sep +may be different from call to call. When no token remains in +.IR s , +a null pointer shall be returned. +.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 +\fB +#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 \fR +.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 +\fB +#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 \fR +.P +.RE +.SH "APPLICATION USAGE" +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 lasts , +to keep track of the current position in the string. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strtol.3p b/man-pages-posix-2013/man3p/strtol.3p new file mode 100644 index 0000000..ad1dc2e --- /dev/null +++ b/man-pages-posix-2013/man3p/strtol.3p @@ -0,0 +1,244 @@ +'\" et +.TH STRTOL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \fIstr\fP, char **restrict \fIendptr\fP, int \fIbase\fP); +long long strtoll(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\(hy2008 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 "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 '\(mi' +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 '\(mi' +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 minus-sign, 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 +locales, other implementation-defined subject sequences 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 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, +{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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strtold.3p b/man-pages-posix-2013/man3p/strtold.3p new file mode 100644 index 0000000..6e53bf1 --- /dev/null +++ b/man-pages-posix-2013/man3p/strtold.3p @@ -0,0 +1,38 @@ +'\" et +.TH STRTOLD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strtoll.3p b/man-pages-posix-2013/man3p/strtoll.3p new file mode 100644 index 0000000..fa41797 --- /dev/null +++ b/man-pages-posix-2013/man3p/strtoll.3p @@ -0,0 +1,39 @@ +'\" et +.TH STRTOLL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strtoul.3p b/man-pages-posix-2013/man3p/strtoul.3p new file mode 100644 index 0000000..cf88249 --- /dev/null +++ b/man-pages-posix-2013/man3p/strtoul.3p @@ -0,0 +1,240 @@ +'\" et +.TH STRTOUL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 '\(mi' +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 '\(mi' +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 minus-sign, 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 +locales, other implementation-defined subject sequences 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strtoumax.3p b/man-pages-posix-2013/man3p/strtoumax.3p new file mode 100644 index 0000000..7942019 --- /dev/null +++ b/man-pages-posix-2013/man3p/strtoumax.3p @@ -0,0 +1,39 @@ +'\" et +.TH STRTOUMAX "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/strxfrm.3p b/man-pages-posix-2013/man3p/strxfrm.3p new file mode 100644 index 0000000..687197b --- /dev/null +++ b/man-pages-posix-2013/man3p/strxfrm.3p @@ -0,0 +1,154 @@ +'\" et +.TH STRXFRM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/swab.3p b/man-pages-posix-2013/man3p/swab.3p new file mode 100644 index 0000000..14ce430 --- /dev/null +++ b/man-pages-posix-2013/man3p/swab.3p @@ -0,0 +1,77 @@ +'\" et +.TH SWAB "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 +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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/swprintf.3p b/man-pages-posix-2013/man3p/swprintf.3p new file mode 100644 index 0000000..ee0fd20 --- /dev/null +++ b/man-pages-posix-2013/man3p/swprintf.3p @@ -0,0 +1,40 @@ +'\" et +.TH SWPRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/swscanf.3p b/man-pages-posix-2013/man3p/swscanf.3p new file mode 100644 index 0000000..91d0333 --- /dev/null +++ b/man-pages-posix-2013/man3p/swscanf.3p @@ -0,0 +1,40 @@ +'\" et +.TH SWSCANF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/symlink.3p b/man-pages-posix-2013/man3p/symlink.3p new file mode 100644 index 0000000..c5979e8 --- /dev/null +++ b/man-pages-posix-2013/man3p/symlink.3p @@ -0,0 +1,264 @@ +'\" et +.TH SYMLINK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 relative to directory file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int symlink(const char *\fIpath1\fP, const char *\fIpath2\fP); +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 character 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 file descriptor was +opened without O_SEARCH, the function shall check whether directory +searches are permitted using the current permissions of the directory +underlying the file descriptor. If the file descriptor was opened with +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 \(mi1 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 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 +.IR fd +was not opened with 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sync.3p b/man-pages-posix-2013/man3p/sync.3p new file mode 100644 index 0000000..6cae26f --- /dev/null +++ b/man-pages-posix-2013/man3p/sync.3p @@ -0,0 +1,65 @@ +'\" et +.TH SYNC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/sysconf.3p b/man-pages-posix-2013/man3p/sysconf.3p new file mode 100644 index 0000000..8e693bf --- /dev/null +++ b/man-pages-posix-2013/man3p/sysconf.3p @@ -0,0 +1,358 @@ +'\" et +.TH SYSCONF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +_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 +_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 +.TE +.ad l +.TS +box center tab(@); +cB | cB +lw(2.6i)1e | le. +Variable@Value of Name +_ +_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 +{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 +_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 \(mi1 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 \(mi1 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 \(mi1 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 \(mi1, 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\(hy2008, 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\(hy2008. +.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\(hy2008 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIgetconf\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/syslog.3p b/man-pages-posix-2013/man3p/syslog.3p new file mode 100644 index 0000000..c51b55c --- /dev/null +++ b/man-pages-posix-2013/man3p/syslog.3p @@ -0,0 +1,38 @@ +'\" et +.TH SYSLOG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/system.3p b/man-pages-posix-2013/man3p/system.3p new file mode 100644 index 0000000..9275c56 --- /dev/null +++ b/man-pages-posix-2013/man3p/system.3p @@ -0,0 +1,459 @@ +'\" et +.TH SYSTEM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +execl(<\fIshell path\fP>, "sh", "-c", \fIcommand\fP, (char *)0); +.fi \fR +.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 \(mi1 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 \(mi1, 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^C\(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\(hy2008. +.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 +\fB +#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 \fR +.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 +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\(hy2008, 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\(hy2008 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 "\fIexec\fR\^", +.IR "\fIpipe\fR\^(\|)", +.IR "\fIpthread_atfork\fR\^(\|)", +.IR "\fIwait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "\fIsh\fR\^" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/tan.3p b/man-pages-posix-2013/man3p/tan.3p new file mode 100644 index 0000000..29c43ae --- /dev/null +++ b/man-pages-posix-2013/man3p/tan.3p @@ -0,0 +1,206 @@ +'\" et +.TH TAN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +#include +\&... +double radians = 45.0 * M_PI / 180; +double result; +\&... +result = tan (radians); +.fi \fR +.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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/tanh.3p b/man-pages-posix-2013/man3p/tanh.3p new file mode 100644 index 0000000..53cd05e --- /dev/null +++ b/man-pages-posix-2013/man3p/tanh.3p @@ -0,0 +1,129 @@ +'\" et +.TH TANH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/tanl.3p b/man-pages-posix-2013/man3p/tanl.3p new file mode 100644 index 0000000..5adf18c --- /dev/null +++ b/man-pages-posix-2013/man3p/tanl.3p @@ -0,0 +1,38 @@ +'\" et +.TH TANL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/tcdrain.3p b/man-pages-posix-2013/man3p/tcdrain.3p new file mode 100644 index 0000000..67cfe28 --- /dev/null +++ b/man-pages-posix-2013/man3p/tcdrain.3p @@ -0,0 +1,97 @@ +'\" et +.TH TCDRAIN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 +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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/tcflow.3p b/man-pages-posix-2013/man3p/tcflow.3p new file mode 100644 index 0000000..f3737a9 --- /dev/null +++ b/man-pages-posix-2013/man3p/tcflow.3p @@ -0,0 +1,133 @@ +'\" et +.TH TCFLOW "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 +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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/tcflush.3p b/man-pages-posix-2013/man3p/tcflush.3p new file mode 100644 index 0000000..641344c --- /dev/null +++ b/man-pages-posix-2013/man3p/tcflush.3p @@ -0,0 +1,110 @@ +'\" et +.TH TCFLUSH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 +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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/tcgetattr.3p b/man-pages-posix-2013/man3p/tcgetattr.3p new file mode 100644 index 0000000..6510980 --- /dev/null +++ b/man-pages-posix-2013/man3p/tcgetattr.3p @@ -0,0 +1,146 @@ +'\" et +.TH TCGETATTR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 +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 \(mi1 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 \(mi1 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/tcgetpgrp.3p b/man-pages-posix-2013/man3p/tcgetpgrp.3p new file mode 100644 index 0000000..c6ee6ae --- /dev/null +++ b/man-pages-posix-2013/man3p/tcgetpgrp.3p @@ -0,0 +1,90 @@ +'\" et +.TH TCGETPGRP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/tcgetsid.3p b/man-pages-posix-2013/man3p/tcgetsid.3p new file mode 100644 index 0000000..f770558 --- /dev/null +++ b/man-pages-posix-2013/man3p/tcgetsid.3p @@ -0,0 +1,76 @@ +'\" et +.TH TCGETSID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/tcsendbreak.3p b/man-pages-posix-2013/man3p/tcsendbreak.3p new file mode 100644 index 0000000..48a2da8 --- /dev/null +++ b/man-pages-posix-2013/man3p/tcsendbreak.3p @@ -0,0 +1,103 @@ +'\" et +.TH TCSENDBREAK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/tcsetattr.3p b/man-pages-posix-2013/man3p/tcsetattr.3p new file mode 100644 index 0000000..014383b --- /dev/null +++ b/man-pages-posix-2013/man3p/tcsetattr.3p @@ -0,0 +1,240 @@ +'\" et +.TH TCSETATTR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008 +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\(hy2008, 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\(hy2008 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, +\(mi1 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\(hy2008. +.SH "SEE ALSO" +.IR "\fIcfgetispeed\fR\^(\|)", +.IR "\fItcgetattr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/tcsetpgrp.3p b/man-pages-posix-2013/man3p/tcsetpgrp.3p new file mode 100644 index 0000000..e20cc00 --- /dev/null +++ b/man-pages-posix-2013/man3p/tcsetpgrp.3p @@ -0,0 +1,109 @@ +'\" et +.TH TCSETPGRP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 +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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/tdelete.3p b/man-pages-posix-2013/man3p/tdelete.3p new file mode 100644 index 0000000..507a3ba --- /dev/null +++ b/man-pages-posix-2013/man3p/tdelete.3p @@ -0,0 +1,319 @@ +'\" et +.TH TDELETE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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. 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 +\fB +typedef enum { preorder, postorder, endorder, leaf } VISIT; +.fi \fR +.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 +\fB +#include +#include +#include +.P +#define STRSZ 10000 +#define NODSZ 500 +.P +struct node { /* Pointers to these are stored in the tree. */ + char *string; + int length; +}; +.P +char string_space[STRSZ]; /* Space to store strings. */ +struct node nodes[NODSZ]; /* Nodes to store. */ +void *root = NULL; /* This points to the root. */ +.P +int main(int argc, char *argv[]) +{ + char *strptr = string_space; + struct node *nodeptr = nodes; + void print_node(const void *, VISIT, int); + int i = 0, node_compare(const void *, const void *); +.P + while (gets(strptr) != NULL && i++ < NODSZ) { + /* Set node. */ + nodeptr\(mi>string = strptr; + nodeptr\(mi>length = strlen(strptr); + /* Put node into the tree. */ + (void) tsearch((void *)nodeptr, (void **)&root, + node_compare); + /* Adjust pointers, so we do not overwrite tree. */ + strptr += nodeptr\(mi>length + 1; + nodeptr++; + } + twalk(root, print_node); + 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 node *) node1)\(mi>string, + ((const struct node *) node2)\(mi>string); +} +.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 node *p = *(const struct node **) ptr; +.P + if (order == postorder \(or\(or order == leaf) { + (void) printf("string = %s, length = %d\en", + p->string, p->length); + } +} +.fi \fR +.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 +\fItsearch\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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/telldir.3p b/man-pages-posix-2013/man3p/telldir.3p new file mode 100644 index 0000000..9e7e3b7 --- /dev/null +++ b/man-pages-posix-2013/man3p/telldir.3p @@ -0,0 +1,73 @@ +'\" et +.TH TELLDIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/tempnam.3p b/man-pages-posix-2013/man3p/tempnam.3p new file mode 100644 index 0000000..1b9c18e --- /dev/null +++ b/man-pages-posix-2013/man3p/tempnam.3p @@ -0,0 +1,148 @@ +'\" et +.TH TEMPNAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +#include +#include +\&... +const char *directory = "/tmp"; +const char *fileprefix = "file"; +char *file; +.P +file = tempnam(directory, fileprefix); +free(file); +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/tfind.3p b/man-pages-posix-2013/man3p/tfind.3p new file mode 100644 index 0000000..21761dc --- /dev/null +++ b/man-pages-posix-2013/man3p/tfind.3p @@ -0,0 +1,39 @@ +'\" et +.TH TFIND "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/tgamma.3p b/man-pages-posix-2013/man3p/tgamma.3p new file mode 100644 index 0000000..d49a6bc --- /dev/null +++ b/man-pages-posix-2013/man3p/tgamma.3p @@ -0,0 +1,244 @@ +'\" et +.TH TGAMMA "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.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\(hy2008 defers to the ISO\ C standard. +.P +These functions shall compute the +.IR gamma +function 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 +.IR Gamma (\c +.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 NaN, a NaN shall be returned. +.P +If +.IR x +is +Inf, +.IR x +shall be returned. +.P +If +.IR x +is \(miInf, 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 \(miInf. +.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" +For IEEE\ Std\ 754\(hy1985 +.BR double , +overflow happens when 0 < \fIx\fP < 1/DBL_MAX, and 171.7 < \fIx\fP. +.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 +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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/time.3p b/man-pages-posix-2013/man3p/time.3p new file mode 100644 index 0000000..cf2569d --- /dev/null +++ b/man-pages-posix-2013/man3p/time.3p @@ -0,0 +1,207 @@ +'\" et +.TH TIME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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)\(mi1 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 +\fB +#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 \fR +.P +.RE +.P +This example writes the current time to +.IR stdout +in a form like this: +.sp +.RS 4 +.nf +\fB +Wed Jun 26 10:32:15 1996 +835810335 secs since the Epoch +.fi \fR +.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 +\fB +#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 \fR +.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\(hy2008 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\(hy2008, +.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\(hy2008 +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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/timer_create.3p b/man-pages-posix-2013/man3p/timer_create.3p new file mode 100644 index 0000000..b0e7cb6 --- /dev/null +++ b/man-pages-posix-2013/man3p/timer_create.3p @@ -0,0 +1,263 @@ +'\" et +.TH TIMER_CREATE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/timer_delete.3p b/man-pages-posix-2013/man3p/timer_delete.3p new file mode 100644 index 0000000..125c23f --- /dev/null +++ b/man-pages-posix-2013/man3p/timer_delete.3p @@ -0,0 +1,78 @@ +'\" et +.TH TIMER_DELETE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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. +.SH "RETURN VALUE" +If successful, the +\fItimer_delete\fR() +function shall return a value of zero. Otherwise, the function shall +return a value of \(mi1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fItimer_delete\fR() +function may fail if: +.TP +.BR EINVAL +The timer ID specified by +.IR timerid +is not a valid timer ID. +.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 "\fItimer_create\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/timer_getoverrun.3p b/man-pages-posix-2013/man3p/timer_getoverrun.3p new file mode 100644 index 0000000..d2835f6 --- /dev/null +++ b/man-pages-posix-2013/man3p/timer_getoverrun.3p @@ -0,0 +1,256 @@ +'\" et +.TH TIMER_GETOVERRUN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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. +.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 \(mi1 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 +These functions may fail if: +.TP +.BR EINVAL +The +.IR timerid +argument does not correspond to an ID returned by +\fItimer_create\fR() +but not yet deleted by +\fItimer_delete\fR(). +.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\(hy2008 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. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclock_getres\fR\^(\|)", +.IR "\fItimer_create\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/times.3p b/man-pages-posix-2013/man3p/times.3p new file mode 100644 index 0000000..9d5754b --- /dev/null +++ b/man-pages-posix-2013/man3p/times.3p @@ -0,0 +1,206 @@ +'\" et +.TH TIMES "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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)\(mi1 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 +.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 +\fB +#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 \fR +.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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/timezone.3p b/man-pages-posix-2013/man3p/timezone.3p new file mode 100644 index 0000000..75869fc --- /dev/null +++ b/man-pages-posix-2013/man3p/timezone.3p @@ -0,0 +1,38 @@ +'\" et +.TH TIMEZONE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/tmpfile.3p b/man-pages-posix-2013/man3p/tmpfile.3p new file mode 100644 index 0000000..df140db --- /dev/null +++ b/man-pages-posix-2013/man3p/tmpfile.3p @@ -0,0 +1,150 @@ +'\" et +.TH TMPFILE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 is opened as in +\fIfopen\fR() +for update (\fIw\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 +\fB +#include +\&... +FILE *fp; +.P +fp = tmpfile (); +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/tmpnam.3p b/man-pages-posix-2013/man3p/tmpnam.3p new file mode 100644 index 0000000..3978390 --- /dev/null +++ b/man-pages-posix-2013/man3p/tmpnam.3p @@ -0,0 +1,146 @@ +'\" et +.TH TMPNAM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +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 +\fB +#include +\&... +char pathname[L_tmpnam+1]; +char *ptr; +.P +ptr = tmpnam(pathname); +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/toascii.3p b/man-pages-posix-2013/man3p/toascii.3p new file mode 100644 index 0000000..968abd8 --- /dev/null +++ b/man-pages-posix-2013/man3p/toascii.3p @@ -0,0 +1,64 @@ +'\" et +.TH TOASCII "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/tolower.3p b/man-pages-posix-2013/man3p/tolower.3p new file mode 100644 index 0000000..2a60c6e --- /dev/null +++ b/man-pages-posix-2013/man3p/tolower.3p @@ -0,0 +1,100 @@ +'\" et +.TH TOLOWER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/toupper.3p b/man-pages-posix-2013/man3p/toupper.3p new file mode 100644 index 0000000..fbe3281 --- /dev/null +++ b/man-pages-posix-2013/man3p/toupper.3p @@ -0,0 +1,103 @@ +'\" et +.TH TOUPPER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/towctrans.3p b/man-pages-posix-2013/man3p/towctrans.3p new file mode 100644 index 0000000..8fbd912 --- /dev/null +++ b/man-pages-posix-2013/man3p/towctrans.3p @@ -0,0 +1,155 @@ +'\" et +.TH TOWCTRANS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +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 \fR +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/towlower.3p b/man-pages-posix-2013/man3p/towlower.3p new file mode 100644 index 0000000..8dff90b --- /dev/null +++ b/man-pages-posix-2013/man3p/towlower.3p @@ -0,0 +1,103 @@ +'\" et +.TH TOWLOWER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +current locale 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/towupper.3p b/man-pages-posix-2013/man3p/towupper.3p new file mode 100644 index 0000000..93fd334 --- /dev/null +++ b/man-pages-posix-2013/man3p/towupper.3p @@ -0,0 +1,103 @@ +'\" et +.TH TOWUPPER "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +current locale 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/trunc.3p b/man-pages-posix-2013/man3p/trunc.3p new file mode 100644 index 0000000..3a7d42a --- /dev/null +++ b/man-pages-posix-2013/man3p/trunc.3p @@ -0,0 +1,85 @@ +'\" et +.TH TRUNC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/truncate.3p b/man-pages-posix-2013/man3p/truncate.3p new file mode 100644 index 0000000..fe2b406 --- /dev/null +++ b/man-pages-posix-2013/man3p/truncate.3p @@ -0,0 +1,167 @@ +'\" et +.TH TRUNCATE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, if the file size +is changed, +\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, \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/truncf.3p b/man-pages-posix-2013/man3p/truncf.3p new file mode 100644 index 0000000..7c9eb84 --- /dev/null +++ b/man-pages-posix-2013/man3p/truncf.3p @@ -0,0 +1,40 @@ +'\" et +.TH TRUNCF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/tsearch.3p b/man-pages-posix-2013/man3p/tsearch.3p new file mode 100644 index 0000000..13a9a5d --- /dev/null +++ b/man-pages-posix-2013/man3p/tsearch.3p @@ -0,0 +1,39 @@ +'\" et +.TH TSEARCH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/ttyname.3p b/man-pages-posix-2013/man3p/ttyname.3p new file mode 100644 index 0000000..2c52d8c --- /dev/null +++ b/man-pages-posix-2013/man3p/ttyname.3p @@ -0,0 +1,130 @@ +'\" et +.TH TTYNAME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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(). +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/twalk.3p b/man-pages-posix-2013/man3p/twalk.3p new file mode 100644 index 0000000..cabe490 --- /dev/null +++ b/man-pages-posix-2013/man3p/twalk.3p @@ -0,0 +1,39 @@ +'\" et +.TH TWALK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/tzset.3p b/man-pages-posix-2013/man3p/tzset.3p new file mode 100644 index 0000000..104167b --- /dev/null +++ b/man-pages-posix-2013/man3p/tzset.3p @@ -0,0 +1,128 @@ +'\" et +.TH TZSET "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 +\fB +tzname[0] = "\fIstd\fP"; +tzname[1] = "\fIdst\fP"; +.fi \fR +.P +.RE +.P +where +.IR std +and +.IR dst +are as described in the Base Definitions volume of POSIX.1\(hy2008, +.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. +.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!\(mi9*60*60 +MET-1MEST!\(mi1*60*60 +MST7MDT!7*60*60 +PST8PDT!8*60*60 +.TE +.SH "APPLICATION USAGE" +None. +.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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/ulimit.3p b/man-pages-posix-2013/man3p/ulimit.3p new file mode 100644 index 0000000..37e1eb2 --- /dev/null +++ b/man-pages-posix-2013/man3p/ulimit.3p @@ -0,0 +1,132 @@ +'\" et +.TH ULIMIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1, 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, \(mi1 +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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/umask.3p b/man-pages-posix-2013/man3p/umask.3p new file mode 100644 index 0000000..6505edf --- /dev/null +++ b/man-pages-posix-2013/man3p/umask.3p @@ -0,0 +1,116 @@ +'\" et +.TH UMASK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008. +.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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/uname.3p b/man-pages-posix-2013/man3p/uname.3p new file mode 100644 index 0000000..f55c537 --- /dev/null +++ b/man-pages-posix-2013/man3p/uname.3p @@ -0,0 +1,122 @@ +'\" et +.TH UNAME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 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\(hy2008 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/ungetc.3p b/man-pages-posix-2013/man3p/ungetc.3p new file mode 100644 index 0000000..2cbd874 --- /dev/null +++ b/man-pages-posix-2013/man3p/ungetc.3p @@ -0,0 +1,118 @@ +'\" et +.TH UNGETC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/ungetwc.3p b/man-pages-posix-2013/man3p/ungetwc.3p new file mode 100644 index 0000000..a1c1d57 --- /dev/null +++ b/man-pages-posix-2013/man3p/ungetwc.3p @@ -0,0 +1,126 @@ +'\" et +.TH UNGETWC "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/unlink.3p b/man-pages-posix-2013/man3p/unlink.3p new file mode 100644 index 0000000..0154c29 --- /dev/null +++ b/man-pages-posix-2013/man3p/unlink.3p @@ -0,0 +1,449 @@ +'\" et +.TH UNLINK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 relative to directory file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int unlink(const char *\fIpath\fP); +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 file descriptor was +opened without O_SEARCH, the function shall check whether directory +searches are permitted using the current permissions of the directory +underlying the file descriptor. If the file descriptor was opened with +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 \(mi1 and set +.IR errno +to indicate the error. If \(mi1 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\(hy2008, +.IR "Section 4.2" ", " "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 +.IR fd +was not opened with 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 +\fB +#include +.P +char *path = "/modules/pass1"; +int status; +\&... +status = unlink(path); +.fi \fR +.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 +\fB +#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 \fR +.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 +\fB +#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 \fR +.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\(hy2008 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\(hy2008, +.IR "Section 4.2" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/unlockpt.3p b/man-pages-posix-2013/man3p/unlockpt.3p new file mode 100644 index 0000000..89347e2 --- /dev/null +++ b/man-pages-posix-2013/man3p/unlockpt.3p @@ -0,0 +1,85 @@ +'\" et +.TH UNLOCKPT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/unsetenv.3p b/man-pages-posix-2013/man3p/unsetenv.3p new file mode 100644 index 0000000..423674d --- /dev/null +++ b/man-pages-posix-2013/man3p/unsetenv.3p @@ -0,0 +1,92 @@ +'\" et +.TH UNSETENV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 +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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/uselocale.3p b/man-pages-posix-2013/man3p/uselocale.3p new file mode 100644 index 0000000..c4f1832 --- /dev/null +++ b/man-pages-posix-2013/man3p/uselocale.3p @@ -0,0 +1,126 @@ +'\" et +.TH USELOCALE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 the current locale for the current thread to the +locale represented by +.IR newloc . +.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 +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. +.P +If the +.IR newloc +argument is (\c +.BR locale_t )0, +the object returned is the current locale or LC_GLOBAL_LOCALE if there +has been no previous call to +\fIuselocale\fR() +for the current thread. +.P +If the +.IR newloc +argument is LC_GLOBAL_LOCALE, the thread shall use the global locale +determined by the +\fIsetlocale\fR() +function. +.SH "RETURN VALUE" +Upon successful completion, the +\fIuselocale\fR() +function shall return the locale handle from the previous call for the +current thread, or LC_GLOBAL_LOCALE if there was no such previous call. +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 locale +is not a valid locale object. +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/utime.3p b/man-pages-posix-2013/man3p/utime.3p new file mode 100644 index 0000000..560bfa6 --- /dev/null +++ b/man-pages-posix-2013/man3p/utime.3p @@ -0,0 +1,202 @@ +'\" et +.TH UTIME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(mi1 +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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/utimensat.3p b/man-pages-posix-2013/man3p/utimensat.3p new file mode 100644 index 0000000..5835dda --- /dev/null +++ b/man-pages-posix-2013/man3p/utimensat.3p @@ -0,0 +1,44 @@ +'\" et +.TH UTIMENSAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 relative to directory +file descriptor +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/va_arg.3p b/man-pages-posix-2013/man3p/va_arg.3p new file mode 100644 index 0000000..6344919 --- /dev/null +++ b/man-pages-posix-2013/man3p/va_arg.3p @@ -0,0 +1,44 @@ +'\" et +.TH VA_ARG "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/vfprintf.3p b/man-pages-posix-2013/man3p/vfprintf.3p new file mode 100644 index 0000000..ef797dd --- /dev/null +++ b/man-pages-posix-2013/man3p/vfprintf.3p @@ -0,0 +1,101 @@ +'\" et +.TH VFPRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/vfscanf.3p b/man-pages-posix-2013/man3p/vfscanf.3p new file mode 100644 index 0000000..07b125a --- /dev/null +++ b/man-pages-posix-2013/man3p/vfscanf.3p @@ -0,0 +1,94 @@ +'\" et +.TH VFSCANF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/vfwprintf.3p b/man-pages-posix-2013/man3p/vfwprintf.3p new file mode 100644 index 0000000..54f8890 --- /dev/null +++ b/man-pages-posix-2013/man3p/vfwprintf.3p @@ -0,0 +1,95 @@ +'\" et +.TH VFWPRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/vfwscanf.3p b/man-pages-posix-2013/man3p/vfwscanf.3p new file mode 100644 index 0000000..c6ffb59 --- /dev/null +++ b/man-pages-posix-2013/man3p/vfwscanf.3p @@ -0,0 +1,96 @@ +'\" et +.TH VFWSCANF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/vprintf.3p b/man-pages-posix-2013/man3p/vprintf.3p new file mode 100644 index 0000000..a5825ff --- /dev/null +++ b/man-pages-posix-2013/man3p/vprintf.3p @@ -0,0 +1,39 @@ +'\" et +.TH VPRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/vscanf.3p b/man-pages-posix-2013/man3p/vscanf.3p new file mode 100644 index 0000000..7f5d18d --- /dev/null +++ b/man-pages-posix-2013/man3p/vscanf.3p @@ -0,0 +1,39 @@ +'\" et +.TH VSCANF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/vsnprintf.3p b/man-pages-posix-2013/man3p/vsnprintf.3p new file mode 100644 index 0000000..fef936d --- /dev/null +++ b/man-pages-posix-2013/man3p/vsnprintf.3p @@ -0,0 +1,43 @@ +'\" et +.TH VSNPRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/vsscanf.3p b/man-pages-posix-2013/man3p/vsscanf.3p new file mode 100644 index 0000000..1218042 --- /dev/null +++ b/man-pages-posix-2013/man3p/vsscanf.3p @@ -0,0 +1,40 @@ +'\" et +.TH VSSCANF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/vswprintf.3p b/man-pages-posix-2013/man3p/vswprintf.3p new file mode 100644 index 0000000..9c28214 --- /dev/null +++ b/man-pages-posix-2013/man3p/vswprintf.3p @@ -0,0 +1,41 @@ +'\" et +.TH VSWPRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/vswscanf.3p b/man-pages-posix-2013/man3p/vswscanf.3p new file mode 100644 index 0000000..72045d7 --- /dev/null +++ b/man-pages-posix-2013/man3p/vswscanf.3p @@ -0,0 +1,41 @@ +'\" et +.TH VSWSCANF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/vwprintf.3p b/man-pages-posix-2013/man3p/vwprintf.3p new file mode 100644 index 0000000..d525110 --- /dev/null +++ b/man-pages-posix-2013/man3p/vwprintf.3p @@ -0,0 +1,40 @@ +'\" et +.TH VWPRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/vwscanf.3p b/man-pages-posix-2013/man3p/vwscanf.3p new file mode 100644 index 0000000..939a3f1 --- /dev/null +++ b/man-pages-posix-2013/man3p/vwscanf.3p @@ -0,0 +1,40 @@ +'\" et +.TH VWSCANF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wait.3p b/man-pages-posix-2013/man3p/wait.3p new file mode 100644 index 0000000..d14b60c --- /dev/null +++ b/man-pages-posix-2013/man3p/wait.3p @@ -0,0 +1,892 @@ +'\" et +.TH WAIT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 pertaining to one of the +caller's child processes. Various options permit status information to +be obtained for child processes that have terminated or stopped. If +status information is available for two or more child processes, the +order in which their status is reported is unspecified. +.P +The +\fIwait\fR() +function shall suspend execution of the calling thread until status +information for one of the terminated child processes of the calling +process is available, or until delivery of a signal whose action is +either to execute a signal-catching function or to terminate the +process. If more than one thread is suspended in +\fIwait\fR() +or +\fIwaitpid\fR() +awaiting termination of the same process, exactly one thread shall +return the process status at the time of the target process +termination. If status information is available prior to the call to +\fIwait\fR(), +return shall be immediate. +.P +The +\fIwaitpid\fR() +function shall be equivalent to +\fIwait\fR() +if the +.IR pid +argument is (\fBpid_t\fP)\(mi1 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)\(mi1, +.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)\(mi1, +.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 the calling process has SA_NOCLDWAIT set or has SIGCHLD set to +SIG_IGN, +and the process has no unwaited-for children that were transformed into +zombie processes, the calling thread shall block until all of the +children of the process containing the calling thread terminate, and +\fIwait\fR() +and +\fIwaitpid\fR() +shall fail and set +.IR errno +to +.BR [ECHILD] . +.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, +or by a call to the +\fIwait\fR() +function, 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, \(mi1 +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, \(mi1 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 +\fB +#include +#include +#include +#include +\&... +.P +pid_t child_pid, wpid; +int status; +.P +child_pid = fork(); +if (child_pid == \(mi1) { /* 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 == \(mi1) { + 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 \fR +.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 \(mi1 as the +.IR pid +argument. (See the APPLICATION USAGE section below for the reasons +why passing a +.IR pid +of \(mi1 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 +\fB +#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 \(mi 1); + } + else if (waitpid(sinfo->si_pid, &status, 0) =\|= \(mi1) + { + static char msg[] = "waitpid() failed\en"; + write(2, msg, sizeof msg \(mi 1); + } + else if (!WIFEXITED(status)) + { + static char msg[] = "WIFEXITED was false\en"; + write(2, msg, sizeof msg \(mi 1); + } + else + { + int code = WEXITSTATUS(status); + char buf[2]; + buf[0] = '0' + code; + buf[1] = '\en'; + 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) =\|= \(mi1) + { + perror("sigaction"); + exit(EXIT_FAILURE); + } +.P + for (i = 0; i < CHILDREN; i++) + { + switch (pid = fork()) + { + case \(mi1: + 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 \fR +.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 \(mi1, and the use of +\fIwaitid\fR() +with the +.IR idtype +argument set to P_ALL, are also not recommended for portable applications. +.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\(hy2008 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\(hy2008, 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 +\fB +stream = popen("/bin/true"); +(void) system("sleep 100"); +(void) pclose(stream); +.fi \fR +.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\(hy2008 +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\(hy2008 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 "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIsystem\fR\^(\|)", +.IR "\fIwaitid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 4.11" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/waitid.3p b/man-pages-posix-2013/man3p/waitid.3p new file mode 100644 index 0000000..555fbf6 --- /dev/null +++ b/man-pages-posix-2013/man3p/waitid.3p @@ -0,0 +1,212 @@ +'\" et +.TH WAITID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 suspend the calling thread until one child of the +process containing the calling thread changes state. It records the +current state of a child in the structure pointed to by +.IR infop . +The fields of the structure pointed to by +.IR infop +are filled in as described for the SIGCHLD signal in +.IR . +If a child process changed state prior to the call to +\fIwaitid\fR(), +\fIwaitid\fR() +shall return immediately. If more than one thread is suspended in +\fIwait\fR(), +\fIwaitid\fR(), +or +\fIwaitpid\fR() +waiting for termination of the same process, exactly one thread shall +return the process status at the time of the target process termination. +.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, \(mi1 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(). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIwait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/waitpid.3p b/man-pages-posix-2013/man3p/waitpid.3p new file mode 100644 index 0000000..3849009 --- /dev/null +++ b/man-pages-posix-2013/man3p/waitpid.3p @@ -0,0 +1,38 @@ +'\" et +.TH WAITPID "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcpcpy.3p b/man-pages-posix-2013/man3p/wcpcpy.3p new file mode 100644 index 0000000..fecc385 --- /dev/null +++ b/man-pages-posix-2013/man3p/wcpcpy.3p @@ -0,0 +1,38 @@ +'\" et +.TH WCPCPY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcpncpy.3p b/man-pages-posix-2013/man3p/wcpncpy.3p new file mode 100644 index 0000000..f497d1e --- /dev/null +++ b/man-pages-posix-2013/man3p/wcpncpy.3p @@ -0,0 +1,40 @@ +'\" et +.TH WCPNCPY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcrtomb.3p b/man-pages-posix-2013/man3p/wcrtomb.3p new file mode 100644 index 0000000..6af7974 --- /dev/null +++ b/man-pages-posix-2013/man3p/wcrtomb.3p @@ -0,0 +1,151 @@ +'\" et +.TH WCRTOMB "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 +\fB +wcrtomb(\fIbuf\fP, L'\e0', \fIps\fP) +.fi \fR +.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\(hy2008 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)\(mi1; 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcscasecmp.3p b/man-pages-posix-2013/man3p/wcscasecmp.3p new file mode 100644 index 0000000..4362bf2 --- /dev/null +++ b/man-pages-posix-2013/man3p/wcscasecmp.3p @@ -0,0 +1,158 @@ +'\" et +.TH WCSCASECMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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_CTIME +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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcscat.3p b/man-pages-posix-2013/man3p/wcscat.3p new file mode 100644 index 0000000..3474716 --- /dev/null +++ b/man-pages-posix-2013/man3p/wcscat.3p @@ -0,0 +1,76 @@ +'\" et +.TH WCSCAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcschr.3p b/man-pages-posix-2013/man3p/wcschr.3p new file mode 100644 index 0000000..30c60ad --- /dev/null +++ b/man-pages-posix-2013/man3p/wcschr.3p @@ -0,0 +1,75 @@ +'\" et +.TH WCSCHR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcscmp.3p b/man-pages-posix-2013/man3p/wcscmp.3p new file mode 100644 index 0000000..53cdbee --- /dev/null +++ b/man-pages-posix-2013/man3p/wcscmp.3p @@ -0,0 +1,78 @@ +'\" et +.TH WCSCMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcscoll.3p b/man-pages-posix-2013/man3p/wcscoll.3p new file mode 100644 index 0000000..43614a7 --- /dev/null +++ b/man-pages-posix-2013/man3p/wcscoll.3p @@ -0,0 +1,135 @@ +'\" et +.TH WCSCOLL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcscpy.3p b/man-pages-posix-2013/man3p/wcscpy.3p new file mode 100644 index 0000000..0b021b2 --- /dev/null +++ b/man-pages-posix-2013/man3p/wcscpy.3p @@ -0,0 +1,99 @@ +'\" et +.TH WCSCPY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcscspn.3p b/man-pages-posix-2013/man3p/wcscspn.3p new file mode 100644 index 0000000..2c39fd1 --- /dev/null +++ b/man-pages-posix-2013/man3p/wcscspn.3p @@ -0,0 +1,72 @@ +'\" et +.TH WCSCSPN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcsdup.3p b/man-pages-posix-2013/man3p/wcsdup.3p new file mode 100644 index 0000000..efd9ce2 --- /dev/null +++ b/man-pages-posix-2013/man3p/wcsdup.3p @@ -0,0 +1,91 @@ +'\" et +.TH WCSDUP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcsftime.3p b/man-pages-posix-2013/man3p/wcsftime.3p new file mode 100644 index 0000000..d4d557b --- /dev/null +++ b/man-pages-posix-2013/man3p/wcsftime.3p @@ -0,0 +1,94 @@ +'\" et +.TH WCSFTIME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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. +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcslen.3p b/man-pages-posix-2013/man3p/wcslen.3p new file mode 100644 index 0000000..f15b173 --- /dev/null +++ b/man-pages-posix-2013/man3p/wcslen.3p @@ -0,0 +1,96 @@ +'\" et +.TH WCSLEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 string to which +.IR ws +points, not including the 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 string 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 an integer containing the smaller of either the +length of the wide-character string pointed to by +.IR ws +or +.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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcsncasecmp.3p b/man-pages-posix-2013/man3p/wcsncasecmp.3p new file mode 100644 index 0000000..e77728f --- /dev/null +++ b/man-pages-posix-2013/man3p/wcsncasecmp.3p @@ -0,0 +1,41 @@ +'\" et +.TH WCSNCASECMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcsncat.3p b/man-pages-posix-2013/man3p/wcsncat.3p new file mode 100644 index 0000000..ef2324f --- /dev/null +++ b/man-pages-posix-2013/man3p/wcsncat.3p @@ -0,0 +1,80 @@ +'\" et +.TH WCSNCAT "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcsncmp.3p b/man-pages-posix-2013/man3p/wcsncmp.3p new file mode 100644 index 0000000..0517cab --- /dev/null +++ b/man-pages-posix-2013/man3p/wcsncmp.3p @@ -0,0 +1,81 @@ +'\" et +.TH WCSNCMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcsncpy.3p b/man-pages-posix-2013/man3p/wcsncpy.3p new file mode 100644 index 0000000..d5b6383 --- /dev/null +++ b/man-pages-posix-2013/man3p/wcsncpy.3p @@ -0,0 +1,106 @@ +'\" et +.TH WCSNCPY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcsnlen.3p b/man-pages-posix-2013/man3p/wcsnlen.3p new file mode 100644 index 0000000..fdd919d --- /dev/null +++ b/man-pages-posix-2013/man3p/wcsnlen.3p @@ -0,0 +1,38 @@ +'\" et +.TH WCSNLEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcsnrtombs.3p b/man-pages-posix-2013/man3p/wcsnrtombs.3p new file mode 100644 index 0000000..51895d3 --- /dev/null +++ b/man-pages-posix-2013/man3p/wcsnrtombs.3p @@ -0,0 +1,39 @@ +'\" et +.TH WCSNRTOMBS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcspbrk.3p b/man-pages-posix-2013/man3p/wcspbrk.3p new file mode 100644 index 0000000..e2f8723 --- /dev/null +++ b/man-pages-posix-2013/man3p/wcspbrk.3p @@ -0,0 +1,73 @@ +'\" et +.TH WCSPBRK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcsrchr.3p b/man-pages-posix-2013/man3p/wcsrchr.3p new file mode 100644 index 0000000..5b7ed7a --- /dev/null +++ b/man-pages-posix-2013/man3p/wcsrchr.3p @@ -0,0 +1,76 @@ +'\" et +.TH WCSRCHR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcsrtombs.3p b/man-pages-posix-2013/man3p/wcsrtombs.3p new file mode 100644 index 0000000..99fd761 --- /dev/null +++ b/man-pages-posix-2013/man3p/wcsrtombs.3p @@ -0,0 +1,165 @@ +'\" et +.TH WCSRTOMBS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008 +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)\(mi1; 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcsspn.3p b/man-pages-posix-2013/man3p/wcsspn.3p new file mode 100644 index 0000000..034dad3 --- /dev/null +++ b/man-pages-posix-2013/man3p/wcsspn.3p @@ -0,0 +1,71 @@ +'\" et +.TH WCSSPN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcsstr.3p b/man-pages-posix-2013/man3p/wcsstr.3p new file mode 100644 index 0000000..8bd8b60 --- /dev/null +++ b/man-pages-posix-2013/man3p/wcsstr.3p @@ -0,0 +1,77 @@ +'\" et +.TH WCSSTR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcstod.3p b/man-pages-posix-2013/man3p/wcstod.3p new file mode 100644 index 0000000..a52ac29 --- /dev/null +++ b/man-pages-posix-2013/man3p/wcstod.3p @@ -0,0 +1,267 @@ +'\" et +.TH WCSTOD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 '\(mi' +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 '\(mi' +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 '\(mi' +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 +\fB +n-wchar-sequence: + digit + nondigit + n-wchar-sequence digit + n-wchar-sequence nondigit +.fi \fR +.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 minus-sign, +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 +locales, other implementation-defined subject sequences 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcstoimax.3p b/man-pages-posix-2013/man3p/wcstoimax.3p new file mode 100644 index 0000000..8800679 --- /dev/null +++ b/man-pages-posix-2013/man3p/wcstoimax.3p @@ -0,0 +1,103 @@ +'\" et +.TH WCSTOIMAX "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcstok.3p b/man-pages-posix-2013/man3p/wcstok.3p new file mode 100644 index 0000000..f3d34d0 --- /dev/null +++ b/man-pages-posix-2013/man3p/wcstok.3p @@ -0,0 +1,122 @@ +'\" et +.TH WCSTOK "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcstol.3p b/man-pages-posix-2013/man3p/wcstol.3p new file mode 100644 index 0000000..3b9befb --- /dev/null +++ b/man-pages-posix-2013/man3p/wcstol.3p @@ -0,0 +1,229 @@ +'\" et +.TH WCSTOL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 '\(mi' +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 '\(mi' +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 minus-sign, 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 +locales, other implementation-defined subject sequences 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcstold.3p b/man-pages-posix-2013/man3p/wcstold.3p new file mode 100644 index 0000000..19047ba --- /dev/null +++ b/man-pages-posix-2013/man3p/wcstold.3p @@ -0,0 +1,39 @@ +'\" et +.TH WCSTOLD "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcstoll.3p b/man-pages-posix-2013/man3p/wcstoll.3p new file mode 100644 index 0000000..1c49609 --- /dev/null +++ b/man-pages-posix-2013/man3p/wcstoll.3p @@ -0,0 +1,39 @@ +'\" et +.TH WCSTOLL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcstombs.3p b/man-pages-posix-2013/man3p/wcstombs.3p new file mode 100644 index 0000000..f893097 --- /dev/null +++ b/man-pages-posix-2013/man3p/wcstombs.3p @@ -0,0 +1,111 @@ +'\" et +.TH WCSTOMBS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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)\(mi1. 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcstoul.3p b/man-pages-posix-2013/man3p/wcstoul.3p new file mode 100644 index 0000000..ee0d510 --- /dev/null +++ b/man-pages-posix-2013/man3p/wcstoul.3p @@ -0,0 +1,231 @@ +'\" et +.TH WCSTOUL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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 '\(mi' +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 '\(mi' +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 minus-sign, 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 +locales, other implementation-defined subject sequences 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcstoumax.3p b/man-pages-posix-2013/man3p/wcstoumax.3p new file mode 100644 index 0000000..6e999b7 --- /dev/null +++ b/man-pages-posix-2013/man3p/wcstoumax.3p @@ -0,0 +1,40 @@ +'\" et +.TH WCSTOUMAX "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcswidth.3p b/man-pages-posix-2013/man3p/wcswidth.3p new file mode 100644 index 0000000..1195140 --- /dev/null +++ b/man-pages-posix-2013/man3p/wcswidth.3p @@ -0,0 +1,79 @@ +'\" et +.TH WCSWIDTH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 (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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcsxfrm.3p b/man-pages-posix-2013/man3p/wcsxfrm.3p new file mode 100644 index 0000000..eee5259 --- /dev/null +++ b/man-pages-posix-2013/man3p/wcsxfrm.3p @@ -0,0 +1,161 @@ +'\" et +.TH WCSXFRM "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wctob.3p b/man-pages-posix-2013/man3p/wctob.3p new file mode 100644 index 0000000..9943bc7 --- /dev/null +++ b/man-pages-posix-2013/man3p/wctob.3p @@ -0,0 +1,80 @@ +'\" et +.TH WCTOB "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wctomb.3p b/man-pages-posix-2013/man3p/wctomb.3p new file mode 100644 index 0000000..d24da98 --- /dev/null +++ b/man-pages-posix-2013/man3p/wctomb.3p @@ -0,0 +1,127 @@ +'\" et +.TH WCTOMB "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008 +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 \(mi1 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wctrans.3p b/man-pages-posix-2013/man3p/wctrans.3p new file mode 100644 index 0000000..1a5313c --- /dev/null +++ b/man-pages-posix-2013/man3p/wctrans.3p @@ -0,0 +1,139 @@ +'\" et +.TH WCTRANS "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wctype.3p b/man-pages-posix-2013/man3p/wctype.3p new file mode 100644 index 0000000..7aed3fd --- /dev/null +++ b/man-pages-posix-2013/man3p/wctype.3p @@ -0,0 +1,166 @@ +'\" et +.TH WCTYPE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wcwidth.3p b/man-pages-posix-2013/man3p/wcwidth.3p new file mode 100644 index 0000000..7424201 --- /dev/null +++ b/man-pages-posix-2013/man3p/wcwidth.3p @@ -0,0 +1,76 @@ +'\" et +.TH WCWIDTH "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 (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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wmemchr.3p b/man-pages-posix-2013/man3p/wmemchr.3p new file mode 100644 index 0000000..ab27e57 --- /dev/null +++ b/man-pages-posix-2013/man3p/wmemchr.3p @@ -0,0 +1,88 @@ +'\" et +.TH WMEMCHR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wmemcmp.3p b/man-pages-posix-2013/man3p/wmemcmp.3p new file mode 100644 index 0000000..6b86191 --- /dev/null +++ b/man-pages-posix-2013/man3p/wmemcmp.3p @@ -0,0 +1,93 @@ +'\" et +.TH WMEMCMP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wmemcpy.3p b/man-pages-posix-2013/man3p/wmemcpy.3p new file mode 100644 index 0000000..3648a74 --- /dev/null +++ b/man-pages-posix-2013/man3p/wmemcpy.3p @@ -0,0 +1,88 @@ +'\" et +.TH WMEMCPY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wmemmove.3p b/man-pages-posix-2013/man3p/wmemmove.3p new file mode 100644 index 0000000..66d26e9 --- /dev/null +++ b/man-pages-posix-2013/man3p/wmemmove.3p @@ -0,0 +1,103 @@ +'\" et +.TH WMEMMOVE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wmemset.3p b/man-pages-posix-2013/man3p/wmemset.3p new file mode 100644 index 0000000..c359e82 --- /dev/null +++ b/man-pages-posix-2013/man3p/wmemset.3p @@ -0,0 +1,85 @@ +'\" et +.TH WMEMSET "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008 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\(hy2008, +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wordexp.3p b/man-pages-posix-2013/man3p/wordexp.3p new file mode 100644 index 0000000..96090a2 --- /dev/null +++ b/man-pages-posix-2013/man3p/wordexp.3p @@ -0,0 +1,489 @@ +'\" et +.TH WORDEXP "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(hy2008, +.IR "Section 2.6" ", " "Word Expansions", +subject to quoting as described in the Shell and Utilities volume of POSIX.1\(hy2008, +.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\(hy2008, +.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\(hy2008, +.IR "Section 2.6.5" ", " "Field Splitting") +or pathname expansion (see the Shell and Utilities volume of POSIX.1\(hy2008, +.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\(hy2008, +.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\(hy2008, +.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\(hy2008, +fail if command substitution, as specified in the Shell and Utilities volume of POSIX.1\(hy2008, +.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\(hy2008, +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 ; +however, 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 . +.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 cases, they 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. +.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 \(miq +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 +\fB +(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 \fR +.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\(miw\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\(miP\fP" 6 +Run in ``protected'' mode. If specified with the +.BR \(miw +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 +\fB +execl(<\fIshell path\fP>, "sh", "-P", "-w", \fIwords\fP, (char *)0); +.fi \fR +.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\(hy2008, +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2008, +.IR "Chapter 2" ", " "Shell Command Language" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wprintf.3p b/man-pages-posix-2013/man3p/wprintf.3p new file mode 100644 index 0000000..85a89a6 --- /dev/null +++ b/man-pages-posix-2013/man3p/wprintf.3p @@ -0,0 +1,39 @@ +'\" et +.TH WPRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/write.3p b/man-pages-posix-2013/man3p/write.3p new file mode 100644 index 0000000..5a07dd4 --- /dev/null +++ b/man-pages-posix-2013/man3p/write.3p @@ -0,0 +1,735 @@ +'\" et +.TH WRITE "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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 \(mi1 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 \(mi1 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 \(mi1 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 \(mi1 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 \(mi1 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, \(mi1 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 pointer shall remain unchanged. +.TP +.BR ESPIPE +The file is a pipe, FIFO, or socket. +.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 +\fB +#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 \fR +.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\(hy2008 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 +\fB +int fildes; +size_t nbyte; +ssize_t ret; +char *buf; +.P +ret = write(fildes, buf, nbyte); +.fi \fR +.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\(hy2008 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=\(mi1, \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}!\(mi1, [EAGAIN]!\(mi1, [EAGAIN]!Atomic \fInbyte\fP +_ +\fInbyte\fP>{PIPE_BUF}!\(mi1, [EAGAIN]!<\fInbyte\fP or \(mi1,!\(<=\fInbyte\fP or \(mi1, +!![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\(hy2008 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\(hy2008 requires \(mi1 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\(hy2008). The error indications in this volume of POSIX.1\(hy2008 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\(hy2008 is also silent about any effects of +application-level caching (such as that done by +.IR stdio ). +.P +This volume of POSIX.1\(hy2008 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\(hy2008 does not specify behavior of concurrent writes to a file from +multiple processes. Applications should use some form of concurrency +control. +.P +This volume of POSIX.1\(hy2008 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/writev.3p b/man-pages-posix-2013/man3p/writev.3p new file mode 100644 index 0000000..e16e7f6 --- /dev/null +++ b/man-pages-posix-2013/man3p/writev.3p @@ -0,0 +1,169 @@ +'\" et +.TH WRITEV "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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\(mi1]. +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 \(mi1, 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 +\fB +#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 \fR +.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\(hy2008, +.IR "\fB\fP", +.IR "\fB\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/wscanf.3p b/man-pages-posix-2013/man3p/wscanf.3p new file mode 100644 index 0000000..1cc0b3e --- /dev/null +++ b/man-pages-posix-2013/man3p/wscanf.3p @@ -0,0 +1,39 @@ +'\" et +.TH WSCANF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/man-pages-posix-2013/man3p/y0.3p b/man-pages-posix-2013/man3p/y0.3p new file mode 100644 index 0000000..470a1ab --- /dev/null +++ b/man-pages-posix-2013/man3p/y0.3p @@ -0,0 +1,162 @@ +'\" et +.TH Y0 "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface 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, \(miHUGE_VAL or NaN shall be +returned, and a domain error may occur. +.P +If +.IR x +is 0.0, \(miHUGE_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, \(miHUGE_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\(hy2008, +.IR "Section 4.19" ", " "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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the 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