diff options
Diffstat (limited to 'usr/src/man/man3c')
490 files changed, 86479 insertions, 0 deletions
diff --git a/usr/src/man/man3c/Makefile b/usr/src/man/man3c/Makefile new file mode 100644 index 0000000000..4b2660a1ff --- /dev/null +++ b/usr/src/man/man3c/Makefile @@ -0,0 +1,2100 @@ +# +# This file and its contents are supplied under the terms of the +# Common Development and Distribution License ("CDDL"), version 1.0. +# You may only use this file in accordance with the terms of version +# 1.0 of the CDDL. +# +# A full copy of the text of the CDDL should have accompanied this +# source. A copy of the CDDL is also available via the Internet +# at http://www.illumos.org/license/CDDL. +# + +# Copyright 2011, Richard Lowe + +include ../../Makefile.master + +MANSECT = 3c + +MANFILES = __fbufsize.3c \ + _longjmp.3c \ + _stack_grow.3c \ + a64l.3c \ + abort.3c \ + abs.3c \ + addsev.3c \ + addseverity.3c \ + aio_cancel.3c \ + aio_error.3c \ + aio_fsync.3c \ + aio_read.3c \ + aio_return.3c \ + aio_suspend.3c \ + aio_waitn.3c \ + aio_write.3c \ + aiocancel.3c \ + aioread.3c \ + aiowait.3c \ + assert.3c \ + atexit.3c \ + atomic_add.3c \ + atomic_and.3c \ + atomic_bits.3c \ + atomic_cas.3c \ + atomic_dec.3c \ + atomic_inc.3c \ + atomic_ops.3c \ + atomic_or.3c \ + atomic_swap.3c \ + attropen.3c \ + basename.3c \ + bsd_signal.3c \ + bsearch.3c \ + bstring.3c \ + btowc.3c \ + catgets.3c \ + catopen.3c \ + cfgetispeed.3c \ + cfsetispeed.3c \ + clock.3c \ + clock_nanosleep.3c \ + clock_settime.3c \ + closedir.3c \ + closefrom.3c \ + cond_init.3c \ + confstr.3c \ + crypt.3c \ + crypt_genhash_impl.3c \ + crypt_gensalt.3c \ + crypt_gensalt_impl.3c \ + cset.3c \ + ctermid.3c \ + ctime.3c \ + ctype.3c \ + cuserid.3c \ + daemon.3c \ + decimal_to_floating.3c \ + difftime.3c \ + directio.3c \ + dirfd.3c \ + dirname.3c \ + div.3c \ + dladdr.3c \ + dlclose.3c \ + dldump.3c \ + dlerror.3c \ + dlinfo.3c \ + dlopen.3c \ + dlsym.3c \ + door_bind.3c \ + door_call.3c \ + door_create.3c \ + door_cred.3c \ + door_getparam.3c \ + door_info.3c \ + door_return.3c \ + door_revoke.3c \ + door_server_create.3c \ + door_ucred.3c \ + drand48.3c \ + dup2.3c \ + econvert.3c \ + ecvt.3c \ + enable_extended_FILE_stdio.3c \ + encrypt.3c \ + end.3c \ + err.3c \ + euclen.3c \ + exit.3c \ + fattach.3c \ + fclose.3c \ + fdatasync.3c \ + fdetach.3c \ + fdopen.3c \ + ferror.3c \ + fflush.3c \ + ffs.3c \ + fgetattr.3c \ + fgetc.3c \ + fgetpos.3c \ + fgetwc.3c \ + floating_to_decimal.3c \ + flockfile.3c \ + fmtmsg.3c \ + fnmatch.3c \ + fopen.3c \ + fpgetround.3c \ + fputc.3c \ + fputwc.3c \ + fputws.3c \ + fread.3c \ + freopen.3c \ + fseek.3c \ + fsetpos.3c \ + fsync.3c \ + ftell.3c \ + ftime.3c \ + ftok.3c \ + ftw.3c \ + fwide.3c \ + fwprintf.3c \ + fwrite.3c \ + fwscanf.3c \ + getcpuid.3c \ + getcwd.3c \ + getdate.3c \ + getdtablesize.3c \ + getenv.3c \ + getexecname.3c \ + getgrnam.3c \ + gethostid.3c \ + gethostname.3c \ + gethrtime.3c \ + getloadavg.3c \ + getlogin.3c \ + getmntent.3c \ + getnetgrent.3c \ + getopt.3c \ + getpagesize.3c \ + getpagesizes.3c \ + getpass.3c \ + getpeerucred.3c \ + getpriority.3c \ + getpw.3c \ + getpwnam.3c \ + getrusage.3c \ + gets.3c \ + getspnam.3c \ + getsubopt.3c \ + gettext.3c \ + gettimeofday.3c \ + gettxt.3c \ + getusershell.3c \ + getutent.3c \ + getutxent.3c \ + getvfsent.3c \ + getwc.3c \ + getwchar.3c \ + getwd.3c \ + getwidth.3c \ + getws.3c \ + getzoneid.3c \ + glob.3c \ + grantpt.3c \ + hsearch.3c \ + iconv.3c \ + iconv_close.3c \ + iconv_open.3c \ + imaxabs.3c \ + imaxdiv.3c \ + index.3c \ + initgroups.3c \ + insque.3c \ + is_system_labeled.3c \ + isaexec.3c \ + isastream.3c \ + isatty.3c \ + isnand.3c \ + iswalpha.3c \ + iswctype.3c \ + killpg.3c \ + lckpwdf.3c \ + lfmt.3c \ + lio_listio.3c \ + localeconv.3c \ + lockf.3c \ + lsearch.3c \ + madvise.3c \ + makecontext.3c \ + makedev.3c \ + malloc.3c \ + mblen.3c \ + mbrlen.3c \ + mbrtowc.3c \ + mbsinit.3c \ + mbsrtowcs.3c \ + mbtowc.3c \ + membar_ops.3c \ + memory.3c \ + mkfifo.3c \ + mkstemp.3c \ + mktemp.3c \ + mktime.3c \ + mlock.3c \ + mlockall.3c \ + monitor.3c \ + mq_close.3c \ + mq_getattr.3c \ + mq_notify.3c \ + mq_open.3c \ + mq_receive.3c \ + mq_send.3c \ + mq_setattr.3c \ + mq_unlink.3c \ + msync.3c \ + mutex_init.3c \ + nanosleep.3c \ + ndbm.3c \ + nl_langinfo.3c \ + offsetof.3c \ + opendir.3c \ + perror.3c \ + pfmt.3c \ + plock.3c \ + popen.3c \ + port_alert.3c \ + port_associate.3c \ + port_create.3c \ + port_get.3c \ + port_send.3c \ + posix_fadvise.3c \ + posix_fallocate.3c \ + posix_madvise.3c \ + posix_memalign.3c \ + posix_openpt.3c \ + posix_spawn.3c \ + posix_spawn_file_actions_addclose.3c \ + posix_spawn_file_actions_addclosefrom_np.3c \ + posix_spawn_file_actions_adddup2.3c \ + posix_spawn_file_actions_destroy.3c \ + posix_spawnattr_destroy.3c \ + posix_spawnattr_getflags.3c \ + posix_spawnattr_getpgroup.3c \ + posix_spawnattr_getschedparam.3c \ + posix_spawnattr_getschedpolicy.3c \ + posix_spawnattr_getsigdefault.3c \ + posix_spawnattr_getsigignore_np.3c \ + posix_spawnattr_getsigmask.3c \ + printf.3c \ + priv_addset.3c \ + priv_set.3c \ + priv_str_to_set.3c \ + pset_getloadavg.3c \ + psignal.3c \ + pthread_atfork.3c \ + pthread_attr_getdetachstate.3c \ + pthread_attr_getguardsize.3c \ + pthread_attr_getinheritsched.3c \ + pthread_attr_getschedparam.3c \ + pthread_attr_getschedpolicy.3c \ + pthread_attr_getscope.3c \ + pthread_attr_getstack.3c \ + pthread_attr_getstackaddr.3c \ + pthread_attr_getstacksize.3c \ + pthread_attr_init.3c \ + pthread_barrier_destroy.3c \ + pthread_barrier_wait.3c \ + pthread_barrierattr_destroy.3c \ + pthread_barrierattr_getpshared.3c \ + pthread_cancel.3c \ + pthread_cleanup_pop.3c \ + pthread_cleanup_push.3c \ + pthread_cond_init.3c \ + pthread_cond_signal.3c \ + pthread_cond_wait.3c \ + pthread_condattr_getclock.3c \ + pthread_condattr_getpshared.3c \ + pthread_condattr_init.3c \ + pthread_create.3c \ + pthread_detach.3c \ + pthread_equal.3c \ + pthread_exit.3c \ + pthread_getconcurrency.3c \ + pthread_getschedparam.3c \ + pthread_getspecific.3c \ + pthread_join.3c \ + pthread_key_create.3c \ + pthread_key_delete.3c \ + pthread_kill.3c \ + pthread_mutex_getprioceiling.3c \ + pthread_mutex_init.3c \ + pthread_mutex_lock.3c \ + pthread_mutex_timedlock.3c \ + pthread_mutexattr_getprioceiling.3c \ + pthread_mutexattr_getprotocol.3c \ + pthread_mutexattr_getpshared.3c \ + pthread_mutexattr_gettype.3c \ + pthread_mutexattr_init.3c \ + pthread_once.3c \ + pthread_rwlock_init.3c \ + pthread_rwlock_rdlock.3c \ + pthread_rwlock_timedrdlock.3c \ + pthread_rwlock_timedwrlock.3c \ + pthread_rwlock_unlock.3c \ + pthread_rwlock_wrlock.3c \ + pthread_rwlockattr_getpshared.3c \ + pthread_rwlockattr_init.3c \ + pthread_self.3c \ + pthread_setcancelstate.3c \ + pthread_setcanceltype.3c \ + pthread_setschedprio.3c \ + pthread_sigmask.3c \ + pthread_spin_destroy.3c \ + pthread_spin_lock.3c \ + pthread_spin_unlock.3c \ + pthread_testcancel.3c \ + ptrace.3c \ + ptsname.3c \ + putenv.3c \ + putpwent.3c \ + puts.3c \ + putspent.3c \ + putws.3c \ + qsort.3c \ + raise.3c \ + rand.3c \ + random.3c \ + rctl_walk.3c \ + rctlblk_set_value.3c \ + re_comp.3c \ + readdir.3c \ + realpath.3c \ + reboot.3c \ + regcmp.3c \ + regcomp.3c \ + remove.3c \ + rewind.3c \ + rewinddir.3c \ + rwlock.3c \ + scandir.3c \ + scanf.3c \ + sched_get_priority_max.3c \ + sched_getparam.3c \ + sched_getscheduler.3c \ + sched_rr_get_interval.3c \ + sched_setparam.3c \ + sched_setscheduler.3c \ + sched_yield.3c \ + schedctl_init.3c \ + seekdir.3c \ + select.3c \ + sem_close.3c \ + sem_destroy.3c \ + sem_getvalue.3c \ + sem_init.3c \ + sem_open.3c \ + sem_post.3c \ + sem_timedwait.3c \ + sem_unlink.3c \ + sem_wait.3c \ + semaphore.3c \ + setbuf.3c \ + setbuffer.3c \ + setcat.3c \ + setenv.3c \ + setjmp.3c \ + setkey.3c \ + setlabel.3c \ + setlocale.3c \ + shm_open.3c \ + shm_unlink.3c \ + sigfpe.3c \ + siginterrupt.3c \ + signal.3c \ + sigqueue.3c \ + sigsetops.3c \ + sigstack.3c \ + sigwaitinfo.3c \ + sleep.3c \ + ssignal.3c \ + stack_getbounds.3c \ + stack_inbounds.3c \ + stack_setbounds.3c \ + stack_violation.3c \ + stdio.3c \ + str2sig.3c \ + strcoll.3c \ + strerror.3c \ + strftime.3c \ + string.3c \ + string_to_decimal.3c \ + strptime.3c \ + strsignal.3c \ + strtod.3c \ + strtoimax.3c \ + strtol.3c \ + strtoul.3c \ + strtows.3c \ + strxfrm.3c \ + swab.3c \ + sync_instruction_memory.3c \ + sysconf.3c \ + syslog.3c \ + system.3c \ + tcdrain.3c \ + tcflow.3c \ + tcflush.3c \ + tcgetattr.3c \ + tcgetpgrp.3c \ + tcgetsid.3c \ + tcsendbreak.3c \ + tcsetattr.3c \ + tcsetpgrp.3c \ + tell.3c \ + telldir.3c \ + termios.3c \ + thr_create.3c \ + thr_exit.3c \ + thr_getconcurrency.3c \ + thr_getprio.3c \ + thr_join.3c \ + thr_keycreate.3c \ + thr_kill.3c \ + thr_main.3c \ + thr_min_stack.3c \ + thr_self.3c \ + thr_sigsetmask.3c \ + thr_stksegment.3c \ + thr_suspend.3c \ + thr_yield.3c \ + timer_create.3c \ + timer_delete.3c \ + timer_settime.3c \ + timeradd.3c \ + tmpfile.3c \ + tmpnam.3c \ + toascii.3c \ + tolower.3c \ + toupper.3c \ + truncate.3c \ + tsearch.3c \ + ttyname.3c \ + ttyslot.3c \ + u8_strcmp.3c \ + u8_textprep_str.3c \ + u8_validate.3c \ + ualarm.3c \ + uconv_u16tou32.3c \ + ucred_get.3c \ + ungetc.3c \ + ungetwc.3c \ + unlockpt.3c \ + unsetenv.3c \ + usleep.3c \ + vfwprintf.3c \ + vlfmt.3c \ + vpfmt.3c \ + vprintf.3c \ + vsyslog.3c \ + wait.3c \ + wait3.3c \ + waitpid.3c \ + walkcontext.3c \ + wcrtomb.3c \ + wcscoll.3c \ + wcsftime.3c \ + wcsrtombs.3c \ + wcsstr.3c \ + wcstod.3c \ + wcstoimax.3c \ + wcstol.3c \ + wcstoul.3c \ + wcstring.3c \ + wcswidth.3c \ + wcsxfrm.3c \ + wctob.3c \ + wctomb.3c \ + wctype.3c \ + wcwidth.3c \ + wmemchr.3c \ + wmemcmp.3c \ + wmemcpy.3c \ + wmemmove.3c \ + wmemset.3c \ + wordexp.3c \ + wsprintf.3c \ + wsscanf.3c \ + wstring.3c \ + +MANSOFILES = FD_CLR.3c \ + FD_ISSET.3c \ + FD_SET.3c \ + FD_ZERO.3c \ + __flbf.3c \ + __fpending.3c \ + __fpurge.3c \ + __freadable.3c \ + __freading.3c \ + __fsetlocking.3c \ + __fwritable.3c \ + __fwriting.3c \ + _edata.3c \ + _end.3c \ + _etext.3c \ + _exithandle.3c \ + _flushlbf.3c \ + _setjmp.3c \ + addrtosymstr.3c \ + aiowrite.3c \ + alloca.3c \ + alphasort.3c \ + ascftime.3c \ + asctime.3c \ + asctime_r.3c \ + asprintf.3c \ + atof.3c \ + atoi.3c \ + atol.3c \ + atoll.3c \ + atomic_add_16.3c \ + atomic_add_16_nv.3c \ + atomic_add_32.3c \ + atomic_add_32_nv.3c \ + atomic_add_64.3c \ + atomic_add_64_nv.3c \ + atomic_add_8.3c \ + atomic_add_8_nv.3c \ + atomic_add_char.3c \ + atomic_add_char_nv.3c \ + atomic_add_int.3c \ + atomic_add_int_nv.3c \ + atomic_add_long.3c \ + atomic_add_long_nv.3c \ + atomic_add_ptr.3c \ + atomic_add_ptr_nv.3c \ + atomic_add_short.3c \ + atomic_add_short_nv.3c \ + atomic_and_16.3c \ + atomic_and_16_nv.3c \ + atomic_and_32.3c \ + atomic_and_32_nv.3c \ + atomic_and_64.3c \ + atomic_and_64_nv.3c \ + atomic_and_8.3c \ + atomic_and_8_nv.3c \ + atomic_and_uchar.3c \ + atomic_and_uchar_nv.3c \ + atomic_and_uint.3c \ + atomic_and_uint_nv.3c \ + atomic_and_ulong.3c \ + atomic_and_ulong_nv.3c \ + atomic_and_ushort.3c \ + atomic_and_ushort_nv.3c \ + atomic_cas_16.3c \ + atomic_cas_32.3c \ + atomic_cas_64.3c \ + atomic_cas_8.3c \ + atomic_cas_ptr.3c \ + atomic_cas_uchar.3c \ + atomic_cas_uint.3c \ + atomic_cas_ulong.3c \ + atomic_cas_ushort.3c \ + atomic_clear_long_excl.3c \ + atomic_dec_16.3c \ + atomic_dec_16_nv.3c \ + atomic_dec_32.3c \ + atomic_dec_32_nv.3c \ + atomic_dec_64.3c \ + atomic_dec_64_nv.3c \ + atomic_dec_8.3c \ + atomic_dec_8_nv.3c \ + atomic_dec_ptr.3c \ + atomic_dec_ptr_nv.3c \ + atomic_dec_uchar.3c \ + atomic_dec_uchar_nv.3c \ + atomic_dec_uint.3c \ + atomic_dec_uint_nv.3c \ + atomic_dec_ulong.3c \ + atomic_dec_ulong_nv.3c \ + atomic_dec_ushort.3c \ + atomic_dec_ushort_nv.3c \ + atomic_inc_16.3c \ + atomic_inc_16_nv.3c \ + atomic_inc_32.3c \ + atomic_inc_32_nv.3c \ + atomic_inc_64.3c \ + atomic_inc_64_nv.3c \ + atomic_inc_8.3c \ + atomic_inc_8_nv.3c \ + atomic_inc_ptr.3c \ + atomic_inc_ptr_nv.3c \ + atomic_inc_uchar.3c \ + atomic_inc_uchar_nv.3c \ + atomic_inc_uint.3c \ + atomic_inc_uint_nv.3c \ + atomic_inc_ulong.3c \ + atomic_inc_ulong_nv.3c \ + atomic_inc_ushort.3c \ + atomic_inc_ushort_nv.3c \ + atomic_or_16.3c \ + atomic_or_16_nv.3c \ + atomic_or_32.3c \ + atomic_or_32_nv.3c \ + atomic_or_64.3c \ + atomic_or_64_nv.3c \ + atomic_or_8.3c \ + atomic_or_8_nv.3c \ + atomic_or_uchar.3c \ + atomic_or_uchar_nv.3c \ + atomic_or_uint.3c \ + atomic_or_uint_nv.3c \ + atomic_or_ulong.3c \ + atomic_or_ulong_nv.3c \ + atomic_or_ushort.3c \ + atomic_or_ushort_nv.3c \ + atomic_set_long_excl.3c \ + atomic_swap_16.3c \ + atomic_swap_32.3c \ + atomic_swap_64.3c \ + atomic_swap_8.3c \ + atomic_swap_ptr.3c \ + atomic_swap_uchar.3c \ + atomic_swap_uint.3c \ + atomic_swap_ulong.3c \ + atomic_swap_ushort.3c \ + backtrace.3c \ + backtrace_symbols.3c \ + backtrace_symbols_fd.3c \ + bcmp.3c \ + bcopy.3c \ + bind_textdomain_codeset.3c \ + bindtextdomain.3c \ + bzero.3c \ + calloc.3c \ + catclose.3c \ + cfgetospeed.3c \ + cfsetospeed.3c \ + cftime.3c \ + clearerr.3c \ + clock_getres.3c \ + clock_gettime.3c \ + closelog.3c \ + cond_broadcast.3c \ + cond_destroy.3c \ + cond_reltimedwait.3c \ + cond_signal.3c \ + cond_timedwait.3c \ + cond_wait.3c \ + csetcol.3c \ + csetlen.3c \ + csetno.3c \ + ctermid_r.3c \ + ctime_r.3c \ + dbm_clearerr.3c \ + dbm_close.3c \ + dbm_delete.3c \ + dbm_error.3c \ + dbm_fetch.3c \ + dbm_firstkey.3c \ + dbm_nextkey.3c \ + dbm_open.3c \ + dbm_store.3c \ + dcgettext.3c \ + dcngettext.3c \ + decimal_to_double.3c \ + decimal_to_extended.3c \ + decimal_to_quadruple.3c \ + decimal_to_single.3c \ + dgettext.3c \ + dladdr1.3c \ + dlmopen.3c \ + dngettext.3c \ + door_setparam.3c \ + door_unbind.3c \ + double_to_decimal.3c \ + edata.3c \ + endgrent.3c \ + endnetgrent.3c \ + endpwent.3c \ + endspent.3c \ + endusershell.3c \ + endutent.3c \ + endutxent.3c \ + erand48.3c \ + errno.3c \ + errx.3c \ + etext.3c \ + euccol.3c \ + eucscol.3c \ + extended_to_decimal.3c \ + fconvert.3c \ + fcvt.3c \ + fdopendir.3c \ + fdwalk.3c \ + feof.3c \ + fgetgrent.3c \ + fgetgrent_r.3c \ + fgetpwent.3c \ + fgetpwent_r.3c \ + fgets.3c \ + fgetspent.3c \ + fgetspent_r.3c \ + fgetws.3c \ + file_to_decimal.3c \ + fileno.3c \ + finite.3c \ + fpclass.3c \ + fpgetmask.3c \ + fpgetsticky.3c \ + fprintf.3c \ + fpsetmask.3c \ + fpsetround.3c \ + fpsetsticky.3c \ + fputs.3c \ + free.3c \ + fscanf.3c \ + fseeko.3c \ + fsetattr.3c \ + ftello.3c \ + ftruncate.3c \ + ftrylockfile.3c \ + func_to_decimal.3c \ + funlockfile.3c \ + gconvert.3c \ + gcvt.3c \ + getattrat.3c \ + getc.3c \ + getc_unlocked.3c \ + getchar.3c \ + getchar_unlocked.3c \ + getextmntent.3c \ + getgrent.3c \ + getgrent_r.3c \ + getgrgid.3c \ + getgrgid_r.3c \ + getgrnam_r.3c \ + gethomelgroup.3c \ + gethrvtime.3c \ + getlogin_r.3c \ + getmntany.3c \ + getnetgrent_r.3c \ + getpassphrase.3c \ + getpwent.3c \ + getpwent_r.3c \ + getpwnam_r.3c \ + getpwuid.3c \ + getpwuid_r.3c \ + getspent.3c \ + getspent_r.3c \ + getspnam_r.3c \ + getutid.3c \ + getutline.3c \ + getutmp.3c \ + getutmpx.3c \ + getutxid.3c \ + getutxline.3c \ + getvfsany.3c \ + getvfsfile.3c \ + getvfsspec.3c \ + getw.3c \ + getzoneidbyname.3c \ + getzonenamebyid.3c \ + globfree.3c \ + gmtime.3c \ + gmtime_r.3c \ + gsignal.3c \ + hasmntopt.3c \ + hcreate.3c \ + hdestroy.3c \ + initstate.3c \ + innetgr.3c \ + isalnum.3c \ + isalpha.3c \ + isascii.3c \ + isblank.3c \ + iscntrl.3c \ + isdigit.3c \ + isenglish.3c \ + isgraph.3c \ + isideogram.3c \ + islower.3c \ + isnanf.3c \ + isnumber.3c \ + isphonogram.3c \ + isprint.3c \ + ispunct.3c \ + isspace.3c \ + isspecial.3c \ + isupper.3c \ + iswalnum.3c \ + iswascii.3c \ + iswblank.3c \ + iswcntrl.3c \ + iswdigit.3c \ + iswgraph.3c \ + iswlower.3c \ + iswprint.3c \ + iswpunct.3c \ + iswspace.3c \ + iswupper.3c \ + iswxdigit.3c \ + isxdigit.3c \ + jrand48.3c \ + l64a.3c \ + labs.3c \ + lcong48.3c \ + ldiv.3c \ + lfind.3c \ + llabs.3c \ + lldiv.3c \ + lltostr.3c \ + localtime.3c \ + localtime_r.3c \ + longjmp.3c \ + lrand48.3c \ + major.3c \ + memalign.3c \ + membar_consumer.3c \ + membar_enter.3c \ + membar_exit.3c \ + membar_producer.3c \ + memccpy.3c \ + memchr.3c \ + memcmp.3c \ + memcpy.3c \ + memmove.3c \ + memset.3c \ + minor.3c \ + mkdtemp.3c \ + mkstemps.3c \ + mq_reltimedreceive_np.3c \ + mq_reltimedsend_np.3c \ + mq_timedreceive.3c \ + mq_timedsend.3c \ + mrand48.3c \ + munlock.3c \ + munlockall.3c \ + mutex_consistent.3c \ + mutex_destroy.3c \ + mutex_lock.3c \ + mutex_trylock.3c \ + mutex_unlock.3c \ + nftw.3c \ + ngettext.3c \ + nrand48.3c \ + openlog.3c \ + pclose.3c \ + port_dissociate.3c \ + port_getn.3c \ + port_sendn.3c \ + posix_spawn_file_actions_addopen.3c \ + posix_spawn_file_actions_init.3c \ + posix_spawnattr_init.3c \ + posix_spawnattr_setflags.3c \ + posix_spawnattr_setpgroup.3c \ + posix_spawnattr_setschedparam.3c \ + posix_spawnattr_setschedpolicy.3c \ + posix_spawnattr_setsigdefault.3c \ + posix_spawnattr_setsigignore_np.3c \ + posix_spawnattr_setsigmask.3c \ + posix_spawnp.3c \ + printstack.3c \ + priv_allocset.3c \ + priv_basicset.3c \ + priv_copyset.3c \ + priv_delset.3c \ + priv_emptyset.3c \ + priv_fillset.3c \ + priv_freeset.3c \ + priv_getbyname.3c \ + priv_getbynum.3c \ + priv_getsetbyname.3c \ + priv_getsetbynum.3c \ + priv_gettext.3c \ + priv_ineffect.3c \ + priv_intersect.3c \ + priv_inverse.3c \ + priv_isemptyset.3c \ + priv_isequalset.3c \ + priv_isfullset.3c \ + priv_ismember.3c \ + priv_issubset.3c \ + priv_set_to_str.3c \ + priv_union.3c \ + pselect.3c \ + psiginfo.3c \ + pthread_attr_destroy.3c \ + pthread_attr_setdetachstate.3c \ + pthread_attr_setguardsize.3c \ + pthread_attr_setinheritsched.3c \ + pthread_attr_setschedparam.3c \ + pthread_attr_setschedpolicy.3c \ + pthread_attr_setscope.3c \ + pthread_attr_setstack.3c \ + pthread_attr_setstackaddr.3c \ + pthread_attr_setstacksize.3c \ + pthread_barrier_init.3c \ + pthread_barrierattr_init.3c \ + pthread_barrierattr_setpshared.3c \ + pthread_cond_broadcast.3c \ + pthread_cond_destroy.3c \ + pthread_cond_reltimedwait_np.3c \ + pthread_cond_timedwait.3c \ + pthread_condattr_destroy.3c \ + pthread_condattr_setclock.3c \ + pthread_condattr_setpshared.3c \ + pthread_key_create_once_np.3c \ + pthread_mutex_destroy.3c \ + pthread_mutex_reltimedlock_np.3c \ + pthread_mutex_setprioceiling.3c \ + pthread_mutex_trylock.3c \ + pthread_mutex_unlock.3c \ + pthread_mutexattr_destroy.3c \ + pthread_mutexattr_setprioceiling.3c \ + pthread_mutexattr_setprotocol.3c \ + pthread_mutexattr_setpshared.3c \ + pthread_mutexattr_settype.3c \ + pthread_rwlock_destroy.3c \ + pthread_rwlock_reltimedrdlock_np.3c \ + pthread_rwlock_reltimedwrlock_np.3c \ + pthread_rwlock_tryrdlock.3c \ + pthread_rwlock_trywrlock.3c \ + pthread_rwlockattr_destroy.3c \ + pthread_rwlockattr_setpshared.3c \ + pthread_setconcurrency.3c \ + pthread_setschedparam.3c \ + pthread_setspecific.3c \ + pthread_spin_init.3c \ + pthread_spin_trylock.3c \ + putc.3c \ + putc_unlocked.3c \ + putchar.3c \ + putchar_unlocked.3c \ + putmntent.3c \ + pututline.3c \ + pututxline.3c \ + putw.3c \ + putwc.3c \ + putwchar.3c \ + qeconvert.3c \ + qfconvert.3c \ + qgconvert.3c \ + quadruple_to_decimal.3c \ + rand_r.3c \ + rctlblk_get_enforced_value.3c \ + rctlblk_get_firing_time.3c \ + rctlblk_get_global_action.3c \ + rctlblk_get_global_flags.3c \ + rctlblk_get_local_action.3c \ + rctlblk_get_local_flags.3c \ + rctlblk_get_privilege.3c \ + rctlblk_get_recipient_pid.3c \ + rctlblk_get_value.3c \ + rctlblk_set_local_action.3c \ + rctlblk_set_local_flags.3c \ + rctlblk_set_privilege.3c \ + rctlblk_set_recipient_pid.3c \ + rctlblk_size.3c \ + re_exec.3c \ + readdir_r.3c \ + realloc.3c \ + regerror.3c \ + regex.3c \ + regexec.3c \ + regfree.3c \ + remque.3c \ + resetmnttab.3c \ + rindex.3c \ + rw_rdlock.3c \ + rw_tryrdlock.3c \ + rw_trywrlock.3c \ + rw_unlock.3c \ + rw_wrlock.3c \ + rwlock_destroy.3c \ + rwlock_init.3c \ + sched_get_priority_min.3c \ + schedctl_exit.3c \ + schedctl_lookup.3c \ + schedctl_start.3c \ + schedctl_stop.3c \ + seconvert.3c \ + seed48.3c \ + sem_reltimedwait_np.3c \ + sem_trywait.3c \ + sema_destroy.3c \ + sema_init.3c \ + sema_post.3c \ + sema_trywait.3c \ + sema_wait.3c \ + setattrat.3c \ + setgrent.3c \ + sethostname.3c \ + setlinebuf.3c \ + setlogmask.3c \ + setnetgrent.3c \ + setpriority.3c \ + setpwent.3c \ + setspent.3c \ + setstate.3c \ + settimeofday.3c \ + setusershell.3c \ + setutent.3c \ + setutxent.3c \ + setvbuf.3c \ + sfconvert.3c \ + sgconvert.3c \ + sig2str.3c \ + sigaddset.3c \ + sigdelset.3c \ + sigemptyset.3c \ + sigfillset.3c \ + sighold.3c \ + sigignore.3c \ + sigismember.3c \ + siglongjmp.3c \ + sigpause.3c \ + sigrelse.3c \ + sigset.3c \ + sigsetjmp.3c \ + sigtimedwait.3c \ + single_to_decimal.3c \ + snprintf.3c \ + sprintf.3c \ + srand.3c \ + srand48.3c \ + srandom.3c \ + sscanf.3c \ + strcasecmp.3c \ + strcat.3c \ + strchr.3c \ + strcmp.3c \ + strcpy.3c \ + strcspn.3c \ + strdup.3c \ + strerror_r.3c \ + strlcat.3c \ + strlcpy.3c \ + strlen.3c \ + strncasecmp.3c \ + strncat.3c \ + strncmp.3c \ + strncpy.3c \ + strnlen.3c \ + strpbrk.3c \ + strrchr.3c \ + strsep.3c \ + strspn.3c \ + strstr.3c \ + strtof.3c \ + strtok.3c \ + strtok_r.3c \ + strtold.3c \ + strtoll.3c \ + strtoull.3c \ + strtoumax.3c \ + swapcontext.3c \ + swprintf.3c \ + swscanf.3c \ + tdelete.3c \ + tempnam.3c \ + textdomain.3c \ + tfind.3c \ + thr_continue.3c \ + thr_getspecific.3c \ + thr_keycreate_once.3c \ + thr_setconcurrency.3c \ + thr_setprio.3c \ + thr_setspecific.3c \ + timer_getoverrun.3c \ + timer_gettime.3c \ + timerclear.3c \ + timercmp.3c \ + timerisset.3c \ + timersub.3c \ + tmpnam_r.3c \ + ttyname_r.3c \ + twalk.3c \ + tzset.3c \ + uconv_u16tou8.3c \ + uconv_u32tou16.3c \ + uconv_u32tou8.3c \ + uconv_u8tou16.3c \ + uconv_u8tou32.3c \ + ucred_free.3c \ + ucred_getegid.3c \ + ucred_geteuid.3c \ + ucred_getgroups.3c \ + ucred_getlabel.3c \ + ucred_getpflags.3c \ + ucred_getpid.3c \ + ucred_getprivset.3c \ + ucred_getprojid.3c \ + ucred_getrgid.3c \ + ucred_getruid.3c \ + ucred_getsgid.3c \ + ucred_getsuid.3c \ + ucred_getzoneid.3c \ + ucred_size.3c \ + ulckpwdf.3c \ + ulltostr.3c \ + unordered.3c \ + updwtmp.3c \ + updwtmpx.3c \ + utmpname.3c \ + utmpxname.3c \ + valloc.3c \ + vasprintf.3c \ + verr.3c \ + verrx.3c \ + vfprintf.3c \ + vfscanf.3c \ + vfwscanf.3c \ + vscanf.3c \ + vsnprintf.3c \ + vsprintf.3c \ + vsscanf.3c \ + vswprintf.3c \ + vswscanf.3c \ + vwarn.3c \ + vwarnx.3c \ + vwprintf.3c \ + vwscanf.3c \ + wait4.3c \ + warn.3c \ + warnx.3c \ + watof.3c \ + watoi.3c \ + watol.3c \ + watoll.3c \ + wcscat.3c \ + wcschr.3c \ + wcscmp.3c \ + wcscpy.3c \ + wcscspn.3c \ + wcsetno.3c \ + wcslen.3c \ + wcsncat.3c \ + wcsncmp.3c \ + wcsncpy.3c \ + wcspbrk.3c \ + wcsrchr.3c \ + wcsspn.3c \ + wcstof.3c \ + wcstok.3c \ + wcstold.3c \ + wcstoll.3c \ + wcstoull.3c \ + wcstoumax.3c \ + wcswcs.3c \ + windex.3c \ + wordfree.3c \ + wprintf.3c \ + wrindex.3c \ + wscanf.3c \ + wscasecmp.3c \ + wscat.3c \ + wschr.3c \ + wscmp.3c \ + wscol.3c \ + wscoll.3c \ + wscpy.3c \ + wscspn.3c \ + wsdup.3c \ + wslen.3c \ + wsncasecmp.3c \ + wsncat.3c \ + wsncmp.3c \ + wsncpy.3c \ + wspbrk.3c \ + wsrchr.3c \ + wsspn.3c \ + wstod.3c \ + wstok.3c \ + wstol.3c \ + wstostr.3c \ + wsxfrm.3c + +MANFILES += $(MANSOFILES) + +__flbf.3c := SOSRC = man3c/__fbufsize.3c +__fpending.3c := SOSRC = man3c/__fbufsize.3c +__fpurge.3c := SOSRC = man3c/__fbufsize.3c +__freadable.3c := SOSRC = man3c/__fbufsize.3c +__freading.3c := SOSRC = man3c/__fbufsize.3c +__fsetlocking.3c := SOSRC = man3c/__fbufsize.3c +__fwritable.3c := SOSRC = man3c/__fbufsize.3c +__fwriting.3c := SOSRC = man3c/__fbufsize.3c +_flushlbf.3c := SOSRC = man3c/__fbufsize.3c + +_setjmp.3c := SOSRC = man3c/_longjmp.3c + +l64a.3c := SOSRC = man3c/a64l.3c + +labs.3c := SOSRC = man3c/abs.3c +llabs.3c := SOSRC = man3c/abs.3c + +aiowrite.3c := SOSRC = man3c/aioread.3c + +atomic_add_16.3c := SOSRC = man3c/atomic_add.3c +atomic_add_16_nv.3c := SOSRC = man3c/atomic_add.3c +atomic_add_32.3c := SOSRC = man3c/atomic_add.3c +atomic_add_32_nv.3c := SOSRC = man3c/atomic_add.3c +atomic_add_64.3c := SOSRC = man3c/atomic_add.3c +atomic_add_64_nv.3c := SOSRC = man3c/atomic_add.3c +atomic_add_8.3c := SOSRC = man3c/atomic_add.3c +atomic_add_8_nv.3c := SOSRC = man3c/atomic_add.3c +atomic_add_char.3c := SOSRC = man3c/atomic_add.3c +atomic_add_char_nv.3c := SOSRC = man3c/atomic_add.3c +atomic_add_int.3c := SOSRC = man3c/atomic_add.3c +atomic_add_int_nv.3c := SOSRC = man3c/atomic_add.3c +atomic_add_long.3c := SOSRC = man3c/atomic_add.3c +atomic_add_long_nv.3c := SOSRC = man3c/atomic_add.3c +atomic_add_ptr.3c := SOSRC = man3c/atomic_add.3c +atomic_add_ptr_nv.3c := SOSRC = man3c/atomic_add.3c +atomic_add_short.3c := SOSRC = man3c/atomic_add.3c +atomic_add_short_nv.3c := SOSRC = man3c/atomic_add.3c +atomic_and_16.3c := SOSRC = man3c/atomic_and.3c +atomic_and_16_nv.3c := SOSRC = man3c/atomic_and.3c +atomic_and_32.3c := SOSRC = man3c/atomic_and.3c +atomic_and_32_nv.3c := SOSRC = man3c/atomic_and.3c +atomic_and_64.3c := SOSRC = man3c/atomic_and.3c +atomic_and_64_nv.3c := SOSRC = man3c/atomic_and.3c +atomic_and_8.3c := SOSRC = man3c/atomic_and.3c +atomic_and_8_nv.3c := SOSRC = man3c/atomic_and.3c +atomic_and_uchar.3c := SOSRC = man3c/atomic_and.3c +atomic_and_uchar_nv.3c := SOSRC = man3c/atomic_and.3c +atomic_and_uint.3c := SOSRC = man3c/atomic_and.3c +atomic_and_uint_nv.3c := SOSRC = man3c/atomic_and.3c +atomic_and_ulong.3c := SOSRC = man3c/atomic_and.3c +atomic_and_ulong_nv.3c := SOSRC = man3c/atomic_and.3c +atomic_and_ushort.3c := SOSRC = man3c/atomic_and.3c +atomic_and_ushort_nv.3c := SOSRC = man3c/atomic_and.3c + +atomic_clear_long_excl.3c := SOSRC = man3c/atomic_bits.3c +atomic_set_long_excl.3c := SOSRC = man3c/atomic_bits.3c + +atomic_cas_16.3c := SOSRC = man3c/atomic_cas.3c +atomic_cas_32.3c := SOSRC = man3c/atomic_cas.3c +atomic_cas_64.3c := SOSRC = man3c/atomic_cas.3c +atomic_cas_8.3c := SOSRC = man3c/atomic_cas.3c +atomic_cas_ptr.3c := SOSRC = man3c/atomic_cas.3c +atomic_cas_uchar.3c := SOSRC = man3c/atomic_cas.3c +atomic_cas_uint.3c := SOSRC = man3c/atomic_cas.3c +atomic_cas_ulong.3c := SOSRC = man3c/atomic_cas.3c +atomic_cas_ushort.3c := SOSRC = man3c/atomic_cas.3c + +atomic_dec_16.3c := SOSRC = man3c/atomic_dec.3c +atomic_dec_16_nv.3c := SOSRC = man3c/atomic_dec.3c +atomic_dec_32.3c := SOSRC = man3c/atomic_dec.3c +atomic_dec_32_nv.3c := SOSRC = man3c/atomic_dec.3c +atomic_dec_64.3c := SOSRC = man3c/atomic_dec.3c +atomic_dec_64_nv.3c := SOSRC = man3c/atomic_dec.3c +atomic_dec_8.3c := SOSRC = man3c/atomic_dec.3c +atomic_dec_8_nv.3c := SOSRC = man3c/atomic_dec.3c +atomic_dec_ptr.3c := SOSRC = man3c/atomic_dec.3c +atomic_dec_ptr_nv.3c := SOSRC = man3c/atomic_dec.3c +atomic_dec_uchar.3c := SOSRC = man3c/atomic_dec.3c +atomic_dec_uchar_nv.3c := SOSRC = man3c/atomic_dec.3c +atomic_dec_uint.3c := SOSRC = man3c/atomic_dec.3c +atomic_dec_uint_nv.3c := SOSRC = man3c/atomic_dec.3c +atomic_dec_ulong.3c := SOSRC = man3c/atomic_dec.3c +atomic_dec_ulong_nv.3c := SOSRC = man3c/atomic_dec.3c +atomic_dec_ushort.3c := SOSRC = man3c/atomic_dec.3c +atomic_dec_ushort_nv.3c := SOSRC = man3c/atomic_dec.3c + +atomic_inc_16.3c := SOSRC = man3c/atomic_inc.3c +atomic_inc_16_nv.3c := SOSRC = man3c/atomic_inc.3c +atomic_inc_32.3c := SOSRC = man3c/atomic_inc.3c +atomic_inc_32_nv.3c := SOSRC = man3c/atomic_inc.3c +atomic_inc_64.3c := SOSRC = man3c/atomic_inc.3c +atomic_inc_64_nv.3c := SOSRC = man3c/atomic_inc.3c +atomic_inc_8.3c := SOSRC = man3c/atomic_inc.3c +atomic_inc_8_nv.3c := SOSRC = man3c/atomic_inc.3c +atomic_inc_ptr.3c := SOSRC = man3c/atomic_inc.3c +atomic_inc_ptr_nv.3c := SOSRC = man3c/atomic_inc.3c +atomic_inc_uchar.3c := SOSRC = man3c/atomic_inc.3c +atomic_inc_uchar_nv.3c := SOSRC = man3c/atomic_inc.3c +atomic_inc_uint.3c := SOSRC = man3c/atomic_inc.3c +atomic_inc_uint_nv.3c := SOSRC = man3c/atomic_inc.3c +atomic_inc_ulong.3c := SOSRC = man3c/atomic_inc.3c +atomic_inc_ulong_nv.3c := SOSRC = man3c/atomic_inc.3c +atomic_inc_ushort.3c := SOSRC = man3c/atomic_inc.3c +atomic_inc_ushort_nv.3c := SOSRC = man3c/atomic_inc.3c + +atomic_or_16.3c := SOSRC = man3c/atomic_or.3c +atomic_or_16_nv.3c := SOSRC = man3c/atomic_or.3c +atomic_or_32.3c := SOSRC = man3c/atomic_or.3c +atomic_or_32_nv.3c := SOSRC = man3c/atomic_or.3c +atomic_or_64.3c := SOSRC = man3c/atomic_or.3c +atomic_or_64_nv.3c := SOSRC = man3c/atomic_or.3c +atomic_or_8.3c := SOSRC = man3c/atomic_or.3c +atomic_or_8_nv.3c := SOSRC = man3c/atomic_or.3c +atomic_or_uchar.3c := SOSRC = man3c/atomic_or.3c +atomic_or_uchar_nv.3c := SOSRC = man3c/atomic_or.3c +atomic_or_uint.3c := SOSRC = man3c/atomic_or.3c +atomic_or_uint_nv.3c := SOSRC = man3c/atomic_or.3c +atomic_or_ulong.3c := SOSRC = man3c/atomic_or.3c +atomic_or_ulong_nv.3c := SOSRC = man3c/atomic_or.3c +atomic_or_ushort.3c := SOSRC = man3c/atomic_or.3c +atomic_or_ushort_nv.3c := SOSRC = man3c/atomic_or.3c + +atomic_swap_16.3c := SOSRC = man3c/atomic_swap.3c +atomic_swap_32.3c := SOSRC = man3c/atomic_swap.3c +atomic_swap_64.3c := SOSRC = man3c/atomic_swap.3c +atomic_swap_8.3c := SOSRC = man3c/atomic_swap.3c +atomic_swap_ptr.3c := SOSRC = man3c/atomic_swap.3c +atomic_swap_uchar.3c := SOSRC = man3c/atomic_swap.3c +atomic_swap_uint.3c := SOSRC = man3c/atomic_swap.3c +atomic_swap_ulong.3c := SOSRC = man3c/atomic_swap.3c +atomic_swap_ushort.3c := SOSRC = man3c/atomic_swap.3c + +bcmp.3c := SOSRC = man3c/bstring.3c +bcopy.3c := SOSRC = man3c/bstring.3c +bzero.3c := SOSRC = man3c/bstring.3c + +catclose.3c := SOSRC = man3c/catopen.3c + +cfgetospeed.3c := SOSRC = man3c/cfgetispeed.3c + +cfsetospeed.3c := SOSRC = man3c/cfsetispeed.3c + +clock_getres.3c := SOSRC = man3c/clock_settime.3c +clock_gettime.3c := SOSRC = man3c/clock_settime.3c + +fdwalk.3c := SOSRC = man3c/closefrom.3c + +cond_broadcast.3c := SOSRC = man3c/cond_init.3c +cond_destroy.3c := SOSRC = man3c/cond_init.3c +cond_reltimedwait.3c := SOSRC = man3c/cond_init.3c +cond_signal.3c := SOSRC = man3c/cond_init.3c +cond_timedwait.3c := SOSRC = man3c/cond_init.3c +cond_wait.3c := SOSRC = man3c/cond_init.3c + +csetcol.3c := SOSRC = man3c/cset.3c +csetlen.3c := SOSRC = man3c/cset.3c +csetno.3c := SOSRC = man3c/cset.3c +wcsetno.3c := SOSRC = man3c/cset.3c + +ctermid_r.3c := SOSRC = man3c/ctermid.3c + +asctime.3c := SOSRC = man3c/ctime.3c +asctime_r.3c := SOSRC = man3c/ctime.3c +ctime_r.3c := SOSRC = man3c/ctime.3c +gmtime.3c := SOSRC = man3c/ctime.3c +gmtime_r.3c := SOSRC = man3c/ctime.3c +localtime.3c := SOSRC = man3c/ctime.3c +localtime_r.3c := SOSRC = man3c/ctime.3c +tzset.3c := SOSRC = man3c/ctime.3c + +isalnum.3c := SOSRC = man3c/ctype.3c +isalpha.3c := SOSRC = man3c/ctype.3c +isascii.3c := SOSRC = man3c/ctype.3c +isblank.3c := SOSRC = man3c/ctype.3c +iscntrl.3c := SOSRC = man3c/ctype.3c +isdigit.3c := SOSRC = man3c/ctype.3c +isgraph.3c := SOSRC = man3c/ctype.3c +islower.3c := SOSRC = man3c/ctype.3c +isprint.3c := SOSRC = man3c/ctype.3c +ispunct.3c := SOSRC = man3c/ctype.3c +isspace.3c := SOSRC = man3c/ctype.3c +isupper.3c := SOSRC = man3c/ctype.3c +isxdigit.3c := SOSRC = man3c/ctype.3c + +decimal_to_double.3c := SOSRC = man3c/decimal_to_floating.3c +decimal_to_extended.3c := SOSRC = man3c/decimal_to_floating.3c +decimal_to_quadruple.3c := SOSRC = man3c/decimal_to_floating.3c +decimal_to_single.3c := SOSRC = man3c/decimal_to_floating.3c + +ldiv.3c := SOSRC = man3c/div.3c +lldiv.3c := SOSRC = man3c/div.3c + +dladdr1.3c := SOSRC = man3c/dladdr.3c + +dlmopen.3c := SOSRC = man3c/dlopen.3c + +door_unbind.3c := SOSRC = man3c/door_bind.3c + +door_setparam.3c := SOSRC = man3c/door_getparam.3c + +erand48.3c := SOSRC = man3c/drand48.3c +jrand48.3c := SOSRC = man3c/drand48.3c +lcong48.3c := SOSRC = man3c/drand48.3c +lrand48.3c := SOSRC = man3c/drand48.3c +mrand48.3c := SOSRC = man3c/drand48.3c +nrand48.3c := SOSRC = man3c/drand48.3c +seed48.3c := SOSRC = man3c/drand48.3c +srand48.3c := SOSRC = man3c/drand48.3c + +fconvert.3c := SOSRC = man3c/econvert.3c +gconvert.3c := SOSRC = man3c/econvert.3c +qeconvert.3c := SOSRC = man3c/econvert.3c +qfconvert.3c := SOSRC = man3c/econvert.3c +qgconvert.3c := SOSRC = man3c/econvert.3c +seconvert.3c := SOSRC = man3c/econvert.3c +sfconvert.3c := SOSRC = man3c/econvert.3c +sgconvert.3c := SOSRC = man3c/econvert.3c + +fcvt.3c := SOSRC = man3c/ecvt.3c +gcvt.3c := SOSRC = man3c/ecvt.3c + +_edata.3c := SOSRC = man3c/end.3c +_end.3c := SOSRC = man3c/end.3c +_etext.3c := SOSRC = man3c/end.3c +edata.3c := SOSRC = man3c/end.3c +etext.3c := SOSRC = man3c/end.3c + +errx.3c := SOSRC = man3c/err.3c +verr.3c := SOSRC = man3c/err.3c +verrx.3c := SOSRC = man3c/err.3c +vwarn.3c := SOSRC = man3c/err.3c +vwarnx.3c := SOSRC = man3c/err.3c +warn.3c := SOSRC = man3c/err.3c +warnx.3c := SOSRC = man3c/err.3c + +euccol.3c := SOSRC = man3c/euclen.3c +eucscol.3c := SOSRC = man3c/euclen.3c + +_exithandle.3c := SOSRC = man3c/exit.3c + +clearerr.3c := SOSRC = man3c/ferror.3c +feof.3c := SOSRC = man3c/ferror.3c +fileno.3c := SOSRC = man3c/ferror.3c + +fsetattr.3c := SOSRC = man3c/fgetattr.3c +getattrat.3c := SOSRC = man3c/fgetattr.3c +setattrat.3c := SOSRC = man3c/fgetattr.3c + +getc.3c := SOSRC = man3c/fgetc.3c +getc_unlocked.3c := SOSRC = man3c/fgetc.3c +getchar.3c := SOSRC = man3c/fgetc.3c +getchar_unlocked.3c := SOSRC = man3c/fgetc.3c +getw.3c := SOSRC = man3c/fgetc.3c + +double_to_decimal.3c := SOSRC = man3c/floating_to_decimal.3c +extended_to_decimal.3c := SOSRC = man3c/floating_to_decimal.3c +quadruple_to_decimal.3c := SOSRC = man3c/floating_to_decimal.3c +single_to_decimal.3c := SOSRC = man3c/floating_to_decimal.3c + +ftrylockfile.3c := SOSRC = man3c/flockfile.3c +funlockfile.3c := SOSRC = man3c/flockfile.3c + +fpgetmask.3c := SOSRC = man3c/fpgetround.3c +fpgetsticky.3c := SOSRC = man3c/fpgetround.3c +fpsetmask.3c := SOSRC = man3c/fpgetround.3c +fpsetround.3c := SOSRC = man3c/fpgetround.3c +fpsetsticky.3c := SOSRC = man3c/fpgetround.3c + +putc.3c := SOSRC = man3c/fputc.3c +putc_unlocked.3c := SOSRC = man3c/fputc.3c +putchar.3c := SOSRC = man3c/fputc.3c +putchar_unlocked.3c := SOSRC = man3c/fputc.3c +putw.3c := SOSRC = man3c/fputc.3c + +putwc.3c := SOSRC = man3c/fputwc.3c +putwchar.3c := SOSRC = man3c/fputwc.3c + +fseeko.3c := SOSRC = man3c/fseek.3c + +ftello.3c := SOSRC = man3c/ftell.3c + +nftw.3c := SOSRC = man3c/ftw.3c + +swprintf.3c := SOSRC = man3c/fwprintf.3c +wprintf.3c := SOSRC = man3c/fwprintf.3c + +swscanf.3c := SOSRC = man3c/fwscanf.3c +vfwscanf.3c := SOSRC = man3c/fwscanf.3c +vswscanf.3c := SOSRC = man3c/fwscanf.3c +vwscanf.3c := SOSRC = man3c/fwscanf.3c +wscanf.3c := SOSRC = man3c/fwscanf.3c + +gethomelgroup.3c := SOSRC = man3c/getcpuid.3c + +endgrent.3c := SOSRC = man3c/getgrnam.3c +fgetgrent.3c := SOSRC = man3c/getgrnam.3c +fgetgrent_r.3c := SOSRC = man3c/getgrnam.3c +getgrent.3c := SOSRC = man3c/getgrnam.3c +getgrent_r.3c := SOSRC = man3c/getgrnam.3c +getgrgid.3c := SOSRC = man3c/getgrnam.3c +getgrgid_r.3c := SOSRC = man3c/getgrnam.3c +getgrnam_r.3c := SOSRC = man3c/getgrnam.3c +setgrent.3c := SOSRC = man3c/getgrnam.3c + +sethostname.3c := SOSRC = man3c/gethostname.3c + +gethrvtime.3c := SOSRC = man3c/gethrtime.3c + +getlogin_r.3c := SOSRC = man3c/getlogin.3c + +getextmntent.3c := SOSRC = man3c/getmntent.3c +getmntany.3c := SOSRC = man3c/getmntent.3c +hasmntopt.3c := SOSRC = man3c/getmntent.3c +putmntent.3c := SOSRC = man3c/getmntent.3c +resetmnttab.3c := SOSRC = man3c/getmntent.3c + +endnetgrent.3c := SOSRC = man3c/getnetgrent.3c +getnetgrent_r.3c := SOSRC = man3c/getnetgrent.3c +innetgr.3c := SOSRC = man3c/getnetgrent.3c +setnetgrent.3c := SOSRC = man3c/getnetgrent.3c + +getpassphrase.3c := SOSRC = man3c/getpass.3c + +setpriority.3c := SOSRC = man3c/getpriority.3c + +endpwent.3c := SOSRC = man3c/getpwnam.3c +fgetpwent.3c := SOSRC = man3c/getpwnam.3c +fgetpwent_r.3c := SOSRC = man3c/getpwnam.3c +getpwent.3c := SOSRC = man3c/getpwnam.3c +getpwent_r.3c := SOSRC = man3c/getpwnam.3c +getpwnam_r.3c := SOSRC = man3c/getpwnam.3c +getpwuid.3c := SOSRC = man3c/getpwnam.3c +getpwuid_r.3c := SOSRC = man3c/getpwnam.3c +setpwent.3c := SOSRC = man3c/getpwnam.3c + +fgets.3c := SOSRC = man3c/gets.3c + +endspent.3c := SOSRC = man3c/getspnam.3c +fgetspent.3c := SOSRC = man3c/getspnam.3c +fgetspent_r.3c := SOSRC = man3c/getspnam.3c +getspent.3c := SOSRC = man3c/getspnam.3c +getspent_r.3c := SOSRC = man3c/getspnam.3c +getspnam_r.3c := SOSRC = man3c/getspnam.3c +setspent.3c := SOSRC = man3c/getspnam.3c + +bind_textdomain_codeset.3c := SOSRC = man3c/gettext.3c +bindtextdomain.3c := SOSRC = man3c/gettext.3c +dcgettext.3c := SOSRC = man3c/gettext.3c +dcngettext.3c := SOSRC = man3c/gettext.3c +dgettext.3c := SOSRC = man3c/gettext.3c +dngettext.3c := SOSRC = man3c/gettext.3c +ngettext.3c := SOSRC = man3c/gettext.3c +textdomain.3c := SOSRC = man3c/gettext.3c + +settimeofday.3c := SOSRC = man3c/gettimeofday.3c + +endusershell.3c := SOSRC = man3c/getusershell.3c +setusershell.3c := SOSRC = man3c/getusershell.3c + +endutent.3c := SOSRC = man3c/getutent.3c +getutid.3c := SOSRC = man3c/getutent.3c +getutline.3c := SOSRC = man3c/getutent.3c +pututline.3c := SOSRC = man3c/getutent.3c +setutent.3c := SOSRC = man3c/getutent.3c +utmpname.3c := SOSRC = man3c/getutent.3c + +endutxent.3c := SOSRC = man3c/getutxent.3c +getutmp.3c := SOSRC = man3c/getutxent.3c +getutmpx.3c := SOSRC = man3c/getutxent.3c +getutxid.3c := SOSRC = man3c/getutxent.3c +getutxline.3c := SOSRC = man3c/getutxent.3c +pututxline.3c := SOSRC = man3c/getutxent.3c +setutxent.3c := SOSRC = man3c/getutxent.3c +updwtmp.3c := SOSRC = man3c/getutxent.3c +updwtmpx.3c := SOSRC = man3c/getutxent.3c +utmpxname.3c := SOSRC = man3c/getutxent.3c + +getvfsany.3c := SOSRC = man3c/getvfsent.3c +getvfsfile.3c := SOSRC = man3c/getvfsent.3c +getvfsspec.3c := SOSRC = man3c/getvfsent.3c + +fgetws.3c := SOSRC = man3c/getws.3c + +getzoneidbyname.3c := SOSRC = man3c/getzoneid.3c +getzonenamebyid.3c := SOSRC = man3c/getzoneid.3c + +globfree.3c := SOSRC = man3c/glob.3c + +hcreate.3c := SOSRC = man3c/hsearch.3c +hdestroy.3c := SOSRC = man3c/hsearch.3c + +rindex.3c := SOSRC = man3c/index.3c + +remque.3c := SOSRC = man3c/insque.3c + +finite.3c := SOSRC = man3c/isnand.3c +fpclass.3c := SOSRC = man3c/isnand.3c +isnanf.3c := SOSRC = man3c/isnand.3c +unordered.3c := SOSRC = man3c/isnand.3c + +isenglish.3c := SOSRC = man3c/iswalpha.3c +isideogram.3c := SOSRC = man3c/iswalpha.3c +isnumber.3c := SOSRC = man3c/iswalpha.3c +isphonogram.3c := SOSRC = man3c/iswalpha.3c +isspecial.3c := SOSRC = man3c/iswalpha.3c +iswalnum.3c := SOSRC = man3c/iswalpha.3c +iswascii.3c := SOSRC = man3c/iswalpha.3c +iswblank.3c := SOSRC = man3c/iswalpha.3c +iswcntrl.3c := SOSRC = man3c/iswalpha.3c +iswdigit.3c := SOSRC = man3c/iswalpha.3c +iswgraph.3c := SOSRC = man3c/iswalpha.3c +iswlower.3c := SOSRC = man3c/iswalpha.3c +iswprint.3c := SOSRC = man3c/iswalpha.3c +iswpunct.3c := SOSRC = man3c/iswalpha.3c +iswspace.3c := SOSRC = man3c/iswalpha.3c +iswupper.3c := SOSRC = man3c/iswalpha.3c +iswxdigit.3c := SOSRC = man3c/iswalpha.3c + +ulckpwdf.3c := SOSRC = man3c/lckpwdf.3c + +lfind.3c := SOSRC = man3c/lsearch.3c + +swapcontext.3c := SOSRC = man3c/makecontext.3c + +major.3c := SOSRC = man3c/makedev.3c +minor.3c := SOSRC = man3c/makedev.3c + +alloca.3c := SOSRC = man3c/malloc.3c +calloc.3c := SOSRC = man3c/malloc.3c +free.3c := SOSRC = man3c/malloc.3c +memalign.3c := SOSRC = man3c/malloc.3c +realloc.3c := SOSRC = man3c/malloc.3c +valloc.3c := SOSRC = man3c/malloc.3c + +membar_consumer.3c := SOSRC = man3c/membar_ops.3c +membar_enter.3c := SOSRC = man3c/membar_ops.3c +membar_exit.3c := SOSRC = man3c/membar_ops.3c +membar_producer.3c := SOSRC = man3c/membar_ops.3c + +memccpy.3c := SOSRC = man3c/memory.3c +memchr.3c := SOSRC = man3c/memory.3c +memcmp.3c := SOSRC = man3c/memory.3c +memcpy.3c := SOSRC = man3c/memory.3c +memmove.3c := SOSRC = man3c/memory.3c +memset.3c := SOSRC = man3c/memory.3c + +mkdtemp.3c := SOSRC = man3c/mkstemp.3c +mkstemps.3c := SOSRC = man3c/mkstemp.3c + +munlock.3c := SOSRC = man3c/mlock.3c + +munlockall.3c := SOSRC = man3c/mlockall.3c + +mq_reltimedreceive_np.3c := SOSRC = man3c/mq_receive.3c +mq_timedreceive.3c := SOSRC = man3c/mq_receive.3c + +mq_reltimedsend_np.3c := SOSRC = man3c/mq_send.3c +mq_timedsend.3c := SOSRC = man3c/mq_send.3c + +mutex_consistent.3c := SOSRC = man3c/mutex_init.3c +mutex_destroy.3c := SOSRC = man3c/mutex_init.3c +mutex_lock.3c := SOSRC = man3c/mutex_init.3c +mutex_trylock.3c := SOSRC = man3c/mutex_init.3c +mutex_unlock.3c := SOSRC = man3c/mutex_init.3c + +dbm_clearerr.3c := SOSRC = man3c/ndbm.3c +dbm_close.3c := SOSRC = man3c/ndbm.3c +dbm_delete.3c := SOSRC = man3c/ndbm.3c +dbm_error.3c := SOSRC = man3c/ndbm.3c +dbm_fetch.3c := SOSRC = man3c/ndbm.3c +dbm_firstkey.3c := SOSRC = man3c/ndbm.3c +dbm_nextkey.3c := SOSRC = man3c/ndbm.3c +dbm_open.3c := SOSRC = man3c/ndbm.3c +dbm_store.3c := SOSRC = man3c/ndbm.3c + +fdopendir.3c := SOSRC = man3c/opendir.3c + +errno.3c := SOSRC = man3c/perror.3c + +pclose.3c := SOSRC = man3c/popen.3c + +port_dissociate.3c := SOSRC = man3c/port_associate.3c + +port_getn.3c := SOSRC = man3c/port_get.3c + +port_sendn.3c := SOSRC = man3c/port_send.3c + +posix_spawnp.3c := SOSRC = man3c/posix_spawn.3c + +posix_spawn_file_actions_addopen.3c := SOSRC = man3c/posix_spawn_file_actions_addclose.3c +posix_spawn_file_actions_init.3c := SOSRC = man3c/posix_spawn_file_actions_destroy.3c + +posix_spawnattr_init.3c := SOSRC = man3c/posix_spawnattr_destroy.3c + +posix_spawnattr_setflags.3c := SOSRC = man3c/posix_spawnattr_getflags.3c + +posix_spawnattr_setpgroup.3c := SOSRC = man3c/posix_spawnattr_getpgroup.3c + +posix_spawnattr_setschedparam.3c := SOSRC = man3c/posix_spawnattr_getschedparam.3c + +posix_spawnattr_setschedpolicy.3c := SOSRC = man3c/posix_spawnattr_getschedpolicy.3c + +posix_spawnattr_setsigdefault.3c := SOSRC = man3c/posix_spawnattr_getsigdefault.3c + +posix_spawnattr_setsigignore_np.3c := SOSRC = man3c/posix_spawnattr_getsigignore_np.3c + +posix_spawnattr_setsigmask.3c := SOSRC = man3c/posix_spawnattr_getsigmask.3c + +asprintf.3c := SOSRC = man3c/printf.3c +fprintf.3c := SOSRC = man3c/printf.3c +snprintf.3c := SOSRC = man3c/printf.3c +sprintf.3c := SOSRC = man3c/printf.3c + +priv_allocset.3c := SOSRC = man3c/priv_addset.3c +priv_basicset.3c := SOSRC = man3c/priv_addset.3c +priv_copyset.3c := SOSRC = man3c/priv_addset.3c +priv_delset.3c := SOSRC = man3c/priv_addset.3c +priv_emptyset.3c := SOSRC = man3c/priv_addset.3c +priv_fillset.3c := SOSRC = man3c/priv_addset.3c +priv_freeset.3c := SOSRC = man3c/priv_addset.3c +priv_intersect.3c := SOSRC = man3c/priv_addset.3c +priv_inverse.3c := SOSRC = man3c/priv_addset.3c +priv_isemptyset.3c := SOSRC = man3c/priv_addset.3c +priv_isequalset.3c := SOSRC = man3c/priv_addset.3c +priv_isfullset.3c := SOSRC = man3c/priv_addset.3c +priv_ismember.3c := SOSRC = man3c/priv_addset.3c +priv_issubset.3c := SOSRC = man3c/priv_addset.3c +priv_union.3c := SOSRC = man3c/priv_addset.3c + +priv_ineffect.3c := SOSRC = man3c/priv_set.3c + +priv_getbyname.3c := SOSRC = man3c/priv_str_to_set.3c +priv_getbynum.3c := SOSRC = man3c/priv_str_to_set.3c +priv_getsetbyname.3c := SOSRC = man3c/priv_str_to_set.3c +priv_getsetbynum.3c := SOSRC = man3c/priv_str_to_set.3c +priv_gettext.3c := SOSRC = man3c/priv_str_to_set.3c +priv_set_to_str.3c := SOSRC = man3c/priv_str_to_set.3c + +psiginfo.3c := SOSRC = man3c/psignal.3c + +pthread_attr_setdetachstate.3c := SOSRC = man3c/pthread_attr_getdetachstate.3c + +pthread_attr_setguardsize.3c := SOSRC = man3c/pthread_attr_getguardsize.3c + +pthread_attr_setinheritsched.3c := SOSRC = man3c/pthread_attr_getinheritsched.3c + +pthread_attr_setschedparam.3c := SOSRC = man3c/pthread_attr_getschedparam.3c + +pthread_attr_setschedpolicy.3c := SOSRC = man3c/pthread_attr_getschedpolicy.3c + +pthread_attr_setscope.3c := SOSRC = man3c/pthread_attr_getscope.3c +pthread_attr_setstack.3c := SOSRC = man3c/pthread_attr_getstack.3c + +pthread_attr_setstackaddr.3c := SOSRC = man3c/pthread_attr_getstackaddr.3c + +pthread_attr_setstacksize.3c := SOSRC = man3c/pthread_attr_getstacksize.3c + +pthread_attr_destroy.3c := SOSRC = man3c/pthread_attr_init.3c + +pthread_barrier_init.3c := SOSRC = man3c/pthread_barrier_destroy.3c + +pthread_barrierattr_init.3c := SOSRC = man3c/pthread_barrierattr_destroy.3c + +pthread_barrierattr_setpshared.3c := SOSRC = man3c/pthread_barrierattr_getpshared.3c + +pthread_cond_destroy.3c := SOSRC = man3c/pthread_cond_init.3c + +pthread_cond_broadcast.3c := SOSRC = man3c/pthread_cond_signal.3c + +pthread_cond_reltimedwait_np.3c := SOSRC = man3c/pthread_cond_wait.3c +pthread_cond_timedwait.3c := SOSRC = man3c/pthread_cond_wait.3c + +pthread_condattr_setclock.3c := SOSRC = man3c/pthread_condattr_getclock.3c + +pthread_condattr_setpshared.3c := SOSRC = man3c/pthread_condattr_getpshared.3c + +pthread_condattr_destroy.3c := SOSRC = man3c/pthread_condattr_init.3c + +pthread_setconcurrency.3c := SOSRC = man3c/pthread_getconcurrency.3c + +pthread_setschedparam.3c := SOSRC = man3c/pthread_getschedparam.3c + +pthread_setspecific.3c := SOSRC = man3c/pthread_getspecific.3c + +pthread_key_create_once_np.3c := SOSRC = man3c/pthread_key_create.3c + +pthread_mutex_setprioceiling.3c := SOSRC = man3c/pthread_mutex_getprioceiling.3c + +pthread_mutex_destroy.3c := SOSRC = man3c/pthread_mutex_init.3c + +pthread_mutex_trylock.3c := SOSRC = man3c/pthread_mutex_lock.3c +pthread_mutex_unlock.3c := SOSRC = man3c/pthread_mutex_lock.3c + +pthread_mutex_reltimedlock_np.3c := SOSRC = man3c/pthread_mutex_timedlock.3c + +pthread_mutexattr_setprioceiling.3c := SOSRC = man3c/pthread_mutexattr_getprioceiling.3c + +pthread_mutexattr_setprotocol.3c := SOSRC = man3c/pthread_mutexattr_getprotocol.3c + +pthread_mutexattr_setpshared.3c := SOSRC = man3c/pthread_mutexattr_getpshared.3c + +pthread_mutexattr_settype.3c := SOSRC = man3c/pthread_mutexattr_gettype.3c + +pthread_mutexattr_destroy.3c := SOSRC = man3c/pthread_mutexattr_init.3c + +pthread_rwlock_destroy.3c := SOSRC = man3c/pthread_rwlock_init.3c + +pthread_rwlock_tryrdlock.3c := SOSRC = man3c/pthread_rwlock_rdlock.3c + +pthread_rwlock_reltimedrdlock_np.3c := SOSRC = man3c/pthread_rwlock_timedrdlock.3c + +pthread_rwlock_reltimedwrlock_np.3c := SOSRC = man3c/pthread_rwlock_timedwrlock.3c + +pthread_rwlock_trywrlock.3c := SOSRC = man3c/pthread_rwlock_wrlock.3c + +pthread_rwlockattr_setpshared.3c := SOSRC = man3c/pthread_rwlockattr_getpshared.3c + +pthread_rwlockattr_destroy.3c := SOSRC = man3c/pthread_rwlockattr_init.3c + +pthread_spin_init.3c := SOSRC = man3c/pthread_spin_destroy.3c + +pthread_spin_trylock.3c := SOSRC = man3c/pthread_spin_lock.3c + +fputs.3c := SOSRC = man3c/puts.3c + +rand_r.3c := SOSRC = man3c/rand.3c +srand.3c := SOSRC = man3c/rand.3c + +initstate.3c := SOSRC = man3c/random.3c +setstate.3c := SOSRC = man3c/random.3c +srandom.3c := SOSRC = man3c/random.3c + +rctlblk_get_enforced_value.3c := SOSRC = man3c/rctlblk_set_value.3c +rctlblk_get_firing_time.3c := SOSRC = man3c/rctlblk_set_value.3c +rctlblk_get_global_action.3c := SOSRC = man3c/rctlblk_set_value.3c +rctlblk_get_global_flags.3c := SOSRC = man3c/rctlblk_set_value.3c +rctlblk_get_local_action.3c := SOSRC = man3c/rctlblk_set_value.3c +rctlblk_get_local_flags.3c := SOSRC = man3c/rctlblk_set_value.3c +rctlblk_get_privilege.3c := SOSRC = man3c/rctlblk_set_value.3c +rctlblk_get_recipient_pid.3c := SOSRC = man3c/rctlblk_set_value.3c +rctlblk_get_value.3c := SOSRC = man3c/rctlblk_set_value.3c +rctlblk_set_local_action.3c := SOSRC = man3c/rctlblk_set_value.3c +rctlblk_set_local_flags.3c := SOSRC = man3c/rctlblk_set_value.3c +rctlblk_set_privilege.3c := SOSRC = man3c/rctlblk_set_value.3c +rctlblk_set_recipient_pid.3c := SOSRC = man3c/rctlblk_set_value.3c +rctlblk_size.3c := SOSRC = man3c/rctlblk_set_value.3c + +re_exec.3c := SOSRC = man3c/re_comp.3c + +readdir_r.3c := SOSRC = man3c/readdir.3c + +regex.3c := SOSRC = man3c/regcmp.3c + +regerror.3c := SOSRC = man3c/regcomp.3c +regexec.3c := SOSRC = man3c/regcomp.3c +regfree.3c := SOSRC = man3c/regcomp.3c + +rw_rdlock.3c := SOSRC = man3c/rwlock.3c +rw_tryrdlock.3c := SOSRC = man3c/rwlock.3c +rw_trywrlock.3c := SOSRC = man3c/rwlock.3c +rw_unlock.3c := SOSRC = man3c/rwlock.3c +rw_wrlock.3c := SOSRC = man3c/rwlock.3c +rwlock_destroy.3c := SOSRC = man3c/rwlock.3c +rwlock_init.3c := SOSRC = man3c/rwlock.3c + +alphasort.3c := SOSRC = man3c/scandir.3c + +fscanf.3c := SOSRC = man3c/scanf.3c +sscanf.3c := SOSRC = man3c/scanf.3c +vfscanf.3c := SOSRC = man3c/scanf.3c +vscanf.3c := SOSRC = man3c/scanf.3c +vsscanf.3c := SOSRC = man3c/scanf.3c + +sched_get_priority_min.3c := SOSRC = man3c/sched_get_priority_max.3c + +schedctl_exit.3c := SOSRC = man3c/schedctl_init.3c +schedctl_lookup.3c := SOSRC = man3c/schedctl_init.3c +schedctl_start.3c := SOSRC = man3c/schedctl_init.3c +schedctl_stop.3c := SOSRC = man3c/schedctl_init.3c + +FD_CLR.3c := SOSRC = man3c/select.3c +FD_ISSET.3c := SOSRC = man3c/select.3c +FD_SET.3c := SOSRC = man3c/select.3c +FD_ZERO.3c := SOSRC = man3c/select.3c +pselect.3c := SOSRC = man3c/select.3c + +sem_reltimedwait_np.3c := SOSRC = man3c/sem_timedwait.3c + +sem_trywait.3c := SOSRC = man3c/sem_wait.3c + +sema_destroy.3c := SOSRC = man3c/semaphore.3c +sema_init.3c := SOSRC = man3c/semaphore.3c +sema_post.3c := SOSRC = man3c/semaphore.3c +sema_trywait.3c := SOSRC = man3c/semaphore.3c +sema_wait.3c := SOSRC = man3c/semaphore.3c + +setvbuf.3c := SOSRC = man3c/setbuf.3c + +setlinebuf.3c := SOSRC = man3c/setbuffer.3c + +longjmp.3c := SOSRC = man3c/setjmp.3c +siglongjmp.3c := SOSRC = man3c/setjmp.3c +sigsetjmp.3c := SOSRC = man3c/setjmp.3c + +sighold.3c := SOSRC = man3c/signal.3c +sigignore.3c := SOSRC = man3c/signal.3c +sigpause.3c := SOSRC = man3c/signal.3c +sigrelse.3c := SOSRC = man3c/signal.3c +sigset.3c := SOSRC = man3c/signal.3c + +sigaddset.3c := SOSRC = man3c/sigsetops.3c +sigdelset.3c := SOSRC = man3c/sigsetops.3c +sigemptyset.3c := SOSRC = man3c/sigsetops.3c +sigfillset.3c := SOSRC = man3c/sigsetops.3c +sigismember.3c := SOSRC = man3c/sigsetops.3c + +sigtimedwait.3c := SOSRC = man3c/sigwaitinfo.3c + +gsignal.3c := SOSRC = man3c/ssignal.3c + +sig2str.3c := SOSRC = man3c/str2sig.3c + +strerror_r.3c := SOSRC = man3c/strerror.3c + +ascftime.3c := SOSRC = man3c/strftime.3c +cftime.3c := SOSRC = man3c/strftime.3c + +strcasecmp.3c := SOSRC = man3c/string.3c +strcat.3c := SOSRC = man3c/string.3c +strchr.3c := SOSRC = man3c/string.3c +strcmp.3c := SOSRC = man3c/string.3c +strcpy.3c := SOSRC = man3c/string.3c +strcspn.3c := SOSRC = man3c/string.3c +strdup.3c := SOSRC = man3c/string.3c +strlcat.3c := SOSRC = man3c/string.3c +strlcpy.3c := SOSRC = man3c/string.3c +strlen.3c := SOSRC = man3c/string.3c +strncasecmp.3c := SOSRC = man3c/string.3c +strncat.3c := SOSRC = man3c/string.3c +strncmp.3c := SOSRC = man3c/string.3c +strncpy.3c := SOSRC = man3c/string.3c +strnlen.3c := SOSRC = man3c/string.3c +strpbrk.3c := SOSRC = man3c/string.3c +strrchr.3c := SOSRC = man3c/string.3c +strsep.3c := SOSRC = man3c/string.3c +strspn.3c := SOSRC = man3c/string.3c +strstr.3c := SOSRC = man3c/string.3c +strtok.3c := SOSRC = man3c/string.3c +strtok_r.3c := SOSRC = man3c/string.3c + +file_to_decimal.3c := SOSRC = man3c/string_to_decimal.3c +func_to_decimal.3c := SOSRC = man3c/string_to_decimal.3c + +atof.3c := SOSRC = man3c/strtod.3c +strtof.3c := SOSRC = man3c/strtod.3c +strtold.3c := SOSRC = man3c/strtod.3c + +strtoumax.3c := SOSRC = man3c/strtoimax.3c + +atoi.3c := SOSRC = man3c/strtol.3c +atol.3c := SOSRC = man3c/strtol.3c +atoll.3c := SOSRC = man3c/strtol.3c +lltostr.3c := SOSRC = man3c/strtol.3c +strtoll.3c := SOSRC = man3c/strtol.3c +ulltostr.3c := SOSRC = man3c/strtol.3c + +strtoull.3c := SOSRC = man3c/strtoul.3c +wstostr.3c := SOSRC = man3c/strtows.3c + +closelog.3c := SOSRC = man3c/syslog.3c +openlog.3c := SOSRC = man3c/syslog.3c +setlogmask.3c := SOSRC = man3c/syslog.3c + +thr_setconcurrency.3c := SOSRC = man3c/thr_getconcurrency.3c + +thr_setprio.3c := SOSRC = man3c/thr_getprio.3c + +thr_getspecific.3c := SOSRC = man3c/thr_keycreate.3c +thr_keycreate_once.3c := SOSRC = man3c/thr_keycreate.3c +thr_setspecific.3c := SOSRC = man3c/thr_keycreate.3c + +thr_continue.3c := SOSRC = man3c/thr_suspend.3c + +timer_getoverrun.3c := SOSRC = man3c/timer_settime.3c +timer_gettime.3c := SOSRC = man3c/timer_settime.3c + +timerclear.3c := SOSRC = man3c/timeradd.3c +timercmp.3c := SOSRC = man3c/timeradd.3c +timerisset.3c := SOSRC = man3c/timeradd.3c +timersub.3c := SOSRC = man3c/timeradd.3c + +tempnam.3c := SOSRC = man3c/tmpnam.3c +tmpnam_r.3c := SOSRC = man3c/tmpnam.3c + +ftruncate.3c := SOSRC = man3c/truncate.3c + +tdelete.3c := SOSRC = man3c/tsearch.3c +tfind.3c := SOSRC = man3c/tsearch.3c +twalk.3c := SOSRC = man3c/tsearch.3c + +ttyname_r.3c := SOSRC = man3c/ttyname.3c + +uconv_u16tou8.3c := SOSRC = man3c/uconv_u16tou32.3c +uconv_u32tou16.3c := SOSRC = man3c/uconv_u16tou32.3c +uconv_u32tou8.3c := SOSRC = man3c/uconv_u16tou32.3c +uconv_u8tou16.3c := SOSRC = man3c/uconv_u16tou32.3c +uconv_u8tou32.3c := SOSRC = man3c/uconv_u16tou32.3c + +ucred_free.3c := SOSRC = man3c/ucred_get.3c +ucred_getegid.3c := SOSRC = man3c/ucred_get.3c +ucred_geteuid.3c := SOSRC = man3c/ucred_get.3c +ucred_getgroups.3c := SOSRC = man3c/ucred_get.3c +ucred_getlabel.3c := SOSRC = man3c/ucred_get.3c +ucred_getpflags.3c := SOSRC = man3c/ucred_get.3c +ucred_getpid.3c := SOSRC = man3c/ucred_get.3c +ucred_getprivset.3c := SOSRC = man3c/ucred_get.3c +ucred_getprojid.3c := SOSRC = man3c/ucred_get.3c +ucred_getrgid.3c := SOSRC = man3c/ucred_get.3c +ucred_getruid.3c := SOSRC = man3c/ucred_get.3c +ucred_getsgid.3c := SOSRC = man3c/ucred_get.3c +ucred_getsuid.3c := SOSRC = man3c/ucred_get.3c +ucred_getzoneid.3c := SOSRC = man3c/ucred_get.3c +ucred_size.3c := SOSRC = man3c/ucred_get.3c + +vswprintf.3c := SOSRC = man3c/vfwprintf.3c +vwprintf.3c := SOSRC = man3c/vfwprintf.3c + +vasprintf.3c := SOSRC = man3c/vprintf.3c +vfprintf.3c := SOSRC = man3c/vprintf.3c +vsnprintf.3c := SOSRC = man3c/vprintf.3c +vsprintf.3c := SOSRC = man3c/vprintf.3c + +wait4.3c := SOSRC = man3c/wait3.3c + +addrtosymstr.3c := SOSRC = man3c/walkcontext.3c +backtrace.3c := SOSRC = man3c/walkcontext.3c +backtrace_symbols.3c := SOSRC = man3c/walkcontext.3c +backtrace_symbols_fd.3c := SOSRC = man3c/walkcontext.3c +printstack.3c := SOSRC = man3c/walkcontext.3c + +wscoll.3c := SOSRC = man3c/wcscoll.3c + +watof.3c := SOSRC = man3c/wcstod.3c +wcstof.3c := SOSRC = man3c/wcstod.3c +wcstold.3c := SOSRC = man3c/wcstod.3c +wstod.3c := SOSRC = man3c/wcstod.3c + +wcstoumax.3c := SOSRC = man3c/wcstoimax.3c + +watoi.3c := SOSRC = man3c/wcstol.3c +watol.3c := SOSRC = man3c/wcstol.3c +watoll.3c := SOSRC = man3c/wcstol.3c +wcstoll.3c := SOSRC = man3c/wcstol.3c +wstol.3c := SOSRC = man3c/wcstol.3c + +wcstoull.3c := SOSRC = man3c/wcstoul.3c + +wcscat.3c := SOSRC = man3c/wcstring.3c +wcschr.3c := SOSRC = man3c/wcstring.3c +wcscmp.3c := SOSRC = man3c/wcstring.3c +wcscpy.3c := SOSRC = man3c/wcstring.3c +wcscspn.3c := SOSRC = man3c/wcstring.3c +wcslen.3c := SOSRC = man3c/wcstring.3c +wcsncat.3c := SOSRC = man3c/wcstring.3c +wcsncmp.3c := SOSRC = man3c/wcstring.3c +wcsncpy.3c := SOSRC = man3c/wcstring.3c +wcspbrk.3c := SOSRC = man3c/wcstring.3c +wcsrchr.3c := SOSRC = man3c/wcstring.3c +wcsspn.3c := SOSRC = man3c/wcstring.3c +wcstok.3c := SOSRC = man3c/wcstring.3c +wcswcs.3c := SOSRC = man3c/wcstring.3c +windex.3c := SOSRC = man3c/wcstring.3c +wrindex.3c := SOSRC = man3c/wcstring.3c +wscat.3c := SOSRC = man3c/wcstring.3c +wschr.3c := SOSRC = man3c/wcstring.3c +wscmp.3c := SOSRC = man3c/wcstring.3c +wscpy.3c := SOSRC = man3c/wcstring.3c +wscspn.3c := SOSRC = man3c/wcstring.3c +wslen.3c := SOSRC = man3c/wcstring.3c +wsncat.3c := SOSRC = man3c/wcstring.3c +wsncmp.3c := SOSRC = man3c/wcstring.3c +wsncpy.3c := SOSRC = man3c/wcstring.3c +wspbrk.3c := SOSRC = man3c/wcstring.3c +wsrchr.3c := SOSRC = man3c/wcstring.3c +wsspn.3c := SOSRC = man3c/wcstring.3c +wstok.3c := SOSRC = man3c/wcstring.3c + +wsxfrm.3c := SOSRC = man3c/wcsxfrm.3c + +wordfree.3c := SOSRC = man3c/wordexp.3c + +wscasecmp.3c := SOSRC = man3c/wstring.3c +wscol.3c := SOSRC = man3c/wstring.3c +wsdup.3c := SOSRC = man3c/wstring.3c +wsncasecmp.3c := SOSRC = man3c/wstring.3c + +.KEEP_STATE: + +include ../Makefile.man + +install: $(ROOTMANFILES) + + diff --git a/usr/src/man/man3c/__fbufsize.3c b/usr/src/man/man3c/__fbufsize.3c new file mode 100644 index 0000000000..c1193b58f4 --- /dev/null +++ b/usr/src/man/man3c/__fbufsize.3c @@ -0,0 +1,175 @@ +'\" te +.\" Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH __fbufsize 3C "5 Feb 1998" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +__fbufsize, __flbf, __fpending, __fpurge, __freadable, __freading, +__fsetlocking, __fwritable, __fwriting, _flushlbf \- interfaces to stdio FILE +structure +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> +#include <stdio_ext.h> + +\fBsize_t\fR \fB__fbufsiz\fR(\fBFILE *\fR\fIstream\fR); +.fi + +.LP +.nf +\fBint\fR \fB__flbf\fR(\fBFILE *\fR\fIstream\fR); +.fi + +.LP +.nf +\fBsize_t\fR \fB__fpending\fR(\fBFILE *\fR\fIstream\fR); +.fi + +.LP +.nf +\fBvoid\fR \fB__fpurge\fR(\fBFILE *\fR\fIstream\fR); +.fi + +.LP +.nf +\fBint\fR \fB__freadable\fR(\fBFILE *\fR\fIstream\fR); +.fi + +.LP +.nf +\fBint\fR \fB__freading\fR(\fBFILE *\fR\fIstream\fR); +.fi + +.LP +.nf +\fBint\fR \fB__fsetlocking\fR(\fBFILE *\fR\fIstream\fR, \fBint\fR \fItype\fR); +.fi + +.LP +.nf +\fBint\fR \fB__fwritable\fR(\fBFILE *\fR\fIstream\fR); +.fi + +.LP +.nf +\fBint\fR \fB__fwriting\fR(\fBFILE *\fR\fIstream\fR); +.fi + +.LP +.nf +\fBvoid\fR \fB_flushlbf\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions provide portable access to the members of the \fBstdio\fR(3C) +\fBFILE\fR structure. +.sp +.LP +The \fB__fbufsize()\fR function returns in bytes the size of the buffer +currently in use by the given stream. +.sp +.LP +The \fB__flbf()\fR function returns non-zero if the stream is line-buffered. +.sp +.LP +The \fB__fpending\fR function returns in bytes the amount of output pending on +a stream. +.sp +.LP +The \fB__fpurge()\fR function discards any pending buffered I/O on the stream. +.sp +.LP +The \fB__freadable()\fR function returns non-zero if it is possible to read +from a stream. +.sp +.LP +The \fB__freading()\fR function returns non-zero if the file is open readonly, +or if the last operation on the stream was a read operation such as +\fBfread\fR(3C) or \fBfgetc\fR(3C). Otherwise it returns 0. +.sp +.LP +The \fB__fsetlocking()\fR function allows the type of locking performed by +\fBstdio\fR on a given stream to be controlled by the programmer. +.sp +.LP +If \fItype\fR is \fBFSETLOCKING_INTERNAL\fR, \fBstdio\fR performs implicit +locking around every operation on the given stream. This is the default system +behavior on that stream. +.sp +.LP +If \fItype\fR is \fBFSETLOCKING_BYCALLER\fR, \fBstdio\fR assumes that the +caller is responsible for maintaining the integrity of the stream in the face +of access by multiple threads. If there is only one thread accessing the +stream, nothing further needs to be done. If multiple threads are accessing +the stream, then the caller can use the \fBflockfile()\fR, \fBfunlockfile()\fR, +and \fBftrylockfile()\fR functions described on the \fBflockfile\fR(3C) manual +page to provide the appropriate locking. In both this and the case where +\fItype\fR is \fBFSETLOCKING_INTERNAL\fR, \fB__fsetlocking()\fR returns the +previous state of the stream. +.sp +.LP +If \fItype\fR is \fBFSETLOCKING_QUERY\fR, \fB__fsetlocking()\fR returns the +current state of the stream without changing it. +.sp +.LP +The \fB__fwritable()\fR function returns non-zero if it is possible to write on +a stream. +.sp +.LP +The \fB__fwriting()\fR function returns non-zero if the file is open write-only +or append-only, or if the last operation on the stream was a write operation +such as \fBfwrite\fR(3C) or \fBfputc\fR(3C). Otherwise it returns 0. +.sp +.LP +The \fB_flushlbf()\fR function flushes all line-buffered files. It is used +when reading from a line-buffered file. +.SH USAGE +.sp +.LP +Although the contents of the \fBstdio FILE\fR structure have always been +private to the \fBstdio\fR implementation, some applications have needed to +obtain information about a \fBstdio\fR stream that was not accessible through a +supported interface. These applications have resorted to accessing fields of +the \fBFILE\fR structure directly, rendering them possibly non-portable to new +implementations of \fBstdio\fR, or more likely, preventing enhancements to +\fBstdio\fR that would cause those applications to break. +.sp +.LP +In the 64-bit environment, the \fBFILE\fR structure is opaque. The functions +described here are provided as a means of obtaining the information that up to +now has been retrieved directly from the \fBFILE\fR structure. Because they +are based on the needs of existing applications (such as \fBmh\fR and +\fBemacs\fR), they may be extended as other programs are ported. Although they +may still be non-portable to other operating systems, they will be compatible +from each Solaris release to the next. Interfaces that are more portable are +under development. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelT{ +\fB__fsetlocking()\fR is Unsafe; all others are MT-Safe +T} +_ +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBfgetc\fR(3C), \fBflockfile\fR(3C), \fBfputc\fR(3C), \fBfread\fR(3C), +\fBfwrite\fR(3C), \fBstdio\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/_longjmp.3c b/usr/src/man/man3c/_longjmp.3c new file mode 100644 index 0000000000..75c81cf4c6 --- /dev/null +++ b/usr/src/man/man3c/_longjmp.3c @@ -0,0 +1,92 @@ +'\" te +.\" Copyright (c) 1994, X/Open Company Limited. All Rights Reserved. +.\" Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH _longjmp 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +_longjmp, _setjmp \- non-local goto +.SH SYNOPSIS +.LP +.nf +#include <setjmp.h> + +\fBvoid\fR \fB_longjmp\fR(\fBjmp_buf\fR \fIenv\fR, \fBint\fR \fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fB_setjmp\fR(\fBjmp_buf\fR \fIenv\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fB_longjmp()\fR and \fB_setjmp()\fR functions are identical to +\fBlongjmp\fR(3C) and \fBsetjmp\fR(3C), respectively, with the additional +restriction that \fB_longjmp()\fR and \fB_setjmp()\fR do not manipulate the +signal mask. +.sp +.LP +If \fB_longjmp()\fR is called even though \fBenv\fR was never initialized by a +call to \fB_setjmp()\fR, or when the last such call was in a function that has +since returned, the results are undefined. +.SH RETURN VALUES +.sp +.LP +Refer to \fBlongjmp\fR(3C) and \fBsetjmp\fR(3C). +.SH ERRORS +.sp +.LP +No errors are defined. +.SH USAGE +.sp +.LP +If \fB_longjmp()\fR is executed and the environment in which \fB_setjmp()\fR +was executed no longer exists, errors can occur. The conditions under which the +environment of the \fB_setjmp()\fR no longer exists include exiting the +function that contains the \fB_setjmp()\fR call, and exiting an inner block +with temporary storage. This condition might not be detectable, in which case +the \fB_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. +.sp +.LP +Passing \fBlongjmp()\fR a pointer to a buffer not created by \fBsetjmp(\|),\fR +passing \fB_longjmp()\fR a pointer to a buffer not created by \fB_setjmp()\fR, +passing \fBsiglongjmp\fR(3C) a pointer to a buffer not created by +\fBsigsetjmp\fR(3C) 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. +.sp +.LP +The \fB_longjmp()\fR and \fB_setjmp()\fR functions are included to support +programs written to historical system interfaces. New applications should use +\fBsiglongjmp\fR(3C) and \fBsigsetjmp\fR(3C) respectively. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityStandard +.TE + +.SH SEE ALSO +.sp +.LP +\fBlongjmp\fR(3C), \fBsetjmp\fR(3C), \fBsiglongjmp\fR(3C), \fBsigsetjmp\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/_stack_grow.3c b/usr/src/man/man3c/_stack_grow.3c new file mode 100644 index 0000000000..68bd632800 --- /dev/null +++ b/usr/src/man/man3c/_stack_grow.3c @@ -0,0 +1,86 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH _stack_grow 3C "18 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +_stack_grow \- express an intention to extend the stack +.SH SYNOPSIS +.LP +.nf +#include <ucontext.h> + +\fBvoid *\fR\fB_stack_grow\fR(\fBvoid *\fR\fIaddr\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fB_stack_grow()\fR function indicates to the system that the stack is +about to be extended to the address specified by \fIaddr\fR. If extending the +stack to this address would violate the stack boundaries as retreived by +\fBstack_getbounds\fR(3C), a \fBSIGSEGV\fR is raised. +.sp +.LP +If the disposition of \fBSIGSEGV\fR is \fBSIG_DFL\fR, the process is terminated +and a core dump is generated. If the application has installed its own +\fBSIGSEGV\fR handler to run on the alternate signal stack, the signal +information passed to the handler will be such that a call to +\fBstack_violation\fR(3C) with these parameters returns 1. +.sp +.LP +The \fIaddr\fR argument is a biased stack pointer value. See the Solaris 64-bit +Developer's Guide. +.sp +.LP +This function has no effect if the specified address, \fIaddr\fR, is within the +bounds of the current stack. +.SH RETURN VALUES +.sp +.LP +If the \fB_stack_grow()\fR function succeeds and does not detect a stack +violation, it returns \fIaddr\fR. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH USAGE +.sp +.LP +The \fB_stack_grow()\fR function does not actually adjust the stack pointer +register. The caller is responsible for manipulating the stack pointer register +once \fB_stack_grow()\fR returns. +.sp +.LP +The \fB_stack_grow()\fR function is typically invoked by code created by the +compilation environment prior to executing code that modifies the stack +pointer. It can also be used by hand-written assembly routines to allocate +stack-based storage safely. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelAsync-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBstack_getbounds\fR(3C), \fBstack_inbounds\fR(3C), \fBstack_violation\fR(3C), +\fBattributes\fR(5) +.sp +.LP +Solaris 64-bit Developer's Guide diff --git a/usr/src/man/man3c/a64l.3c b/usr/src/man/man3c/a64l.3c new file mode 100644 index 0000000000..d469aeecb2 --- /dev/null +++ b/usr/src/man/man3c/a64l.3c @@ -0,0 +1,92 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH a64l 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +a64l, l64a \- convert between long integer and base-64 ASCII string +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBlong\fR \fBa64l\fR(\fBconst char *\fR\fIs\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBl64a\fR(\fBlong\fR \fIl\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions maintain numbers stored in base-64 \fBASCII\fR characters that +define a notation by which long integers can be represented by up to six +characters. Each character represents a "digit" in a radix-64 notation. +.sp +.LP +The characters used to represent "digits" are as follows: +.sp + +.sp +.TS +tab() box; +lw(2.76i) |lw(2.74i) +lw(2.76i) |lw(2.74i) +. +CharacterDigit +_ +\fB\&.\fR\fB0\fR +\fB/\fR\fB1\fR +\fB0-9\fR\fB2-11\fR +\fBA-Z\fR\fB12-37\fR +\fBa-z\fR\fB38-63\fR +.TE + +.sp +.LP +The \fBa64l()\fR function takes a pointer to a null-terminated base-64 +representation and returns a corresponding \fBlong\fR value. If the string +pointed to by \fIs\fR contains more than six characters, \fBa64l()\fR uses the +first six. +.sp +.LP +The \fBa64l()\fR function scans 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. +.sp +.LP +The \fBl64a()\fR function takes a \fBlong\fR argument and returns a pointer to +the corresponding base-64 representation. If the argument is 0, \fBl64a()\fR +returns a pointer to a null string. +.sp +.LP +The value returned by \fBl64a()\fR is a pointer into a static buffer, the +contents of which are overwritten by each call. In the case of multithreaded +applications, the return value is a pointer to thread specific data. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/abort.3c b/usr/src/man/man3c/abort.3c new file mode 100644 index 0000000000..a55011fed6 --- /dev/null +++ b/usr/src/man/man3c/abort.3c @@ -0,0 +1,72 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH abort 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +abort \- terminate the process abnormally +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBvoid\fR \fBabort\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBabort()\fR function causes abnormal process termination to occur, unless +the signal \fBSIGABRT\fR is being caught and the signal handler does not +return. The abnormal termination processing includes at least the effect of +\fBfclose\fR(3C) on all open streams and message catalogue descriptors, and the +default actions defined for \fBSIGABRT\fR. The \fBSIGABRT\fR signal is sent to +the calling process as if by means of the \fBraise\fR(3C) function with the +argument \fBSIGABRT\fR. +.sp +.LP +The status made available to \fBwait\fR(3C) or \fBwaitpid\fR(3C) by +\fBabort\fR will be that of a process terminated by the \fBSIGABRT\fR signal. +\fBabort\fR will override blocking or ignoring the \fBSIGABRT\fR signal. +.SH RETURN VALUES +.sp +.LP +The \fBabort()\fR function does not return. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH USAGE +.sp +.LP +Catching the signal is intended to provide the application writer with a +portable means to abort processing, free from possible interference from any +implementation-provided library functions. If \fBSIGABRT\fR is neither caught +nor ignored, and the current directory is writable, a core dump may be +produced. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBexit\fR(2), \fBgetrlimit\fR(2), \fBkill\fR(2), \fBfclose\fR(3C), +\fBraise\fR(3C), \fBsignal\fR(3C), \fBwait\fR(3C), \fBwaitpid\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/abs.3c b/usr/src/man/man3c/abs.3c new file mode 100644 index 0000000000..1754096315 --- /dev/null +++ b/usr/src/man/man3c/abs.3c @@ -0,0 +1,65 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH abs 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +abs, labs, llabs \- return absolute value of integer +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBint\fR \fBabs\fR(\fBint\fR \fIval\fR); +.fi + +.LP +.nf +\fBlong\fR \fBlabs\fR(\fBlong\fR \fIlval\fR); +.fi + +.LP +.nf +\fBlong long\fR \fBllabs\fR(\fBlong long\fR \fIllval\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBabs()\fR function returns the absolute value of its \fBint\fR operand. +.sp +.LP +The \fBlabs()\fR function returns the absolute value of its \fBlong\fR operand. +.sp +.LP +The \fBllabs()\fR function returns the absolute value of its \fBlong long\fR +operand. +.SH USAGE +.sp +.LP +In 2's-complement representation, the absolute value of the largest magnitude +negative integral value is undefined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/addsev.3c b/usr/src/man/man3c/addsev.3c new file mode 100644 index 0000000000..84ee6c87a5 --- /dev/null +++ b/usr/src/man/man3c/addsev.3c @@ -0,0 +1,91 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH addsev 3C "29 Dec 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +addsev \- define additional severities +.SH SYNOPSIS +.LP +.nf +#include <pfmt.h> + +\fBint\fR \fBaddsev\fR(\fBint\fR \fIint_val\fR, \fBconst char *\fR\fIstring\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBaddsev()\fR function defines additional severities for use in subsequent +calls to \fBpfmt\fR(3C) or \fBlfmt\fR(3C). It associates an integer value +\fIint_val\fR in the range [5-255] with a character \fIstring\fR, overwriting +any previous string association between \fIint_val\fR and \fIstring\fR. +.sp +.LP +If \fIint_val\fR is OR-ed with the \fIflags\fR argument passed to subsequent +calls to \fBpfmt()\fR or \fBlfmt()\fR, \fIstring\fR will be used as severity. +Passing a null \fIstring\fR removes the severity. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBaddsev()\fR returns \fB0\fR. Otherwise it +returns\fB\(mi1\fR\&. +.SH USAGE +.sp +.LP +Only the standard severities are automatically displayed for the locale in +effect at runtime. An application must provide the means for displaying +locale-specific versions of add-on severities. Add-on severities are only +effective within the applications defining them. +.SH EXAMPLES +.LP +\fBExample 1 \fRExample of \fBaddsev()\fR function. +.sp +.LP +The following example + +.sp +.in +2 +.nf +#define Panic 5 +setlabel("APPL"); +setcat("my_appl"); +addsev(Panic, gettxt(":26", "PANIC")); +/* .\|.\|. */ +lfmt(stderr, MM_SOFT|MM_APPL|PANIC, ":12:Cannot locate database\en"); +.fi +.in -2 + +.sp +.LP +will display the message to \fIstderr\fR and forward to the logging service + +.sp +.in +2 +.nf +APPL: PANIC: Cannot locate database +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgettxt\fR(3C), \fBlfmt\fR(3C), \fBpfmt\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/addseverity.3c b/usr/src/man/man3c/addseverity.3c new file mode 100644 index 0000000000..dd7b92f3d8 --- /dev/null +++ b/usr/src/man/man3c/addseverity.3c @@ -0,0 +1,167 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH addseverity 3C "29 Dec 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +addseverity \- build a list of severity levels for an application for use with +fmtmsg +.SH SYNOPSIS +.LP +.nf +#include <fmtmsg.h> + +\fBint\fR \fBaddseverity\fR(\fBint\fR \fIseverity\fR, \fBconst char *\fR\fIstring\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBaddseverity()\fR function builds a list of severity levels for an +application to be used with the message formatting facility \fBfmtmsg()\fR. The +\fIseverity\fR argument is an integer value indicating the seriousness of the +condition. The \fIstring\fR argument is a pointer to a string describing the +condition (string is not limited to a specific size). +.sp +.LP +If \fBaddseverity()\fR is called with an integer value that has not been +previously defined, the function adds that new severity value and print string +to the existing set of standard severity levels. +.sp +.LP +If \fBaddseverity()\fR is called with an integer value that has been previously +defined, the function redefines that value with the new print string. +Previously defined severity levels may be removed by supplying the null string. +If \fBaddseverity()\fR is called with a negative number or an integer value of +0, 1, 2, 3, or 4, the function fails and returns \fB\(mi1\fR\&. The values +0\(mi4 are reserved for the standard severity levels and cannot be modified. +Identifiers for the standard levels of severity are: +.sp +.ne 2 +.mk +.na +\fB\fBMM_HALT\fR\fR +.ad +.RS 14n +.rt +Indicates that the application has encountered a severe fault and is halting. +Produces the print string \fBHALT\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMM_ERROR\fR\fR +.ad +.RS 14n +.rt +Indicates that the application has detected a fault. Produces the print string +\fBERROR\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMM_WARNING\fR\fR +.ad +.RS 14n +.rt +Indicates a condition that is out of the ordinary, that might be a problem, and +should be watched. Produces the print string \fBWARNING\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMM_INFO\fR\fR +.ad +.RS 14n +.rt +Provides information about a condition that is not in error. Produces the print +string \fBINFO\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMM_NOSEV\fR\fR +.ad +.RS 14n +.rt +Indicates that no severity level is supplied for the message. +.RE + +.sp +.LP +Severity levels may also be defined at run time using the \fBSEV_LEVEL\fR +environment variable (see \fBfmtmsg\fR(3C)). +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBaddseverity()\fR returns \fBMM_OK\fR. Otherwise +it returns \fBMM_NOTOK\fR. +.SH EXAMPLES +.LP +\fBExample 1 \fRExample of \fBaddseverity()\fR function. +.sp +.LP +When the function call + +.sp +.in +2 +.nf +addseverity(7,"ALERT") +.fi +.in -2 + +.sp +.LP +is followed by the call + +.sp +.in +2 +.nf +fmtmsg(MM_PRINT, "UX:cat", 7, "invalid syntax", "refer to manual", +"UX:cat:001") +.fi +.in -2 + +.sp +.LP +the resulting output is + +.sp +.in +2 +.nf +UX:cat: ALERT: invalid syntax +TO FIX: refer to manual UX:cat:001 +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfmtmsg\fR(1), \fBfmtmsg\fR(3C), \fBgettxt\fR(3C), \fBprintf\fR(3C), +\fBattributes\fR(5) diff --git a/usr/src/man/man3c/aio_cancel.3c b/usr/src/man/man3c/aio_cancel.3c new file mode 100644 index 0000000000..6af566d54f --- /dev/null +++ b/usr/src/man/man3c/aio_cancel.3c @@ -0,0 +1,124 @@ +'\" te +.\" Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH aio_cancel 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +aio_cancel \- cancel asynchronous I/O request +.SH SYNOPSIS +.LP +.nf +#include <aio.h> + +\fBint\fR \fBaio_cancel\fR(\fBint\fR \fIfildes\fR, \fBstruct aiocb *\fR\fIaiocbp\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBaio_cancel()\fR function attempts to cancel one or more asynchronous I/O +requests currently outstanding against file descriptor \fIfildes\fR. The +\fIaiocbp\fR argument points to the asynchronous I/O control block for a +particular request to be canceled. If \fIaiocbp\fR is \fINULL\fR, then all +outstanding cancelable asynchronous I/O requests against \fIfildes\fR are +canceled. +.sp +.LP +Normal asynchronous notification occurs for asynchronous I/O operations that +are successfully canceled. If there are requests that cannot be canceled, then +the normal asynchronous completion process takes place for those requests when +they are completed. +.sp +.LP +For requested operations that are successfully canceled, the associated error +status is set to \fBECANCELED\fR and the return status is \fB\(mi1\fR\&. For +requested operations that are not successfully canceled, the \fIaiocbp\fR is +not modified by \fBaio_cancel()\fR. +.sp +.LP +If \fIaiocbp\fR is not \fINULL\fR, then if \fIfildes\fR does not have the same +value as the file descriptor with which the asynchronous operation was +initiated, unspecified results occur. +.SH RETURN VALUES +.sp +.LP +The \fBaio_cancel()\fR function returns the value \fBAIO_CANCELED\fR to the +calling process if the requested operation(s) were canceled. The value +\fBAIO_NOTCANCELED\fR is 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 \fBaio_cancel()\fR is not +indicated by the return value of \fBaio_cancel()\fR. The application may +determine the state of affairs for these operations by using +\fBaio_error\fR(3C). The value \fBAIO_ALLDONE\fR is returned if all of the +operations have already completed. Otherwise, the function returns \fB\(mi1\fR +and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBaio_cancel()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIfildes\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR\fR +.ad +.RS 10n +.rt +The \fBaio_cancel()\fR function is not supported. +.RE + +.SH USAGE +.sp +.LP +The \fBaio_cancel()\fR function has a transitional interface for 64-bit file +offsets. See \fBlf64\fR(5). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBaio.h\fR(3HEAD), \fBsignal.h\fR(3HEAD), \fBaio_read\fR(3C), +\fBaio_return\fR(3C), \fBattributes\fR(5), \fBlf64\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +Solaris 2.6 was the first release to support the Asynchronous Input and Output +option. Prior to this release, this function always returned \fB\(mi1\fR and +set \fBerrno\fR to \fBENOSYS\fR. diff --git a/usr/src/man/man3c/aio_error.3c b/usr/src/man/man3c/aio_error.3c new file mode 100644 index 0000000000..e8f776c152 --- /dev/null +++ b/usr/src/man/man3c/aio_error.3c @@ -0,0 +1,132 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH aio_error 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +aio_error \- retrieve errors status for an asynchronous I/O operation +.SH SYNOPSIS +.LP +.nf +#include <aio.h> + +\fBint\fR \fBaio_error\fR(\fBconst struct aiocb *\fR\fIaiocbp\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBaio_error()\fR function returns the error status associated with the +\fBaiocb\fR structure referenced by the \fIaiocbp\fR argument. The error status +for an asynchronous I/O operation is the \fBerrno\fR value that would be set by +the corresponding \fBread\fR(2), \fBwrite\fR(2), or \fBfsync\fR(3C) operation. +If the operation has not yet completed, then the error status will be equal to +\fBEINPROGRESS\fR. +.SH RETURN VALUES +.sp +.LP +If the asynchronous I/O operation has completed successfully, then \fB0\fR is +returned. If the asynchronous operation has completed unsuccessfully, then the +error status, as described for \fBread\fR(2), \fBwrite\fR(2), and +\fBfsync\fR(3C), is returned. If the asynchronous I/O operation has not yet +completed, then \fBEINPROGRESS\fR is returned. +.SH ERRORS +.sp +.LP +The \fBaio_error()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIaiocbp\fR argument does not refer to an asynchronous operation whose +return status has not yet been retrieved. +.RE + +.SH USAGE +.sp +.LP +The \fBaio_error()\fR function has a transitional interface for 64-bit file +offsets. See \fBlf64\fR(5). +.SH EXAMPLES +.LP +\fBExample 1 \fRThe following is an example of an error handling routine using +the \fBaio_error()\fR function. +.sp +.in +2 +.nf +#include <aio.h> +#include <errno.h> +#include <signal.h> +struct aiocb my_aiocb; +struct sigaction my_sigaction; +void my_aio_handler(int, siginfo_t *, void *); +\|.\|.\|. +my_sigaction.sa_flags = SA_SIGINFO; +my_sigaction.sa_sigaction = my_aio_handler; +sigemptyset(&my_sigaction.sa_mask); +(void) sigaction(SIGRTMIN, &my_sigaction, NULL); +\|.\|.\|. +my_aiocb.aio_sigevent.sigev_notify = SIGEV_SIGNAL; +my_aiocb.aio_sigevent.sigev_signo = SIGRTMIN; +my_aiocb.aio_sigevent.sigev_value.sival_ptr = &myaiocb; +\|.\|.\|. +(void) aio_read(&my_aiocb); +\|.\|.\|. +void +my_aio_handler(int signo, siginfo_t *siginfo, void *context) { +int my_errno; +struct aiocb *my_aiocbp; + +my_aiocbp = siginfo->si_value.sival_ptr; + if ((my_errno = aio_error(my_aiocb)) != EINPROGRESS) { + int my_status = aio_return(my_aiocb); + if (my_status >= 0){ /* start another operation */ + \|.\|.\|. + } else { /* handle I/O error */ + \|.\|.\|. + } + } +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelAsync-Signal-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fB_Exit\fR(2), \fBclose\fR(2), \fBfork\fR(2), \fBlseek\fR(2), \fBread\fR(2), +\fBwrite\fR(2), \fBaio.h\fR(3HEAD), \fBaio_cancel\fR(3C), \fBaio_fsync\fR(3C), +\fBaio_read\fR(3C), \fBaio_return\fR(3C), \fBaio_write\fR(3C), +\fBlio_listio\fR(3C), \fBsignal.h\fR(3HEAD), \fBattributes\fR(5), +\fBlf64\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/aio_fsync.3c b/usr/src/man/man3c/aio_fsync.3c new file mode 100644 index 0000000000..32ff99a68d --- /dev/null +++ b/usr/src/man/man3c/aio_fsync.3c @@ -0,0 +1,167 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH aio_fsync 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +aio_fsync \- asynchronous file synchronization +.SH SYNOPSIS +.LP +.nf +#include <aio.h> + +\fBint\fR \fBaio_fsync\fR(\fBint\fR \fIop\fR, \fBstruct aiocb *\fR\fIaiocbp\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBaio_fsync()\fR function asynchronously forces all I/O operations +associated with the file indicated by the file descriptor \fBaio_fildes\fR +member of the \fBaiocb\fR structure referenced by the \fIaiocbp\fR argument and +queued at the time of the call to \fBaio_fsync()\fR to the synchronized I/O +completion state. The function call returns when the synchronization request +has been initiated or queued to the file or device (even when the data cannot +be synchronized immediately). +.sp +.LP +If \fIop\fR is \fBO_DSYNC\fR, all currently queued I/O operations are completed +as if by a call to \fBfdatasync\fR(3C); that is, as defined for synchronized +I/O data integrity completion. If \fIop\fR is \fBO_SYNC\fR, all currently +queued I/O operations are completed as if by a call to \fBfsync\fR(3C); that +is, as defined for synchronized I/O file integrity completion. If the +\fBaio_fsync()\fR function fails, or if the operation queued by +\fBaio_fsync()\fR fails, then, as for \fBfsync\fR(3C) and \fBfdatasync\fR(3C), +outstanding I/O operations are not guaranteed to have been completed. +.sp +.LP +If \fBaio_fsync()\fR succeeds, then it is only the I/O that was queued at the +time of the call to \fBaio_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. +.sp +.LP +The \fIaiocbp\fR argument refers to an asynchronous I/O control block. The +\fIaiocbp\fR value may be used as an argument to \fBaio_error\fR(3C) and +\fBaio_return\fR(3C) 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 \fBEINPROGRESS.\fR +When all data has been successfully transferred, the error status will be reset +to reflect the success or failure of the operation. If the operation does not +complete successfully, the error status for the operation will be set to +indicate the error. The \fIaio_sigevent\fR member determines the asynchronous +notification to occur when all operations have achieved synchronized I/O +completion (see \fBsignal.h\fR(3HEAD)). All other members of the structure +referenced by \fIaiocbp\fR are ignored. If the control block referenced by +\fIaiocbp\fR becomes an illegal address prior to asynchronous I/O completion, +then the behavior is undefined. +.sp +.LP +If the \fBaio_fsync()\fR function fails or the \fIaiocbp\fR indicates an error +condition, data is not guaranteed to have been successfully transferred. +.sp +.LP +If \fIaiocbp\fR is \fINULL\fR, then no status is returned in \fIaiocbp\fR, and +no signal is generated upon completion of the operation. +.SH RETURN VALUES +.sp +.LP +The \fBaio_fsync()\fR function returns \fB0\fR to the calling process if the +I/O operation is successfully queued; otherwise, the function returns +\fB\(mi1\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBaio_fsync()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +The requested asynchronous operation was not queued due to temporary resource +limitations. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fBaio_fildes\fR member of the \fBaiocb\fR structure referenced by the +\fIaiocbp\fR argument is not a valid file descriptor open for writing. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The system does not support synchronized I/O for this file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +A value of \fIop\fR other than \fBO_DSYNC\fR or \fBO_SYNC\fR was specified. +.RE + +.sp +.LP +In the event that any of the queued I/O operations fail, \fBaio_fsync()\fR +returns the error condition defined for \fBread\fR(2) and \fBwrite\fR(2). The +error will be returned in the error status for the asynchronous \fBfsync\fR(3C) +operation, which can be retrieved using \fBaio_error\fR(3C). +.SH USAGE +.sp +.LP +The \fBaio_fsync()\fR function has a transitional interface for 64-bit file +offsets. See \fBlf64\fR(5). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBfcntl\fR(2), \fBopen\fR(2), \fBread\fR(2), \fBwrite\fR(2), +\fBaio_error\fR(3C), \fBaio_return\fR(3C), \fBaio.h\fR(3HEAD), +\fBfcntl.h\fR(3HEAD), \fBfdatasync\fR(3C), \fBfsync\fR(3C), +\fBsignal.h\fR(3HEAD), \fBattributes\fR(5), \fBlf64\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/aio_read.3c b/usr/src/man/man3c/aio_read.3c new file mode 100644 index 0000000000..cd5af78265 --- /dev/null +++ b/usr/src/man/man3c/aio_read.3c @@ -0,0 +1,231 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH aio_read 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +aio_read \- asynchronous read from a file +.SH SYNOPSIS +.LP +.nf +#include <aio.h> + +\fBint\fR \fBaio_read\fR(\fBstruct aiocb *\fR\fIaiocbp\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBaio_read()\fR function allows the calling process to read +\fIaiocbp\fR->\fBaio_nbytes\fR from the file associated with +\fIaiocbp\fR->\fBaio_fildes\fR into the buffer pointed to by +\fIaiocbp\fR->\fBaio_buf\fR. The function call returns when the read request +has been initiated or queued to the file or device (even when the data cannot +be delivered immediately). If \fB_POSIX_PRIORITIZED_IO\fR is defined and +prioritized I/O is supported for this file, then the asynchronous operation is +submitted at a priority equal to the scheduling priority of the process minus +\fIaiocbp\fR->\fBaio_reqprio\fR. The \fIaiocbp\fR value may be used as an +argument to \fBaio_error\fR(3C) and \fBaio_return\fR(3C) 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 returns without having initiated or queued the request. The +requested operation takes place at the absolute position in the file as given +by \fIaio_offset\fR, as if \fBlseek\fR(2) were called immediately prior to the +operation with an \fIoffset\fR equal to \fIaio_offset\fR and a \fBwhence\fR +equal to \fBSEEK_SET\fR. After a successful call to enqueue an asynchronous I/O +operation, the value of the file offset for the file is unspecified. +.sp +.LP +The \fIaiocbp\fR->\fBaio_sigevent\fR structure defines what asynchronous +notification is to occur when the asynchronous operation completes, as +specified in \fBsignal.h\fR(3HEAD). +.sp +.LP +The \fIaiocbp\fR->\fBaio_lio_opcode\fR field is ignored by \fBaio_read()\fR. +.sp +.LP +The \fIaiocbp\fR argument points to an \fBaiocb\fR structure. If the buffer +pointed to by \fIaiocbp\fR->\fBaio_buf\fR or the control block pointed to by +\fIaiocbp\fR becomes an illegal address prior to asynchronous I/O completion, +then the behavior is undefined. +.sp +.LP +Simultaneous asynchronous operations using the same \fIaiocbp\fR produce +undefined results. +.sp +.LP +If \fB_POSIX_SYNCHRONIZED_IO\fR is defined and synchronized I/O is enabled on +the file associated with \fIaiocbp\fR->\fBaio_fildes,\fR the behavior of this +function is according to the definitions of synchronized I/O data integrity +completion and synchronized I/O file integrity completion. +.sp +.LP +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. +.sp +.LP +For regular files, no data transfer will occur past the offset maximum +established in the open file description associated with +\fIaiocbp\fR->\fBaio_fildes\fR. +.SH RETURN VALUES +.sp +.LP +The \fBaio_read()\fR function returns \fB0\fR to the calling process if the I/O +operation is successfully queued; otherwise, the function returns \fB\(mi1\fR +and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBaio_read()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +The requested asynchronous I/O operation was not queued due to system resource +limitations. +.RE + +.sp +.LP +Each of the following conditions may be detected synchronously at the time of +the call to \fBaio_read()\fR, or asynchronously. If any of the conditions below +are detected synchronously, the \fBaio_read()\fR function returns \fB-1\fR and +sets \fBerrno\fR 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 will be set to the +corresponding value. +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIaiocbp\fR->\fBaio_fildes\fR argument is not a valid file descriptor open +for reading. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The file offset value implied by \fIaiocbp\fR->\fBaio_offset\fR would be +invalid, \fIaiocbp->\fR\fBaio_reqprio\fR is not a valid value, or +\fIaiocbp\fR->\fBaio_nbytes\fR is an invalid value. +.RE + +.sp +.LP +In the case that the \fBaio_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 \fBread\fR(2) function call. In addition, the error status of the +asynchronous operation will be set to one of the error statuses normally set by +the \fBread()\fR function call, or one of the following values: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 13n +.rt +The \fIaiocbp\fR->\fBaio_fildes\fR argument is not a valid file descriptor open +for reading. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBECANCELED\fR\fR +.ad +.RS 13n +.rt +The requested I/O was canceled before the I/O completed due to an explicit +\fBaio_cancel\fR(3C) request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 13n +.rt +The file offset value implied by \fIaiocbp\fR->\fBaio_offset\fR would be +invalid. +.RE + +.sp +.LP +The following condition may be detected synchronously or asynchronously: +.sp +.ne 2 +.mk +.na +\fB\fBEOVERFLOW\fR\fR +.ad +.RS 13n +.rt +The file is a regular file, \fIaiobcp\fR->\fBaio_nbytes\fR is greater than 0 +and the starting offset in \fIaiobcp\fR->\fBaio_offset\fR is before the +end-of-file and is at or beyond the offset maximum in the open file description +associated with \fIaiocbp\fR->\fBaio_fildes\fR. +.RE + +.SH USAGE +.sp +.LP +For portability, the application should set \fIaiocb->\fR\fBaio_reqprio\fR to +\fB0\fR. +.sp +.LP +The \fBaio_read()\fR function has a transitional interface for 64-bit file +offsets. See \fBlf64\fR(5). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBclose\fR(2), \fBexec\fR(2), \fBexit\fR(2), \fBfork\fR(2), \fBlseek\fR(2), +\fBread\fR(2), \fBwrite\fR(2), \fBaio_cancel\fR(3C), \fBaio_return\fR(3C), +\fBaio.h\fR(3HEAD), \fBlio_listio\fR(3C), \fBsiginfo.h\fR(3HEAD), +\fBsignal.h\fR(3HEAD), \fBattributes\fR(5), \fBlf64\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/aio_return.3c b/usr/src/man/man3c/aio_return.3c new file mode 100644 index 0000000000..2520fbb5dc --- /dev/null +++ b/usr/src/man/man3c/aio_return.3c @@ -0,0 +1,111 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH aio_return 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +aio_return \- retrieve return status of an asynchronous I/O operation +.SH SYNOPSIS +.LP +.nf +#include <aio.h> + +\fBssize_t\fR \fBaio_return\fR(\fBstruct aiocb *\fR\fIaiocbp\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBaio_return()\fR function returns the return status associated with the +\fBaiocb\fR structure referenced by the \fIaiocbp\fR argument. The return +status for an asynchronous I/O operation is the value that would be returned by +the corresponding \fBread\fR(2), \fBwrite\fR(2), or \fBfsync\fR(3C) function +call. If the error status for the operation is equal to \fBEINPROGRESS\fR, then +the return status for the operation is undefined. The \fBaio_return()\fR +function may be called exactly once to retrieve the return status of a given +asynchronous operation; thereafter, if the same \fBaiocb\fR structure is used +in a call to \fBaio_return()\fR or \fBaio_error\fR(3C), an error may be +returned. When the \fBaiocb\fR structure referred to by \fIaiocbp\fR is used to +submit another asynchronous operation, then \fBaio_return()\fR may be +successfully used to retrieve the return status of that operation. +.SH RETURN VALUES +.sp +.LP +If the asynchronous I/O operation has completed, then the return status, as +described for \fBread\fR(2), \fBwrite\fR(2), and \fBfsync\fR(3C), is returned. +If the asynchronous I/O operation has not yet completed, the results of +\fBaio_return()\fR are undefined. +.SH ERRORS +.sp +.LP +The \fBaio_return()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIaiocbp\fR argument does not refer to an asynchronous operation whose +return status has not yet been retrieved. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR\fR +.ad +.RS 10n +.rt +The \fBaio_return()\fR function is not supported by the system. +.RE + +.SH USAGE +.sp +.LP +The \fBaio_return()\fR function has a transitional interface for 64-bit file +offsets. See \fBlf64\fR(5). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityCommitted +_ +MT-LevelAsync-Signal-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBclose\fR(2), \fBexec\fR(2), \fBexit\fR(2), \fBfork\fR(2), \fBlseek\fR(2), +\fBread\fR(2), \fBwrite\fR(2), \fBfsync\fR(3C), \fBaio.h\fR(3HEAD), +\fBsignal.h\fR(3HEAD), \fBaio_cancel\fR(3C), \fBaio_fsync\fR(3C), +\fBaio_read\fR(3C), \fBlio_listio\fR(3C), \fBattributes\fR(5), \fBlf64\fR(5), +\fBstandards\fR(5) +.SH NOTES +.sp +.LP +Solaris 2.6 was the first release to support the Asynchronous Input and Output +option. Prior to this release, this function always returned \fB\(mi1\fR and +set \fBerrno\fR to \fBENOSYS\fR. diff --git a/usr/src/man/man3c/aio_suspend.3c b/usr/src/man/man3c/aio_suspend.3c new file mode 100644 index 0000000000..c568f48509 --- /dev/null +++ b/usr/src/man/man3c/aio_suspend.3c @@ -0,0 +1,163 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical +.\" and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH aio_suspend 3C "18 Dec 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +aio_suspend \- wait for asynchronous I/O request +.SH SYNOPSIS +.LP +.nf +#include <aio.h> + +\fBint\fR \fBaio_suspend\fR(\fBconst struct aiocb * const\fR \fIlist\fR[], \fBint\fR \fInent\fR, + \fBconst struct timespec *\fR\fItimeout\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBaio_suspend()\fR function suspends the calling thread until at least +one of the asynchronous I/O operations referenced by the \fIlist\fR argument +has completed, until a signal interrupts the function, or, if \fItimeout\fR is +not \fINULL\fR, until the time interval specified by \fItimeout\fR has passed. +If any of the \fBaiocb\fR structures in the list correspond to completed +asynchronous I/O operations (that is, the error status for the operation is not +equal to \fBEINPROGRESS\fR) at the time of the call, the function returns +without suspending the calling thread. The \fIlist\fR argument is an array of +pointers to asynchronous I/O control blocks. The \fInent\fR argument indicates +the number of elements in the array and is limited to \fB_AIO_LISTIO_MAX\fR = +4096. Each \fBaiocb\fR structure pointed to will have been used in initiating +an asynchronous I/O request via \fBaio_read\fR(3C), \fBaio_write\fR(3C), or +\fBlio_listio\fR(3C). This array may contain null pointers, which are ignored. +If this array contains pointers that refer to \fBaiocb\fR structures that have +not been used in submitting asynchronous I/O, the effect is undefined. +.sp +.LP +If the time interval indicated in the \fBtimespec\fR structure pointed to by +\fItimeout\fR passes before any of the I/O operations referenced by \fIlist\fR +are completed, then \fBaio_suspend()\fR returns with an error. +.SH RETURN VALUES +.sp +.LP +If \fBaio_suspend()\fR returns after one or more asynchronous I/O operations +have completed, it returns \fB0\fR. Otherwise, it returns \fB\(mi1\fR, and sets +\fBerrno\fR to indicate the error. +.sp +.LP +The application may determine which asynchronous I/O completed by scanning the +associated error and return status using \fBaio_error\fR(3C) and +\fBaio_return\fR(3C), respectively. +.SH ERRORS +.sp +.LP +The \fBaio_suspend()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR \fR +.ad +.RS 11n +.rt +No asynchronous I/O indicated in the list referenced by \fIlist\fR completed in +the time interval indicated by \fItimeout\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR \fR +.ad +.RS 11n +.rt +A signal interrupted the \fBaio_suspend()\fR function. Since each asynchronous +I/O operation might provoke a signal when it completes, this error return can +be caused by the completion of one or more of the very I/O operations being +awaited. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 11n +.rt +The \fInent\fR argument is less than or equal to 0 or greater than +\fB_AIO_LISTIO_MAX\fR, or the \fBtimespec\fR structure pointed to by +\fItimeout\fR is not properly set because \fItv_sec\fR is less than 0 or +\fItv_nsec\fR is either less than 0 or greater than 10^9. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 11n +.rt +There is currently not enough available memory; the application can try again +later. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR \fR +.ad +.RS 11n +.rt +The \fBaio_suspend()\fR function is not supported by the system. +.RE + +.SH USAGE +.sp +.LP +The \fBaio_suspend()\fR function has a transitional interface for 64-bit file +offsets. See \fBlf64\fR(5). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelAsync-Signal-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBaio.h\fR(3HEAD), \fBaio_fsync\fR(3C), \fBaio_read\fR(3C), +\fBaio_return\fR(3C), \fBaio_write\fR(3C), \fBlio_listio\fR(3C), +\fBsignal.h\fR(3HEAD), \fBattributes\fR(5), \fBlf64\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +Solaris 2.6 was the first release to support the Asynchronous Input and Output +option. Prior to this release, this function always returned \fB\(mi1\fR and +set \fBerrno\fR to \fBENOSYS\fR. diff --git a/usr/src/man/man3c/aio_waitn.3c b/usr/src/man/man3c/aio_waitn.3c new file mode 100644 index 0000000000..b218a77422 --- /dev/null +++ b/usr/src/man/man3c/aio_waitn.3c @@ -0,0 +1,176 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH aio_waitn 3C "18 Dec 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +aio_waitn \- wait for completion of asynchronous I/O operations +.SH SYNOPSIS +.LP +.nf +#include <aio.h> + +\fBint\fR \fBaio_waitn\fR(\fBstruct aiocb *\fR\fIlist\fR[], \fBuint_t\fR \fInent\fR, + \fBuint_t *\fR\fInwait\fR, \fBconst struct timespec *\fR\fItimeout\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBaio_waitn()\fR function suspends the calling thread until at least the +number of requests specified by \fInwait\fR have completed, until a signal +interrupts the function, or if \fItimeout\fR is not \fINULL\fR, until the time +interval specified by \fItimeout\fR has passed. +.sp +.LP +To effect a poll, the \fItimeout\fR argument should be non-zero, pointing to a +zero-valued \fBtimespec\fR structure. +.sp +.LP +The \fIlist\fR argument is an array of uninitialized I/O completion block +pointers to be filled in by the system before \fBaio_waitn()\fR returns. The +\fInent\fR argument indicates the maximum number of elements that can be placed +in \fIlist\fR[] and is limited to \fB_AIO_LISTIO_MAX\fR = 4096. +.sp +.LP +The \fInwait\fR argument points to the minimum number of requests +\fBaio_waitn()\fR should wait for. Upon returning, the content of \fInwait\fR +is set to the actual number of requests in the \fBaiocb\fR list, which can be +greater than the initial value specified in \fInwait\fR. The \fBaio_waitn()\fR +function attempts to return as many requests as possible, up to the number of +outstanding asynchronous I/Os but less than or equal to the maximum specified +by the \fInent\fR argument. As soon as the number of outstanding asynchronous +I/O requests becomes 0, \fBaio_waitn()\fR returns with the current list of +completed requests. +.sp +.LP +The \fBaiocb\fR structures returned will have been used in initiating an +asynchronous I/O request from any thread in the process with +\fBaio_read\fR(3C), \fBaio_write\fR(3C), or \fBlio_listio\fR(3C). +.sp +.LP +If the time interval expires before the expected number of I/O operations +specified by \fInwait\fR are completed, \fBaio_waitn()\fR returns the number of +completed requests and the content of the \fInwait\fR pointer is updated with +that number. +.sp +.LP +If \fBaio_waitn()\fR is interrupted by a signal, \fInwait\fR is set to the +number of completed requests. +.sp +.LP +The application can determine the status of the completed asynchronous I/O by +checking the associated error and return status using \fBaio_error\fR(3C) and +\fBaio_return\fR(3C), respectively. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBaio_waitn()\fR returns 0. Otherwise, it returns +-1 and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBaio_waitn()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +There are no outstanding asynchronous I/O requests. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +.rt +The \fIlist\fR[], \fInwait\fR, or \fItimeout\fR argument points to an address +outside the address space of the process. The \fBerrno\fR variable is set to +\fBEFAULT\fR only if this condition is detected by the application process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 10n +.rt +The execution of \fBaio_waitn()\fR was interrupted by a signal. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fItimeout\fR element \fItv_sec\fR or \fItv_nsec\fR is < 0, \fInent\fR is +set to 0 or > \fB_AIO_LISTIO_MAX\fR, or \fInwait\fR is either set to 0 or is > +\fInent\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +There is currently not enough available memory. The application can try again +later. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBETIME\fR\fR +.ad +.RS 10n +.rt +The time interval expired before \fInwait\fR outstanding requests have +completed. +.RE + +.SH USAGE +.sp +.LP +The \fBaio_waitn()\fR function has a transitional interface for 64-bit file +offsets. See \fBlf64\fR(5). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBaio.h\fR(3HEAD), \fBaio_error\fR(3C), \fBaio_read\fR(3C), +\fBaio_write\fR(3C), \fBlio_listio\fR(3C), \fBaio_return\fR(3C), +\fBattributes\fR(5), \fBlf64\fR(5) diff --git a/usr/src/man/man3c/aio_write.3c b/usr/src/man/man3c/aio_write.3c new file mode 100644 index 0000000000..c71172a15c --- /dev/null +++ b/usr/src/man/man3c/aio_write.3c @@ -0,0 +1,229 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH aio_write 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +aio_write \- asynchronous write to a file +.SH SYNOPSIS +.LP +.nf +#include <aio.h> + +\fBint\fR \fBaio_write\fR(\fBstruct aiocb *\fR\fIaiocbp\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBaio_write()\fR function allows the calling process to write +\fIaiocbp\fR\(->\fBaio_nbytes\fR to the file associated with +\fIaiocbp\fR\(->\fBaio_fildes\fR from the buffer pointed to by +\fIaiocbp\fR\(->\fBaio_buf\fR. The function call returns when the write request +has been initiated or, at a minimum, queued to the file or device. If +\fB_POSIX_PRIORITIZED_IO\fR is defined and prioritized I/O is supported for +this file, then the asynchronous operation is submitted at a priority equal to +the scheduling priority of the process minus \fIaiocbp\fR\(->\fBaio_reqprio\fR. +The \fIaiocbp\fR may be used as an argument to \fBaio_error\fR(3C) and +\fBaio_return\fR(3C) in order to determine the error status and return status, +respectively, of the asynchronous operation while it is proceeding. +.sp +.LP +The \fIaiocbp\fR argument points to an \fBaiocb\fR structure. If the buffer +pointed to by \fIaiocbp\fR\(->\fBaio_buf\fR or the control block pointed to by +\fIaiocbp\fR becomes an illegal address prior to asynchronous I/O completion, +then the behavior is undefined. +.sp +.LP +If \fBO_APPEND\fR is not set for the file descriptor \fIaio_fildes\fR, then the +requested operation takes place at the absolute position in the file as given +by \fIaio_offset\fR, as if \fBlseek\fR(2) were called immediately prior to the +operation with an \fIoffset\fR equal to \fIaio_offset\fR and a \fIwhence\fR +equal to \fBSEEK_SET\fR. If \fBO_APPEND\fR is set for the file descriptor, +write operations append to the file in the same order as the calls were made. +After a successful call to enqueue an asynchronous I/O operation, the value of +the file offset for the file is unspecified. +.sp +.LP +The \fIaiocbp\fR\(->\fBaio_sigevent\fR structure defines what asynchronous +notification is to occur when the asynchronous operation completes, as +specified in \fBsignal.h\fR(3HEAD). +.sp +.LP +The \fIaiocbp\fR\(->\fBaio_lio_opcode\fR field is ignored by \fBaio_write()\fR. +.sp +.LP +Simultaneous asynchronous operations using the same \fIaiocbp\fR produce +undefined results. +.sp +.LP +If \fB_POSIX_SYNCHRONIZED_IO\fR is defined and synchronized I/O is enabled on +the file associated with \fIaiocbp\fR\(->\fBaio_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. +.sp +.LP +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. +.sp +.LP +For regular files, no data transfer will occur past the offset maximum +established in the open file description associated with +\fIaiocbp\fR\(->\fBaio_fildes\fR. +.SH RETURN VALUES +.sp +.LP +The \fBaio_write()\fR function returns \fB0\fR to the calling process if the +I/O operation is successfully queued; otherwise, the function returns +\fB\(mi1\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBaio_write()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +The requested asynchronous I/O operation was not queued due to system resource +limitations. +.RE + +.sp +.LP +Each of the following conditions may be detected synchronously at the time of +the call to \fBaio_write()\fR, or asynchronously. If any of the conditions +below are detected synchronously, the \fBaio_write()\fR function returns +\fB\(mi1\fR and sets \fBerrno\fR to the corresponding value. If any of the +conditions below are detected asynchronously, the return status of the +asynchronous operation is set to \fB\(mi1\fR, and the error status of the +asynchronous operation will be set to the corresponding value. +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIaiocbp\fR\(->\fBaio_fildes\fR argument is not a valid file descriptor +open for writing. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The file offset value implied by \fIaiocbp\fR->\fBaio_offset\fR would be +invalid, \fIaiocbp->\fR\fBaio_reqprio\fR is not a valid value, or +\fIaiocbp\fR\(->\fBaio_nbytes\fR is an invalid value. +.RE + +.sp +.LP +In the case that the \fBaio_write()\fR successfully queues the I/O operation, +the return status of the asynchronous operation will be one of the values +normally returned by the \fBwrite\fR(2) 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 \fBwrite()\fR function call, or one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 13n +.rt +The \fIaiocbp\fR\(->\fBaio_fildes\fR argument is not a valid file descriptor +open for writing. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 13n +.rt +The file offset value implied by \fIaiocbp\fR->\fBaio_offset\fR would be +invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBECANCELED\fR\fR +.ad +.RS 13n +.rt +The requested I/O was canceled before the I/O completed due to an explicit +\fBaio_cancel\fR(3C) request. +.RE + +.sp +.LP +The following condition may be detected synchronously or asynchronously: +.sp +.ne 2 +.mk +.na +\fB\fBEFBIG\fR\fR +.ad +.RS 9n +.rt +The file is a regular file, \fIaiobcp\fR\(->\fBaio_nbytes\fR is greater than 0 +and the starting offset in \fIaiobcp\fR\(->\fBaio_offset\fR is at or beyond the +offset maximum in the open file description associated with +\fIaiocbp\fR\(->\fBaio_fildes\fR. +.RE + +.SH USAGE +.sp +.LP +The \fBaio_write()\fR function has a transitional interface for 64-bit file +offsets. See \fBlf64\fR(5). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBaio_cancel\fR(3C), \fBaio_error\fR(3C), \fBaio_read\fR(3C), +\fBaio_return\fR(3C), \fBlio_listio\fR(3C), \fBclose\fR(2), \fB_Exit\fR(2), +\fBfork\fR(2), \fBlseek\fR(2), \fBwrite\fR(2), \fBaio.h\fR(3HEAD), +\fBsignal.h\fR(3HEAD), \fBattributes\fR(5), \fBlf64\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/aiocancel.3c b/usr/src/man/man3c/aiocancel.3c new file mode 100644 index 0000000000..66316636a9 --- /dev/null +++ b/usr/src/man/man3c/aiocancel.3c @@ -0,0 +1,100 @@ +'\" te +.\" Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH aiocancel 3C "5 Feb 1997" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +aiocancel \- cancel an asynchronous operation +.SH SYNOPSIS +.LP +.nf +#include <sys/asynch.h> + +\fBint\fR \fBaiocancel\fR(\fBaio_result_t *\fR\fIresultp\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +\fBaiocancel()\fR cancels the asynchronous operation associated with the result +buffer pointed to by \fIresultp\fR. It may not be possible to immediately +cancel an operation which is in progress and in this case, \fBaiocancel()\fR +will not wait to cancel it. +.sp +.LP +Upon successful completion, \fBaiocancel()\fR returns \fB0\fR and the +requested operation is cancelled. The application will not receive the +\fBSIGIO\fR completion signal for an asynchronous operation that is +successfully cancelled. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBaiocancel()\fR returns \fB0\fR. Upon failure, +\fBaiocancel()\fR returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the +error. +.SH ERRORS +.sp +.LP +\fBaiocancel()\fR will fail if any of the following are true: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 10n +.rt +The parameter \fIresultp\fR does not correspond to any outstanding asynchronous +operation, although there is at least one currently outstanding. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +.rt +\fIresultp\fR points to an address outside the address space of the requesting +process. See \fBNOTES\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +There are not any outstanding requests to cancel. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBaioread\fR(3C), \fBaiowait\fR(3C), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +Passing an illegal address as \fIresultp\fR will result in setting \fBerrno\fR +to \fBEFAULT\fR \fIonly\fR if it is detected by the application process. diff --git a/usr/src/man/man3c/aioread.3c b/usr/src/man/man3c/aioread.3c new file mode 100644 index 0000000000..f1457b282e --- /dev/null +++ b/usr/src/man/man3c/aioread.3c @@ -0,0 +1,207 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH aioread 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +aioread, aiowrite \- read or write asynchronous I/O operations +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/asynch.h> + +\fBint\fR \fBaioread\fR(\fBint\fR \fIfildes\fR, \fBchar *\fR\fIbufp\fR, \fBint\fR \fIbufs\fR, \fBoff_t\fR \fIoffset\fR, + \fBint\fR \fIwhence\fR, \fBaio_result_t *\fR\fIresultp\fR); +.fi + +.LP +.nf +\fBint\fR \fBaiowrite\fR(\fBint\fR \fIfildes\fR, \fBconst char *\fR\fIbufp\fR, \fBint\fR \fIbufs\fR, \fBoff_t\fR \fIoffset\fR, + \fBint\fR \fIwhence\fR, \fBaio_result_t *\fR\fIresultp\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBaioread()\fR function initiates one asynchronous \fBread\fR(2) and +returns control to the calling program. The read continues concurrently with +other activity of the process. An attempt is made to read \fIbufs\fR bytes of +data from the object referenced by the descriptor \fIfildes\fR into the buffer +pointed to by \fIbufp\fR. +.sp +.LP +The \fBaiowrite()\fR function initiates one asynchronous \fBwrite\fR(2) and +returns control to the calling program. The write continues concurrently with +other activity of the process. An attempt is made to write \fIbufs\fR bytes of +data from the buffer pointed to by \fIbufp\fR to the object referenced by the +descriptor \fIfildes\fR. +.sp +.LP +On objects capable of seeking, the I/O operation starts at the position +specified by \fIwhence\fR and \fIoffset\fR. These parameters have the same +meaning as the corresponding parameters to the \fBllseek\fR(2) function. On +objects not capable of seeking the I/O operation always start from the current +position and the parameters \fBwhence\fR and \fIoffset\fR are ignored. The seek +pointer for objects capable of seeking is not updated by \fBaioread()\fR or +\fBaiowrite()\fR. Sequential asynchronous operations on these devices must be +managed by the application using the \fIwhence\fR and \fIoffset\fR parameters. +.sp +.LP +The result of the asynchronous operation is stored in the structure pointed to +by \fIresultp\fR: +.sp +.in +2 +.nf +int aio_return; /* return value of read() or write() */ +int aio_errno; /* value of errno for read() or write() */ +.fi +.in -2 + +.sp +.LP +Upon completion of the operation both \fBaio_return\fR and \fBaio_errno\fR are +set to reflect the result of the operation. Since \fBAIO_INPROGRESS\fR is not a +value used by the system, the client can detect a change in state by +initializing \fBaio_return\fR to this value. +.sp +.LP +The application-supplied buffer \fIbufp\fR should not be referenced by the +application until after the operation has completed. While the operation is in +progress, this buffer is in use by the operating system. +.sp +.LP +Notification of the completion of an asynchronous I/O operation can be +obtained synchronously through the \fBaiowait\fR(3C) function, or +asynchronously by installing a signal handler for the \fBSIGIO\fR signal. +Asynchronous notification is accomplished by sending the process a \fBSIGIO\fR +signal. If a signal handler is not installed for the \fBSIGIO\fR signal, +asynchronous notification is disabled. The delivery of this instance of the +\fBSIGIO\fR signal is reliable in that a signal delivered while the handler is +executing is not lost. If the client ensures that \fBaiowait()\fR returns +nothing (using a polling timeout) before returning from the signal handler, no +asynchronous I/O notifications are lost. The \fBaiowait()\fR function is the +only way to dequeue an asynchronous notification. The \fBSIGIO\fR signal can +have several meanings simultaneously. For example, it can signify that a +descriptor generated \fBSIGIO\fR and an asynchronous operation completed. +Further, issuing an asynchronous request successfully guarantees that space +exists to queue the completion notification. +.sp +.LP +The \fBclose\fR(2), \fBexit\fR(2) and \fBexecve\fR(2)) functions block until +all pending asynchronous I/O operations can be canceled by the system. +.sp +.LP +It is an error to use the same result buffer in more than one outstanding +request. These structures can be reused only after the system has completed the +operation. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBaioread()\fR and \fBaiowrite()\fR return +\fB0\fR. Upon failure, \fBaioread()\fR and \fBaiowrite()\fR return \fB\(mi1\fR +and set \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBaioread()\fR and \fBaiowrite()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +The number of asynchronous requests that the system can handle at any one time +has been exceeded +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIfildes\fR argument is not a valid file descriptor open for reading. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +.rt +At least one of \fIbufp\fR or \fIresultp\fR points to an address outside the +address space of the requesting process. This condition is reported only if +detected by the application process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIresultp\fR argument is currently being used by an outstanding +asynchronous request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIoffset\fR argument is not a valid offset for this file system type. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Memory resources are unavailable to initiate request. +.RE + +.SH USAGE +.sp +.LP +The \fBaioread()\fR and \fBaiowrite()\fR functions have transitional interfaces +for 64-bit file offsets. See \fBlf64\fR(5). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBclose\fR(2), \fBexecve\fR(2), \fBexit\fR(2), \fBllseek\fR(2), +\fBlseek\fR(2), \fBopen\fR(2), \fBread\fR(2), \fBwrite\fR(2), +\fBaiocancel\fR(3C), \fBaiowait\fR(3C), \fBsigvec\fR(3UCB), +\fBattributes\fR(5), \fBlf64\fR(5) diff --git a/usr/src/man/man3c/aiowait.3c b/usr/src/man/man3c/aiowait.3c new file mode 100644 index 0000000000..6e36689d35 --- /dev/null +++ b/usr/src/man/man3c/aiowait.3c @@ -0,0 +1,131 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH aiowait 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +aiowait \- wait for completion of asynchronous I/O operation +.SH SYNOPSIS +.LP +.nf +#include <sys/asynch.h> +#include <sys/time.h> + +\fBaio_result_t *\fR\fBaiowait\fR(\fBconst struct timeval *\fR\fItimeout\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBaiowait()\fR function suspends the calling process until one of its +outstanding asynchronous I/O operations completes, providing a synchronous +method of notification. +.sp +.LP +If \fItimeout\fR is a non-zero pointer, it specifies a maximum interval to wait +for the completion of an asynchronous I/O operation. If \fItimeout\fR is a zero +pointer, \fBaiowait()\fR blocks indefinitely. To effect a poll, the +\fItimeout\fR parameter should be non-zero, pointing to a zero-valued +\fItimeval\fR structure. +.sp +.LP +The \fBtimeval\fR structure is defined in <\fBsys/time.h\fR> and contains the +following members: +.sp +.in +2 +.nf +long tv_sec; /* seconds */ +long tv_usec; /* and microseconds */ +.fi +.in -2 + +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBaiowait()\fR returns a pointer to the result +structure used when the completed asynchronous I/O operation was requested. +Upon failure, \fBaiowait()\fR returns \fB\(mi1\fR and sets \fBerrno\fR to +indicate the error. \fBaiowait()\fR returns \fB0\fR if the time limit expires. +.SH ERRORS +.sp +.LP +The \fBaiowait()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +.rt +The \fItimeout\fR argument points to an address outside the address space of +the requesting process. See \fBNOTES\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 10n +.rt +The execution of \fBaiowait()\fR was interrupted by a signal. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +There are no outstanding asynchronous I/O requests. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fBtv_secs\fR member of the \fBtimeval\fR structure pointed to by +\fItimeout\fR is less than 0 or the \fBtv_usecs\fR member is greater than the +number of seconds in a microsecond. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBaiocancel\fR(3C), \fBaioread\fR(3C), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +The \fBaiowait()\fR function is the only way to dequeue an asynchronous +notification. It can be used either inside a \fBSIGIO\fR signal handler or in +the main program. One \fBSIGIO\fR signal can represent several queued events. +.sp +.LP +Passing an illegal address as \fItimeout\fR will result in setting \fBerrno\fR +to \fBEFAULT\fR only if detected by the application process. diff --git a/usr/src/man/man3c/assert.3c b/usr/src/man/man3c/assert.3c new file mode 100644 index 0000000000..dee17803b0 --- /dev/null +++ b/usr/src/man/man3c/assert.3c @@ -0,0 +1,75 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH assert 3C "30 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +assert \- verify program assertion +.SH SYNOPSIS +.LP +.nf +#include <assert.h> + +\fBvoid\fR \fBassert\fR(\fBint\fR \fIexpression\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBassert()\fR macro inserts diagnostics into applications. When executed, +if \fIexpression\fR is \fBFALSE\fR (zero), \fBassert()\fR prints the error +message +.sp +.in +2 +.nf +Assertion failed: \fIexpression\fR, file \fIxyz\fR, line \fInnn\fR +.fi +.in -2 + +.sp +.LP +on the standard error output and aborts. In the error message, \fIxyz\fR is the +name of the source file and \fInnn\fR the source line number of the +\fBassert()\fR statement. These are respectively the values of the preprocessor +macros \fB__FILE__\fR and \fB__LINE__\fR. +.sp +.LP +Since \fBassert()\fR is implemented as a macro, the \fIexpression\fR may not +contain any string literals. +.sp +.LP +Compiling with the preprocessor option \fB\fR\fB-DNDEBUG\fR or with the +preprocessor control statement \fB#define NDEBUG\fR ahead of the \fB#include\fR +<\fBassert.h\fR> statement, will stop assertions from being compiled into the +program. +.sp +.LP +Messages printed from this function are in the native language specified by the +\fBLC_MESSAGES\fR locale category. See \fBsetlocale\fR(3C). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelSafe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBabort\fR(3C), \fBgettext\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/atexit.3c b/usr/src/man/man3c/atexit.3c new file mode 100644 index 0000000000..ed1bdbe074 --- /dev/null +++ b/usr/src/man/man3c/atexit.3c @@ -0,0 +1,100 @@ +'\" te +.\" Copyright (c) 1997, The Open Group. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH atexit 3C "25 May 2001" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +atexit \- register a function to run at process termination or object unloading +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBint\fR \fBatexit\fR(\fBvoid (*\fR\fIfunc\fR)(void)); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBatexit()\fR function registers the function pointed to by \fIfunc\fR to +be called without arguments on normal termination of the program or when the +object defining the function is unloaded. +.sp +.LP +Normal termination occurs by either a call to the \fBexit\fR(3C) function or a +return from \fBmain()\fR. Object unloading occurs when a call to +\fBdlclose\fR(3C) results in the object becoming unreferenced. +.sp +.LP +The number of functions that may be registered with \fBatexit()\fR is limited +only by available memory (refer to the \fB_SC_ATEXIT_MAX\fR argument of +\fBsysconf\fR(3C)). +.sp +.LP +After a successful call to any of the \fBexec\fR(2) functions, any functions +previously registered by \fBatexit()\fR are no longer registered. +.sp +.LP +On process exit, functions are called in the reverse order of their +registration. On object unloading, any functions belonging to an unloadable +object are called in the reverse order of their registration. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBatexit()\fR function returns 0. Otherwise, +it returns a non-zero value. +.SH ERRORS +.sp +.LP +The \fBatexit()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient storage space is available. +.RE + +.SH USAGE +.sp +.LP +The functions registered by a call to \fBatexit()\fR must return to ensure that +all registered functions are called. +.sp +.LP +There is no way for an application to tell how many functions have already been +registered with \fBatexit()\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBexec\fR(2), \fBdlclose\fR(3C), \fBexit\fR(3C), \fBsysconf\fR(3C), +\fBattributes\fR(5) diff --git a/usr/src/man/man3c/atomic_add.3c b/usr/src/man/man3c/atomic_add.3c new file mode 100644 index 0000000000..8fd5808a54 --- /dev/null +++ b/usr/src/man/man3c/atomic_add.3c @@ -0,0 +1,152 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH atomic_add 3C "13 May 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +atomic_add, atomic_add_8, atomic_add_char, atomic_add_16, atomic_add_short, +atomic_add_32, atomic_add_int, atomic_add_long, atomic_add_64, atomic_add_ptr, +atomic_add_8_nv, atomic_add_char_nv, atomic_add_16_nv, atomic_add_short_nv, +atomic_add_32_nv, atomic_add_int_nv, atomic_add_long_nv, atomic_add_64_nv, +atomic_add_ptr_nv \- atomic add operations +.SH SYNOPSIS +.LP +.nf +#include <atomic.h> + +\fBvoid\fR \fBatomic_add_8\fR(\fBvolatile uint8_t *\fR\fItarget\fR, \fBint8_t\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_add_char\fR(\fBvolatile uchar_t *\fR\fItarget\fR, \fBsigned char\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_add_16\fR(\fBvolatile uint16_t *\fR\fItarget\fR, \fBint16_t\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_add_short\fR(\fBvolatile ushort_t *\fR\fItarget\fR, \fBshort\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_add_32\fR(\fBvolatile uint32_t *\fR\fItarget\fR, \fBint32_t\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_add_int\fR(\fBvolatile uint_t *\fR\fItarget\fR, \fBint\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_add_long\fR(\fBvolatile ulong_t *\fR\fItarget\fR, \fBlong\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_add_64\fR(\fBvolatile uint64_t *\fR\fItarget\fR, \fBint64_t\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_add_ptr\fR(\fBvolatile void *\fR\fItarget\fR, \fBssize_t\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBuint8_t\fR \fBatomic_add_8_nv\fR(\fBvolatile uint8_t *\fR\fItarget\fR, \fBint8_t\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBuchar_t\fR \fBatomic_add_char_nv\fR(\fBvolatile uchar_t *\fR\fItarget\fR, \fBsigned char\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBuint16_t\fR \fBatomic_add_16_nv\fR(\fBvolatile uint16_t *\fR\fItarget\fR, \fBint16_t\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBushort_t\fR \fBatomic_add_short_nv\fR(\fBvolatile ushort_t *\fR\fItarget\fR, \fBshort\fR\fIdelta\fR); +.fi + +.LP +.nf +\fBuint32_t\fR \fBatomic_add_32_nv\fR(\fBvolatile uint32_t *\fR\fItarget\fR, \fBint32_t\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBuint_t\fR \fBatomic_add_int_nv\fR(\fBvolatile uint_t *\fR\fItarget\fR, \fBint\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBulong_t\fR \fBatomic_add_long_nv\fR(\fBvolatile ulong_t *\fR\fItarget\fR, \fBlong\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBuint64_t\fR \fBatomic_add_64_nv\fR(\fBvolatile uint64_t *\fR\fItarget\fR, \fBint64_t\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBatomic_add_ptr_nv\fR(\fBvolatile void *\fR\fItarget\fR, \fBssize_t\fR \fIdelta\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions enable the addition of \fIdelta\fR to the value stored in +\fItarget\fR to occur in an atomic manner. +.SH RETURN VALUES +.sp +.LP +The *\fB_nv()\fR variants of these functions return the new value of +\fItarget\fR. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStable +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBatomic_and\fR(3C), \fBatomic_bits\fR(3C), \fBatomic_cas\fR(3C), +\fBatomic_dec\fR(3C), \fBatomic_inc\fR(3C), \fBatomic_or\fR(3C), +\fBatomic_swap\fR(3C), \fBmembar_ops\fR(3C), \fBattributes\fR(5), +\fBatomic_ops\fR(9F) +.SH NOTES +.sp +.LP +The *\fB_nv()\fR variants are substantially more expensive on some platforms +than the versions that do not return values. Do not use them unless you need to +know the new value \fBatomically\fR (for example, when decrementing a reference +count and checking whether it went to zero). diff --git a/usr/src/man/man3c/atomic_and.3c b/usr/src/man/man3c/atomic_and.3c new file mode 100644 index 0000000000..1b241f1da4 --- /dev/null +++ b/usr/src/man/man3c/atomic_and.3c @@ -0,0 +1,141 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH atomic_and 3C "13 May 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +atomic_and, atomic_and_8, atomic_and_uchar, atomic_and_16, atomic_and_ushort, +atomic_and_32, atomic_and_uint, atomic_and_ulong, atomic_and_64, +atomic_and_8_nv, atomic_and_uchar_nv, atomic_and_16_nv, atomic_and_ushort_nv, +atomic_and_32_nv, atomic_and_uint_nv, atomic_and_ulong_nv, atomic_and_64_nv \- +atomic AND operations +.SH SYNOPSIS +.LP +.nf +#include <atomic.h> + +\fBvoid\fR \fBatomic_and_8\fR(\fBvolatile uint8_t *\fR\fItarget\fR, \fBuint8_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_and_uchar\fR(\fBvolatile uchar_t *\fR\fItarget\fR, \fBuchar_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_and_16\fR(\fBvolatile uint16_t *\fR\fItarget\fR, \fBuint16_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_and_ushort\fR(\fBvolatile ushort_t *\fR\fItarget\fR, \fBushort_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_and_32\fR(\fBvolatile uint32_t *\fR\fItarget\fR, \fBuint32_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_and_uint\fR(\fBvolatile uint_t *\fR\fItarget\fR, \fBuint_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_and_ulong\fR(\fBvolatile ulong_t *\fR\fItarget\fR, \fBulong_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_and_64\fR(\fBvolatile uint64_t *\fR\fItarget\fR, \fBuint64_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBuint8_t\fR \fBatomic_and_8_nv\fR(\fBvolatile uint8_t *\fR\fItarget\fR, \fBuint8_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBuchar_t\fR \fBatomic_and_uchar_nv\fR(\fBvolatile uchar_t *\fR\fItarget\fR, \fBuchar_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBuint16_t\fR \fBatomic_and_16_nv\fR(\fBvolatile uint16_t *\fR\fItarget\fR, \fBuint16_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBushort_t\fR \fBatomic_and_ushort_nv\fR(\fBvolatile ushort_t *\fR\fItarget\fR, \fBushort_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBuint32_t\fR \fBatomic_and_32_nv\fR(\fBvolatile uint32_t *\fR\fItarget\fR, \fBuint32_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBuint_t\fR \fBatomic_and_uint_nv\fR(\fBvolatile uint_t *\fR\fItarget\fR, \fBuint_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBulong_t\fR \fBatomic_and_ulong_nv\fR(\fBvolatile ulong_t *\fR\fItarget\fR, \fBulong_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBuint64_t\fR \fBatomic_and_64_nv\fR(\fBvolatile uint64_t *\fR\fItarget\fR, \fBuint64_t\fR \fIbits\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions enable the bitwise AND of \fIbits\fR to the value stored in +\fItarget\fR to occur in an atomic manner. +.SH RETURN VALUES +.sp +.LP +The *\fB_nv()\fR variants of these functions return the new value of +\fItarget\fR. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBatomic_add\fR(3C), \fBatomic_bits\fR(3C), \fBatomic_cas\fR(3C), +\fBatomic_dec\fR(3C), \fBatomic_inc\fR(3C), \fBatomic_or\fR(3C), +\fBatomic_swap\fR(3C), \fBmembar_ops\fR(3C), \fBattributes\fR(5), +\fBatomic_ops\fR(9F) +.SH NOTES +.sp +.LP +The *\fB_nv()\fR variants are substantially more expensive on some platforms +than the versions that do not return values. Do not use them unless you need to +know the new value \fBatomically\fR. diff --git a/usr/src/man/man3c/atomic_bits.3c b/usr/src/man/man3c/atomic_bits.3c new file mode 100644 index 0000000000..3103fc1eab --- /dev/null +++ b/usr/src/man/man3c/atomic_bits.3c @@ -0,0 +1,67 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH atomic_bits 3C "13 May 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +atomic_bits, atomic_set_long_excl, atomic_clear_long_excl \- atomic set and +clear bit operations +.SH SYNOPSIS +.LP +.nf +#include <atomic.h> + +\fBint\fR \fBatomic_set_long_excl\fR(\fBvolatile ulong_t *\fR\fItarget\fR, \fBuint_t\fR \fIbit\fR); +.fi + +.LP +.nf +\fBint\fR \fBatomic_clear_long_excl\fR(\fBvolatile ulong_t *\fR\fItarget\fR, \fBuint_t\fR \fIbit\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBatomic_set_long_excl()\fR and \fBatomic_clear_long_excl()\fR functions +perform an exclusive atomic bit set or clear operation on \fItarget\fR. The +value of \fIbit\fR specifies the number of the bit to be modified within +target. Bits are numbered from zero to one less than the maximum number of bits +in a \fBlong\fR. If the value of bit falls outside of this range, the result of +the operation is undefined. +.SH RETURN VALUES +.sp +.LP +The \fBatomic_set_long_excl()\fR and \fBatomic_clear_long_excl()\fR functions +return 0 if \fIbit\fR was successfully set or cleared. They return -1 if +\fIbit\fR was already set or cleared. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStable +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBatomic_add\fR(3C), \fBatomic_and\fR(3C), \fBatomic_cas\fR(3C), +\fBatomic_dec\fR(3C), \fBatomic_inc\fR(3C), \fBatomic_or\fR(3C), +\fBatomic_swap\fR(3C), \fBmembar_ops\fR(3C), \fBattributes\fR(5), +\fBatomic_ops\fR(9F) diff --git a/usr/src/man/man3c/atomic_cas.3c b/usr/src/man/man3c/atomic_cas.3c new file mode 100644 index 0000000000..c916d448ae --- /dev/null +++ b/usr/src/man/man3c/atomic_cas.3c @@ -0,0 +1,109 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH atomic_cas 3C "13 May 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +atomic_cas, atomic_cas_8, atomic_cas_uchar, atomic_cas_16, atomic_cas_ushort, +atomic_cas_32, atomic_cas_uint, atomic_cas_ulong, atomic_cas_64, atomic_cas_ptr +\- atomic compare and swap operations +.SH SYNOPSIS +.LP +.nf +#include <atomic.h> + +\fBuint8_t\fR \fBatomic_cas_8\fR(\fBvolatile uint8_t *\fR\fItarget\fR, \fBuint8_t\fR \fIcmp\fR, + \fBuint8_t\fR \fInewval\fR); +.fi + +.LP +.nf +\fBuchar_t\fR \fBatomic_cas_uchar\fR(\fBvolatile uchar_t *\fR\fItarget\fR, \fBuchar_t\fR \fIcmp\fR, + \fBuchar_t\fR \fInewval\fR); +.fi + +.LP +.nf +\fBuint16_t\fR \fBatomic_cas_16\fR(\fBvolatile uint16_t *\fR\fItarget\fR, \fBuint16_t\fR \fIcmp\fR, + \fBuint16_t\fR \fInewval\fR); +.fi + +.LP +.nf +\fBushort_t\fR \fBatomic_cas_ushort\fR(\fBvolatile ushort_t *\fR\fItarget\fR, \fBushort_t\fR \fIcmp\fR, + \fBushort_t\fR \fInewval\fR); +.fi + +.LP +.nf +\fBuint32_t\fR \fBatomic_cas_32\fR(\fBvolatile uint32_t *\fR\fItarget\fR, \fBuint32_t\fR \fIcmp\fR, + \fBuint32_t\fR \fInewval\fR); +.fi + +.LP +.nf +\fBuint_t\fR \fBatomic_cas_uint\fR(\fBvolatile uint_t *\fR\fItarget\fR, \fBuint_t\fR \fIcmp\fR, + \fBuint_t\fR \fInewval\fR); +.fi + +.LP +.nf +\fBulong_t\fR \fBatomic_cas_ulong\fR(\fBvolatile ulong_t *\fR\fItarget\fR, \fBulong_t\fR \fIcmp\fR, + \fBulong_t\fR \fInewval\fR); +.fi + +.LP +.nf +\fBuint64_t\fR \fBatomic_cas_64\fR(\fBvolatile uint64_t *\fR\fItarget\fR, \fBuint64_t\fR \fIcmp\fR, + \fBuint64_t\fR \fInewval\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBatomic_cas_ptr\fR(\fBvolatile void *\fR\fItarget\fR, \fBvoid *\fR\fIcmp\fR, + \fBvoid *\fR\fInewval\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions enable a compare and swap operation to occur atomically. The +value stored in \fItarget\fR is compared with \fIcmp\fR. If these values are +equal, the value stored in \fItarget\fR is replaced with \fInewval\fR. The old +value stored in \fItarget\fR is returned by the function whether or not the +replacement occurred. +.SH RETURN VALUES +.sp +.LP +These functions return the old value of *\fItarget\fR. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBatomic_add\fR(3C), \fBatomic_and\fR(3C), \fBatomic_bits\fR(3C), +\fBatomic_dec\fR(3C), \fBatomic_inc\fR(3C), \fBatomic_or\fR(3C), +\fBatomic_swap\fR(3C), \fBmembar_ops\fR(3C), \fBattributes\fR(5), +\fBatomic_ops\fR(9F) diff --git a/usr/src/man/man3c/atomic_dec.3c b/usr/src/man/man3c/atomic_dec.3c new file mode 100644 index 0000000000..5f3b1c7776 --- /dev/null +++ b/usr/src/man/man3c/atomic_dec.3c @@ -0,0 +1,153 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH atomic_dec 3C "13 May 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +atomic_dec, atomic_dec_8, atomic_dec_uchar, atomic_dec_16, atomic_dec_ushort, +atomic_dec_32, atomic_dec_uint, atomic_dec_ulong, atomic_dec_64, +atomic_dec_ptr, atomic_dec_8_nv, atomic_dec_uchar_nv, atomic_dec_16_nv, +atomic_dec_ushort_nv, atomic_dec_32_nv, atomic_dec_uint_nv, +atomic_dec_ulong_nv, atomic_dec_64_nv, atomic_dec_ptr_nv \- atomic decrement +operations +.SH SYNOPSIS +.LP +.nf +#include <atomic.h> + +\fBvoid\fR \fBatomic_dec_8\fR(\fBvolatile uint8_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_dec_uchar\fR(\fBvolatile uchar_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_dec_16\fR(\fBvolatile uint16_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_dec_ushort\fR(\fBvolatile ushort_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_dec_32\fR(\fBvolatile uint32_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_dec_uint\fR(\fBvolatile uint_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_dec_ulong\fR(\fBvolatile ulong_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_dec_64\fR(\fBvolatile uint64_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_dec_ptr\fR(\fBvolatile void *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBuint8_t\fR \fBatomic_dec_8_nv\fR(\fBvolatile uint8_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBuchar_t\fR \fBatomic_dec_uchar_nv\fR(\fBvolatile uchar_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBuint16_t\fR \fBatomic_dec_16_nv\fR(\fBvolatile uint16_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBushort_t\fR \fBatomic_dec_ushort_nv\fR(\fBvolatile ushort_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBuint32_t\fR \fBatomic_dec_32_nv\fR(\fBvolatile uint32_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBuint_t\fR \fBatomic_dec_uint_nv\fR(\fBvolatile uint_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBulong_t\fR \fBatomic_dec_ulong_nv\fR(\fBvolatile ulong_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBuint64_t\fR \fBatomic_dec_64_nv\fR(\fBvolatile uint64_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBatomic_dec_ptr_nv\fR(\fBvolatile void *\fR\fItarget\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions enable the decrementing (by one) of the value stored in +\fItarget\fR to occur in an atomic manner. +.SH RETURN VALUES +.sp +.LP +The *\fB_nv()\fR variants of these functions return the new value of +\fItarget\fR. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStable +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBatomic_add\fR(3C), \fBatomic_and\fR(3C), \fBatomic_bits\fR(3C), +\fBatomic_cas\fR(3C), \fBatomic_inc\fR(3C), \fBatomic_or\fR(3C), +\fBatomic_swap\fR(3C), \fBmembar_ops\fR(3C), \fBattributes\fR(5), +\fBatomic_ops\fR(9F) +.SH NOTES +.sp +.LP +The *\fB_nv()\fR variants are substantially more expensive on some platforms +than the versions that do not return values. Do not use them unless you need to +know the new value atomically (for example, when decrementing a reference count +and checking whether it went to zero). diff --git a/usr/src/man/man3c/atomic_inc.3c b/usr/src/man/man3c/atomic_inc.3c new file mode 100644 index 0000000000..0b445ee2b1 --- /dev/null +++ b/usr/src/man/man3c/atomic_inc.3c @@ -0,0 +1,152 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH atomic_inc 3C "13 May 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +atomic_inc, atomic_inc_8, atomic_inc_uchar, atomic_inc_16, atomic_inc_ushort, +atomic_inc_32, atomic_inc_uint, atomic_inc_ulong, atomic_inc_64, +atomic_inc_ptr, atomic_inc_8_nv, atomic_inc_uchar_nv, atomic_inc_16_nv, +atomic_inc_ushort_nv, atomic_inc_32_nv, atomic_inc_uint_nv, +atomic_inc_ulong_nv, atomic_inc_64_nv, atomic_inc_ptr_nv \- atomic inrement +operations +.SH SYNOPSIS +.LP +.nf +#include <atomic.h> + +\fBvoid\fR \fBatomic_inc_8\fR(\fBvolatile uint8_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_inc_uchar\fR(\fBvolatile uchar_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_inc_16\fR(\fBvolatile uint16_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_inc_ushort\fR(\fBvolatile ushort_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_inc_32\fR(\fBvolatile uint32_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_inc_uint\fR(\fBvolatile uint_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_inc_ulong\fR(\fBvolatile ulong_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_inc_64\fR(\fBvolatile uint64_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_inc_ptr\fR(\fBvolatile void *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBuint8_t\fR \fBatomic_inc_8_nv\fR(\fBvolatile uint8_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBuchar_t\fR \fBatomic_inc_uchar_nv\fR(\fBvolatile uchar_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBuint16_t\fR \fBatomic_inc_16_nv\fR(\fBvolatile uint16_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBushort_t\fR \fBatomic_inc_ushort_nv\fR(\fBvolatile ushort_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBuint32_t\fR \fBatomic_inc_32_nv\fR(\fBvolatile uint32_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBuint_t\fR \fBatomic_inc_uint_nv\fR(\fBvolatile uint_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBulong_t\fR \fBatomic_inc_ulong_nv\fR(\fBvolatile ulong_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBuint64_t\fR \fBatomic_inc_64_nv\fR(\fBvolatile uint64_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBatomic_inc_ptr_nv\fR(\fBvolatile void *\fR\fItarget\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions enable the inrementing (by one) of the value stored in +\fItarget\fR to occur in an atomic manner. +.SH RETURN VALUES +.sp +.LP +The *\fB_nv()\fR variants of these functions return the new value of +\fItarget\fR. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStable +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBatomic_add\fR(3C), \fBatomic_and\fR(3C), \fBatomic_bits\fR(3C), +\fBatomic_cas\fR(3C), \fBatomic_dec\fR(3C), \fBatomic_or\fR(3C), +\fBatomic_swap\fR(3C), \fBmembar_ops\fR(3C), \fBattributes\fR(5), +\fBatomic_ops\fR(9F) +.SH NOTES +.sp +.LP +The *\fB_nv()\fR variants are substantially more expensive on some platforms +than the versions that do not return values. Do not use them unless you need to +know the new value \fBatomically\fR. diff --git a/usr/src/man/man3c/atomic_ops.3c b/usr/src/man/man3c/atomic_ops.3c new file mode 100644 index 0000000000..d2be8c3340 --- /dev/null +++ b/usr/src/man/man3c/atomic_ops.3c @@ -0,0 +1,153 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH atomic_ops 3C "12 Aug 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +atomic_ops \- atomic operations +.SH SYNOPSIS +.LP +.nf +#include <\fBatomic.h\fR> +.fi + +.SH DESCRIPTION +.sp +.LP +This collection of functions provides atomic memory operations. There are 8 +different classes of atomic operations: +.sp +.ne 2 +.mk +.na +\fB\fBatomic_add\fR(3C)\fR +.ad +.RS 19n +.rt +These functions provide an atomic addition of a signed value to a variable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBatomic_and\fR(3C)\fR +.ad +.RS 19n +.rt +These functions provide an atomic logical 'and' of a value to a variable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBatomic_bits\fR(3C)\fR +.ad +.RS 19n +.rt +These functions provide atomic bit setting and clearing within a variable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBatomic_cas\fR(3C)\fR +.ad +.RS 19n +.rt +These functions provide an atomic comparison of a value with a variable. If the +comparison is equal, then swap in a new value for the variable, returning the +old value of the variable in either case. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBatomic_dec\fR(3C)\fR +.ad +.RS 19n +.rt +These functions provide an atomic decrement on a variable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBatomic_inc\fR(3C)\fR +.ad +.RS 19n +.rt +These functions provide an atomic increment on a variable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBatomic_or\fR(3C)\fR +.ad +.RS 19n +.rt +These functions provide an atomic logical 'or' of a value to a variable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBatomic_swap\fR(3C)\fR +.ad +.RS 19n +.rt +These functions provide an atomic swap of a value with a variable, returning +the old value of the variable. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStable +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBatomic_add\fR(3C), \fBatomic_and\fR(3C), \fBatomic_bits\fR(3C), +\fBatomic_cas\fR(3C), \fBatomic_dec\fR(3C), \fBatomic_inc\fR(3C), +\fBatomic_or\fR(3C), \fBatomic_swap\fR(3C), \fBmembar_ops\fR(3C), +\fBattributes\fR(5) +.SH NOTES +.sp +.LP +Atomic instructions ensure global visibility of atomically-modified variables +on completion. In a relaxed store order system, this does not guarantee that +the visibility of other variables will be synchronized with the completion of +the atomic instruction. If such synchronization is required, memory barrier +instructions must be used. See \fBmembar_ops\fR(3C). +.sp +.LP +Atomic instructions can be expensive since they require synchronization to +occur at a hardware level. This means they should be used with care to ensure +that forcing hardware level synchronization occurs a minimum number of times. +For example, if you have several variables that need to be incremented as a +group, and each needs to be done atomically, then do so with a mutex lock +protecting all of them being incremented rather than using the +\fBatomic_inc\fR(3C) operation on each of them. diff --git a/usr/src/man/man3c/atomic_or.3c b/usr/src/man/man3c/atomic_or.3c new file mode 100644 index 0000000000..8d36fa6e62 --- /dev/null +++ b/usr/src/man/man3c/atomic_or.3c @@ -0,0 +1,140 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH atomic_or 3C "13 May 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +atomic_or, atomic_or_8, atomic_or_uchar, atomic_or_16, atomic_or_ushort, +atomic_or_32, atomic_or_uint, atomic_or_ulong, atomic_or_64, atomic_or_8_nv, +atomic_or_uchar_nv, atomic_or_16_nv, atomic_or_ushort_nv, atomic_or_32_nv, +atomic_or_uint_nv, atomic_or_ulong_nv, atomic_or_64_nv \- atomic OR operations +.SH SYNOPSIS +.LP +.nf +#include <atomic.h> + +\fBvoid\fR \fBatomic_or_8\fR(\fBvolatile uint8_t *\fR\fItarget\fR, \fBuint8_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_or_uchar\fR(\fBvolatile uchar_t *\fR\fItarget\fR, \fBuchar_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_or_16\fR(\fBvolatile uint16_t *\fR\fItarget\fR, \fBuint16_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_or_ushort\fR(\fBvolatile ushort_t *\fR\fItarget\fR, \fBushort_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_or_32\fR(\fBvolatile uint32_t *\fR\fItarget\fR, \fBuint32_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_or_uint\fR(\fBvolatile uint_t *\fR\fItarget\fR, \fBuint_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_or_ulong\fR(\fBvolatile ulong_t *\fR\fItarget\fR, \fBulong_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_or_64\fR(\fBvolatile uint64_t *\fR\fItarget\fR, \fBuint64_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBuint8_t\fR \fBatomic_or_8_nv\fR(\fBvolatile uint8_t *\fR\fItarget\fR, \fBuint8_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBuchar_t\fR \fBatomic_or_uchar_nv\fR(\fBvolatile uchar_t *\fR\fItarget\fR, \fBuchar_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBuint16_t\fR \fBatomic_or_16_nv\fR(\fBvolatile uint16_t *\fR\fItarget\fR, \fBuint16_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBushort_t\fR \fBatomic_or_ushort_nv\fR(\fBvolatile ushort_t *\fR\fItarget\fR, \fBushort_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBuint32_t\fR \fBatomic_or_32_nv\fR(\fBvolatile uint32_t *\fR\fItarget\fR, \fBuint32_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBuint_t\fR \fBatomic_or_uint_nv\fR(\fBvolatile uint_t *\fR\fItarget\fR, \fBuint_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBulong_t\fR \fBatomic_or_ulong_nv\fR(\fBvolatile ulong_t *\fR\fItarget\fR, \fBulong_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBuint64_t\fR \fBatomic_or_64_nv\fR(\fBvolatile uint64_t *\fR\fItarget\fR, \fBuint64_t\fR \fIbits\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions enable the the bitwise OR of \fIbits\fR to the value stored in +\fItarget\fR to occur in an atomic manner. +.SH RETURN VALUES +.sp +.LP +The *\fB_nv()\fR variants of these functions return the new value of +\fItarget\fR. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStable +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBatomic_add\fR(3C), \fBatomic_and\fR(3C), \fBatomic_bits\fR(3C), +\fBatomic_cas\fR(3C), \fBatomic_dec\fR(3C), \fBatomic_inc\fR(3C), +\fBatomic_swap\fR(3C), \fBmembar_ops\fR(3C), \fBattributes\fR(5), +\fBatomic_ops\fR(9F) +.SH NOTES +.sp +.LP +The *\fB_nv()\fR variants are substantially more expensive on some platforms +than the versions that do not return values. Do not use them unless you need to +know the new value \fBatomically\fR. diff --git a/usr/src/man/man3c/atomic_swap.3c b/usr/src/man/man3c/atomic_swap.3c new file mode 100644 index 0000000000..7db86beeb0 --- /dev/null +++ b/usr/src/man/man3c/atomic_swap.3c @@ -0,0 +1,98 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH atomic_swap 3C "13 May 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +atomic_swap, atomic_swap_8, atomic_swap_uchar, atomic_swap_16, +atomic_swap_ushort, atomic_swap_32, atomic_swap_uint, atomic_swap_ulong, +atomic_swap_64, atomic_swap_ptr \- atomic swap operations +.SH SYNOPSIS +.LP +.nf +#include <atomic.h> + +\fBuint8_t\fR \fBatomic_swap_8\fR(\fBvolatile uint8_t *\fR\fItarget\fR, \fBuint8_t\fR \fInewval\fR); +.fi + +.LP +.nf +\fBuchar_t\fR \fBatomic_swap_uchar\fR(\fBvolatile uchar_t *\fR\fItarget\fR, \fBuchar_t\fR \fInewval\fR); +.fi + +.LP +.nf +\fBuint16_t\fR \fBatomic_swap_16\fR(\fBvolatile uint16_t *\fR\fItarget\fR, \fBuint16_t\fR \fInewval\fR); +.fi + +.LP +.nf +\fBushort_t\fR \fBatomic_swap_ushort\fR(\fBvolatile ushort_t *\fR\fItarget\fR, \fBushort_t\fR \fInewval\fR); +.fi + +.LP +.nf +\fBuint32_t\fR \fBatomic_swap_32\fR(\fBvolatile uint32_t *\fR\fItarget\fR, \fBuint32_t\fR \fInewval\fR); +.fi + +.LP +.nf +\fBuint_t\fR \fBatomic_swap_uint\fR(\fBvolatile uint_t *\fR\fItarget\fR, \fBuint_t\fR \fInewval\fR); +.fi + +.LP +.nf +\fBulong_t\fR \fBatomic_swap_ulong\fR(\fBvolatile ulong_t *\fR\fItarget\fR, \fBulong_t\fR \fInewval\fR); +.fi + +.LP +.nf +\fBuint64_t\fR \fBatomic_swap_64\fR(\fBvolatile uint64_t *\fR\fItarget\fR, \fBuint64_t\fR \fInewval\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBatomic_swap_ptr\fR(\fBvolatile void *\fR\fItarget\fR, \fBvoid *\fR\fInewval\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions enable a swap operation to occur atomically. The value stored +in \fItarget\fR is replaced with \fInewval\fR. The old value is returned by the +function. +.SH RETURN VALUES +.sp +.LP +These functions return the old of *\fItarget\fR. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStable +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBatomic_add\fR(3C), \fBatomic_and\fR(3C), \fBatomic_bits\fR(3C), +\fBatomic_dec\fR(3C), \fBatomic_inc\fR(3C), \fBatomic_or\fR(3C), +\fBatomic_cas\fR(3C), \fBmembar_ops\fR(3C), \fBattributes\fR(5), +\fBatomic_ops\fR(9F) diff --git a/usr/src/man/man3c/attropen.3c b/usr/src/man/man3c/attropen.3c new file mode 100644 index 0000000000..23d6e18f9a --- /dev/null +++ b/usr/src/man/man3c/attropen.3c @@ -0,0 +1,64 @@ +'\" te +.\" Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH attropen 3C "1 Aug 2001" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +attropen \- open a file +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/stat.h> +#include <fcntl.h> + +\fBint\fR \fBattropen\fR(\fBconst char *\fR\fIpath\fR, \fBconst char *\fR\fIattrpath\fR, \fBint\fR \fIoflag\fR, + \fB/* mode_t\fR \fImode\fR */...); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBattropen()\fR function is similar to the \fBopen\fR(2) function except +that it takes a second path argument, \fIattrpath\fR, that identifies an +extended attribute file associated with the first \fIpath\fR argument. This +function returns a file descriptor for the extended attribute rather than the +file named by the initial argument. +.sp +.LP +The \fBO_XATTR\fR flag is set by default for \fBattropen()\fR and the +\fIattrpath\fR argument is always interpreted as a reference to an extended +attribute. Extended attributes must be referenced with a relative path; +providing an absolute path results in a normal file reference. +.SH RETURN VALUES +.sp +.LP +Refer to \fBopen\fR(2). +.SH ERRORS +.sp +.LP +Refer to \fBopen\fR(2). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBopen\fR(2), \fBattributes\fR(5), \fBfsattr\fR(5) diff --git a/usr/src/man/man3c/basename.3c b/usr/src/man/man3c/basename.3c new file mode 100644 index 0000000000..98a131f819 --- /dev/null +++ b/usr/src/man/man3c/basename.3c @@ -0,0 +1,93 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH basename 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +basename \- return the last element of a path name +.SH SYNOPSIS +.LP +.nf +#include <libgen.h> + +\fBchar *\fR\fBbasename\fR(\fBchar *\fR\fIpath\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBbasename()\fR function takes the pathname pointed to by \fIpath\fR and +returns a pointer to the final component of the pathname, deleting any +trailing '/' characters. +.sp +.LP +If the string consists entirely of the '/' character, \fBbasename()\fR returns +a pointer to the string "/" . +.sp +.LP +If \fIpath\fR is a null pointer or points to an empty string, \fBbasename()\fR +returns a pointer to the string "." . +.SH RETURN VALUES +.sp +.LP +The \fBbasename()\fR function returns a pointer to the final component of +\fIpath\fR. +.SH USAGE +.sp +.LP +The \fBbasename()\fR function may modify the string pointed to by \fIpath\fR, +and may return a pointer to static storage that may then be overwritten by a +subsequent call to \fBbasename()\fR. +.sp +.LP +When compiling multithreaded applications, the \fB_REENTRANT\fR flag must be +defined on the compile line. This flag should only be used in multithreaded +applications. +.SH EXAMPLES +.LP +\fBExample 1 \fRExamples for \fBInput String\fR and \fBOutput String\fR +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBInput String\fR\fBOutput String\fR +_ +"/usr/lib""lib" +_ +"/usr/""usr" +_ +"/""/" +.TE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBbasename\fR(1), \fBdirname\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/bsd_signal.3c b/usr/src/man/man3c/bsd_signal.3c new file mode 100644 index 0000000000..e098f0d1fa --- /dev/null +++ b/usr/src/man/man3c/bsd_signal.3c @@ -0,0 +1,105 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH bsd_signal 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +bsd_signal \- simplified signal facilities +.SH SYNOPSIS +.LP +.nf +#include <signal.h> + +\fBvoid\fR (\fB*bsd_signal(int\fR \fIsig\fR, \fBvoid\fR (*\fIfunc\fR)(\fBint\fR)))(\fBint\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBbsd_signal()\fR function provides a partially compatible interface for +programs written to historical system interfaces (see \fBUSAGE\fR below). +.sp +.LP +The function call \fBbsd_signal\fR(\fIsig\fR, \fIfunc\fR) has an effect as if +implemented as: +.sp +.in +2 +.nf +void (*bsd_signal(int sig, void (*func)\|(int)))\|(int) +{ + struct sigaction act, oact; + + act.sa_handler = \fIfunc\fR; + act.sa_flags = SA_RESTART; + sigemptyset(&act.sa_mask); + sigaddset(&act.sa_mask, \fIsig\fR); + if (sigaction(\fIsig\fR, &act, &oact) == \(mi1) + return(\fBSIG_ERR\fR); + return(oact.sa_handler); +} +.fi +.in -2 + +.sp +.LP +The handler function should be declared: +.sp +.in +2 +.nf +void handler(int \fIsig\fR); +.fi +.in -2 + +.sp +.LP +where \fIsig\fR is the signal number. The behavior is undefined if \fIfunc\fR +is a function that takes more than one argument, or an argument of a different +type. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBbsd_signal()\fR returns the previous action for +\fIsig\fR. Otherwise, \fBSIG_ERR\fR is returned and \fBerrno\fR is set to +indicate the error. +.SH ERRORS +.sp +.LP +Refer to \fBsigaction\fR(2). +.SH USAGE +.sp +.LP +This function is a direct replacement for the \fBBSD\fR \fBsignal\fR(3UCB) +function for simple applications that are installing a single-argument signal +handler function. If a \fBBSD\fR signal handler function is being installed +that expects more than one argument, the application has to be modified to use +\fBsigaction\fR(2). The \fBbsd_signal()\fR function differs from +\fBsignal\fR(3UCB) in that the \fBSA_RESTART\fR flag is set and the +\fBSA_RESETHAND\fR will be clear when \fBbsd_signal()\fR is used. The state of +these flags is not specified for \fBsignal\fR(3UCB). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityStandard +.TE + +.SH SEE ALSO +.sp +.LP +\fBsigaction\fR(2), \fBsigaddset\fR(3C), \fBsigemptyset\fR(3C), +\fBsignal\fR(3UCB), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/bsearch.3c b/usr/src/man/man3c/bsearch.3c new file mode 100644 index 0000000000..500106c541 --- /dev/null +++ b/usr/src/man/man3c/bsearch.3c @@ -0,0 +1,149 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH bsearch 3C "6 Dec 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +bsearch \- binary search a sorted table +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBvoid *\fR\fBbsearch\fR(\fBconst void *\fR\fIkey\fR, \fBconst void *\fR\fIbase\fR, \fBsize_t\fR \fInel\fR, \fBsize_t\fR \fIsize\fR, + \fBint (*\fR\fIcompar\fR)(const void *,const void *)); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBbsearch()\fR function is a binary search routine generalized from Knuth +(6.2.1) Algorithm B. It returns a pointer into a table (an array) indicating +where a datum may be found or a null pointer if the datum cannot be found. The +table must be previously sorted in increasing order according to a comparison +function pointed to by \fIcompar\fR. +.sp +.LP +The \fIkey\fR argument points to a datum instance to be sought in the table. +The \fIbase\fR argument points to the element at the base of the table. The +\fInel\fR argument is the number of elements in the table. The \fBsize\fR +argument is the number of bytes in each element. +.sp +.LP +The comparison function pointed to by \fIcompar\fR is called with two arguments +that point to the \fIkey\fR object and to an array element, in that order. The +function must return an integer less than, equal to, or greater than 0 if the +\fIkey\fR object is considered, respectively, to be less than, equal to, or +greater than the array element. +.SH RETURN VALUES +.sp +.LP +The \fBbsearch()\fR function returns 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 USAGE +.sp +.LP +The pointers to the key and the element at the base of the table should be of +type pointer-to-element. +.sp +.LP +The comparison function need not compare every byte, so arbitrary data may be +contained in the elements in addition to the values being compared. +.sp +.LP +If the number of elements in the table is less than the size reserved for the +table, \fInel\fR should be the lower number. +.sp +.LP +The \fBbsearch()\fR function safely allows concurrent access by multiple +threads to disjoint data, such as overlapping subtrees or tables. +.SH EXAMPLES +.LP +\fBExample 1 \fRExamples for searching a table containing pointers to nodes. +.sp +.LP +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. + +.sp +.LP +This program reads in strings and either finds the corresponding node and +prints out the string and its length, or prints an error message. + +.sp +.in +2 +.nf +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +struct node { /* these are stored in the table */ + char *string; + int length; +}; +static struct node table[] = { /* table to be searched */ + { "asparagus", 10 }, + { "beans", 6 }, + { "tomato", 7 }, + { "watermelon", 11 }, +}; + +main() +{ + struct node *node_ptr, node; + /* routine to compare 2 nodes */ + static int node_compare(const void *, const void *); + char str_space[20]; /* space to read string into */ + + node.string = str_space; + while (scanf("%20s", node.string) != EOF) { + node_ptr = bsearch( &node, + table, sizeof(table)/sizeof(struct node), + sizeof(struct node), node_compare); + if (node_ptr != NULL) { + (void) printf("string = %20s, length = %d\en", + node_ptr\(mi>string, node_ptr\(mi>length); + } else { + (void)printf("not found: %20s\en", node.string); + } + } + return(0); +} + +/* routine to compare two nodes based on an */ +/* alphabetical ordering of the string field */ +static int +node_compare(const void *node1, const void *node2) { + return (strcmp( + ((const struct node *)node1)\(mi>string, + ((const struct node *)node2)\(mi>string)); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBhsearch\fR(3C), \fBlsearch\fR(3C), \fBqsort\fR(3C), \fBtsearch\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/bstring.3c b/usr/src/man/man3c/bstring.3c new file mode 100644 index 0000000000..2baf57c7f2 --- /dev/null +++ b/usr/src/man/man3c/bstring.3c @@ -0,0 +1,76 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH bstring 3C "15 Apr 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +bstring, bcopy, bcmp, bzero \- memory operations +.SH SYNOPSIS +.LP +.nf +#include <strings.h> + +\fBvoid\fR \fBbcopy\fR(\fBconst void *\fR\fIs1\fR, \fBvoid *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +\fBint\fR \fBbcmp\fR(\fBconst void *\fR\fIs1\fR, \fBconst void *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBbzero\fR(\fBvoid *\fR\fIs\fR, \fBsize_t\fR \fIn\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBbcopy()\fR, \fBbcmp()\fR, and \fBbzero()\fR functions operate as +efficiently as possible on memory areas (arrays of bytes bounded by a count, +not terminated by a null character). They do not check for the overflow of +any receiving memory area. These functions are similar to the \fBmemcpy()\fR, +\fBmemcmp()\fR, and \fBmemset()\fR functions described on the \fBmemory\fR(3C) +manual page. +.sp +.LP +The \fBbcopy()\fR function copies \fIn\fR bytes from memory area \fIs1\fR to +\fIs2\fR. Copying between objects that overlap will take place correctly. +.sp +.LP +The \fBbcmp()\fR function compares the first \fIn\fR bytes of its arguments, +returning 0 if they are identical and 1 otherwise. The \fBbcmp()\fR function +always returns 0 when \fIn\fR is 0. +.sp +.LP +The \fBbzero()\fR function sets the first \fIn\fR bytes in memory area \fIs\fR +to 0. +.SH WARNINGS +.sp +.LP +The \fBbcopy()\fR function takes parameters backwards from \fBmemcmp()\fR. See +\fBmemory\fR(3C). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBmemory\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/btowc.3c b/usr/src/man/man3c/btowc.3c new file mode 100644 index 0000000000..f6d3fa4403 --- /dev/null +++ b/usr/src/man/man3c/btowc.3c @@ -0,0 +1,70 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH btowc 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +btowc \- single-byte to wide-character conversion +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> +#include <wchar.h> + +\fBwint_t\fR \fBbtowc\fR(\fBint\fR \fIc\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBbtowc()\fR function determines whether \fIc\fR constitutes a valid +(one-byte) character in the initial shift state. +.sp +.LP +The behavior of this function is affected by the \fBLC_CTYPE\fR category of the +current locale. See \fBenviron\fR(5). +.SH RETURN VALUES +.sp +.LP +The \fBbtowc()\fR function returns \fBWEOF\fR if \fIc\fR has the value +\fBEOF\fR or if \fB(unsigned char)\fR\fIc\fR does not constitute a valid +(one-byte) character in the initial shift state. Otherwise, it returns the +wide-character representation of that character. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBsetlocale\fR(3C), \fBwctob\fR(3C), \fBattributes\fR(5), \fBenviron\fR(5), +\fBstandards\fR(5) +.SH NOTES +.sp +.LP +The \fBbtowc()\fR function can be used safely in multithreaded applications, as +long as \fBsetlocale\fR(3C) is not being called to change the locale. diff --git a/usr/src/man/man3c/catgets.3c b/usr/src/man/man3c/catgets.3c new file mode 100644 index 0000000000..6b85f4b32c --- /dev/null +++ b/usr/src/man/man3c/catgets.3c @@ -0,0 +1,133 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH catgets 3C "22 Mar 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +catgets \- read a program message +.SH SYNOPSIS +.LP +.nf +#include <nl_types.h> + +\fBchar *\fR\fBcatgets\fR(\fBnl_catd\fR \fIcatd\fR, \fBint\fR \fIset_num\fR, \fBint\fR \fImsg_num\fR, \fBconst char *\fR\fIs\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBcatgets()\fR function attempts to read message \fImsg_num\fR, in set +\fIset_num\fR, from the message catalog identified by \fIcatd\fR. The +\fIcatd\fR argument is a catalog descriptor returned from an earlier call to +\fBcatopen()\fR. The \fIs\fR argument points to a default message string which +will be returned by \fBcatgets()\fR if the identified message catalog is not +currently available. +.SH RETURN VALUES +.sp +.LP +If the identified message is retrieved successfully, \fBcatgets()\fR returns a +pointer to an internal buffer area containing the null terminated message +string. If the call is unsuccessful for any reason, \fBcatgets()\fR returns a +pointer to \fIs\fR and \fBerrno\fR may be set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBcatgets()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 11n +.rt +The \fIcatd\fR argument is not a valid message catalogue descriptor open for +reading. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADMSG\fR\fR +.ad +.RS 11n +.rt +The number of \fB%n\fR specifiers that appear in the message string specified +by \fIs\fR does not match the number of \fB%n\fR specifiers that appear in the +message identified by \fIset_id\fR and \fImsg_id\fR in the specified message +catalog. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 11n +.rt +The read operation was terminated due to the receipt of a signal, and no data +was transferred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 11n +.rt +The message catalog identified by \fIcatd\fR is corrupted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMSG\fR\fR +.ad +.RS 11n +.rt +The message identified by \fIset_id\fR and \fImsg_id\fR is not in the message +catalog. +.RE + +.SH USAGE +.sp +.LP +The \fBcatgets()\fR function can be used safely in multithreaded applications +as long as \fBsetlocale\fR(3C) is not being called to change the locale. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgencat\fR(1), \fBcatclose\fR(3C), \fBcatopen\fR(3C), \fBgettext\fR(3C), +\fBsetlocale\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) +.sp +.LP +\fIInternational Language Environments Guide\fR diff --git a/usr/src/man/man3c/catopen.3c b/usr/src/man/man3c/catopen.3c new file mode 100644 index 0000000000..6edfd036b2 --- /dev/null +++ b/usr/src/man/man3c/catopen.3c @@ -0,0 +1,357 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1995, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH catopen 3C "29 Dec 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +catopen, catclose \- open/close a message catalog +.SH SYNOPSIS +.LP +.nf +#include <nl_types.h> + +\fBnl_catd\fR \fBcatopen\fR(\fBconst char *\fR\fIname\fR, \fBint\fR \fIoflag\fR); +.fi + +.LP +.nf +\fBint\fR \fBcatclose\fR(\fBnl_catd\fR \fIcatd\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBcatopen()\fR function opens a message catalog and returns a message +catalog descriptor. \fIname\fR specifies the name of the message catalog to be +opened. If \fIname\fR contains a "/", then \fIname\fR specifies a complete +pathname for the message catalog; otherwise, the environment variable +\fBNLSPATH\fR is used and \fB/usr/lib/locale/\fR\fIlocale\fR\fB/LC_MESSAGES\fR +must exist. If \fBNLSPATH\fR does not exist in the environment, or if a message +catalog cannot be opened in any of the paths specified by \fBNLSPATH\fR, then +the default path \fB/usr/lib/locale/\fIlocale\fR/LC_MESSAGES\fR is used. In the +"C" locale, \fBcatopen()\fR will always succeed without checking the default +search path. +.sp +.LP +The names of message catalogs and their location in the filesystem can vary +from one system to another. Individual applications can choose to name or +locate message catalogs according to their own special needs. A mechanism is +therefore required to specify where the catalog resides. +.sp +.LP +The \fBNLSPATH\fR variable provides both the location of message catalogs, in +the form of a search path, and the naming conventions associated with message +catalog files. For example: +.sp +.in +2 +.nf +NLSPATH=/nlslib/%L/%N.cat:/nlslib/%N/%L +.fi +.in -2 + +.sp +.LP +The metacharacter \fB%\fR introduces a substitution field, where \fB%L\fR +substitutes the current setting of either the \fBLANG\fR environment variable, +if the value of \fIoflag\fR is \fB0\fR, or the \fBLC_MESSAGES\fR category, if +the value of \fIoflag\fR is \fBNL_CAT_LOCALE\fR, and \fB%N\fR substitutes the +value of the \fIname\fR parameter passed to \fBcatopen()\fR. Thus, in the above +example, \fBcatopen()\fR will search in \fB/nlslib/$LANG/\fIname\fR.cat\fR, if +\fIoflag\fR is \fB0\fR, or in \fB/nlslib/{LC_MESSAGES}/\fIname\fR.cat\fR, if +\fIoflag\fR is \fBNL_CAT_LOCALE\fR. +.sp +.LP +The \fBNLSPATH\fR variable will normally be set up on a system wide basis (in +\fB/etc/profile\fR) and thus makes the location and naming conventions +associated with message catalogs transparent to both programs and users. +.sp +.LP +The full set of metacharacters is: +.sp +.ne 2 +.mk +.na +\fB\fB%N\fR\fR +.ad +.RS 6n +.rt +The value of the name parameter passed to \fBcatopen()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%L\fR\fR +.ad +.RS 6n +.rt +The value of \fBLANG\fR or \fBLC_MESSAGES\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%l\fR\fR +.ad +.RS 6n +.rt +The value of the \fIlanguage\fR element of \fBLANG\fR or \fBLC_MESSAGES\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%t\fR\fR +.ad +.RS 6n +.rt +The value of the \fIterritory\fR element of \fBLANG\fR or \fBLC_MESSAGES\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%c\fR\fR +.ad +.RS 6n +.rt +The value of the \fIcodeset\fR element of \fBLANG\fR or \fBLC_MESSAGES\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%%\fR\fR +.ad +.RS 6n +.rt +A single %. +.RE + +.sp +.LP +The \fBLANG\fR environment variable provides the ability to specify the user's +requirements for native languages, local customs and character set, as an ASCII +string in the form +.sp +.in +2 +.nf +LANG=language[_territory[.codeset]] +.fi +.in -2 + +.sp +.LP +A user who speaks German as it is spoken in Austria and has a terminal which +operates in ISO 8859/1 codeset, would want the setting of the LANG variable to +be +.sp +.in +2 +.nf +LANG=De_A.88591 +.fi +.in -2 + +.sp +.LP +With this setting it should be possible for that user to find any relevant +catalogs should they exist. +.sp +.LP +Should the \fBLANG\fR variable not be set, the value of \fBLC_MESSAGES\fR as +returned by \fBsetlocale()\fR is used. If this is \fINULL,\fR the default path +as defined in <\fBnl_types.h\fR> is used. +.sp +.LP +A message catalogue descriptor remains valid in a process until that process +closes it, or a successful call to one of the \fBexec\fR functions. A change in +the setting of the \fBLC_MESSAGES\fR category may invalidate existing open +catalogues. +.sp +.LP +If a file descriptor is used to implement message catalogue descriptors, the +\fBFD_CLOEXEC\fR flag will be set; see <\fBfcntl.h\fR>. +.sp +.LP +If the value of \fIoflag\fR argument is \fB0\fR, the \fBLANG\fR environment +variable is used to locate the catalogue without regard to the +\fBLC_MESSAGES\fR category. If the \fIoflag\fR argument is +\fBNL_CAT_LOCALE\fR, the \fBLC_MESSAGES\fR category is used to locate the +message catalogue. +.sp +.LP +The \fBcatclose()\fR function closes the message catalog identified by +\fIcatd\fR. If a file descriptor is used to implement the type \fBnl_catd\fR, +that file descriptor will be closed. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBcatopen()\fR returns a message catalog +descriptor for use on subsequent calls to \fBcatgets()\fR and +\fBcatclose()\fR. Otherwise it returns \fB(nl_catd) \(mi1\fR. +.sp +.LP +Upon successful completion, \fBcatclose()\fR returns 0. Otherwise it returns +\(mi1 and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBcatopen()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 16n +.rt +Search permission is denied for the component of the path prefix of the message +catalogue or read permission is denied for the message catalogue. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 16n +.rt +There are \fBOPEN_MAX\fR file descriptors currently open in the calling +process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +The length of the pathname of the message catalogue exceeds \fIPATH_MAX\fR, or +a pathname component is longer than \fINAME_MAX\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +Pathname resolution of a symbolic link produced an intermediate result whose +length exceeds \fIPATH_MAX\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENFILE\fR\fR +.ad +.RS 16n +.rt +Too many files are currently open in the system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 16n +.rt +The message catalogue does not exist or the \fIname\fR argument points to an +empty string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 16n +.rt +Insufficient storage space is available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTDIR\fR\fR +.ad +.RS 16n +.rt +A component of the path prefix of the message catalogue is not a directory. +.RE + +.sp +.LP +The \fBcatclose()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 9n +.rt +The catalogue descriptor is not valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 9n +.rt +The \fBcatclose()\fR function was interrupted by a signal. +.RE + +.SH USAGE +.sp +.LP +The \fBcatopen()\fR and \fBcatclose()\fR functions can be used safely in +multithreaded applications, as long as \fBsetlocale\fR(3C) is not being called +to change the locale. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgencat\fR(1), \fBcatgets\fR(3C), \fBgettext\fR(3C), \fBnl_types.h\fR(3HEAD), +\fBsetlocale\fR(3C), \fBattributes\fR(5), \fBenviron\fR(5) diff --git a/usr/src/man/man3c/cfgetispeed.3c b/usr/src/man/man3c/cfgetispeed.3c new file mode 100644 index 0000000000..df53a01c69 --- /dev/null +++ b/usr/src/man/man3c/cfgetispeed.3c @@ -0,0 +1,75 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cfgetispeed 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +cfgetispeed, cfgetospeed \- get input and output baud rate +.SH SYNOPSIS +.LP +.nf +#include <termios.h> + +\fBspeed_t\fR \fBcfgetispeed\fR(\fBconst struct termios *\fR\fItermios_p\fR); +.fi + +.LP +.nf +\fBspeed_t\fR \fBcfgetospeed\fR(\fBconst struct termios *\fR\fItermios_p\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBcfgetispeed()\fR function extracts the input baud rate from the +\fBtermios\fR structure to which the \fItermios_p\fR argument points. +.sp +.LP +The \fBcfgetospeed()\fR function extracts the output baud rate from the +\fBtermios\fR structure to which the \fItermios_p\fR argument points. +.sp +.LP +These functions returns exactly the value in the \fBtermios\fR data structure, +without interpretation. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBcfgetispeed()\fR returns a value of type +\fBspeed_t\fR representing the input baud rate. +.sp +.LP +Upon successful completion, \fBcfgetospeed()\fR returns a value of type +\fBspeed_t\fR representing the output baud rate. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe, and Async-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBcfgetospeed\fR(3C), \fBtcgetattr\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5), \fBtermio\fR(7I) diff --git a/usr/src/man/man3c/cfsetispeed.3c b/usr/src/man/man3c/cfsetispeed.3c new file mode 100644 index 0000000000..abfb8a352c --- /dev/null +++ b/usr/src/man/man3c/cfsetispeed.3c @@ -0,0 +1,95 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cfsetispeed 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +cfsetispeed, cfsetospeed \- set input and output baud rate +.SH SYNOPSIS +.LP +.nf +#include <termios.h> + +\fBint\fR \fBcfsetispeed\fR(\fBstruct termios *\fR\fItermios_p\fR, \fBspeed_t\fR \fIspeed\fR); +.fi + +.LP +.nf +\fBint\fR \fBcfsetospeed\fR(\fBstruct termios *\fR\fItermios_p\fR, \fBspeed_t\fR \fIspeed\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBcfsetispeed()\fR function sets the input baud rate stored in the +structure pointed to by \fItermios_p\fR to \fIspeed.\fR +.sp +.LP +The \fBcfsetospeed()\fR function sets the output baud rate stored in the +structure pointed to by \fItermios_p\fR to \fIspeed.\fR +.sp +.LP +There is no effect on the baud rates set in the hardware until a subsequent +successful call to \fBtcsetattr\fR(3C) on the same \fBtermios\fR structure. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBcfsetispeed()\fR and \fBcfsetospeed()\fR return +\fB0\fR. Otherwise \fB\(mi1\fR is returned, and \fBerrno\fR may be set to +indicate the error. +.SH ERRORS +.sp +.LP +The \fBcfsetispeed()\fR and \fBcfsetospeed()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIspeed\fR value is not a valid baud rate. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of \fIspeed\fR is outside the range of possible speed values as +specified in \fB<termios.h>\fR\&. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe, and Async-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBcfgetispeed\fR(3C), \fBtcsetattr\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5), \fBtermio\fR(7I) diff --git a/usr/src/man/man3c/clock.3c b/usr/src/man/man3c/clock.3c new file mode 100644 index 0000000000..3eed93c744 --- /dev/null +++ b/usr/src/man/man3c/clock.3c @@ -0,0 +1,62 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH clock 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +clock \- report CPU time used +.SH SYNOPSIS +.LP +.nf +#include <time.h> + +\fBclock_t\fR \fBclock\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBclock()\fR function returns the amount of CPU time (in microseconds) +used since the first call to \fBclock()\fR in the calling process. The time +reported is the sum of the user and system times of the calling process and its +terminated child processes for which it has executed the \fBwait\fR(3C) +function, the \fBpclose\fR(3C) function, or the \fBsystem\fR(3C) function. +.SH RETURN VALUES +.sp +.LP +Dividing the value returned by \fBclock()\fR by the constant +\fBCLOCKS_PER_SEC\fR, defined in the <\fBtime.h\fR> header, will give the time +in seconds. If the process time used is not available or cannot be +represented, clock returns the value \fB(clock_t) \(mi1\fR. +.SH USAGE +.sp +.LP +The value returned by \fBclock()\fR is defined in microseconds for +compatibility with systems that have CPU clocks with much higher resolution. +Because of this, the value returned will wrap around after accumulating only +2147 seconds of CPU time (about 36 minutes). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBtimes\fR(2), \fBpopen\fR(3C), \fBsystem\fR(3C), \fBwait\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/clock_nanosleep.3c b/usr/src/man/man3c/clock_nanosleep.3c new file mode 100644 index 0000000000..3b27bf2ba2 --- /dev/null +++ b/usr/src/man/man3c/clock_nanosleep.3c @@ -0,0 +1,151 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH clock_nanosleep 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +clock_nanosleep \- high resolution sleep with specifiable clock +.SH SYNOPSIS +.LP +.nf +#include <time.h> + +\fBint\fR \fBclock_nanosleep\fR(\fBclockid_t\fR \fIclock_id\fR, \fBint\fR \fIflags\fR, + \fBconst struct timespec *\fR\fIrqtp\fR, \fBstruct timespec *\fR\fIrmtp\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +If the flag \fBTIMER_ABSTIME\fR is not set in the \fIflags\fR argument, the +\fBclock_nanosleep()\fR function causes the current thread to be suspended from +execution until either the time interval specified by the \fIrqtp\fR 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 is the clock specified by \fIclock_id\fR. +.sp +.LP +If the flag \fBTIMER_ABSTIME\fR is set in the \fIflags\fR argument, the +\fBclock_nanosleep()\fR function causes the current thread to be suspended from +execution until either the time value of the clock specified by \fIclock_id\fR +reaches the absolute time specified by the \fIrqtp\fR 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 \fIrqtp\fR is less than or equal to the time value of the +specified clock, then \fBclock_nanosleep()\fR returns immediately and the +calling process is not suspended. +.sp +.LP +The suspension time caused by this function can 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 \fBclock_nanosleep()\fR function (that is, with the +\fBTIMER_ABSTIME\fR flag not set) will not be less than the time interval +specified by rqtp, as measured by the corresponding clock. The suspension for +the absolute \fBclock_nanosleep()\fR function (that is, with the +\fBTIMER_ABSTIME\fR flag set) will be in effect at least until the value of the +corresponding clock reaches the absolute time specified by \fIrqtp\fR, except +for the case of being interrupted by a signal. +.sp +.LP +The use of the \fBclock_nanosleep()\fR function has no effect on the action or +blockage of any signal. +.sp +.LP +The \fBclock_nanosleep()\fR function fails if the \fIclock_id\fR argument +refers to the CPU-time clock of the calling thread. It is unspecified if +\fIclock_id\fR values of other CPU-time clocks are allowed. +.SH RETURN VALUES +.sp +.LP +If the \fBclock_nanosleep()\fR function returns because the requested time has +elapsed, its return value is 0. +.sp +.LP +If the \fBclock_nanosleep()\fR function returns because it has been interrupted +by a signal, it returns the corresponding error value. For the relative +\fBclock_nanosleep()\fR function, if the \fIrmtp\fR argument is non-null, the +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). +If the \fIrmtp\fR argument is NULL, the remaining time is not returned. The +absolute \fBclock_nanosleep()\fR function has no effect on the structure +referenced by \fIrmtp\fR. +.sp +.LP +If \fBclock_nanosleep()\fR fails, it shall return the corresponding error +value. +.SH ERRORS +.sp +.LP +The \fBclock_nanosleep()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 11n +.rt +The \fBclock_nanosleep()\fR function was interrupted by a signal. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 11n +.rt +The \fIrqtp\fR 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 +\fIflags\fR and the \fIrqtp\fR argument is outside the range for the clock +specified by \fIclock_id\fR; or the \fIclock_id\fR argument does not specify a +known clock, or specifies the CPU-time clock of the calling thread. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSUP\fR\fR +.ad +.RS 11n +.rt +The \fIclock_id\fR argument specifies a clock for which \fBclock_nanosleep()\fR +is not supported, such as a CPU-time clock. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBclock_getres\fR(3C), \fBnanosleep\fR(3C), \fBpthread_cond_timedwait\fR(3C), +\fBsleep\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/clock_settime.3c b/usr/src/man/man3c/clock_settime.3c new file mode 100644 index 0000000000..3ae62de1e9 --- /dev/null +++ b/usr/src/man/man3c/clock_settime.3c @@ -0,0 +1,168 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH clock_settime 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +clock_settime, clock_gettime, clock_getres \- high-resolution clock operations +.SH SYNOPSIS +.LP +.nf +#include <time.h> + +\fBint\fR \fBclock_settime\fR(\fBclockid_t\fR \fIclock_id\fR, \fBconst struct timespec *\fR\fItp\fR); +.fi + +.LP +.nf +\fBint\fR \fBclock_gettime\fR(\fBclockid_t\fR \fIclock_id\fR, \fBstruct timespec *\fR\fItp\fR); +.fi + +.LP +.nf +\fBint\fR \fBclock_getres\fR(\fBclockid_t\fR \fIclock_id\fR, \fBstruct timespec *\fR\fIres\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBclock_settime()\fR function sets the specified clock, \fIclock_id\fR, to +the value specified by \fItp\fR. Time values that are between two consecutive +non-negative integer multiples of the resolution of the specified clock are +truncated down to the smaller multiple of the resolution. +.sp +.LP +The \fBclock_gettime()\fR function returns the current value \fItp\fR for the +specified clock, \fIclock_id\fR. +.sp +.LP +The resolution of any clock can be obtained by calling \fBclock_getres()\fR. +Clock resolutions are system-dependent and cannot be set by a process. If the +argument \fIres\fR is not \fINULL\fR, the resolution of the specified clock is +stored in the location pointed to by \fIres\fR. If \fIres\fR is \fINULL\fR, the +clock resolution is not returned. If the time argument of \fBclock_settime()\fR +is not a multiple of \fIres\fR, then the value is truncated to a multiple of +\fIres\fR. +.sp +.LP +A clock may be systemwide (that is, visible to all processes) or per-process +(measuring time that is meaningful only within a process). +.sp +.LP +A \fIclock_id\fR of \fBCLOCK_REALTIME\fR is defined in <\fBtime.h\fR>. This +clock represents the realtime clock for the system. For this clock, the values +returned by \fBclock_gettime()\fR and specified by \fBclock_settime()\fR +represent the amount of time (in seconds and nanoseconds) since the Epoch. +Additional clocks may also be supported. The interpretation of time values for +these clocks is unspecified. +.sp +.LP +A \fIclock_id\fR of \fBCLOCK_HIGHRES\fR represents the non-adjustable, +high-resolution clock for the system. For this clock, the value returned by +\fBclock_gettime\fR(3C) represents the amount of time (in seconds and +nanoseconds) since some arbitrary time in the past; it is not correlated in any +way to the time of day, and thus is not subject to resetting or drifting by way +of \fBadjtime\fR(2), \fBntp_adjtime\fR(2), \fBsettimeofday\fR(3C), or +\fBclock_settime()\fR. The time source for this clock is the same as that for +\fBgethrtime\fR(3C). +.sp +.LP +Additional clocks may also be supported. The interpretation of time values for +these clocks is unspecified. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBclock_settime()\fR, \fBclock_gettime()\fR and \fBclock_getres()\fR +functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIclock_id\fR argument does not specify a known clock. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR\fR +.ad +.RS 10n +.rt +The functions \fBclock_settime()\fR, \fBclock_gettime()\fR, and +\fBclock_getres()\fR are not supported by this implementation. +.RE + +.sp +.LP +The \fBclock_settime()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fItp\fR argument to \fBclock_settime()\fR is outside the range for the +given clock ID; or the \fItp\fR argument specified a nanosecond value less than +zero or greater than or equal to 1000 million. +.RE + +.sp +.LP +The \fBclock_settime()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 9n +.rt +The requesting process does not have the appropriate privilege to set the +specified clock. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityCommitted +_ +MT-Level\fBclock_gettime()\fR is Async-Signal-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBtime\fR(2), \fBctime\fR(3C), \fBgethrtime\fR(3C), \fBtime.h\fR(3HEAD), +\fBtimer_gettime\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/closedir.3c b/usr/src/man/man3c/closedir.3c new file mode 100644 index 0000000000..0a15f47853 --- /dev/null +++ b/usr/src/man/man3c/closedir.3c @@ -0,0 +1,84 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH closedir 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +closedir \- close a directory stream +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <dirent.h> + +\fBint\fR \fBclosedir\fR(\fBDIR *\fR\fIdirp\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBclosedir()\fR function closes the directory stream referred to by the +argument \fIdirp.\fR Upon return, the value of \fIdirp\fR may no longer point +to an accessible object of the type \fBDIR\fR. If a file descriptor is used to +implement type \fBDIR\fR, that file descriptor will be closed. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBclosedir()\fR returns \fB0\fR. Otherwise, +\fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBclosedir()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 9n +.rt +The \fIdirp\fR argument does not refer to an open directory stream. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 9n +.rt +The \fBclosedir()\fR function was interrupted by a signal. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBopendir\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/closefrom.3c b/usr/src/man/man3c/closefrom.3c new file mode 100644 index 0000000000..ad207d80b0 --- /dev/null +++ b/usr/src/man/man3c/closefrom.3c @@ -0,0 +1,147 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH closefrom 3C "27 Apr 2000" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +closefrom, fdwalk \- close or iterate over open file descriptors +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBvoid\fR \fBclosefrom\fR(\fBint\fR \fIlowfd\fR); +.fi + +.LP +.nf +\fBint\fR \fBfdwalk\fR(\fBint\fR (*\fIfunc\fR)(\fBvoid\fR *, \fBint\fR), \fBvoid *\fR\fIcd\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBclosefrom()\fR function calls \fBclose\fR(2) on all open file +descriptors greater than or equal to \fIlowfd\fR. +.sp +.LP +The effect of \fBclosefrom\fR(\fIlowfd\fR) is the same as the code +.sp +.in +2 +.nf +#include <sys/resource.h> +struct rlimit rl; +int i; + +getrlimit(RLIMIT_NOFILE, &rl); +for (i = lowfd; i < rl.rlim_max; i++) + (void) close(i); +.fi +.in -2 + +.sp +.LP +except that \fBclose()\fR is called only on file descriptors that are actually +open, not on every possible file descriptor greater than or equal to +\fIlowfd\fR, and \fBclose()\fR is also called on any open file descriptors +greater than or equal to \fBrl.rlim_max\fR (and \fIlowfd\fR), should any exist. +.sp +.LP +The \fBfdwalk()\fR function first makes a list of all currently open file +descriptors. Then for each file descriptor in the list, it calls the +user-defined function, \fIfunc\fR(\fIcd\fR, \fIfd\fR), passing it the pointer +to the callback data, \fIcd\fR, and the value of the file descriptor from the +list, \fIfd\fR. The list is processed in file descriptor value order, lowest +numeric value first. +.sp +.LP +If \fIfunc\fR() returns a non-zero value, the iteration over the list is +terminated and \fBfdwalk()\fR returns the non-zero value returned by +\fIfunc\fR(). Otherwise, \fBfdwalk()\fR returns 0 after having called +\fIfunc\fR() for every file descriptor in the list. +.sp +.LP +The \fBfdwalk()\fR function can be used for fine-grained control over the +closing of file descriptors. For example, the \fBclosefrom()\fR function can +be implemented as: +.sp +.in +2 +.nf +static int +close_func(void *lowfdp, int fd) +{ + if (fd >= *(int *)lowfdp) + (void) close(fd); + return (0); +} + +void +closefrom(int lowfd) +{ + (void) fdwalk(close_func, &lowfd); +} +.fi +.in -2 + +.sp +.LP +The \fBfdwalk()\fR function can then be used to count the number of open files +in the process. +.SH RETURN VALUES +.sp +.LP +No return value is defined for \fBclosefrom()\fR. If \fBclose()\fR fails for +any of the open file descriptors, the error is ignored and the file descriptors +whose \fBclose()\fR operation failed might remain open on return from +\fBclosefrom()\fR. +.sp +.LP +The \fBfdwalk()\fR function returns the return value of the last call to the +callback function \fIfunc\fR(), or 0 if \fIfunc\fR() is never called (no open +files). +.SH ERRORS +.sp +.LP +No errors are defined. The \fBclosefrom()\fR and \fBfdwalk()\fR functions do +not set \fBerrno\fR but \fBerrno\fR can be set by \fBclose()\fR or by another +function called by the callback function, \fIfunc\fR(). +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/proc/self/fd\fR\fR +.ad +.RS 17n +.rt +directory (list of open files) +.RE + +.SH USAGE +.sp +.LP +The act of closing all open file descriptors should be performed only as the +first action of a daemon process. Closing file descriptors that are in use +elsewhere in the current process normally leads to disastrous results. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBclose\fR(2), \fBgetrlimit\fR(2), \fBproc\fR(4), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/cond_init.3c b/usr/src/man/man3c/cond_init.3c new file mode 100644 index 0000000000..3f17dcabce --- /dev/null +++ b/usr/src/man/man3c/cond_init.3c @@ -0,0 +1,443 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 1995 IEEE. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cond_init 3C "5 Jun 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +cond_init, cond_wait, cond_timedwait, cond_reltimedwait, cond_signal, +cond_broadcast, cond_destroy \- condition variables +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <thread.h> +#include <synch.h> + +\fBint\fR \fBcond_init\fR(\fBcond_t *\fR\fIcvp\fR, \fBint\fR \fItype\fR, \fBvoid *\fR\fIarg\fR); +.fi + +.LP +.nf +\fBint\fR \fBcond_wait\fR(\fBcond_t *\fR\fIcvp\fR, \fBmutex_t *\fR\fImp\fR); +.fi + +.LP +.nf +\fBint\fR \fBcond_timedwait\fR(\fBcond_t *\fR\fIcvp\fR, \fBmutex_t *\fR\fImp\fR, + \fBtimestruc_t *\fR\fIabstime\fR); +.fi + +.LP +.nf +\fBint\fR \fBcond_reltimedwait\fR(\fBcond_t *\fR\fIcvp\fR, \fBmutex_t *\fR\fImp\fR, + \fBtimestruc_t *\fR\fIreltime\fR); +.fi + +.LP +.nf +\fBint\fR \fBcond_signal\fR(\fBcond_t *\fR\fIcvp\fR); +.fi + +.LP +.nf +\fBint\fR \fBcond_broadcast\fR(\fBcond_t *\fR\fIcvp\fR); +.fi + +.LP +.nf +\fBint\fR \fBcond_destroy\fR(\fBcond_t *\fR\fIcvp\fR); +.fi + +.SH DESCRIPTION +.SS "Initialize" +.sp +.LP +Condition variables and mutexes should be global. Condition variables that are +allocated in writable memory can synchronize threads among processes if they +are shared by the cooperating processes (see \fBmmap\fR(2)) and are initialized +for this purpose. +.sp +.LP +The scope of a condition variable is either intra-process or inter-process. +This is dependent upon whether the argument is passed implicitly or explicitly +to the initialization of that condition variable. A condition variable does not +need to be explicitly initialized. A condition variable is initialized with all +zeros, by default, and its scope is set to within the calling process. For +inter-process synchronization, a condition variable must be initialized once, +and only once, before use. +.sp +.LP +A condition variable must not be simultaneously initialized by multiple threads +or re-initialized while in use by other threads. +.sp +.LP +Attributes of condition variables can be set to the default or customized at +initialization. +.sp +.LP +The \fBcond_init()\fR function initializes the condition variable pointed to by +\fIcvp\fR. A condition variable can have several different types of behavior, +specified by \fItype\fR. No current type uses \fIarg\fR although a future type +may specify additional behavior parameters with \fIarg\fR. The \fItype\fR +argument c take one of the following values: +.sp +.ne 2 +.mk +.na +\fB\fBUSYNC_THREAD\fR\fR +.ad +.RS 17n +.rt +The condition variable can synchronize threads only in this process. This is +the default. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUSYNC_PROCESS\fR\fR +.ad +.RS 17n +.rt +The condition variable can synchronize threads in this process and other +processes. Only one process should initialize the condition variable. The +object initialized with this attribute must be allocated in memory shared +between processes, either in System V shared memory (see \fBshmop\fR(2)) or in +memory mapped to a file (see \fBmmap\fR(2)). It is illegal to initialize the +object this way and to not allocate it in such shared memory. +.RE + +.sp +.LP +Initializing condition variables can also be accomplished by allocating in +zeroed memory, in which case, a \fItype\fR of \fBUSYNC_THREAD\fR is assumed. +.sp +.LP +If default condition variable attributes are used, statically allocated +condition variables can be initialized by the macro \fBDEFAULTCV\fR. +.sp +.LP +Default condition variable initialization (intra-process): +.sp +.in +2 +.nf +cond_t cvp; + +cond_init(&cvp, NULL, NULL); /*initialize condition variable + with default*/ +.fi +.in -2 + +.sp +.LP +or +.sp +.in +2 +.nf +cond_init(&cvp, USYNC_THREAD, NULL); +.fi +.in -2 + +.sp +.LP +or +.sp +.in +2 +.nf +cond_t cond = DEFAULTCV; +.fi +.in -2 + +.sp +.LP +Customized condition variable initialization (inter-process): +.sp +.in +2 +.nf +cond_init(&cvp, USYNC_PROCESS, NULL); /* initialize cv with + inter-process scope */ +.fi +.in -2 + +.SS "Condition Wait" +.sp +.LP +The condition wait interface allows a thread to wait for a condition and +atomically release the associated mutex that it needs to hold to check the +condition. The thread waits for another thread to make the condition true and +that thread's resulting call to signal and wakeup the waiting thread. +.sp +.LP +The \fBcond_wait()\fR function atomically releases the mutex pointed to by +\fImp\fR and causes the calling thread to block on the condition variable +pointed to by \fIcvp\fR. The blocked thread may be awakened by +\fBcond_signal()\fR, \fBcond_broadcast()\fR, or when interrupted by delivery of +a \fBUNIX\fR signal or a \fBfork()\fR. +.sp +.LP +The \fBcond_wait()\fR, \fBcond_timedwait()\fR, and \fBcond_reltimedwait()\fR +functions always return with the mutex locked and owned by the calling thread +even when returning an error, except when the mutex has the \fBLOCK_ROBUST\fR +attribute and has been left irrecoverable by the mutex's last owner. The +\fBcond_wait()\fR, \fBcond_timedwait()\fR, and \fBcond_reltimedwait()\fR +functions return the appropriate error value if they fail to internally +reacquire the mutex. +.SS "Condition Signaling" +.sp +.LP +A condition signal allows a thread to unblock a single thread waiting on the +condition variable, whereas a condition broadcast allows a thread to unblock +all threads waiting on the condition variable. +.sp +.LP +The \fBcond_signal()\fR function unblocks one thread that is blocked on the +condition variable pointed to by \fIcvp\fR. +.sp +.LP +The \fBcond_broadcast()\fR function unblocks all threads that are blocked on +the condition variable pointed to by \fIcvp\fR. +.sp +.LP +If no threads are blocked on the condition variable, then \fBcond_signal()\fR +and \fBcond_broadcast()\fR have no effect. +.sp +.LP +The \fBcond_signal()\fR or \fBcond_broadcast()\fR functions can be called by a +thread whether or not it currently owns the mutex that threads calling +\fBcond_wait()\fR, \fBcond_timedwait()\fR, or \fBcond_reltimedwait()\fR have +associated with the condition variable during their waits. If, however, +predictable scheduling behavior is required, then that mutex should be locked +by the thread prior to calling \fBcond_signal()\fR or \fBcond_broadcast()\fR. +.SS "Destroy" +.sp +.LP +The condition destroy functions destroy any state, but not the space, +associated with the condition variable. +.sp +.LP +The \fBcond_destroy()\fR function destroys any state associated with the +condition variable pointed to by \fIcvp\fR. The space for storing the condition +variable is not freed. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, these functions return \fB0\fR. Otherwise, a +non-zero value is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBcond_timedwait()\fR and \fBcond_reltimedwait()\fR functions will fail +if: +.sp +.ne 2 +.mk +.na +\fB\fBETIME\fR\fR +.ad +.RS 9n +.rt +The time specified by \fIabstime\fR or \fIreltime\fR has passed. +.RE + +.sp +.LP +The \fBcond_wait()\fR, \fBcond_timedwait()\fR, and \fBcond_reltimedwait()\fR +functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 9n +.rt +Interrupted. The calling thread was awakened by the delivery of a UNIX signal. +.RE + +.sp +.LP +If the mutex pointed to by \fImp\fR is a robust mutex (initialized with the +\fBLOCK_ROBUST\fR attribute), the \fBcond_wait()\fR, \fBcond_timedwait()\fR and +\fBcond_reltimedwait()\fR functions will, under the specified conditions, +return the following error values. For complete information, see the +description of the \fBmutex_lock()\fR function on the \fBmutex_init\fR(3C) +manual page. +.sp +.ne 2 +.mk +.na +\fB\fBENOTRECOVERABLE\fR\fR +.ad +.RS 19n +.rt +The mutex was protecting the state that has now been left irrecoverable. The +mutex has not been acquired. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOWNERDEAD\fR\fR +.ad +.RS 19n +.rt +The last owner of the mutex died while holding the mutex, possibly leaving the +state it was protecting inconsistent. The mutex is now owned by the caller. +.RE + +.sp +.LP +These functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +.rt +The \fIcond\fR, \fIattr\fR, \fIcvp\fR, \fIarg\fR, \fIabstime\fR, or \fImutex\fR +argument points to an illegal address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +Invalid argument. For \fBcond_init()\fR, \fItype\fR is not a recognized type. +For \fBcond_timedwait()\fR, the number of nanoseconds is greater than or equal +to 1,000,000,000. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRUse \fBcond_wait()\fR in a loop to test some condition. +.sp +.LP +The \fBcond_wait()\fR functin is normally used in a loop testing some +condition, as follows: + +.sp +.in +2 +.nf +(void) mutex_lock(mp); +while (cond == FALSE) { + (void) cond_wait(cvp, mp); +} +(void) mutex_unlock(mp); +.fi +.in -2 + +.LP +\fBExample 2 \fRUse \fBcond_timedwait()\fR in a loop to test some condition. +.sp +.LP +The \fBcond_timedwait()\fR function is normally used in a loop testing some +condition. It uses an absolute timeout value as follows: + +.sp +.in +2 +.nf +timestruc_t to; +\&... +(void) mutex_lock(mp); +to.tv_sec = time(NULL) + TIMEOUT; +to.tv_nsec = 0; +while (cond == FALSE) { + err = cond_timedwait(cvp, mp, &to); + if (err == ETIME) { + /* timeout, do something */ + break; + } +} +(void) mutex_unlock(mp); +.fi +.in -2 + +.LP +\fBExample 3 \fRUse \fBcond_reltimedwait()\fR in a loop to test some condition. +.sp +.LP +The \fBcond_reltimedwait()\fR function is normally used in a loop testing in +some condition. It uses a relative timeout value as follows: + +.sp +.in +2 +.nf +timestruc_t to; +\&... +(void) mutex_lock(mp); +while (cond == FALSE) { + to.tv_sec = TIMEOUT; + to.tv_nsec = 0; + err = cond_reltimedwait(cvp, mp, &to); + if (err == ETIME) { + /* timeout, do something */ + break; + } +} +(void) mutex_unlock(mp); +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfork\fR(2), \fBmmap\fR(2), \fBsetitimer\fR(2), \fBshmop\fR(2), +\fBmutex_init\fR(3C), \fBsignal\fR(3C), \fBattributes\fR(5), +\fBcondition\fR(5), \fBmutex\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +If more than one thread is blocked on a condition variable, the order in which +threads are unblocked is determined by the scheduling policy. When each thread, +unblocked as a result of a \fBcond_signal()\fR or \fBcond_broadcast()\fR, +returns from its call to \fBcond_wait()\fR or \fBcond_timedwait()\fR , the +thread owns the mutex with which it called \fBcond_wait()\fR, +\fBcond_timedwait()\fR, or \fBcond_reltimedwait()\fR. The thread(s) that are +unblocked compete for the mutex according to the scheduling policy and as if +each had called \fBmutex_lock\fR(3C). +.sp +.LP +When \fBcond_wait()\fR returns the value of the condition is indeterminate and +must be reevaluated. +.sp +.LP +The \fBcond_timedwait()\fR and \fBcond_reltimedwait()\fR functions are similar +to \fBcond_wait()\fR, except that the calling thread will not wait for the +condition to become true past the absolute time specified by \fIabstime\fR or +the relative time specified by \fIreltime\fR. Note that \fBcond_timedwait()\fR +or \fBcond_reltimedwait()\fR might continue to block as it trys to reacquire +the mutex pointed to by \fImp\fR, which may be locked by another thread. If +either \fBcond_timedwait()\fR or \fBcond_reltimedwait()\fR returns because of a +timeout, it returns the error value \fBETIME\fR. diff --git a/usr/src/man/man3c/confstr.3c b/usr/src/man/man3c/confstr.3c new file mode 100644 index 0000000000..a985bdd984 --- /dev/null +++ b/usr/src/man/man3c/confstr.3c @@ -0,0 +1,658 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH confstr 3C "15 Dec 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +confstr \- get configurable variables +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> + +\fBsize_t\fR \fBconfstr\fR(\fBint\fR \fIname\fR, \fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIlen\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBconfstr()\fR function provides a method for applications to get +configuration-defined string values. Its use and purpose are similar to the +\fBsysconf\fR(3C) function, but it is used where string values rather than +numeric values are returned. +.sp +.LP +The \fIname\fR argument represents the system variable to be queried. +.sp +.LP +If \fIlen\fR is not \fB0\fR, and if \fIname\fR has a configuration-defined +value, \fBconfstr()\fR copies that value into the \fIlen\fR-byte buffer +pointed to by \fIbuf\fR. If the string to be returned is longer than \fIlen\fR +bytes, including the terminating null, then \fBconfstr()\fR truncates the +string to \fIlen\fR\(mi1 bytes and null-terminates the result. The application +can detect that the string was truncated by comparing the value returned by +\fBconfstr()\fR with \fIlen\fR. +.sp +.LP +If \fIlen\fR is \fB0\fR, \fBconfstr()\fR still returns the integer value as +defined below, but does not return the string. +.sp +.LP +The \fBconfstr()\fR function supports the following values for \fIname\fR, +defined in \fB<unistd.h>\fR, for both SPARC and x86: +.sp +.ne 2 +.mk +.na +\fB\fB_CS_LFS64_CFLAGS\fR\fR +.ad +.sp .6 +.RS 4n +If \fB_LFS64_LARGEFILE\fR is defined in \fB<unistd.h>\fR, this value is the set +of initial options to be given to the \fBcc\fR and \fBc89\fR utilities to build +an application using the Large File Summit transitional compilation environment +(see \fBlfcompile64\fR(5)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_LFS64_LDFLAGS\fR\fR +.ad +.sp .6 +.RS 4n +If \fB_LFS64_LARGEFILE\fR is defined in \fB<unistd.h>\fR, this value is the set +of final options to be given to the \fBcc\fR and \fBc89\fR utilities to build +an application using the Large File Summit transitional compilation environment +(see \fBlfcompile64\fR(5)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_LFS64_LIBS\fR\fR +.ad +.sp .6 +.RS 4n +If \fB_LFS64_LARGEFILE\fR is defined in \fB<unistd.h>\fR, this value is the set +of libraries to be given to the \fBcc\fR and \fBc89\fR utilities to build an +application using the Large File Summit transitional compilation environment +(see \fBlfcompile64\fR(5)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_LFS64_LINTFLAGS\fR\fR +.ad +.sp .6 +.RS 4n +If \fB_LFS64_LARGEFILE\fR is defined in \fB<unistd.h>\fR, this value is the set +of options to be given to the \fBlint\fR utility to check application source +using the Large File Summit transitional compilation environment (see +\fBlfcompile64\fR(5)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_LFS_CFLAGS\fR\fR +.ad +.sp .6 +.RS 4n +If \fB_LFS_LARGEFILE\fR is defined in \fB<unistd.h>\fR, this value is the set +of initial options to be given to the \fBcc\fR and \fBc89\fR utilities to build +an application using the Large File Summit large file compilation environment +for 32-bit applications (see \fBlfcompile\fR(5)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_LFS_LDFLAGS\fR\fR +.ad +.sp .6 +.RS 4n +If \fB_LFS_LARGEFILE\fR is defined in \fB<unistd.h>\fR, this value is the set +of final options to be given to the \fBcc\fR and \fBc89\fR utilities to build +an application using the Large File Summit large file compilation environment +for 32-bit applications (see \fBlfcompile\fR(5)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_LFS_LIBS\fR\fR +.ad +.sp .6 +.RS 4n +If \fB_LFS_LARGEFILE\fR is defined in \fB<unistd.h>\fR, this value is the set +of libraries to be given to the \fBcc\fR and \fBc89\fR utilities to build an +application using the Large File Summit large file compilation environment for +32-bit applications (see \fBlfcompile\fR(5)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_LFS_LINTFLAGS\fR\fR +.ad +.sp .6 +.RS 4n +If \fB_LFS_LARGEFILE\fR is defined in \fB<unistd.h>\fR, this value is the set +of options to be given to the \fBlint\fR utility to check application source +using the Large File Summit large file compilation environment for 32-bit +applications (see \fBlfcompile\fR(5)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_PATH\fR\fR +.ad +.sp .6 +.RS 4n +If the ISO POSIX.2 standard is supported, this is the value for the \fBPATH\fR +environment variable that finds all standard utilities. Otherwise the meaning +of this value is unspecified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_POSIX_V6_ILP32_OFF32_CFLAGS\fR\fR +.ad +.sp .6 +.RS 4n +If \fBsysconf\fR(\fB_SC_V6_ILP32_OFF32\fR) returns -1, the meaning of this +value is unspecified. Otherwise, this value is the set of initial options to +be given to the \fBc99\fR utility to build an application using a programming +model with 32-bit \fBint\fR, \fBlong\fR, \fBpointer\fR, and \fBoff_t\fR types. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_POSIX_V6_ILP32_OFF32_LDFLAGS\fR\fR +.ad +.sp .6 +.RS 4n +If \fBsysconf\fR(\fB_SC_V6_ILP32_OFF32\fR) returns -1, the meaning of this +value is unspecified. Otherwise, this value is the set of final options to be +given to the \fBc99\fR utility to build an application using a programming +model with 32-bit \fBint\fR, \fBlong\fR, \fBpointer\fR, and \fBoff_t\fR types. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_POSIX_V6_ILP32_OFF32_LIBS\fR\fR +.ad +.sp .6 +.RS 4n +If \fBsysconf\fR(\fB_SC_V6_ILP32_OFF32\fR) returns -1, the meaning of this +value is unspecified. Otherwise, this value is the set of libraries to be given +to the \fBc99\fR utility to build an application using a programming model with +32-bit \fBint\fR, \fBlong\fR, \fBpointer\fR, and \fBoff_t\fR types. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_POSIX_V6_ILP32_OFFBIG_CFLAGS\fR\fR +.ad +.sp .6 +.RS 4n + If \fBsysconf\fR(\fB_SC_V6_ILP32_OFFBIG\fR) returns -1, the meaning of this +value is unspecified. Otherwise, this value is the set of initial options to be +given to the \fBc99\fR utility to build an application using a programming +model with 32-bit \fBint\fR, \fBlong\fR, and \fBpointer\fR types, and an +\fBoff_t\fR type using at least 64 bits. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_POSIX_V6_ILP32_OFFBIG_LDFLAGS\fR\fR +.ad +.sp .6 +.RS 4n +If \fBsysconf\fR(\fB_SC_V6_ILP32_OFFBIG\fR) returns -1, the meaning of this +value is unspecified. Otherwise, this value is the set of final options to be +given to the \fBc99\fR utility to build an application using a programming +model with 32-bit \fBint\fR, \fBlong\fR, and \fBpointer\fR types, and an +\fBoff_t\fR type using at least 64 bits. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_POSIX_V6_ILP32_OFFBIG_LIBS\fR\fR +.ad +.sp .6 +.RS 4n +If \fBsysconf\fR(\fB_SC_V6_ILP32_OFFBIG\fR) returns -1, the meaning of this +value is unspecified. Otherwise, this value is the set of libraries to be given +to the \fBc99\fR utility to build an application using a programming model with +32-bit \fBint\fR, \fBlong\fR, and \fBpointer\fR types, and an \fBoff_t\fR type +using at least 64 bits. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_POSIX_V6_LP64_OFF64_CFLAGS\fR\fR +.ad +.sp .6 +.RS 4n +If \fBsysconf\fR(\fB_SC_V6_LP64_OFF64\fR) returns -1, the meaning of this value +is unspecified. Otherwise, this value is the set of initial options to be given +to the \fBc99\fR utility to build an application using a programming model with +64-bit \fBint\fR, \fBlong\fR, \fBpointer\fR, and \fBoff_t\fR types. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_POSIX_V6_LP64_OFF64_LDFLAGS\fR\fR +.ad +.sp .6 +.RS 4n +If \fBsysconf\fR(\fB_SC_V6_LP64_OFF64\fR) returns -1, the meaning of this value +is unspecified. Otherwise, this value is the set of final options to be given +to the \fBc99\fR utility to build an application using a programming model with +64-bit \fBint\fR, \fBlong\fR, \fBpointer\fR, and \fBoff_t\fR types. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_POSIX_V6_LP64_OFF64_LIBS\fR\fR +.ad +.sp .6 +.RS 4n +If \fBsysconf\fR(\fB_SC_V6_LP64_OFF64\fR) returns -1, the meaning of this value +is unspecified. Otherwise, this value is the set of libraries to be given to +the \fBc99\fR utility to build an application using a programming model with +64-bit \fBint\fR, \fBlong\fR, \fBpointer\fR, and \fBoff_t\fR types. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_POSIX_V6_LPBIG_OFFBIG_CFLAGS\fR\fR +.ad +.sp .6 +.RS 4n +If \fBsysconf\fR(\fB_SC_V6_LPBIG_OFFBIG\fR) returns -1, the meaning of this +value is unspecified. Otherwise, this value is the set of initial options to be +given to the \fBc99\fR utility to build an application using a programming +model with an \fBint\fR type using at least 32 bits and \fBlong\fR, +\fBpointer\fR, and \fBoff_t\fR types using at least 64 bits. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_POSIX_V6_LPBIG_OFFBIG_LDFLAGS\fR\fR +.ad +.sp .6 +.RS 4n +If \fBsysconf\fR(\fB_SC_V6_LPBIG_OFFBIG\fR) returns -1, the meaning of this +value is unspecified. Otherwise, this value is the set of final options to be +given to the \fBc99\fR utility to build an application using a programming +model with an \fBint\fR type using at least 32 bits and \fBlong\fR, +\fBpointer\fR, and \fBoff_t\fR types using at least 64 bits. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_POSIX_V6_LPBIG_OFFBIG_LIBS\fR\fR +.ad +.sp .6 +.RS 4n +If \fBsysconf\fR(\fB_SC_V6_LPBIG_OFFBIG\fR) returns -1, the meaning of this +value is unspecified. Otherwise, this value is the set of libraries to be given +to the \fBc99\fR utility to build an application using a programming model with +an \fBint\fR type using at least 32 bits and \fBlong\fR, \fBpointer\fR, and +\fBoff_t\fR types using at least 64 bits. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_POSIX_V6_WIDTH_RESTRICTED_ENVS\fR\fR +.ad +.sp .6 +.RS 4n +This value is a <newline>-separated list of names of programming environments +supported by the implementation in which the widths of the \fBblksize_t\fR, +\fBcc_t\fR, \fBmode_t\fR, \fBnfds_t\fR, \fBpid_t\fR, \fBptrdiff_t\fR, +\fBsize_t\fR, \fBspeed_t\fR, \fBssize_t\fR, \fBsuseconds_t\fR, \fBtcflag_t\fR, +\fBuseconds_t\fR, \fBwchar_t\fR, and \fBwint_t\fR types are no greater than the +width of type \fBlong\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_XBS5_ILP32_OFF32_CFLAGS\fR\fR +.ad +.sp .6 +.RS 4n +If \fBsysconf(_SC_XBS5_ILP32_OFF32)\fR returns \(mi1 the meaning of this value +is unspecified. Otherwise, this value is the set of initial options to be +given to the \fBcc\fR and \fBc89\fR utilities to build an application using a +programming model with 32-bit \fBint\fR, \fBlong\fR, \fBpointer\fR, and +\fBoff_t\fR types. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_XBS5_ILP32_OFF32_LDFLAGS\fR\fR +.ad +.sp .6 +.RS 4n +If \fBsysconf(_SC_XBS5_ILP32_OFF32)\fR returns \(mi1 the meaning of this value +is unspecified. Otherwise, this value is the set of final options to be given +to the \fBcc\fR and \fBc89\fR utilities to build an application using a +programming model with 32-bit \fBint\fR, \fBlong\fR, \fBpointer\fR, and +\fBoff_t\fR types. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_XBS5_ILP32_OFF32_LIBS\fR\fR +.ad +.sp .6 +.RS 4n +If \fBsysconf(_SC_XBS5_ILP32_OFF32)\fR returns \(mi1 the meaning of this value +is unspecified. Otherwise, this value is the set of libraries to be given to +the \fBcc\fR and \fBc89\fR utilities to build an application using a +programming model with 32-bit \fBint\fR, \fBlong\fR, \fBpointer\fR, and +\fBoff_t\fR types. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_XBS5_ILP32_OFF32_LINTFLAGS\fR\fR +.ad +.sp .6 +.RS 4n +If \fBsysconf(_SC_XBS5_ILP32_OFF32)\fR returns \(mi1 the meaning of this value +is unspecified. Otherwise, this value is the set of options to be given to the +\fBlint\fR utility to check application source using a programming model with +32-bit \fBint\fR, \fBlong\fR, \fBpointer\fR, and \fBoff_t\fR types. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_XBS5_ILP32_OFFBIG_CFLAGS\fR\fR +.ad +.sp .6 +.RS 4n +If \fBsysconf(_SC_XBS5_ILP32_OFFBIG)\fR returns \(mi1 the meaning of this value +is unspecified. Otherwise, this value is the set of initial options to be +given to the \fBcc\fR and \fBc89\fR utilities to build an application using a +programming model with 32-bit \fBint\fR, \fBlong\fR, and \fBpointer\fR types, +and an \fBoff_t\fR type using at least 64 bits. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_XBS5_ILP32_OFFBIG_LDFLAGS\fR\fR +.ad +.sp .6 +.RS 4n +If \fBsysconf(SC_XBS5_ILP32_OFFBIG)\fR returns \(mi1 the meaning of this value +is unspecified. Otherwise, this value is the set of final options to be given +to the \fBcc\fR and \fBc89\fR utilities to build an application using a +programming model with 32-bit \fBint\fR, \fBlong\fR, and \fBpointer\fR types, +and an \fBoff_t\fR type using at least 64 bits. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_XBS5_ILP32_OFFBIG_LIBS\fR\fR +.ad +.sp .6 +.RS 4n +If \fBsysconf(_SC_XBS5_ILP32_OFFBIG)\fR returns \(mi1 the meaning of this value +is unspecified. Otherwise, this value is the set of libraries to be given to +the \fBcc\fR and \fBc89\fR utilities to build an application using a +programming model with 32-bit \fBint\fR, \fBlong\fR, and \fBpointer\fR types, +and an \fBoff_t\fR type using at least 64 bits. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_XBS5_ILP32_OFFBIG_LINTFLAGS\fR\fR +.ad +.sp .6 +.RS 4n +If \fBsysconf(_SC_XBS5_ILP32_OFFBIG)\fR returns \(mi1 the meaning of this value +is unspecified. Otherwise, this value is the set of options to be given to the +\fBlint\fR utility to check an application using a programming model with +32-bit \fBint\fR, \fBlong\fR, and \fBpointer\fR types, and an \fBoff_t\fR type +using at least 64 bits. +.RE + +.sp +.LP +The \fBconfstr()\fR function supports the following values for \fIname\fR, +defined in \fB<unistd.h>\fR, for SPARC only: +.sp +.ne 2 +.mk +.na +\fB\fB_CS_XBS5_LP64_OFF64_CFLAGS\fR\fR +.ad +.sp .6 +.RS 4n +If \fBsysconf(_SC_XBS5_LP64_OFF64)\fR returns \(mi1 the meaning of this value +is unspecified. Otherwise, this value is the set of initial options to be +given to the \fBcc\fR and \fBc89\fR utilities to build an application using a +programming model with 64-bit \fBint\fR, \fBlong\fR, \fBpointer\fR, and +\fBoff_t\fR types. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_XBS5_LP64_OFF64_LDFLAGS\fR\fR +.ad +.sp .6 +.RS 4n +If \fBsysconf(_SC_XBS5_LP64_OFF64)\fR returns \(mi1 the meaning of this value +is unspecified. Otherwise, this value is the set of final options to be given +to the \fBcc\fR and \fBc89\fR utilities to build an application using a +programming model with 64-bit \fBint\fR, \fBlong\fR, \fBpointer\fR, and +\fBoff_t\fR types. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_XBS5_LP64_OFF64_LIBS\fR\fR +.ad +.sp .6 +.RS 4n +If \fBsysconf(_SC_XBS5_LP64_OFF64)\fR returns \(mi1 the meaning of this value +is unspecified. Otherwise, this value is the set of libraries to be given to +the \fBcc\fR and \fBc89\fR utilities to build an application using a +programming model with 64-bit \fBint\fR, \fBlong\fR, \fBpointer\fR, and +\fBoff_t\fR types. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_XBS5_LP64_OFF64_LINTFLAGS\fR\fR +.ad +.sp .6 +.RS 4n +If \fBsysconf(_SC_XBS5_LP64_OFF64)\fR returns \(mi1 the meaning of this value +is unspecified. Otherwise, this value is the set of options to be given to the +\fBlint\fR utility to check application source using a programming model with +64-bit \fBint\fR, \fBlong\fR, \fBpointer\fR, and \fBoff_t\fR types. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_XBS5_LPBIG_OFFBIG_CFLAGS\fR\fR +.ad +.sp .6 +.RS 4n +If \fBsysconf(_SC_XBS5_LPBIG_OFFBIG)\fR returns \(mi1 the meaning of this value +is unspecified. Otherwise, this value is the set of initial options to be +given to the \fBcc\fR and \fBc89\fR utilities to build an application using a +programming model with an \fBint\fR type using at least 32 bits and \fBlong\fR, +\fBpointer\fR, and \fBoff_t\fR types using at least 64 bits. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_XBS5_LPBIG_OFFBIG_LDFLAGS\fR\fR +.ad +.sp .6 +.RS 4n +If \fBsysconf(_SC_XBS5_LPBIG_OFFBIG)\fR returns \(mi1 the meaning of this value +is unspecified. Otherwise, this value is the set of final options to be given +to the \fBcc\fR and \fBc89\fR utilities to build an application using a +programming model with an \fBint\fR type using at least 32 bits and \fBlong\fR, +\fBpointer\fR, and \fBoff_t\fR types using at least 64 bits. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_XBS5_LPBIG_OFFBIG_LIBS\fR\fR +.ad +.sp .6 +.RS 4n +If \fBsysconf(_SC_XBS5_LPBIG_OFFBIG)\fR returns \(mi1 the meaning of this value +is unspecified. Otherwise, this value is the set of libraries to be given to +the \fBcc\fR and \fBc89\fR utilities to build an application using a +programming model with an \fBint\fR type using at least 32 bits and \fBlong\fR, +\fBpointer\fR, and \fBoff_t\fR types using at least 64 bits. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_CS_XBS5_LPBIG_OFFBIG_LINTFLAGS\fR\fR +.ad +.sp .6 +.RS 4n +If \fBsysconf(_SC_XBS5_LPBIG_OFFBIG)\fR returns \(mi1 the meaning of this value +is unspecified. Otherwise, this value is the set of options to be given to the +\fBlint\fR utility to check application source using a programming model with +an \fBint\fR type using at least 32 bits and \fBlong\fR, \fBpointer\fR, and +\fBoff_t\fR types using at least 64 bits. +.RE + +.SH RETURN VALUES +.sp +.LP +If \fIname\fR has a configuration-defined value, the \fBconfstr()\fR function +returns the size of buffer that would be needed to hold the entire +configuration-defined value. If this return value is greater than \fIlen\fR, +the string returned in \fIbuf\fR is truncated. +.sp +.LP +If \fIname\fR is invalid, \fBconfstr()\fR returns \fB0\fR and sets \fBerrno\fR +to indicate the error. +.sp +.LP +If \fIname\fR does not have a configuration-defined value, \fBconfstr()\fR +returns \fB0\fR and leaves \fBerrno\fR unchanged. +.SH ERRORS +.sp +.LP +The \fBconfstr()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of the \fIname\fR argument is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMt-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpathconf\fR(2), \fBsysconf\fR(3C), \fBattributes\fR(5), \fBlfcompile\fR(5), +\fBlfcompile64\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/crypt.3c b/usr/src/man/man3c/crypt.3c new file mode 100644 index 0000000000..b5c9afa0e9 --- /dev/null +++ b/usr/src/man/man3c/crypt.3c @@ -0,0 +1,139 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH crypt 3C "28 Sep 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +crypt \- string encoding function +.SH SYNOPSIS +.LP +.nf +#include <crypt.h> + +\fBchar *\fR\fBcrypt\fR(\fBconst char *\fR\fIkey\fR, \fBconst char *\fR\fIsalt\fR); +.fi + +.SS "Standard conforming" +.LP +.nf +#include <unistd.h> + +\fBchar *\fR\fBcrypt\fR(\fBconst char *\fR\fIkey\fR, \fBconst char *\fR\fIsalt\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBcrypt()\fR function encodes strings suitable for secure storage as +passwords. It generates the password hash given the \fIkey\fR and \fIsalt\fR. +.sp +.LP +The \fIkey\fR argument is the plain text password to be encrypted. +.sp +.LP +If the first character of \fIsalt\fR is "$", \fBcrypt()\fR uses +\fBcrypt.conf\fR(4) to determine which shared module to load for the encryption +algorithm. The algorithm name \fBcrypt()\fR uses to search in \fBcrypt.conf\fR +is the string between the first and second "$", or between the first "$" and +first "," if a "," comes before the second "$". +.sp +.LP +If the first character of \fIsalt\fR is not "$", the algorithm described on +\fBcrypt_unix\fR(5) is used. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBcrypt()\fR returns a pointer to the encoded +string. Otherwise it returns a null pointer and sets \fBerrno\fR to indicate +the error. +.sp +.LP +The return value points to static data that is overwritten by each call. +.SH ERRORS +.sp +.LP +The \fBcrypt()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 11n +.rt +An entry in \fBcrypt.conf\fR is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBELIBACC\fR\fR +.ad +.RS 11n +.rt +The required shared library was not found. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 11n +.rt +There is insufficient memory to generate the hash. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR\fR +.ad +.RS 11n +.rt +The functionality is not supported on this system. +.RE + +.SH USAGE +.sp +.LP +The values returned by this function might not be portable among +standard-conforming systems. See \fBstandards\fR(5). +.sp +.LP +Applications should not use \fBcrypt()\fR to store or verify user passwords but +should use the functions described on \fBpam\fR(3PAM) instead. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpasswd\fR(1), \fBcrypt_genhash_impl\fR(3C), \fBcrypt_gensalt\fR(3C), +\fBcrypt_gensalt_impl\fR(3C), \fBgetpassphrase\fR(3C), \fBpam\fR(3PAM), +\fBpasswd\fR(4), \fBpolicy.conf\fR(4), \fBattributes\fR(5), +\fBcrypt_unix\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/crypt_genhash_impl.3c b/usr/src/man/man3c/crypt_genhash_impl.3c new file mode 100644 index 0000000000..ec2805d0e6 --- /dev/null +++ b/usr/src/man/man3c/crypt_genhash_impl.3c @@ -0,0 +1,109 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH crypt_genhash_impl 3C "10 Jun 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +crypt_genhash_impl \- generate encrypted password +.SH SYNOPSIS +.LP +.nf +#include <crypt.h> + +\fBchar *\fR\fBcrypt_genhash_impl\fR(\fBchar *\fR\fIctbuffer\fR, \fBsize_t\fR \fIctbufflen\fR, + \fBconst char *\fR\fIplaintext\fR, \fBconst char *\fR\fIsalt\fR, \fBconst char **\fR\fIparams\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBcrypt_genhash_impl()\fR function is called by \fBcrypt\fR(3C) to +generate the encrypted password \fIplaintext\fR. +.sp +.LP +The \fIctbuffer\fR argument is a pointer to an MT-safe buffer of +\fIctbufflen\fR size that is used to return the result. +.sp +.LP +The \fIsalt\fR argument is the salt used in encoding. +.sp +.LP +The \fIparams\fR argument is an \fIargv\fR-like null-terminated vector of type +\fBchar *\fR. The first element of \fIparams\fR represents the mechanism token +name from \fBcrypt.conf\fR(4). The remaining elements of \fIparams\fR represent +strings of the form <\fBparameter\fR>[=<\fBvalue\fR>] to allow passing in +additional information from the \fBcrypt.conf\fR entry, such as specifing +rounds information "\fBrounds=4096\fR". +.sp +.LP +The \fBcrypt_genhash_impl()\fR function must not \fBfree\fR(3C) \fIctbufflen\fR +on error. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBcrypt_genhash_impl()\fR returns a pointer to the +encoded version of \fIplaintext\fR. Otherwise a null pointer is returned and +\fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBcrypt_genhash_impl()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 11n +.rt +The configuration file \fBcrypt.conf\fR contains an invalid entry. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBELIBACC\fR\fR +.ad +.RS 11n +.rt +The required shared library was not found. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 11n +.rt +There is insufficient memory to perform hashing. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpasswd\fR(1), \fBcrypt\fR(3C), \fBcrypt_gensalt_impl\fR(3C), \fBfree\fR(3C), +\fBgetpassphrase\fR(3C), \fBcrypt.conf\fR(4), \fBpasswd\fR(4), +\fBattributes\fR(5) diff --git a/usr/src/man/man3c/crypt_gensalt.3c b/usr/src/man/man3c/crypt_gensalt.3c new file mode 100644 index 0000000000..c6fa5eeeb9 --- /dev/null +++ b/usr/src/man/man3c/crypt_gensalt.3c @@ -0,0 +1,119 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH crypt_gensalt 3C "10 Jun 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +crypt_gensalt \- generate salt string for string encoding +.SH SYNOPSIS +.LP +.nf +#include <crypt.h> + +\fBchar *\fR\fBcrypt_gensalt\fR(\fBconst char *\fR\fIoldsalt\fR, \fBconst struct passwd *\fR\fIuserinfo\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBcrypt_gensalt()\fR function generates the salt string required by +\fBcrypt\fR(3C). +.sp +.LP +If \fIoldsalt\fR is \fINULL\fR, \fBcrypt_gensalt()\fR uses the algorithm +defined by \fBCRYPT_DEFAULT\fR in \fB/etc/security/policy.conf\fR. See +\fBpolicy.conf\fR(4). +.sp +.LP +If \fIoldsalt\fR is non-null, \fBcrypt_gensalt()\fR determines if the algorithm +specified by \fIoldsalt\fR is allowable by checking the +\fBCRYPT_ALGORITHMS_ALLOW\fR and \fBCRYPT_ALGORITHMS_DEPRECATE\fR variables in +\fB/etc/security/policy.conf\fR. If the algorithm is allowed, +\fBcrypt_gensalt()\fR loads the appropriate shared library and calls +\fBcrypt_gensalt_impl\fR(3C). If the algorithm is not allowed or there is no +entry for it in \fBcrypt.conf\fR, \fBcrypt_gensalt()\fR uses the default +algorithm. +.sp +.LP +The mechanism just described provides a means to migrate users to new password +hashing algorithms when the password is changed. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBcrypt_gensalt()\fR returns a pointer to the new +salt. Otherwise a null pointer is returned and \fBerrno\fR is set to indicate +the error. +.SH ERRORS +.sp +.LP +The \fBcrypt_gensalt()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 11n +.rt +The configuration file \fBcrypt.conf\fR contains an invalid entry. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBELIBACC\fR\fR +.ad +.RS 11n +.rt +The required shared library was not found. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 11n +.rt +There is insufficient memory to perform hashing. +.RE + +.SH USAGE +.sp +.LP +The value returned by \fBcrypt_gensalt()\fR points to a null-terminated string. +The caller of \fBcrypt_gensalt()\fR is responsible for calling \fBfree\fR(3C). +.sp +.LP +Applications dealing with user authentication and password changing should not +call \fBcrypt_gensalt()\fR directly but should instead call the appropriate +\fBpam\fR(3PAM) functions. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpasswd\fR(1), \fBcrypt\fR(3C), \fBcrypt_genhash_impl\fR(3C), +\fBcrypt_gensalt_impl\fR(3C), \fBgetpassphrase\fR(3C), \fBmalloc\fR(3C), +\fBpam\fR(3PAM), \fBcrypt.conf\fR(4), \fBpasswd\fR(4), \fBpolicy.conf\fR(4), +\fBattributes\fR(5) diff --git a/usr/src/man/man3c/crypt_gensalt_impl.3c b/usr/src/man/man3c/crypt_gensalt_impl.3c new file mode 100644 index 0000000000..74e53bdea6 --- /dev/null +++ b/usr/src/man/man3c/crypt_gensalt_impl.3c @@ -0,0 +1,112 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH crypt_gensalt_impl 3C "10 Jun 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +crypt_gensalt_impl \- generate salt for password encryption +.SH SYNOPSIS +.LP +.nf +#include <crypt.h> + +\fBchar *\fR\fBcrypt_gensalt_impl\fR(\fBchar *\fR\fIgsbuffer\fR, \fBsize_t\fR \fIgsbufflen\fR, + \fBconst char *\fR\fIoldsalt\fR, \fBconst struct passwd *\fR\fIuserinfo\fR, + \fBconst char **\fR\fIparams\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBcrypt_gensalt_impl()\fR function is called by \fBcrypt_gensalt\fR(3C) to +generate the salt for password encryption. +.sp +.LP +The \fIgsbuffer\fR argument is a pointer to an MT-safe buffer of size +\fIgsbufflen\fR. +.sp +.LP +The \fIoldsalt\fR and \fIuserinfo\fR arguments are passed unchanged from +\fBcrypt_gensalt\fR(3C). +.sp +.LP +The \fIparams\fR argument is an \fIargv\fR-like null terminated vector of type +\fBchar *\fR. The first element of \fIparams\fR represents the mechanism token +name from \fBcrypt.conf\fR(4). The remaining elements of \fIparams\fR represent +strings of the form <\fBparameter\fR>[=<\fBvalue\fR>] to allow passing in +additional information from the \fBcrypt.conf\fR entry, such as specifying +rounds information "\fBrounds=4096\fR". +.sp +.LP +The value returned by \fBcrypt_gensalt_impl()\fR points to a thread-specific +buffer to be freed by the caller of \fBcrypt_gensalt\fR(3C) after calling +\fBcrypt\fR(3C). +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBcrypt_gensalt_impl()\fR returns a pointer to the +new salt. Otherwise a null pointer is returned and \fBerrno\fR is set to +indicate the error. +.SH ERRORS +.sp +.LP +The \fBcrypt_gensalt_impl()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 11n +.rt +The configuration file \fBcrypt.conf\fR contains an invalid entry. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBELIBACC\fR\fR +.ad +.RS 11n +.rt +The required crypt shared library was not found. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 11n +.rt +There is insufficient memory to perform hashing. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpasswd\fR(1), \fBcrypt\fR(3C), \fBcrypt_genhash_impl\fR(3C), +\fBcrypt_gensalt\fR(3C), \fBgetpassphrase\fR(3C), \fBcrypt.conf\fR(4), +\fBpasswd\fR(4), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/cset.3c b/usr/src/man/man3c/cset.3c new file mode 100644 index 0000000000..106d69df49 --- /dev/null +++ b/usr/src/man/man3c/cset.3c @@ -0,0 +1,108 @@ +'\" te +.\" Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cset 3C "16 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +cset, csetlen, csetcol, csetno, wcsetno \- get information on EUC codesets +.SH SYNOPSIS +.LP +.nf +#include <euc.h> + +\fBint\fR \fBcsetlen\fR(\fBint\fR \fIcodeset\fR); +.fi + +.LP +.nf +\fBint\fR \fBcsetcol\fR(\fBint\fR \fIcodeset\fR); +.fi + +.LP +.nf +\fBint\fR \fBcsetno\fR(\fBunsigned char\fR \fIc\fR); +.fi + +.LP +.nf +#include <widec.h> + +\fBint\fR \fBwcsetno\fR(\fBwchar_t\fR \fIpc\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +Both \fBcsetlen()\fR and \fBcsetcol()\fR take a code set number \fIcodeset\fR, +which must be 0, 1, 2, or 3. The \fBcsetlen()\fR function returns the number of +bytes needed to represent a character of the given Extended Unix Code (EUC) +code set, excluding the single-shift characters SS2 and SS3 for codesets 2 and +3. The \fBcsetcol()\fR function returns the number of columns a character in +the given \fBEUC\fR code set would take on the display. +.sp +.LP +The \fBcsetno()\fR function is implemented as a macro that returns a codeset +number (0, 1, 2, or 3) for the \fBEUC\fR character whose first byte is \fIc\fR. +For example, +.sp +.in +2 +.nf +#include<euc.h> +\|.\|.\|. +x+=csetcol(csetno(c)); +.fi +.in -2 + +.sp +.LP +increments a counter "x" (such as the cursor position) by the width of the +character whose first byte is \fIc\fR. +.sp +.LP +The \fBwcsetno()\fR function is implemented as a macro that returns a codeset +number (0, 1, 2, or 3) for the given process code character \fIpc\fR. For +example, +.sp +.in +2 +.nf +#include<euc.h> +#include<widec.h> +\|.\|.\|. +x+=csetcol(wcsetno(pc)); +.fi +.in -2 + +.sp +.LP +increments a counter "x" (such as the cursor position) by the width of the +Process Code character \fIpc\fR. +.SH USAGE +.sp +.LP +These functions work only for the EUC locales. +.sp +.LP +The \fBcset()\fR, \fBcsetlen()\fR, \fBcsetcol()\fR, \fBcsetno()\fR, and +\fBwcsetno()\fR functions can be used safely in multithreaded applications, as +long as \fBsetlocale\fR(3C) is not being called to change the locale. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) cw(2.75i) +lw(2.75i) lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +MT-LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBsetlocale\fR(3C) \fBeuclen\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/ctermid.3c b/usr/src/man/man3c/ctermid.3c new file mode 100644 index 0000000000..b4a8820c85 --- /dev/null +++ b/usr/src/man/man3c/ctermid.3c @@ -0,0 +1,83 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ctermid 3C "25 Jul 2000" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +ctermid, ctermid_r \- generate path name for controlling terminal +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBchar *\fR\fBctermid\fR(\fBchar *\fR\fIs\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBctermid_r\fR(\fBchar *\fR\fIs\fR); +.fi + +.SH DESCRIPTION +.SS "\fBctermid()\fR" +.sp +.LP +The \fBctermid()\fR function generates the path name of the controlling +terminal for the current process and stores it in a string. +.sp +.LP +If \fIs\fR is a null pointer, the string is stored in an internal static area +whose address is returned and whose contents are overwritten at the next call +to \fBctermid()\fR. Otherwise, \fIs\fR is assumed to point to a character array +of at least \fBL_ctermid\fR elements. The path name is placed in this array and +the value of \fIs\fR is returned. The constant \fBL_ctermid\fR is defined in +the header \fB<stdio.h>\fR\&. +.SS "\fBctermid_r()\fR" +.sp +.LP +The \fBctermid_r()\fR function behaves as \fBctermid()\fR except that if +\fIs\fR is a null pointer, the function returns \fINULL\fR. +.SH USAGE +.sp +.LP +The difference between \fBctermid()\fR and \fBttyname\fR(3C) is that +\fBttyname()\fR must be passed a file descriptor and returns the actual name of +the terminal associated with that file descriptor, while \fBctermid()\fR +returns a string (\fB/dev/tty\fR) that will refer to the terminal if used as a +file name. The \fBttyname()\fR function is useful only if the process already +has at least one file open to a terminal. +.sp +.LP +The \fBctermid()\fR function is unsafe in multithreaded applications. The +\fBctermid_r()\fR function is MT-Safe and should be used instead. +.sp +.LP +When compiling multithreaded applications, the \fB_REENTRANT\fR flag must be +defined on the compile line. This flag should be used only with multithreaded +applications. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface Stability\fBctermid()\fR is Standard +_ +MT-LevelT{ +\fBctermid()\fR is Unsafe; \fBctermid_r()\fR is MT-Safe +T} +.TE + +.SH SEE ALSO +.sp +.LP +\fBttyname\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/ctime.3c b/usr/src/man/man3c/ctime.3c new file mode 100644 index 0000000000..7bb23cb23f --- /dev/null +++ b/usr/src/man/man3c/ctime.3c @@ -0,0 +1,401 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ctime 3C "27 May 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +ctime, ctime_r, localtime, localtime_r, gmtime, gmtime_r, asctime, asctime_r, +tzset \- convert date and time to string +.SH SYNOPSIS +.LP +.nf +#include <time.h> + +\fBchar *\fR\fBctime\fR(\fBconst time_t *\fR\fIclock\fR); +.fi + +.LP +.nf +\fBstruct tm *\fR\fBlocaltime\fR(\fBconst time_t *\fR\fIclock\fR); +.fi + +.LP +.nf +\fBstruct tm *\fR\fBgmtime\fR(\fBconst time_t *\fR\fIclock\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBasctime\fR(\fBconst struct tm *\fR\fItm\fR); +.fi + +.LP +.nf +extern time_t timezone, altzone; +extern int daylight; +extern char *tzname[2]; + +\fBvoid\fR \fBtzset\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBctime_r\fR(\fBconst time_t *\fR\fIclock\fR, \fBchar *\fR\fIbuf\fR, \fBint\fR \fIbuflen\fR); +.fi + +.LP +.nf +\fBstruct tm *\fR\fBlocaltime_r\fR(\fBconst time_t *restrict\fR \fIclock\fR, + \fBstruct tm *restrict\fR \fIres\fR); +.fi + +.LP +.nf +\fBstruct tm *\fR\fBgmtime_r\fR(\fBconst time_t *restrict\fR \fIclock\fR, + \fBstruct tm *restrict\fR \fIres\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBasctime_r\fR(\fBconst struct tm *restrict\fR \fItm\fR, \fBchar *restrict\fR \fIbuf\fR, + \fBint\fR \fIbuflen\fR); +.fi + +.SS "Standard conforming" +.LP +.nf +cc [ \fIflag\fR... ] \fIfile\fR... \fB-D_POSIX_PTHREAD_SEMANTICS\fR [ \fIlibrary\fR... ] + +\fBchar *\fR\fBctime_r\fR(\fBconst time_t *\fR\fIclock\fR, \fBchar *\fR\fIbuf\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBasctime_r\fR(\fBconst struct tm *\fR\fItm\fR, \fBchar *\fR\fIbuf\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBctime()\fR function converts the time pointed to by \fIclock\fR, +representing the time in seconds since the Epoch (00:00:00 UTC, January 1, +1970), to local time in the form of a 26-character string, as shown below. Time +zone and daylight savings corrections are made before string generation. The +fields are in constant width: +.sp +.LP +Fri Sep 13 00:00:00 1986\en\e0 +.sp +.LP +The \fBctime()\fR function is equivalent to: +.sp +.LP +\fBasctime(localtime(\fR\fIclock\fR\fB\fR\fB))\fR +.sp +.LP +The \fBctime()\fR, \fBasctime()\fR, \fBgmtime()\fR, and \fBlocaltime()\fR +functions return values in one of two thread-specific data objects: a +broken-down time structure and an array of \fBchar\fR. Execution of any of the +functions can overwrite the information returned in either of these objects by +any of the other functions executed by the same thread. +.sp +.LP +The \fBctime_r()\fR function has the same functionality as \fBctime()\fR except +that the caller must supply a buffer \fIbuf\fR with length \fIbuflen\fR to +store the result; \fIbuf\fR must be at least 26 bytes. The standard-conforming +\fBctime_r()\fR function does not take a \fIbuflen\fR parameter. +.sp +.LP +The \fBlocaltime()\fR and \fBgmtime()\fR functions return pointers to \fBtm\fR +structures (see below). The \fBlocaltime()\fR function corrects for the main +time zone and possible alternate ("daylight savings") time zone; the +\fBgmtime()\fR function converts directly to Coordinated Universal Time (UTC), +which is what the UNIX system uses internally. +.sp +.LP +The \fBlocaltime_r()\fR and \fBgmtime_r()\fR functions have the same +functionality as \fBlocaltime()\fR and \fBgmtime()\fR respectively, except that +the caller must supply a buffer \fIres\fR to store the result. +.sp +.LP +The \fBasctime()\fR function converts a \fBtm\fR structure to a 26-character +string, as shown in the previous example, and returns a pointer to the string. +.sp +.LP +The \fBasctime_r()\fR function has the same functionality as \fBasctime()\fR +except that the caller must supply a buffer \fIbuf\fR with length \fIbuflen\fR +for the result to be stored. The \fIbuf\fR argument must be at least 26 bytes. +The standard-conforming \fBasctime_r()\fR function does not take a \fIbuflen\fR +parameter. The \fBasctime_r()\fR function returns a pointer to \fIbuf\fR upon +success. In case of failure, \fINULL\fR is returned and \fBerrno\fR is set. +.sp +.LP +Declarations of all the functions and externals, and the \fBtm\fR structure, +are in the <\fBtime.h\fR> header. The members of the \fBtm\fR structure are: +.sp +.in +2 +.nf +int tm_sec; /* seconds after the minute \(em [0, 60] */ + /* for leap seconds */ +int tm_min; /* minutes after the hour \(em [0, 59] */ +int tm_hour; /* hour since midnight \(em [0, 23] */ +int tm_mday; /* day of the month \(em [1, 31] */ +int tm_mon; /* months since January \(em [0, 11] */ +int tm_year; /* years since 1900 */ +int tm_wday; /* days since Sunday \(em [0, 6] */ +int tm_yday; /* days since January 1 \(em [0, 365] */ +int tm_isdst; /* flag for alternate daylight savings time */ +.fi +.in -2 + +.sp +.LP +The value of \fBtm_isdst\fR is positive if daylight savings time is in effect, +zero if daylight savings time is not in effect, and negative if the information +is not available. Previously, the value of \fBtm_isdst\fR was defined as +non-zero if daylight savings was in effect. +.sp +.LP +The external \fBtime_t\fR variable \fBaltzone\fR contains the difference, in +seconds, between Coordinated Universal Time and the alternate time zone. The +external variable \fBtimezone\fR contains the difference, in seconds, between +UTC and local standard time. The external variable \fBdaylight\fR indicates +whether time should reflect daylight savings time. Both \fBtimezone\fR and +\fBaltzone\fR default to 0 (UTC). The external variable \fBdaylight\fR is +non-zero if an alternate time zone exists. The time zone names are contained in +the external variable \fBtzname\fR, which by default is set to: +.sp +.LP +char *tzname[2] = { "GMT", "\|" }; +.sp +.LP +These functions know about the peculiarities of this conversion for various +time periods for the \fBU.S.\fR (specifically, the years 1974, 1975, and 1987). +They start handling the new daylight savings time starting with the first +Sunday in April, 1987. +.sp +.LP +The \fBtzset()\fR function uses the contents of the environment variable +\fBTZ\fR to override the value of the different external variables. It is +called by \fBasctime()\fR and can also be called by the user. If \fBTZ\fR is +not specified or has an invalid setting, \fBtzset()\fR uses \fBGMT0\fR. See +\fBenviron\fR(5) for a description of the \fBTZ\fR environment variable. +.sp +.LP +Starting and ending times are relative to the current local time zone. If the +alternate time zone start and end dates and the time are not provided, the days +for the United States that year will be used and the time will be 2 AM. If the +start and end dates are provided but the time is not provided, the time will be +2 AM. The effects of \fBtzset()\fR change the values of the external variables +\fBtimezone\fR, \fBaltzone\fR, \fBdaylight\fR, and \fBtzname\fR. +.sp +.LP +Note that in most installations, \fBTZ\fR is set to the correct value by +default when the user logs on, using the local \fB/etc/default/init\fR file +(see \fBTIMEZONE\fR(4)). +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBgmtime()\fR and \fBlocaltime()\fR functions +return a pointer to a \fBstruct tm\fR. If an error is detected, \fBgmtime()\fR +and \fBlocaltime()\fR return a null pointer. +.sp +.LP +Upon successful completion, the \fBgmtime_r()\fR and \fBlocaltime_r()\fR +functions return the address of the structure pointed to by the \fIres\fR +argument. If an error is detected, \fBgmtime_r()\fR and \fBlocaltime_r()\fR +return a null pointer and set \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBctime_r()\fR and \fBasctime_r()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBERANGE\fR\fR +.ad +.RS 10n +.rt +The length of the buffer supplied by the caller is not large enough to store +the result. +.RE + +.sp +.LP +The \fBgmtime()\fR, \fBgmtime_r()\fR, \fBlocaltime()\fR, and +\fBlocaltime_r()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEOVERFLOW\fR\fR +.ad +.RS 13n +.rt +The result cannot be represented. +.RE + +.SH USAGE +.sp +.LP +These functions do not support localized date and time formats. The +\fBstrftime\fR(3C) function can be used when localization is required. +.sp +.LP +The \fBlocaltime()\fR, \fBlocaltime_r()\fR, \fBgmtime()\fR, \fBgmtime_r()\fR, +\fBctime()\fR, and \fBctime_r()\fR functions assume Gregorian dates. Times +before the adoption of the Gregorian calendar will not match historial records. +.SH EXAMPLES +.LP +\fBExample 1 \fRExamples of the \fBtzset()\fR function. +.sp +.LP +The \fBtzset()\fR function scans the contents of the environment variable and +assigns the different fields to the respective variable. For example, the most +complete setting for New Jersey in 1986 could be: + +.sp +.in +2 +.nf +EST5EDT4,116/2:00:00,298/2:00:00 +.fi +.in -2 + +.sp +.LP +or simply + +.sp +.in +2 +.nf +EST5EDT +.fi +.in -2 + +.sp +.LP +An example of a southern hemisphere setting such as the Cook Islands could be + +.sp +.in +2 +.nf +KDT9:30KST10:00,63/5:00,302/20:00 +.fi +.in -2 + +.sp +.LP +In the longer version of the New Jersey example of \fBTZ,\fR +\fBtzname\fR[\fB0\fR] is EST, \fBtimezone\fR is set to 5*60*60, +\fBtzname\fR[\fB1\fR] is EDT, \fBaltzone\fR is set to 4*60*60, the starting +date of the alternate time zone is the 117th day at 2 AM, the ending date of +the alternate time zone is the 299th day at 2 AM (using zero-based Julian +days), and \fBdaylight\fR is set positive. Starting and ending times are +relative to the current local time zone. If the alternate time zone start and +end dates and the time are not provided, the days for the United States that +year will be used and the time will be 2 AM. If the start and end dates are +provided but the time is not provided, the time will be 2 AM. The effects of +\fBtzset()\fR are thus to change the values of the external variables +\fBtimezone\fR, \fBaltzone\fR, \fBdaylight\fR, and \fBtzname\fR. The +\fBctime()\fR, \fBlocaltime()\fR, \fBmktime()\fR, and \fBstrftime()\fR +functions also update these external variables as if they had called +\fBtzset()\fR at the time specified by the \fBtime_t\fR or \fBstruct tm\fR +value that they are converting. + +.SH BUGS +.sp +.LP +The \fBzoneinfo\fR timezone data files do not transition past Tue Jan 19 +03:14:07 2038 UTC. Therefore for 64-bit applications using \fBzoneinfo\fR +timezones, calculations beyond this date might not use the correct offset from +standard time, and could return incorrect values. This affects the 64-bit +version of \fBlocaltime()\fR, \fBlocaltime_r()\fR, \fBctime()\fR, and +\fBctime_r()\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +CSIEnabled +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe with exceptions +.TE + +.sp +.LP +The \fBasctime()\fR, \fBctime()\fR, \fBgmtime()\fR, and \fBlocaltime()\fR +functions are safe to use in multithread applications because they employ +thread-specific data. However, their use is discouraged because standards do +not require them to be thread-safe. The \fBasctime_r()\fR and \fBgmtime_r()\fR +functions are MT-Safe. The \fBctime_r()\fR, \fBlocaltime_r()\fR, and +\fBtzset()\fR functions are MT-Safe in multithread applications, as long as no +user-defined function directly modifies one of the following variables: +\fBtimezone\fR, \fBaltzone\fR, \fBdaylight\fR, and \fBtzname\fR. These four +variables are not MT-Safe to access. They are modified by the \fBtzset()\fR +function in an MT-Safe manner. The \fBmktime()\fR, \fBlocaltime_r()\fR, and +\fBctime_r()\fR functions call \fBtzset()\fR. +.SH SEE ALSO +.sp +.LP +\fBtime\fR(2), \fBIntro\fR(3), \fBgetenv\fR(3C), \fBmktime\fR(3C), +\fBprintf\fR(3C), \fBputenv\fR(3C), \fBsetlocale\fR(3C), \fBstrftime\fR(3C), +\fBTIMEZONE\fR(4), \fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +When compiling multithreaded programs, see \fBIntro\fR(3). +.sp +.LP +The return values for \fBasctime()\fR, \fBctime()\fR, \fBgmtime()\fR, and +\fBlocaltime()\fR point to thread-specific data whose content is overwritten by +each call by the same thread. +.sp +.LP +Setting the time during the interval of change from \fBtimezone\fR to +\fBaltzone\fR or vice versa can produce unpredictable results. The system +administrator must change the Julian start and end days annually. +.sp +.LP +If \fBtzset()\fR has previously evaluated the timezone identified by the value +of the \fBTZ\fR environment variable, \fBtzset()\fR can reuse the previous +settings of the external variables \fBaltzone\fR, \fBdaylight\fR, +\fBtimezone\fR, and \fBtzname\fR[] associated with that timezone. +.sp +.LP +Solaris 2.4 and earlier releases provided definitions of the \fBctime_r()\fR, +\fBlocaltime_r()\fR, \fBgmtime_r()\fR, and \fBasctime_r()\fR functions as +specified in POSIX.1c Draft 6. The final POSIX.1c standard changed the +interface for \fBctime_r()\fR and \fBasctime_r()\fR. Support for the Draft 6 +interface is provided for compatibility only and might not be supported in +future releases. New applications and libraries should use the +standard-conforming interface. +.sp +.LP +For POSIX.1c-conforming applications, the \fB_POSIX_PTHREAD_SEMANTICS\fR and +\fB_REENTRANT\fR flags are automatically turned on by defining the +\fB_POSIX_C_SOURCE\fR flag with a value >= 199506L. +.sp +.LP +In Solaris 10, \fBgmtime()\fR, \fBgmtime_r()\fR, \fBlocaltime()\fR, and +\fBlocaltime_r()\fR were updated to return a null pointer if an error is +detected. This change was based on the SUSv3 specification. See +\fBstandards\fR(5). diff --git a/usr/src/man/man3c/ctype.3c b/usr/src/man/man3c/ctype.3c new file mode 100644 index 0000000000..3f518acd5a --- /dev/null +++ b/usr/src/man/man3c/ctype.3c @@ -0,0 +1,374 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 1992, X/Open Company Limited All Rights Reserved. Portions Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ctype 3C "28 Jan 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +ctype, isalpha, isalnum, isascii, isblank, iscntrl, isdigit, islower, isprint, +isspace, isupper, ispunct, isgraph, isxdigit \- character handling +.SH SYNOPSIS +.LP +.nf +#include <ctype.h> + +\fBint\fR \fBisalpha\fR(\fBint\fR \fIc\fR); +.fi + +.LP +.nf +\fBint\fR \fBisalnum\fR(\fBint\fR \fIc\fR); +.fi + +.LP +.nf +\fBint\fR \fBisascii\fR(\fBint\fR \fIc\fR); +.fi + +.LP +.nf +\fBint\fR \fBisblank\fR(\fBint\fR \fIc\fR); +.fi + +.LP +.nf +\fBint\fR \fBiscntrl\fR(\fBint\fR \fIc\fR); +.fi + +.LP +.nf +\fBint\fR \fBisdigit\fR(\fBint\fR \fIc\fR); +.fi + +.LP +.nf +\fBint\fR \fBisgraph\fR(\fBint\fR \fIc\fR); +.fi + +.LP +.nf +\fBint\fR \fBislower\fR(\fBint\fR \fIc\fR); +.fi + +.LP +.nf +\fBint\fR \fBisprint\fR(\fBint\fR \fIc\fR); +.fi + +.LP +.nf +\fBint\fR \fBispunct\fR(\fBint\fR \fIc\fR); +.fi + +.LP +.nf +\fBint\fR \fBisspace\fR(\fBint\fR \fIc\fR); +.fi + +.LP +.nf +\fBint\fR \fBisupper\fR(\fBint\fR \fIc\fR); +.fi + +.LP +.nf +\fBint\fR \fBisxdigit\fR(\fBint\fR \fIc\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These macros classify character-coded integer values. Each is a predicate +returning non-zero for true, \fB0\fR for false. The behavior of these macros, +except \fBisascii()\fR, is affected by the current locale (see +\fBsetlocale\fR(3C)). To modify the behavior, change the \fBLC_TYPE\fR category +in \fBsetlocale()\fR, that is, \fBsetlocale(\fR\fBLC_CTYPE\fR, +\fInewlocale\fR). In the "C" locale, or in a locale where character type +information is not defined, characters are classified according to the rules of +the \fBUS-ASCII\fR 7-bit coded character set. +.sp +.LP +The \fBisascii()\fR macro is defined on all integer values. The rest are +defined only where the argument is an \fBint\fR, the value of which is +representable as an \fBunsigned char\fR, or \fBEOF\fR, which is defined by the +<\fBstdio.h\fR> header and represents end-of-file. +.sp +.LP +Functions exist for all the macros defined below. To get the function form, the +macro name must be undefined (for example, \fB#undef isdigit\fR). +.sp +.LP +For macros described with \fBDefault\fR and \fBStandard conforming\fR versions, +standard-conforming behavior is provided for standard-conforming applications +(see \fBstandards\fR(5)) and for applications that define +\fB__XPG4_CHAR_CLASS__\fR before including <\fBctype.h\fR>. +.SS "Default" +.sp +.ne 2 +.mk +.na +\fB\fBisalpha()\fR\fR +.ad +.RS 13n +.rt +Tests for any character for which \fBisupper()\fR or \fBislower()\fR is true. +.RE + +.SS "Standard conforming" +.sp +.ne 2 +.mk +.na +\fB\fBisalpha()\fR\fR +.ad +.RS 13n +.rt +Tests for any character for which \fBisupper()\fR or \fBislower()\fR is true, +or any character that is one of the current locale-defined set of characters +for which none of \fBiscntrl()\fR, \fBisdigit()\fR, \fBispunct()\fR, or +\fBisspace()\fR is true. In "C" locale, \fBisalpha()\fR returns true only for +the characters for which \fBisupper()\fR or \fBislower()\fR is true. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBisalnum()\fR\fR +.ad +.RS 13n +.rt +Tests for any character for which \fBisalpha()\fR or \fBisdigit()\fR is true +(letter or digit). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBisascii()\fR\fR +.ad +.RS 13n +.rt +Tests for any ASCII character, code between \fB0\fR and \fB0177\fR inclusive. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBisblank()\fR\fR +.ad +.RS 13n +.rt +Tests whether \fIc\fR is a character of class blank in the current locale. This +macro/function is not available to applications conforming to standards prior +to SUSv3. See \fBstandards\fR(5) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBiscntrl()\fR\fR +.ad +.RS 13n +.rt +Tests for any ``control character'' as defined by the character set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBisdigit()\fR\fR +.ad +.RS 13n +.rt +Tests for any decimal-digit character. +.RE + +.SS "Default" +.sp +.ne 2 +.mk +.na +\fB\fBisgraph()\fR\fR +.ad +.RS 13n +.rt +Tests for any character for which \fBispunct()\fR, \fBisupper()\fR, +\fBislower()\fR, and \fBisdigit()\fR is true. +.RE + +.SS "Standard conforming" +.sp +.ne 2 +.mk +.na +\fB\fBisgraph()\fR\fR +.ad +.RS 13n +.rt +Tests for any character for which \fBisalnum()\fR and \fBispunct()\fR are true, +or any character in the current locale-defined "graph" class which is neither a +space ("\|") nor a character for which \fBiscntrl()\fR is true. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBislower()\fR\fR +.ad +.RS 13n +.rt +Tests for any character that is a lower-case letter or is one of the current +locale-defined set of characters for which none of \fBiscntrl()\fR, +\fBisdigit()\fR, \fBispunct()\fR, \fBisspace()\fR, or \fBisupper()\fR is true. +In the "C" locale, \fBislower()\fR returns true only for the characters defined +as lower-case \fBASCII\fR characters. +.RE + +.SS "Default" +.sp +.ne 2 +.mk +.na +\fB\fBisprint()\fR\fR +.ad +.RS 13n +.rt +Tests for any character for which \fBispunct()\fR, \fBisupper()\fR, +\fBislower()\fR, \fBisdigit()\fR, and the space character ("\|") is true. +.RE + +.SS "Standard conforming" +.sp +.ne 2 +.mk +.na +\fB\fBisprint()\fR\fR +.ad +.RS 13n +.rt +Tests for any character for which \fBiscntrl()\fR is false, and +\fBisalnum()\fR, \fBisgraph()\fR, \fBispunct()\fR, the space character ("\|"), +and the characters in the current locale-defined "print" class are true. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBispunct()\fR\fR +.ad +.RS 13n +.rt +Tests for any printing character which is neither a space ("\|") nor a +character for which \fBisalnum()\fR or \fBiscntrl()\fR is true. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBisspace()\fR\fR +.ad +.RS 13n +.rt +Tests for any space, tab, carriage-return, newline, vertical-tab or form-feed +(standard white-space characters) or for one of the current locale-defined set +of characters for which \fBisalnum()\fR is false. In the "C" locale, +\fBisspace()\fR returns true only for the standard white-space characters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBisupper()\fR\fR +.ad +.RS 13n +.rt +Tests for any character that is an upper-case letter or is one of the current +locale-defined set of characters for which none of \fBiscntrl()\fR, +\fBisdigit()\fR, \fBispunct()\fR, \fBisspace()\fR, or \fBislower()\fR is true. +In the "C" locale, \fBisupper()\fR returns true only for the characters defined +as upper-case \fBASCII\fR characters. +.RE + +.SS "Default" +.sp +.ne 2 +.mk +.na +\fB\fBisxdigit()\fR\fR +.ad +.RS 14n +.rt +Tests for any hexadecimal-digit character (\fB[0\(mi9]\fR, \fB[A\(miF]\fR, or +\fB[a\(mif]\fR). +.RE + +.SS "Standard conforming" +.sp +.ne 2 +.mk +.na +\fB\fBisxdigit()\fR\fR +.ad +.RS 14n +.rt +Tests for any hexadecimal-digit character (\fB[0\(mi9]\fR, \fB[A\(miF]\fR, or +\fB[a\(mif]\fR or the current locale-defined sets of characters representing +the hexadecimal digits \fB10\fR to \fB15\fR inclusive). In the "C" locale, only +.sp +.in +2 +.nf +0 1 2 3 4 5 6 7 8 9 A B C D E F a b c d e f +.fi +.in -2 + +are included. +.RE + +.SH RETURN VALUES +.sp +.LP +If the argument to any of the character handling macros is not in the domain of +the function, the result is undefined. Otherwise, the macro or function returns +non-zero if the classification is \fBTRUE\fR and \fB0\fR if the classification +is \fBFALSE\fR. +.SH USAGE +.sp +.LP +These macros or functions can be used safely in multithreaded applications, as +long as \fBsetlocale\fR(3C) is not being called to change the locale. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +CSIEnabled +Interface StabilityStandard +MT-LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBsetlocale\fR(3C), \fBstdio\fR(3C), \fBascii\fR(5), \fBenviron\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/cuserid.3c b/usr/src/man/man3c/cuserid.3c new file mode 100644 index 0000000000..02bf30287d --- /dev/null +++ b/usr/src/man/man3c/cuserid.3c @@ -0,0 +1,57 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cuserid 3C "30 Dec 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +cuserid \- get character login name of the user +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBchar *\fR\fBcuserid\fR(\fBchar *\fR\fIs\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBcuserid()\fR function generates a character-string representation of the +login name under which the owner of the current process is logged in. If +\fIs\fR is a null pointer, this representation is generated in an internal +static area whose address is returned. Otherwise, \fIs\fR is assumed to point +to an array of at least \fBL_cuserid\fR characters; the representation is left +in this array. The constant \fBL_cuserid\fR is defined in the <\fBstdio.h\fR> +header. +.sp +.LP +In multithreaded applications, the caller must always supply an array \fIs\fR +for the return value. +.SH RETURN VALUES +.sp +.LP +If the login name cannot be found, \fBcuserid()\fR returns a null pointer. If +\fIs\fR is not a null pointer, the null character \fB`\e0'\fR will be placed at +\fIs\fR[\fB0\fR]. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgetlogin\fR(3C), \fBgetpwnam\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/daemon.3c b/usr/src/man/man3c/daemon.3c new file mode 100644 index 0000000000..b82c45b9d6 --- /dev/null +++ b/usr/src/man/man3c/daemon.3c @@ -0,0 +1,118 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH daemon 3C "15 Sep 2009" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +daemon \- basic daemonization function +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBint\fR \fBdaemon\fR(\fBint\fR \fInochdir\fR, \fBint\fR \fInoclose\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBdaemon()\fR function provides a means for applications to run in the +background. +.sp +.LP +This function ensures that the process calling this function: +.RS +4 +.TP +.ie t \(bu +.el o +runs in the background +.RE +.RS +4 +.TP +.ie t \(bu +.el o +detaches from the controlling terminal +.RE +.RS +4 +.TP +.ie t \(bu +.el o +forms a new process group +.RE +.RS +4 +.TP +.ie t \(bu +.el o +is not a session group leader. +.RE +.sp +.LP +The arguments to this function are treated as boolean variables and are +evaluated using negative logic. +.sp +.LP +If the \fInochdir\fR argument is zero the working directory will be changed to +the root directory (/); otherwise it will not be. +.sp +.LP +If the \fInoclose\fR argument is zero the descriptors 0, 1, and 2 (normally +corresponding to standard input, output and error output, depending on the +application) will be redirected to \fB/dev/null\fR; otherwise they will not be. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBdaemon()\fR returns 0. Otherwise it returns -1 +and sets \fBerrno\fR to the values specified for \fBfork\fR(2), +\fBsetsid\fR(2), \fBopen\fR(2), and \fBdup\fR(2). +.sp +.LP +If \fBdaemon()\fR is called with \fInoclose\fR set to 0 and fails to redirect +descriptors 0, 1, and 2 to \fB/dev/null\fR, those descriptors are not +guaranteed to be the same as before the call. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing daemon to run a process in the background. +.sp +.LP +The \fBmain()\fR function of a network server could look like this: + +.sp +.in +2 +.nf +int background; /* background flag */ + +/* Load and verify the configuration. */ + +/* Go into background. */ +if (background && daemon(0, 0) < 0) + err(1, "daemon"); + +/* Process requests here. */ +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelAsync-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(2), \fBdup\fR(2), \fBfork\fR(2), \fBopen\fR(2), \fBsetsid\fR(2), +\fBattributes\fR(5) diff --git a/usr/src/man/man3c/decimal_to_floating.3c b/usr/src/man/man3c/decimal_to_floating.3c new file mode 100644 index 0000000000..8357ae14ab --- /dev/null +++ b/usr/src/man/man3c/decimal_to_floating.3c @@ -0,0 +1,101 @@ +'\" te +.\" Copyright (c) 1996, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH decimal_to_floating 3C "1 Oct 2001" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +decimal_to_floating, decimal_to_single, decimal_to_double, decimal_to_extended, +decimal_to_quadruple \- convert decimal record to floating-point value +.SH SYNOPSIS +.LP +.nf +#include <floatingpoint.h> + +\fBvoid\fR \fBdecimal_to_single\fR(\fBsingle *\fR\fIpx\fR, \fBdecimal_mode *\fR\fIpm\fR, + \fBdecimal_record *\fR\fIpd\fR, \fBfp_exception_field_type *\fR\fIps\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBdecimal_to_double\fR(\fBdouble *\fR\fIpx\fR, \fBdecimal_mode *\fR\fIpm\fR, + \fBdecimal_record *\fR\fIpd\fR, \fBfp_exception_field_type *\fR\fIps\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBdecimal_to_extended\fR(\fBextended *\fR\fIpx\fR, \fBdecimal_mode *\fR\fIpm\fR, + \fBdecimal_record *\fR\fIpd\fR, \fBfp_exception_field_type *\fR\fIps\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBdecimal_to_quadruple\fR(\fBquadruple *\fR\fIpx\fR, \fBdecimal_mode *\fR\fIpm\fR, + \fBdecimal_record *\fR\fIpd\fR, \fBfp_exception_field_type *\fR\fIps\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions convert the decimal record *\fIpd\fR to a floating-point value +*\fIpx\fR observing the rounding direction specified in *\fIpm\fR and setting +*\fIps\fR to reflect any floating-point exceptions that occur. +.sp +.LP +When \fIpd\fR->\fBfpclass\fR is \fBfp_zero\fR, \fBfp_infinity\fR, +\fBfp_quiet\fR, or \fBfp_signaling\fR, *\fIpx\fR is set to zero, infinity, a +quiet NaN, or a signaling NaN, respectively, with the sign indicated by +\fIpd\fR->\fBsign\fR. All other fields in *\fIpd\fR are ignored. +.sp +.LP +When \fIpd\fR->\fBfpclass\fR is \fBfp_normal\fR or \fBfp_subnormal\fR, +\fIpd\fR->\fBds\fR must contain a null-terminated string of one or more ASCII +digits representing a non-zero integer \fIm\fR, and \fIpd\fR->\fBndigits\fR +must be equal to the length of this string. Then *\fIpx\fR is set to a +correctly rounded approximation to +.sp +.in +2 +.nf +\(mi1**(pd->sign) * m * 10**(pd->exponent) +.fi +.in -2 + +.sp +.LP +\fIpd\fR->\fBmore\fR can be set to a non-zero value to indicate that +insignificant trailing digits were omitted from \fIpd\fR->\fBds\fR. In this +case, \fIm\fR is replaced by \fIm\fR + \fIdelta\fR in the expression above, +where \fIdelta\fR is some tiny positive fraction. +.sp +.LP +The converted value is rounded according to the rounding direction specified in +\fIpm\fR->\fBrd\fR. \fIpm\fR->\fBdf\fR and \fIpm\fR->\fBndigits\fR are not +used. +.sp +.LP +On exit, *\fIps\fR contains a bitwise OR of flags corresponding to any +floating-point exceptions that occurred. The only possible exceptions are +underflow, overflow, and inexact. If no floating-point exceptions occurred, +*\fIps\fR is set to zero. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBscanf\fR(3C), \fBstring_to_decimal\fR(3C), \fBstrtod\fR(3C), +\fBattributes\fR(5) diff --git a/usr/src/man/man3c/difftime.3c b/usr/src/man/man3c/difftime.3c new file mode 100644 index 0000000000..6b26ff0a9d --- /dev/null +++ b/usr/src/man/man3c/difftime.3c @@ -0,0 +1,54 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH difftime 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +difftime \- computes the difference between two calendar times +.SH SYNOPSIS +.LP +.nf +#include <time.h> + +\fBdouble\fR \fBdifftime\fR(\fBtime_t\fR \fItime1\fR, \fBtime_t\fR \fItime0\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBdifftime()\fR function computes the difference between two calendar +times. +.SH RETURN VALUES +.sp +.LP +The \fBdifftime()\fR functions returns the difference \fI(time1-time0)\fR +expressed in seconds as a \fBdouble\fR. +.SH USAGE +.sp +.LP +The \fBdifftime()\fR function is provided because there are no general +arithmetic properties defined for type \fBtime_t\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBctime\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/directio.3c b/usr/src/man/man3c/directio.3c new file mode 100644 index 0000000000..8b08fdbb40 --- /dev/null +++ b/usr/src/man/man3c/directio.3c @@ -0,0 +1,172 @@ +'\" te +.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH directio 3C "9 Apr 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +directio \- provide advice to file system +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/fcntl.h> + +\fBint\fR \fBdirectio\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIadvice\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBdirectio()\fR function provides advice to the system about the expected +behavior of the application when accessing the data in the file associated with +the open file descriptor \fIfildes\fR. The system uses this information to help +optimize accesses to the file's data. The \fBdirectio()\fR function has no +effect on the semantics of the other operations on the data, though it may +affect the performance of other operations. +.sp +.LP +The \fIadvice\fR argument is kept per file; the last caller of \fBdirectio()\fR +sets the \fIadvice\fR for all applications using the file associated with +\fIfildes\fR. +.sp +.LP +Values for \fIadvice\fR are defined in \fB<sys/fcntl.h>\fR\&. +.sp +.ne 2 +.mk +.na +\fB\fBDIRECTIO_OFF\fR\fR +.ad +.RS 16n +.rt +Applications get the default system behavior when accessing file data. +.sp +When an application reads data from a file, the data is first cached in system +memory and then copied into the application's buffer (see \fBread\fR(2)). If +the system detects that the application is reading sequentially from a file, +the system will asynchronously "read ahead" from the file into system memory so +the data is immediately available for the next \fBread\fR(2) operation. +.sp +When an application writes data into a file, the data is first cached in system +memory and is written to the device at a later time (see \fBwrite\fR(2)). When +possible, the system increases the performance of \fBwrite\fR(2) operations by +cacheing the data in memory pages. The data is copied into system memory and +the \fBwrite\fR(2) operation returns immediately to the application. The data +is later written asynchronously to the device. When possible, the cached data +is "clustered" into large chunks and written to the device in a single write +operation. +.sp +The system behavior for \fBDIRECTIO_OFF\fR can change without notice. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDIRECTIO_ON\fR\fR +.ad +.RS 16n +.rt +The system behaves as though the application is not going to reuse the file +data in the near future. In other words, the file data is not cached in the +system's memory pages. +.sp +When possible, data is read or written directly between the application's +memory and the device when the data is accessed with \fBread\fR(2) and +\fBwrite\fR(2) operations. When such transfers are not possible, the system +switches back to the default behavior, but just for that operation. In general, +the transfer is possible when the application's buffer is aligned on a two-byte +(short) boundary, the offset into the file is on a device sector boundary, and +the size of the operation is a multiple of device sectors. +.sp +This advisory is ignored while the file associated with \fIfildes\fR is mapped +(see \fBmmap\fR(2)). +.sp +The system behavior for \fBDIRECTIO_ON\fR can change without notice. +.RE + +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBdirectio()\fR returns \fB0\fR. Otherwise, it +returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBdirectio()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIfildes\fR argument is not a valid open file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTTY\fR\fR +.ad +.RS 10n +.rt +The \fIfildes\fR argument is not associated with a file system that accepts +advisory functions. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value in \fIadvice\fR is invalid. +.RE + +.SH USAGE +.sp +.LP +Small sequential I/O generally performs best with \fBDIRECTIO_OFF\fR. +.sp +.LP +Large sequential I/O generally performs best with \fBDIRECTIO_ON\fR, except +when a file is sparse or is being extended and is opened with \fBO_SYNC\fR or +\fBO_DSYNC\fR (see \fBopen\fR(2)). +.sp +.LP +The \fBdirectio()\fR function is supported for the NFS and UFS file system +types (see \fBfstyp\fR(1M)). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfstyp\fR(1M), \fBmmap\fR(2), \fBopen\fR(2), \fBread\fR(2), \fBwrite\fR(2), +\fBfcntl.h\fR(3HEAD), \fBattributes\fR(5) +.SH WARNINGS +.sp +.LP +Switching between \fBDIRECTIO_OFF\fR and \fBDIRECTIO_ON\fR can slow the +system because each switch to \fBDIRECTIO_ON\fR might entail flushing the +file's data from the system's memory. diff --git a/usr/src/man/man3c/dirfd.3c b/usr/src/man/man3c/dirfd.3c new file mode 100644 index 0000000000..adde122cf7 --- /dev/null +++ b/usr/src/man/man3c/dirfd.3c @@ -0,0 +1,78 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems Inc. All Rights Reserved. +.\" Portions of this manual page are derived from documentation obtained from linuxmanpages.com +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dirfd 3C "24 Oct 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +dirfd \- get directory stream file descriptor +.SH SYNOPSIS +.LP +.nf +#include <dirent.h> + +\fBint\fR \fBdirfd\fR(\fBDIR *\fR\fIdir\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBdirfd()\fR function returns the file descriptor associated with the +directory stream \fIdir\fR. +.sp +.LP +This file descriptor is the one used internally by the directory stream +operations. See \fBopendir\fR(3C), \fBclosedir\fR(3C), \fBreaddir\fR(3C), +\fBrewinddir\fR(3C), \fBseekdir\fR(3C), \fBtelldir\fR(3C). The file descriptor +is automatically closed when \fBclosedir()\fR is called for the directory +stream \fIdir\fR or when one of the \fBexec\fR functions is called. See +\fBexec\fR(2). +.sp +.LP +The file descriptor can safely be used only by functions that do not depend on +or alter the file position, such as \fBfstat\fR(2) and \fBfchdir\fR(2). +Closing the file descriptor with \fBclose\fR(2) or modifying the file position +by means other than the directory stream operations listed above causes +undefined behavior to occur when one of the directory stream operations is +subsequently called with the directory stream \fIdir\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBdirfd()\fR function returns an open file +descriptor for the directory associated with the directory stream \fIdir\fR. +.SH ERRORS +.sp +.LP +There are no defined error returns. Passing an invalid directory stream as an +argument to the \fBdirfd()\fR function results in undefined behavior. +.SH USAGE +.sp +.LP +The \fBdirfd()\fR function is intended to be used to obtain a file descriptor +for use with the \fBfchdir()\fR function. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBclose\fR(2), \fBexec\fR(2), \fBfchdir\fR(2), \fBfstat\fR(2), +\fBclosedir\fR(3C), \fBopendir\fR(3C), \fBreaddir\fR(3C), \fBrewinddir\fR(3C), +\fBseekdir\fR(3C), \fBtelldir\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/dirname.3c b/usr/src/man/man3c/dirname.3c new file mode 100644 index 0000000000..ba5bf81069 --- /dev/null +++ b/usr/src/man/man3c/dirname.3c @@ -0,0 +1,126 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dirname 3C "18 Mar 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +dirname \- report the parent directory name of a file path name +.SH SYNOPSIS +.LP +.nf +#include <libgen.h> + +\fBchar *\fR\fBdirname\fR(\fBchar *\fR\fIpath\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBdirname()\fR function takes a pointer to a character string that +contains a pathname, and returns a pointer to a string that is a pathname of +the parent directory of that file. Trailing '/' characters in the path are not +counted as part of the path. +.sp +.LP +If \fIpath\fR does not contain a '/', then \fBdirname()\fR returns a pointer to +the string "." . If \fIpath\fR is a null pointer or points to an empty string, +\fBdirname()\fR returns a pointer to the string "." . +.SH RETURN VALUES +.sp +.LP +The \fBdirname()\fR function returns a pointer to a string that is the parent +directory of \fIpath\fR. If \fIpath\fR is a null pointer or points to an empty +string, a pointer to a string "." is returned. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH EXAMPLES +.LP +\fBExample 1 \fRChanging the Current Directory to the Parent Directory. +.sp +.LP +The following code fragment reads a pathname, changes the current working +directory to the parent directory of the named file (see \fBchdir\fR(2)), and +opens the file. + +.sp +.in +2 +.nf +char path[[MAXPATHLEN], *pathcopy; +int fd; +fgets(path, MAXPATHLEN, stdin); +pathcopy = strdup(path); +chdir(dirname(pathcopy)); +fd = open(basename(path), O_RDONLY); +.fi +.in -2 + +.LP +\fBExample 2 \fRSample Input and Output Strings for \fBdirname()\fR. +.sp +.LP +In the following table, the input string is the value pointed to by \fIpath\fR, +and the output string is the return value of the \fBdirname()\fR function. + +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBInput String\fR\fBOutput String\fR +_ +"/usr/lib"""/usr" +_ +"/usr/""/" +_ +"usr""/" +_ +"/""/" +_ +".""." +_ +"..""." +.TE + +.SH USAGE +.sp +.LP +The \fBdirname()\fR function modifies the string pointed to by \fIpath\fR. +.sp +.LP +The \fBdirname()\fR and \fBbasename\fR(3C) functions together yield a complete +pathname. The expression \fBdirname(\fR\fIpath\fR\fB)\fR obtains the pathname +of the directory where \fBbasename(\fR\fIpath\fR\fB)\fR is found. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBbasename\fR(1), \fBchdir\fR(2), \fBbasename\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/div.3c b/usr/src/man/man3c/div.3c new file mode 100644 index 0000000000..1b7b2916a4 --- /dev/null +++ b/usr/src/man/man3c/div.3c @@ -0,0 +1,96 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH div 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +div, ldiv, lldiv \- compute the quotient and remainder +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBdiv_t\fR \fBdiv\fR(\fBint\fR \fInumer\fR, \fBint\fR \fIdenom\fR); +.fi + +.LP +.nf +\fBldiv_t\fR \fBldiv\fR(\fBlong int\fR \fInumer\fR, \fBlong int\fR \fIdenom\fR); +.fi + +.LP +.nf +\fBlldiv_t\fR \fBlldiv\fR(\fBlong long\fR \fInumer\fR, \fBlong long\fR \fIdenom\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBdiv()\fR function computes the quotient and remainder of the division of +the numerator \fInumer\fR by the denominator \fIdenom\fR. It provides a +well-defined semantics for the signed integral division and remainder +operations, unlike the implementation-defined semantics of the built-in +operations. The sign of the resulting quotient is that of the algebraic +quotient, and if the division is inexact, the magnitude of the resulting +quotient is the largest integer less than the magnitude of the algebraic +quotient. If the result cannot be represented, the behavior is undefined; +otherwise, \fIquotient\fR * \fIdenom\fR + \fIremainder\fR will equal +\fInumer\fR. +.sp +.LP +The \fBldiv()\fR and \fBlldiv()\fR functions are similar to \fBdiv()\fR, except +that the arguments and the members of the returned structure are different. +The \fBldiv()\fR function returns a structure of type \fBldiv_t\fR and has type +\fBlong int\fR. The \fBlldiv()\fR function returns a structure of type +\fBlldiv_t\fR and has type \fBlong long\fR. +.SH RETURN VALUES +.sp +.LP +The \fBdiv()\fR function returns a structure of type \fBdiv_t\fR, comprising +both the quotient and remainder: +.sp +.in +2 +.nf +int quot; /*quotient*/ +int rem; /*remainder*/ +.fi +.in -2 + +.sp +.LP +The \fBldiv()\fR function returns a structure of type \fBldiv_t\fR and +\fBlldiv()\fR returns a structure of type \fBlldiv_t\fR, comprising both the +quotient and remainder: +.sp +.in +2 +.nf +long int quot; /*quotient*/ +long int rem; /*remainder*/ +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/dladdr.3c b/usr/src/man/man3c/dladdr.3c new file mode 100644 index 0000000000..646358f997 --- /dev/null +++ b/usr/src/man/man3c/dladdr.3c @@ -0,0 +1,198 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dladdr 3C "4 Feb 2009" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +dladdr, dladdr1 \- translate address to symbolic information +.SH SYNOPSIS +.LP +.nf +#include <dlfcn.h> + +\fBint\fR \fBdladdr\fR(\fBvoid *\fR\fIaddress\fR, \fBDl_info_t *\fR\fIdlip\fR); +.fi + +.LP +.nf +\fBint\fR \fBdladdr1\fR(\fBvoid *\fR\fIaddress\fR, \fBDl_info_t *\fR\fIdlip\fR, \fBvoid **\fR\fIinfo\fR, \fBint\fR \fIflags\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBdladdr()\fR and \fBdladdr1()\fR functions determine if the specified +\fIaddress\fR is located within one of the mapped objects that make up the +current applications address space. An address is deemed to fall within a +mapped object when it is between the base address, and the \fI_end\fR address +of that object. See NOTES. If a mapped object fits this criteria, the symbol +table made available to the runtime linker is searched to locate the nearest +symbol to the specified address. The nearest symbol is one that has a value +less than or equal to the required address. +.sp +.LP +The \fBDl_info_t\fR structure must be preallocated by the user. The structure +members are filled in by \fBdladdr()\fR, based on the specified \fIaddress\fR. +The \fBDl_info_t\fR structure includes the following members: +.sp +.in +2 +.nf + const char *dli_fname; + void *dli_fbase; + const char *dli_sname; + void *dli_saddr; +.fi +.in -2 + +.sp +.LP +The \fBDl_info_t\fR members provide the following information. +.sp +.ne 2 +.mk +.na +\fB\fBdli_fname\fR\fR +.ad +.RS 13n +.rt +Contains a pointer to the filename of the containing object. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdli_fbase\fR\fR +.ad +.RS 13n +.rt +Contains the base address of the containing object. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdli_sname\fR\fR +.ad +.RS 13n +.rt +Contains a pointer to the symbol name that is nearest to the specified address. +This symbol either represents the exact address that was specified, or is the +nearest symbol with a lower address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdli_saddr\fR\fR +.ad +.RS 13n +.rt +Contains the actual address of the symbol pointed to by \fBdli_sname\fR. +.RE + +.sp +.LP +The \fBdladdr1()\fR function provides for addition information to be returned +as specified by the \fIflags\fR argument: +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_DL_SYMENT\fR\fR +.ad +.RS 19n +.rt +Obtain the \fBELF\fR symbol table entry for the matched symbol. The \fIinfo\fR +argument points to a symbol pointer as defined in <\fBsys/elf.h\fR> +(\fBElf32_Sym **\fR\fIinfo\fR or \fBElf64_Sym **\fR\fIinfo\fR). Most of the +information found in an ELF symbol can only be properly interpreted by the +runtime linker. However, there are two fields that contain information useful +to the caller of \fBdladdr1()\fR: The \fBst_size\fR field contains the size of +the referenced item. The \fBst_info\fR field provides symbol type and binding +attributes. See the \fILinker and Libraries Guild\fR for more information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_DL_LINKMAP\fR\fR +.ad +.RS 19n +.rt +Obtain the \fBLink_map\fR for the matched file. The \fIinfo\fR argument points +to a \fBLink_map\fR pointer as defined in <\fBsys/link.h\fR> (\fBLink_map +**\fR\fIinfo\fR). +.RE + +.SH RETURN VALUES +.sp +.LP +If the specified \fIaddress\fR cannot be matched to a mapped object, a \fB0\fR +is returned. Otherwise, a non-zero return is made and the associated +\fBDl_info_t\fR elements are filled. +.SH USAGE +.sp +.LP +The \fBdladdr()\fR and \fBdladdr1()\fR functions are one of a family of +functions that give the user direct access to the dynamic linking facilities. +These facilities are available to dynamically-linked processes only. See +\fILinker and Libraries Guide\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBld\fR(1), \fBdlclose\fR(3C), \fBdldump\fR(3C), \fBdlerror\fR(3C), +\fBdlopen\fR(3C), \fBdlsym\fR(3C), \fBattributes\fR(5) +.sp +.LP +\fILinker and Libraries Guide\fR +.SH NOTES +.sp +.LP +The \fBDl_info_t\fR pointer elements point to addresses within the mapped +objects. These pointers can become invalid if objects are removed prior to +these elements use. See \fBdlclose\fR(3C). +.sp +.LP +If no symbol is found to describe the specified address, both the +\fBdli_sname\fR and \fBdli_saddr\fR members are set to \fB0\fR. +.sp +.LP +If the address specified exists within a mapped object in the range between the +base address and the address of the first global symbol in the object, the +reserved local symbol \fB_START_\fR is returned. This symbol acts as a label +representing the start of the mapped object. As a label, this symbol has no +size. The \fBdli_saddr\fR member is set to the base address of the associated +object. The \fBdli_sname\fR member is set to the symbol name \fB_START_\fR. If +the flag argument is set to \fBRTLD_DL_SYMENT\fR, symbol information for +\fB_START_\fR is returned. +.sp +.LP +If an object is acting as a filter, care should be taken when interpreting the +address of any symbol obtained using a handle to this object. For example, +using \fBdlsym\fR(3C) to obtain the symbol \fI_end\fR for this object, results +in returning the address of the symbol \fI_end\fR within the filtee, not the +filter. For more information on filters see the \fILinker and Libraries +Guide\fR. diff --git a/usr/src/man/man3c/dlclose.3c b/usr/src/man/man3c/dlclose.3c new file mode 100644 index 0000000000..6e0536d598 --- /dev/null +++ b/usr/src/man/man3c/dlclose.3c @@ -0,0 +1,94 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dlclose 3C "1 March 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +dlclose \- close a shared object +.SH SYNOPSIS +.LP +.nf +#include <dlfcn.h> + +\fBint\fR \fBdlclose\fR(\fBvoid *\fR\fIhandle\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBdlclose()\fR function decrements the reference count of the supplied +\fIhandle\fR. This \fIhandle\fR represents an executable object file and its +dependencies, acquired from a previous call to \fBdlopen()\fR. A \fIhandle\fR +that is no longer referenced is processed in an attempt to unload any objects +that are associated with the \fIhandle\fR from the current process. An +unreferenced \fIhandle\fR is no longer available to \fBdlsym()\fR. +.sp +.LP +Any finalization code within an object is executed prior to that object being +unloaded. Any routines registered by an object using \fBatexit\fR(3C) are +called prior to that object being unloaded. See NOTES. +.SH RETURN VALUES +.sp +.LP +If the \fIhandle\fR was successfully unreferenced, \fBdlclose()\fR returns +\fB0\fR. If the \fIhandle\fR is invalid, or an error occurred as a result of +unloading an object, \fBdlclose()\fR returns a non-zero value. Additional +diagnostic information is available through \fBdlerror()\fR. +.SH USAGE +.sp +.LP +The \fBdlclose()\fR function is one of a family of functions that give the user +direct access to the dynamic linking facilities. These facilities are available +to dynamically-linked processes only. See the \fILinker and Libraries Guide\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBld\fR(1), \fBld.so.1\fR(1), \fBatexit\fR(3C), \fBdladdr\fR(3C), +\fBdldump\fR(3C), \fBdlerror\fR(3C), \fBdlopen\fR(3C), \fBdlsym\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) +.sp +.LP +\fILinker and Libraries Guide\fR +.SH NOTES +.sp +.LP +A successful invocation of \fBdlclose()\fR does not guarantee that the objects +associated with the \fIhandle\fR are removed from the address space of the +current process. Objects can be referenced by multiple \fIhandles\fR, or by +other objects. An object is not removed from the address space of the current +process until all references to that object are removed. +.sp +.LP +Once an object has been closed by \fBdlclose()\fR, referencing symbols +contained in that object can cause undefined behavior. +.sp +.LP +As part of unloading an object, finalization code within the object is called +\fBbefore\fR the \fBdlclose()\fR returns. This finalization is user code, and +as such, can produce errors that can not be caught by \fBdlclose()\fR. For +example, an object loaded using \fBRTLD_LAZY\fR that attempts to call a +function that can not be located, results in process termination. Erroneous +programming practices within the finalization code can also result in process +termination. The runtime linkers debugging facility can offer help identifying +these types of error. See the \fBLD_DEBUG\fR environment variable of +\fBld.so.1\fR(1). diff --git a/usr/src/man/man3c/dldump.3c b/usr/src/man/man3c/dldump.3c new file mode 100644 index 0000000000..bd195dc22a --- /dev/null +++ b/usr/src/man/man3c/dldump.3c @@ -0,0 +1,480 @@ +'\" te +.\" Copyright (c) 2004 by Sun Microsystems, Inc. All rights reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dldump 3C "1 Mar 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +dldump \- create a new file from a dynamic object component of the calling +process +.SH SYNOPSIS +.LP +.nf +#include <dlfcn.h> + +\fBint\fR \fBdldump\fR(\fBconst char *\fR \fIipath\fR, \fBconst char *\fR \fIopath\fR, \fBint\fR \fIflags\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBdldump()\fR function creates a new dynamic object \fIopath\fR from an +existing dynamic object \fIipath\fR that is bound to the current process. An +\fIipath\fR value of \fB0\fR is interpreted as the dynamic object that started +the process. The new object is constructed from the existing objects' disc +file. Relocations can be applied to the new object to pre-bind it to other +dynamic objects, or fix the object to a specific memory location. In addition, +data elements within the new object can be obtained from the objects' memory +image as this data exists in the calling process. +.sp +.LP +These techniques allow the new object to be executed with a lower startup cost. +This reduction can be because of less relocations being required to load the +object, or because of a reduction in the data processing requirements of the +object. However, limitations can exist in using these techniques. The +application of relocations to the new dynamic object \fIopath\fR can restrict +its flexibility within a dynamically changing environment. In addition, +limitations in regards to data usage can make dumping a memory image +impractical. See \fBEXAMPLES\fR. +.sp +.LP +The runtime linker verifies that the dynamic object \fIipath\fR is mapped as +part of the current process. Thus, the object must either be the dynamic object +that started the process, one of the process's dependencies, or an object that +has been preloaded. See \fBexec\fR(2), and \fBld.so.1\fR(1). +.sp +.LP +As part of the runtime processing of a dynamic object, \fIrelocation\fR records +within the object are interpreted and applied to offsets within the object. +These offsets are said to be \fIrelocated\fR. Relocations can be categorized +into two basic types: \fInon-symbolic\fR and \fIsymbolic\fR. +.sp +.LP +The \fInon-symbolic\fR relocation is a simple \fIrelative\fR relocation that +requires the base address at which the object is mapped to perform the +relocation. The \fIsymbolic\fR relocation requires the address of an associated +symbol, and results in a \fIbinding\fR to the dynamic object that defines this +symbol. The symbol definition can originate from any of the dynamic objects +that make up the process, that is, the object that started the process, one of +the process's dependencies, an object that has been preloaded, or the dynamic +object being relocated. +.sp +.LP +The \fIflags\fR parameter controls the relocation processing and other +attributes of producing the new dynamic object \fIopath\fR. Without any +\fIflags\fR, the new object is constructed solely from the contents of the +\fIipath\fR disc file without any relocations applied. +.sp +.LP +Various relocation flags can be \fBor\fR'ed into the \fIflags\fR parameter to +affect the relocations that are applied to the new object. \fINon-symbolic\fR +relocations can be applied using the following: +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_REL_RELATIVE\fR\fR +.ad +.RS 21n +.rt +Relocation records from the object \fIipath\fR, that define \fIrelative\fR +relocations, are applied to the object \fIopath\fR. +.RE + +.sp +.LP +A variety of \fIsymbolic\fR relocations can be applied using the following +flags (each of these flags also implies \fBRTLD_REL_RELATIVE\fR is in effect): +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_REL_EXEC\fR\fR +.ad +.RS 20n +.rt +Symbolic relocations that result in binding \fIipath\fR to the dynamic object +that started the process, commonly a dynamic executable, are applied to the +object \fIopath\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_REL_DEPENDS\fR\fR +.ad +.RS 20n +.rt +Symbolic relocations that result in binding \fIipath\fR to any of the dynamic +dependencies of the process are applied to the object \fIopath\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_REL_PRELOAD\fR\fR +.ad +.RS 20n +.rt +Symbolic relocations that result in binding \fIipath\fR to any objects +preloaded with the process are applied to the object \fIopath\fR. See +\fBLD_PRELOAD\fR in \fBld.so.1\fR(1). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_REL_SELF\fR\fR +.ad +.RS 20n +.rt +Symbolic relocations that result in binding \fIipath\fR to itself, are applied +to the object \fIopath\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_REL_WEAK\fR\fR +.ad +.RS 20n +.rt +Weak relocations that remain unresolved are applied to the object \fIopath\fR +as \fB0\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_REL_ALL\fR\fR +.ad +.RS 20n +.rt +\fIAll\fR relocation records defined in the object \fIipath\fR are applied to +the new object \fIopath\fR. This is basically a concatenation of all the above +relocation flags. +.RE + +.sp +.LP +Note that for dynamic executables, \fBRTLD_REL_RELATIVE\fR, +\fBRTLD_REL_EXEC\fR, and \fBRTLD_REL_SELF\fR have no effect. See +\fBEXAMPLES\fR. +.sp +.LP +If relocations, knowledgeable of the base address of the mapped object, are +applied to the new object \fIopath\fR, then the new object becomes fixed to the +location that the \fIipath\fR image is mapped within the current process. +.sp +.LP +Any relocations applied to the new object \fIopath\fR will have the original +relocation record removed so that the relocation will not be applied more than +once. Otherwise, the new object \fIopath\fR will retain the relocation records +as they exist in the \fIipath\fR disc file. +.sp +.LP +The following additional attributes for creating the new dynamic object +\fIopath\fR can be specified using the \fIflags\fR parameter: +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_MEMORY\fR\fR +.ad +.RS 15n +.rt +The new object \fIopath\fR is constructed from the current memory contents of +the \fIipath\fR image as it exists in the calling process. This option allows +data modified by the calling process to be captured in the new object. Note +that not all data modifications may be applicable for capture; significant +restrictions exist in using this technique. See \fBEXAMPLES\fR. By default, +when processing a dynamic executable, any allocated memory that follows the end +of the data segment is captured in the new object (see \fBmalloc\fR(3C) and +\fBbrk\fR(2)). This data, which represents the process heap, is saved as a new +\fI\&.SUNW_heap\fR section in the object \fIopath\fR. The objects' program +headers and symbol entries, such as \fB_end\fR, are adjusted accordingly. See +also \fBRTLD_NOHEAP.\fR When using this attribute, any relocations that have +been applied to the \fIipath\fR memory image that do not fall into one of the +requested relocation categories are undone, that is, the relocated element is +returned to the value as it existed in the \fIipath\fR disc file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_STRIP\fR\fR +.ad +.RS 15n +.rt +Only collect allocatable sections within the object \fIopath\fR. Sections that +are not part of the dynamic objects' memory image are removed. \fBRTLD_STRIP\fR +reduces the size of the \fIopath\fR disc file and is comparable to having run +the new object through \fBstrip\fR(1). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_NOHEAP\fR\fR +.ad +.RS 15n +.rt +Do not save any heap to the new object. This option is only meaningful when +processing a dynamic executable with the \fBRTLD_MEMORY\fR attribute and allows +for reducing the size of the \fIopath\fR disc file. The executable must confine +its data initialization to data elements within its data segment, and must not +use any allocated data elements that comprise the heap. +.RE + +.sp +.LP +It should be emphasized, that an object created by \fBdldump()\fR is simply an +updated \fBELF\fR object file. No additional state regarding the process at the +time \fBdldump()\fR is called is maintained in the new object. \fBdldump()\fR +does not provide a panacea for checkpoint and resume. A new dynamic executable, +for example, will not start where the original executable called +\fBdldump()\fR. It will gain control at the executable's normal entry point. +See \fBEXAMPLES\fR. +.SH RETURN VALUES +.sp +.LP +On successful creation of the new object, \fBdldump()\fR returns \fB0\fR. +Otherwise, a non-zero value is returned and more detailed diagnostic +information is available through \fBdlerror()\fR. +.SH EXAMPLES +.LP +\fBExample 1 \fRSample code using \fBdldump()\fR. +.sp +.LP +The following code fragment, which can be part of a dynamic executable +\fBa.out\fR, can be used to create a new shared object from one of the dynamic +executables' dependencies \fBlibfoo.so.1\fR: + +.sp +.in +2 +.nf +const char * ipath = "libfoo.so.1"; +const char * opath = "./tmp/libfoo.so.1"; +\&... +if (dldump(ipath, opath, RTLD_REL_RELATIVE) != 0) + (void) printf("dldump failed: %s\en", dlerror(\|)); +.fi +.in -2 + +.sp +.LP +The new shared object \fIopath\fR is fixed to the address of the mapped +\fIipath\fR bound to the dynamic executable \fBa.out\fR. All relative +relocations are applied to this new shared object, which will reduce its +relocation overhead when it is used as part of another process. + +.sp +.LP +By performing only relative relocations, any symbolic relocation records remain +defined within the new object, and thus the dynamic binding to external symbols +will be preserved when the new object is used. + +.sp +.LP +Use of the other relocation flags can fix specific relocations in the new +object and thus can reduce even more the runtime relocation startup cost of the +new object. However, this will also restrict the flexibility of using the new +object within a dynamically changing environment, as it will bind the new +object to some or all of the dynamic objects presently mapped as part of the +process. + +.sp +.LP +For example, the use of \fBRTLD_REL_SELF\fR will cause any references to +symbols from \fIipath\fR to be bound to definitions within itself if no other +preceding object defined the same symbol. In other words, a call to +\fIfoo(\|)\fR within \fIipath\fR will bind to the definition \fIfoo\fR within +the same object. Therefore, \fIopath\fR will have one less binding that must be +computed at runtime. This reduces the startup cost of using \fIopath\fR by +other applications; however, interposition of the symbol \fIfoo\fR will no +longer be possible. + +.sp +.LP +Using a dumped shared object with applied relocations as an applications +dependency normally requires that the application have the same dependencies as +the application that produced the dumped image. Dumping shared objects, and the +various flags associated with relocation processing, have some specialized +uses. However, the technique is intended as a building block for future +technology. + +.sp +.LP +The following code fragment, which is part of the dynamic executable +\fBa.out\fR, can be used to create a new version of the dynamic executable: + +.sp +.in +2 +.nf +static char * dumped = 0; +const char * opath = "./a.out.new"; +\&... +if (dumped == 0) { + char buffer[100]; + int size; + time_t seconds; + ... + /* Perform data initialization */ + seconds = time((time_t *)0); + size = cftime(buffer, (char *)0, &seconds); + if ((dumped = (char *)malloc(size + 1)) == 0) { + (void) printf("malloc failed: %s\en", strerror(errno)); + return (1); + } + (void) strcpy(dumped, buffer); + ... + /* + * Tear down any undesirable data initializations and + * dump the dynamic executables memory image. + */ + _exithandle(\|); + _exit(dldump(0, opath, RTLD_MEMORY)); +} +(void) printf("Dumped: %s\en", dumped); +.fi +.in -2 + +.sp +.LP +Any modifications made to the dynamic executable, up to the point the +\fBdldump()\fR call is made, are saved in the new object \fBa.out.new\fR. This +mechanism allows the executable to update parts of its data segment and heap +prior to creating the new object. In this case, the date the executable is +dumped is saved in the new object. The new object can then be executed without +having to carry out the same (presumably expensive) initialization. + +.sp +.LP +For greatest flexibility, this example does not save \fIany\fR relocated +information. The elements of the dynamic executable \fIipath\fR that have been +modified by relocations at process startup, that is, references to external +functions, are returned to the values of these elements as they existed in the +\fIipath\fR disc file. This preservation of relocation records allows the new +dynamic executable to be flexible, and correctly bind and initialize to its +dependencies when executed on the same or newer upgrades of the \fBOS\fR. + +.sp +.LP +Fixing relocations by applying some of the relocation flags would bind the new +object to the dependencies presently mapped as part of the process calling +\fBdldump()\fR. It may also remove necessary copy relocation processing +required for the correct initialization of its shared object dependencies. +Therefore, if the new dynamic executables' dependencies have no specialized +initialization requirements, the executable may still only interact correctly +with the dependencies to which it binds if they were mapped to the same +locations as they were when \fBdldump()\fR was called. + +.sp +.LP +Note that for dynamic executables, \fBRTLD_REL_RELATIVE,\fR +\fBRTLD_REL_EXEC,\fR and \fBRTLD_REL_SELF\fR have no effect, as relocations +within the dynamic executable will have been fixed when it was created by +\fBld\fR(1). + +.sp +.LP +When \fBRTLD_MEMORY\fR is used, care should be taken to insure that dumped data +sections that reference external objects are not reused without appropriate +re-initialization. For example, if a data item contains a file descriptor, a +variable returned from a shared object, or some other external data, and this +data item has been initialized prior to the \fBdldump()\fR call, its value will +have no meaning in the new dumped image. + +.sp +.LP +When \fBRTLD_MEMORY\fR is used, any modification to a data item that is +initialized via a relocation whose relocation record will be retained in the +new image will effectively be lost or invalidated within the new image. For +example, if a pointer to an external object is incremented prior to the +\fBdldump()\fR call, this data item will be reset to its disc file contents so +that it can be relocated when the new image is used; hence, the previous +increment is lost. + +.sp +.LP +Non-idempotent data initializations may prevent the use of \fBRTLD_MEMORY\fR. +For example, the addition of elements to a linked-list via \fBinit\fR sections +can result in the linked-list data being captured in the new image. Running +this new image may result in \fBinit\fR sections continuing to add new elements +to the list without the prerequisite initialization of the list head. It is +recommended that \fB_exithandle\fR(3C) be called before \fBdldump()\fR to tear +down any data initializations established via initialization code. Note that +this may invalidate the calling image; thus, following the call to +\fBdldump()\fR, only a call to \fB_Exit\fR(2) should be made. + +.SH USAGE +.sp +.LP +The \fBdldump()\fR function is one of a family of functions that give the user +direct access to the dynamic linking facilities. These facilities are available +to dynamically-linked processes only. See \fILinker and Libraries Guide\fR). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBld\fR(1), \fBld.so.1\fR(1), \fBstrip\fR(1), \fB_Exit\fR(2), \fBbrk\fR(2), +\fBexec\fR(2), \fB_exithandle\fR(3C), \fBdladdr\fR(3C), \fBdlclose\fR(3C), +\fBdlerror\fR(3C), \fBdlopen\fR(3C), \fBdlsym\fR(3C), \fBend\fR(3C), +\fBmalloc\fR(3C), \fBattributes\fR(5) +.sp +.LP +\fILinker and Libraries Guide\fR +.SH NOTES +.sp +.LP +These functions are available to dynamically-linked processes only. +.sp +.LP +Any \fBNOBITS\fR sections within the \fIipath\fR are expanded to \fBPROGBITS\fR +sections within the \fIopath\fR. \fBNOBITS\fR sections occupy no space within +an \fBELF\fR file image. \fBNOBITS\fR sections declare memory that must be +created and zero-filled when the object is mapped into the runtime environment. +\fB\&.bss\fR is a typical example of this section type. \fBPROGBITS\fR +sections, on the other hand, hold information defined by the object within the +\fBELF\fR file image. This section conversion reduces the runtime +initialization cost of the new dumped object but increases the objects' disc +space requirement. +.sp +.LP +When a shared object is dumped, and relocations are applied which are +knowledgeable of the base address of the mapped object, the new object is fixed +to this new base address. The dumped object has its \fBELF\fR type reclassified +to be a dynamic executable. The dumped object can be processed by the runtime +linker, but is not valid as input to the link-editor. +.sp +.LP +If relocations are applied to the new object, any remaining relocation records +are reorganized for better locality of reference. The relocation sections are +renamed to \fB\&.SUNW_reloc\fR and the association with the section to +relocate, is lost. Only the offset of the relocation record is meaningful. +\fB\&.SUNW_reloc\fR relocations do not make the new object invalid to either +the runtime linker or link-editor, but can reduce the objects analysis with +some \fBELF\fR readers. diff --git a/usr/src/man/man3c/dlerror.3c b/usr/src/man/man3c/dlerror.3c new file mode 100644 index 0000000000..a2e9b692d4 --- /dev/null +++ b/usr/src/man/man3c/dlerror.3c @@ -0,0 +1,65 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dlerror 3C "1 Mar 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +dlerror \- get diagnostic information +.SH SYNOPSIS +.LP +.nf +#include <dlfcn.h> + +\fBchar *\fR\fBdlerror\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBdlerror()\fR function returns a null-terminated character string that +describes the last error that occurred during dynamic linking processing. The +returned string contains no trailing newline. If no dynamic linking errors have +occurred since the last invocation of \fBdlerror()\fR, \fBdlerror()\fR returns +\fINULL\fR. Thus, invoking \fBdlerror()\fR a second time, immediately +following a prior invocation, results in \fINULL\fR being returned. +.SH USAGE +.sp +.LP +The \fBdlerror()\fR function is one of a family of functions that give the user +direct access to the dynamic linking facilities. These facilities are available +to dynamically-linked processes only. See \fILinker and Libraries Guide\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBld\fR(1), \fBdladdr\fR(3C), \fBdlclose\fR(3C), \fBdldump\fR(3C), +\fBdlopen\fR(3C), \fBdlsym\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) +.sp +.LP +\fILinker and Libraries Guide\fR +.SH NOTES +.sp +.LP +The messages returned by \fBdlerror()\fR can reside in a static buffer that is +overwritten on each call to \fBdlerror()\fR. Application code should not write +to this buffer. Programs wanting to preserve an error message should make their +own copies of that message. diff --git a/usr/src/man/man3c/dlinfo.3c b/usr/src/man/man3c/dlinfo.3c new file mode 100644 index 0000000000..53dc20e518 --- /dev/null +++ b/usr/src/man/man3c/dlinfo.3c @@ -0,0 +1,502 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, +.\" Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dlinfo 3C "4 Feb 2009" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +dlinfo \- dynamic load information +.SH SYNOPSIS +.LP +.nf +#include <dlfcn.h> +#include <link.h> +#include <limits.h> +#include <sys/mman.h> + +\fBint\fR \fBdlinfo\fR(\fBvoid *\fR\fIhandle\fR, \fBint\fR \fIrequest\fR, \fBvoid *\fR\fIp\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBdlinfo()\fR function sets or extracts information from the runtime +linker \fBld.so.1\fR(1). This function is loosely modeled after the +\fBioctl\fR(2) function. The \fIrequest\fR argument and a third argument of +varying type are passed to \fBdlinfo()\fR. The action taken by \fBdlinfo()\fR +depends on the value of the \fIrequest\fR that is provided. +.sp +.LP +The \fIhandle\fR argument is either the value that is returned from a +\fBdlopen\fR(3C) or \fBdlmopen()\fR call, or the special handle +\fBRTLD_SELF\fR. A \fIhandle\fR argument is required for all requests except +\fBRTLD_DI_CONFIGADDR\fR, \fBRTLD_DI_GETSIGNAL\fR, and \fBRTLD_DI_SETSIGNAL\fR. +If \fIhandle\fR is the value that is returned from a \fBdlopen()\fR or +\fBdlmopen()\fR call, the information returned by the \fBdlinfo()\fR call +pertains to the specified object. If \fIhandle\fR is the special handle +\fBRTLD_SELF\fR, the information returned by the \fBdlinfo()\fR call pertains +to the caller. +.sp +.LP +The \fIrequest\fR argument can take the following values: +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_DI_ARGSINFO\fR\fR +.ad +.sp .6 +.RS 4n +Obtain process argument information. The \fIp\fR argument is a pointer +(\fBDl_argsinfo_t *\fR\fIp\fR). The following elements from this structure are +initialized: +.sp +.ne 2 +.mk +.na +\fB\fBdla_argc\fR\fR +.ad +.RS 12n +.rt +The number of arguments passed to the process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdla_argv\fR\fR +.ad +.RS 12n +.rt +The argument array passed to the process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdla_envp\fR\fR +.ad +.RS 12n +.rt +The active environment variable array that is available to the process. This +element initially points to the environment variable array that is made +available to \fBexec\fR(2). This element can be updated should an alternative +environment be established by the process. See \fBputenv\fR(3C). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdla_auxv\fR\fR +.ad +.RS 12n +.rt +The auxiliary vector array passed to the process. +.RE + +A process can be established from executing the runtime linker directly from +the command line. See \fBld.so.1\fR(1). The \fBDl_argsinfo_t\fR information +reflects the information that is made available to the application regardless +of how the runtime linker has been invoked. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_DI_CONFIGADDR\fR\fR +.ad +.sp .6 +.RS 4n +Obtain the configuration file information. The \fIp\fR argument is a +\fBDl_info_t\fR pointer (\fBDl_info_t *\fR\fIp\fR). The following elements from +this structure are initialized: +.sp +.ne 2 +.mk +.na +\fB\fBdli_fname\fR\fR +.ad +.RS 13n +.rt +The full name of the configuration file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdli_fbase\fR\fR +.ad +.RS 13n +.rt +The base address of the configuration file loaded into memory. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_DI_LINKMAP\fR\fR +.ad +.sp .6 +.RS 4n +Obtain the \fBLink_map\fR for the \fIhandle\fR that is specified. The \fIp\fR +argument points to a \fBLink_map\fR pointer (\fBLink_map **\fR\fIp\fR). The +actual storage for the \fBLink_map\fR structure is maintained by \fBld.so.1\fR. +.sp +The \fBLink_map\fR structure includes the following members: +.sp +.in +2 +.nf + unsigned long l_addr; /* base address */ + char *l_name; /* object name */ + Elf32_Dyn *l_ld; /* .dynamic section */ + Link_map *l_next; /* next link object */ + Link_map *l_prev; /* previous link object */ + char *l_refname; /* filter reference name */ +.fi +.in -2 + +.sp +.ne 2 +.mk +.na +\fB\fBl_addr\fR\fR +.ad +.RS 13n +.rt +The base address of the object loaded into memory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBl_name\fR\fR +.ad +.RS 13n +.rt +The full name of the loaded object. This full name is the filename of the +object as referenced by \fBld.so.1\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBl_ld\fR\fR +.ad +.RS 13n +.rt +Points to the \fBSHT_DYNAMIC\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBl_next\fR\fR +.ad +.RS 13n +.rt +The next \fBLink_map\fR on the link-map list. Other objects on the same +link-map list as the current object can be examined by following the +\fBl_next\fR and \fBl_prev\fR members. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBl_prev\fR\fR +.ad +.RS 13n +.rt +The previous \fBLink_map\fR on the link-map list. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBl_refname\fR\fR +.ad +.RS 13n +.rt +If the object that is referenced is a \fIfilter\fR, this member points to the +name of the object being filtered. If the object is not a \fIfilter\fR, this +member is \fB0\fR. See the \fILinker and Libraries Guide\fR. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_DI_LMID\fR\fR +.ad +.sp .6 +.RS 4n +Obtain the \fBID\fR for the link-map list upon which the \fIhandle\fR is +loaded. The \fIp\fR argument is a \fBLmid_t\fR pointer (\fBLmid_t *\fR\fIp\fR). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_DI_MMAPCNT\fR\fR +.ad +.sp .6 +.RS 4n +Determine the number of segment mappings for the \fIhandle\fR that is +specified, for use in a \fBRTLD_DI_MMAPS\fR request. The \fIp\fR argument is a +\fBuint_t\fR pointer (\fBuint_t *\fR\fIp\fR). On return from a +\fBRTLD_DI_MMAPCNT\fR request, the \fBuint_t\fR value that is pointed to by +\fIp\fR contains the number of segment mappings that the associated object +uses. +.sp +To obtain the complete mapping information for an object, a +\fBmmapobj_result_t\fR array for \fBRTLD_DI_MMAPCNT\fR entries must be +provided. This array is assigned to the \fBdlm_maps\fR member, and the number +of entries available in the arry are assigned to the \fBdlm_acnt\fR member. +This initialized structure is then passed to a \fBRTLD_DI_MMAPS\fR request. See +\fBEXAMPLES\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_DI_MMAPS\fR\fR +.ad +.sp .6 +.RS 4n +Obtain segment mapping information for the \fIhandle\fR that is specified. The +\fIp\fR argument is a \fBDl_mapinfo_t\fR pointer (\fBDl_mapinfo_t *\fR\fIp\fR). +This structure can be initialized from the mapping count obtained from a +previous \fBRTLD_DI_MMAPCNT\fR request. +.sp +Segment mapping information is provided in an array of \fBmmapobj_result_t\fR +structures that originate from the \fBmmapobj\fR(2) of the associated object. +The \fBdlm_acnt\fR member, typically initialized from a previous +\fBRTLD_DI_MMAPCNT\fR request, indicates the number of enteries in a +\fBmmapobj_result_t\fR array. This array is assigned to the \fBdlm_maps\fR +member. This initialized structure is then passed to a \fBRTLD_DI_MMAPS\fR +request, where the segment mapping information is copied to the +\fBmmapobj_result_t\fR array. The \fBdlm_rcnt\fR member indicates the number of +\fBmmapobj_result_t\fR element entries that are returned. See \fBEXAMPLES\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_DI_SERINFO\fR\fR +.ad +.sp .6 +.RS 4n +Obtain the library search paths for the \fIhandle\fR that is specified. The +\fIp\fR argument is a \fBDl_serinfo_t\fR pointer (\fBDl_serinfo_t *\fR\fIp\fR). +A user must first initialize the \fBDl_serinfo_t\fR structure with a +\fBRTLD_DI_SERINFOSIZE\fR request. See \fBEXAMPLES\fR. +.sp +The returned \fBDl_serinfo_t\fR structure contains \fBdls_cnt\fR +\fBDl_serpath_t\fR entries. Each entry's \fBdlp_name\fR member points to the +search path. The corresponding \fBdlp_info\fR member contains one of more flags +indicating the origin of the path. See the \fBLA_SER_*\fR flags that are +defined in <\fBlink.h\fR>. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_DI_SERINFOSIZE\fR\fR +.ad +.sp .6 +.RS 4n +Initialize a \fBDl_serinfo_t\fR structure for the \fIhandle\fR that is +specified, for use in a \fBRTLD_DI_SERINFO\fR request. Both the \fBdls_cnt\fR +and \fBdls_size\fR members are returned. The \fBdls_cnt\fR member indicates the +number of search paths that are applicable to the \fIhandle\fR. The +\fBdls_size\fR member indicates the total size of a \fBDl_serinfo_t\fR buffer +required to hold \fBdls_cnt\fR \fBDl_serpath_t\fR entries and the associated +search path strings. The \fIp\fR argument is a \fBDl_serinfo_t\fR pointer +(\fBDl_serinfo_t *\fR\fIp\fR). +.sp +To obtain the complete path information, a new \fBDl_serinfo_t\fR buffer of +size \fBdls_size\fR should be allocated. This new buffer should be initialized +with the \fBdls_cnt\fR and \fBdls_size\fR entries. The initialized buffer is +then passed to a \fBRTLD_DI_SERINFO\fR request. See \fBEXAMPLES\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_DI_ORIGIN\fR\fR +.ad +.sp .6 +.RS 4n +Obtain the origin of the dynamic object that is associated with the +\fIhandle\fR. The \fIp\fR argument is a \fBchar\fR pointer (\fBchar +*\fR\fIp\fR). The \fBdirname\fR(3C) of the associated object's +\fBrealpath\fR(3C), which can be no larger than {\fBPATH_MAX\fR}, is copied to +the pointer \fIp\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_DI_GETSIGNAL\fR\fR +.ad +.sp .6 +.RS 4n +Obtain the numeric signal number used by the runtime linker to kill the process +in the event of a fatal runtime error. The \fIp\fR argument is an \fBint\fR +pointer (\fBint *\fR\fIp\fR). The signal number is copied to the pointer +\fIp\fR. +.sp +By default, the signal used by the runtime linker to terminate a process is +\fBSIGKILL\fR. See \fBthr_kill\fR(3C). This default can be changed by calling +\fBdlinfo()\fR with \fBRTLD_DI_SETSIGNAL\fR or by setting the environment +variable \fBLD_SIGNAL\fR. See \fBld.so.1\fR(1). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_DI_SETSIGNAL\fR\fR +.ad +.sp .6 +.RS 4n +Provide a numeric signal number used by the runtime linker to kill the process +in the event of a fatal runtime error. The \fIp\fR argument is an \fBint\fR +pointer (\fBint *\fR\fIp\fR). The value pointed to by \fIp\fR is established as +the terminating signal value. +.sp +The current signal number used by the runtime linker to terminate a process can +be obtained from \fBdlinfo()\fR using \fBRTLD_DI_GETSIGNAL\fR. Use of the +\fBRTLD_DI_SETSIGNAL\fR option is equivalent to setting the environment +variable \fBLD_SIGNAL\fR. See \fBld.so.1\fR(1). +.RE + +.SH RETURN VALUES +.sp +.LP +The \fBdlinfo()\fR function returns \(mi1 if the \fIrequest\fR is invalid, the +parameter \fIp\fR is \fINULL\fR, or the \fBDl_serinfo_t\fR structure is +uninitialized for a \fBRTLD_DI_SERINFO\fR request. \fBdlinfo()\fR also returns +\(mi1 if the \fIhandle\fR argument does not refer to a valid object opened by +\fBdlopen()\fR, or is not the special handle \fBRTLD_SELF\fR. Detailed +diagnostic information is available with \fBdlerror\fR(3C). +.SH EXAMPLES +.LP +\fBExample 1 \fRUse \fBdlinfo()\fR to obtain library search paths. +.sp +.LP +The following example demonstrates how a dynamic object can inspect the library +search paths that would be used to locate a simple filename with +\fBdlopen()\fR. For simplicity, error checking has been omitted. + +.sp +.in +2 +.nf + Dl_serinfo_t _info, *info = &_info; + Dl_serpath_t *path; + uint_t cnt; + + /* determine search path count and required buffer size */ + dlinfo(RTLD_SELF, RTLD_DI_SERINFOSIZE, info); + + /* allocate new buffer and initialize */ + info = malloc(_info.dls_size); + info->dls_size = _info.dls_size; + info->dls_cnt = _info.dls_cnt; + + /* obtain sarch path information */ + dlinfo(RTLD_SELF, RTLD_DI_SERINFO, info); + + path = &info->dls_serpath[0]; + + for (cnt = 1; cnt <= info->dls_cnt; cnt++, path++) { + (void) printf("%2d: %s\en", cnt, path->dls_name); + } +.fi +.in -2 + +.LP +\fBExample 2 \fRUse \fBdlinfo()\fR to obtain segment information. +.sp +.LP +The following example demonstrates how a dynamic object can inspect its segment +mapping information. For simplicity, error checking has been omitted + +.sp +.in +2 +.nf + Dl_mapinfo_t mi; + uint_t cnt; + + /* determine the number of segment mappings */ + dlinfo(RTLD_SELF, RTLD_DI_MMAPCNT, &mi.dlm_acnt); + + /* allocate the appropriate mapping array */ + mi.dlm_maps = malloc(mi.dlm_acnt * sizeof (mmapobj_result_t)); + + /* obtain the mapping information */ + dlinfo(RTLD_SELF, RTLD_DI_MMAPS, &mi); + + for (cnt = 0; cnt < mi.dlm_rcnt; cnt++) { + (void) printf("addr=%x - memory size=%x\en", + mi.dlm_maps[cnt].mr_addr, mi.dlm_maps[cnt].mr_msize); + } +.fi +.in -2 + +.SH USAGE +.sp +.LP +The \fBdlinfo()\fR function is one of a family of functions that give the user +direct access to the dynamic linking facilities. These facilities are available +to dynamically-linked processes only. See the \fILinker and Libraries Guide\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStable +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBld\fR(1), \fBld.so.1\fR(1), \fBexec\fR(2), \fBioctl\fR(2), \fBmmapobj\fR(2), +\fBdirname\fR(3C), \fBdlclose\fR(3C), \fBdldump\fR(3C), \fBdlerror\fR(3C), +\fBdlopen\fR(3C), \fBdlsym\fR(3C), \fBputenv\fR(3C), \fBrealpath\fR(3C), +\fBthr_kill\fR(3C), \fBattributes\fR(5). +.sp +.LP +\fILinker and Libraries Guide\fR diff --git a/usr/src/man/man3c/dlopen.3c b/usr/src/man/man3c/dlopen.3c new file mode 100644 index 0000000000..48d536af43 --- /dev/null +++ b/usr/src/man/man3c/dlopen.3c @@ -0,0 +1,401 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dlopen 3C "4 Feb 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +dlopen, dlmopen \- gain access to an executable object file +.SH SYNOPSIS +.LP +.nf +#include <dlfcn.h> +#include <link.h> + +\fBvoid *\fR \fBdlopen\fR(\fBconst char *\fR\fIpathname\fR, \fBint\fR \fImode\fR); +.fi + +.LP +.nf +\fBvoid *\fR \fBdlmopen\fR(\fBLmid_t\fR \fIlmid\fR, \fBconst char *\fR\fIpathname\fR, \fBint\fR \fImode\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBdlopen()\fR function makes an executable object file available to a +running process. \fBdlopen()\fR returns to the process a \fIhandle\fR that the +process can use on subsequent calls to \fBdlsym\fR(3C), \fBdladdr\fR(3C), +\fBdlinfo\fR(3C), and \fBdlclose\fR(3C). The value of this \fIhandle\fR should +not be interpreted in any way by the process. The \fIpathname\fR argument is +the path name of the object to be opened. A path name containing an embedded +\fB\&'/'\fR is interpreted as an absolute path or relative to the current +directory. Otherwise, the set of search paths currently in effect by the +runtime linker are used to locate the specified file. See \fBNOTES\fR. +.sp +.LP +The \fBdlopen()\fR function also loads any dependencies recorded within +\fIpathname\fR. These dependencies are searched in the order in which the +dependencies were loaded to locate any additional dependencies. This process +continues until all the dependencies of \fIpathname\fR are loaded. This +dependency tree is referred to as a group. +.sp +.LP +If the value of \fIpathname\fR is \fB0\fR, \fBdlopen()\fR provides a +\fIhandle\fR on a set of global symbol objects. These objects consist of the +original program image file, any dependencies loaded at program startup, and +any objects loaded using \fBdlopen()\fR with the \fBRTLD_GLOBAL\fR flag. +Because the latter set of objects can change during process execution, the set +identified by \fIhandle\fR can also change dynamically. +.sp +.LP +The \fImode\fR argument describes how \fBdlopen()\fR operates on \fIpathname\fR +with respect to the processing of reference relocations. The \fImode\fR also +affects the scope of visibility of the symbols provided by \fIpathname\fR and +its dependencies. This visibility can affect how the resulting \fIhandle\fR is +used. +.sp +.LP +When an object is loaded, the object can contain references to symbols whose +addresses are not known until the object is loaded. These references must be +relocated before the symbols can be accessed. References are categorized as +either \fBimmediate\fR or \fBlazy\fR. Immediate references are typically +references to data items used by the object code. Immediate references include +pointers to functions and calls to functions made from position-dependent +shared objects. Lazy references are typically calls to global functions that +are made from position-independent shared objects. The \fImode\fR argument +governs when these references take place. The \fImode\fR argument can be one of +the following values: +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_LAZY\fR\fR +.ad +.RS 13n +.rt +Only immediate symbol references are relocated when the object is first loaded. +Lazy references are not relocated until a given function is called for the +first time. This value for \fImode\fR should improve performance, since a +process might not require all lazy references in any given object. This +behavior mimics the normal loading of dependencies during process +initialization. See \fBNOTES\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_NOW\fR\fR +.ad +.RS 13n +.rt +All necessary relocations are performed when the object is first loaded. This +process might waste some processing if relocations are performed for lazy +references that are never used. However, this mode ensures that when an object +is loaded, all symbols referenced during execution are available. This behavior +mimics the loading of dependencies when the environment variable +\fBLD_BIND_NOW\fR is in effect. +.RE + +.sp +.LP +See the \fILinker and Libraries Guide\fR for more information about symbol +references. +.sp +.LP +The visibility of symbols that are available for relocation can be affected by +\fImode\fR. To specify the scope of visibility for symbols that are loaded with +a \fBdlopen()\fR call, \fImode\fR should be a bitwise-inclusive OR with one of +the following values: +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_GLOBAL\fR\fR +.ad +.RS 15n +.rt +The object's global symbols are made available for the relocation processing of +any other object. In addition, symbol lookup using \fBdlopen(0,\fR +\fImode\fR\fB)\fR and an associated \fBdlsym()\fR allows objects that are +loaded with \fBRTLD_GLOBAL\fR to be searched. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_LOCAL\fR\fR +.ad +.RS 15n +.rt +The object's globals symbols are only available for the relocation processing +of other objects that include the same group. +.RE + +.sp +.LP +The program image file and any objects loaded at program startup have the mode +\fBRTLD_GLOBAL\fR. The mode \fBRTLD_LOCAL\fR is the default mode for any +objects that are acquired with \fBdlopen()\fR. A local object can be a +dependency of more then one group. Any object of mode \fBRTLD_LOCAL\fR that is +referenced as a dependency of an object of mode \fBRTLD_GLOBAL\fR is promoted +to \fBRTLD_GLOBAL\fR. In other words, the \fBRTLD_LOCAL\fR mode is ignored. +.sp +.LP +Any object loaded by \fBdlopen()\fR that requires relocations against global +symbols can reference the symbols in any \fBRTLD_GLOBAL\fR object. Objects of +this mode are at least the program image file and any objects loaded at program +startup. A loaded object can also reference symbols from itself, and from any +dependencies the object references. However, the \fImode\fR parameter can also +be a bitwise-inclusive \fBOR\fR with one of the following values to affect the +scope of symbol availability: +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_GROUP\fR\fR +.ad +.RS 15n +.rt +Only symbols from the associated group are made available for relocation. A +group is established from the defined object and all the dependencies of that +object. A group must be completely self-contained. All dependency relationships +between the members of the group must be sufficient to satisfy the relocation +requirements of each object that defines the group. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_PARENT\fR\fR +.ad +.RS 15n +.rt +The symbols of the object initiating the \fBdlopen()\fR call are made available +to the objects obtained by \fBdlopen()\fR. This option is useful when +hierarchical \fBdlopen()\fR families are created. Although the parent object +can supply symbols for the relocation of this object, the parent object is not +available to \fBdlsym()\fR through the returned \fIhandle\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_WORLD\fR\fR +.ad +.RS 15n +.rt +Only symbols from \fBRTLD_GLOBAL\fR objects are made available for relocation. +.RE + +.sp +.LP +The default modes for \fBdlopen()\fR are both \fBRTLD_WORLD\fR and +\fBRTLD_GROUP\fR. If an object is requires additional modes, the \fImode\fR +parameter can be the bitwise-inclusive OR of the required modes together with +the default modes. +.sp +.LP +The following modes provide additional capabilities outside of relocation +processing: +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_NODELETE\fR\fR +.ad +.RS 17n +.rt +The specified object is tagged to prevent its deletion from the address space +as part of a \fBdlclose()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_NOLOAD\fR\fR +.ad +.RS 17n +.rt +The specified object is not loaded as part of the \fBdlopen()\fR. However, a +valid \fIhandle\fR is returned if the object already exists as part of the +process address space. Additional modes can be specified as a bitwise-inclusive +OR with the present mode of the object and its dependencies. The +\fBRTLD_NOLOAD\fR mode provides a means of querying the presence or promoting +the modes of an existing dependency. +.RE + +.sp +.LP +The default use of a \fIhandle\fR with \fBdlsym()\fR allows a symbol search to +inspect all objects that are associated with the group of objects that are +loaded from \fBdlopen()\fR. The \fImode\fR parameter can also be a +bitwise-inclusive OR with the following value to restrict this symbol search: +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_FIRST\fR\fR +.ad +.RS 14n +.rt +Use of this \fIhandle\fR with \fBdlsym()\fR, restricts the symbol search to the +first object associated with the \fIhandle\fR. +.RE + +.sp +.LP +An object can be accessed from a process both with and without +\fBRTLD_FIRST\fR. Although the object will only be loaded once, two different +\fIhandle\fRs are created to provide for the different \fBdlsym()\fR +requirements. +.sp +.LP +The \fBdlmopen()\fR function is identical to \fBdlopen()\fR, except that an +identifying link-map ID \fI(lmid)\fR is provided. This link-map ID informs the +dynamic linking facilities upon which link-map list to load the object. See the +\fILinker and Libraries Guide\fR for details about link-maps. +.sp +.LP +The \fIlmid\fR passed to \fBdlmopen()\fR identifies the link-map list on which +the object is loaded. This parameter can be any valid \fBLmid_t\fR returned by +\fBdlinfo()\fR or one of the following special values: +.sp +.ne 2 +.mk +.na +\fB\fBLM_ID_BASE\fR\fR +.ad +.RS 15n +.rt +Load the object on the applications link-map list. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLM_ID_LDSO\fR\fR +.ad +.RS 15n +.rt +Load the object on the dynamic linkers (\fBld.so.1\fR) link-map list. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLM_ID_NEWLM\fR\fR +.ad +.RS 15n +.rt +Cause the object to create a new link-map list as part of loading. Objects that +are opened on a new link-map list must express all of their dependencies. +.RE + +.SH RETURN VALUES +.sp +.LP +The \fBdlopen()\fR function returns \fINULL\fR if \fIpathname\fR cannot be +found, cannot be opened for reading, or is not a shared object or a relocatable +object. \fBdlopen()\fR also returns \fINULL\fR if an error occurs during the +process of loading \fIpathname\fR or relocating its symbolic references. See +\fBNOTES\fR. Additional diagnostic information is available through +\fBdlerror()\fR. +.SH USAGE +.sp +.LP +The \fBdlopen()\fR and \fBdlmopen()\fR functions are members of a family of +functions that give the user direct access to the dynamic linking facilities. +This family of functions is available only to dynamically-linked processes. See +the \fILinker and Libraries Guide\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT\(miLevelMT\(miSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBld\fR(1), \fBld.so.1\fR(1), \fBdladdr\fR(3C), \fBdlclose\fR(3C), +\fBdldump\fR(3C), \fBdlerror\fR(3C), \fBdlinfo\fR(3C), \fBdlsym\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) +.sp +.LP +\fILinker and Libraries Guide\fR +.SH NOTES +.sp +.LP +If \fIpathname\fR has dependencies on other objects, these objects are +automatically loaded by \fBdlopen()\fR. The directory search path used to find +\fIpathname\fR and any dependencies can be affected by setting the environment +variable \fBLD_LIBRARY_PATH\fR. Any \fBLD_LIBRARY_PATH\fR variable is analyzed +once at process startup. The search path can also be affected from a runpath +setting within the object from which the call to \fBdlopen()\fR originates. +These search rules will only be applied to path names that do not contain an +embedded \fB\&'/'\fR. Objects whose names resolve to the same absolute path +name or relative path name can be opened any number of times using +\fBdlopen()\fR. However, the object that is referenced will only be loaded once +into the address space of the current process. +.sp +.LP +When loading shared objects, the application should open a specific version of +the shared object. Do not rely on the version of the shared object pointed to +by the symbolic link. +.sp +.LP +When building objects to be loaded on a new link-map list, some precautions +need to be taken. In general, all dependencies must be included when building +an object. Also, include \fB/usr/lib/libmapmalloc.so.1\fR before +\fB/lib/libc.so.1\fR when building an object. +.sp +.LP +When an object is loaded on a new link-map list, the object is isolated from +the main running program. Certain global resources are only usable from one +link-map list. A few examples are the \fBsbrk()\fR based \fBmalloc()\fR, +\fBlibthread()\fR, and the signal vectors. Care must be taken not to use any of +these resources other than from the primary link-map list. These issues are +discussed in further detail in the \fILinker and Libraries Guide\fR. +.sp +.LP +Some symbols defined in dynamic executables or shared objects can not be +available to the runtime linker. The symbol table created by \fBld\fR for use +by the runtime linker might contain only a subset of the symbols that are +defined in the object. +.sp +.LP +As part of loading a new object, initialization code within the object is +called \fBbefore\fR the \fBdlopen()\fR returns. This initialization is user +code, and as such, can produce errors that can not be caught by \fBdlopen()\fR. +For example, an object loaded using \fBRTLD_LAZY\fR that attempts to call a +function that can not be located results in process termination. Erroneous +programming practices within the initialization code can also result in process +termination. The runtime linkers debugging facility can offer help identifying +these types of error. See the \fBLD_DEBUG\fR environment variable of +\fBld.so.1\fR(1). +.sp +.LP +Loading relocatable objects is an expensive operation that requires converting +the relocatable object into a shared object memory image. This capability may +be useful in a debugging environment, but is not recommended for production +software. diff --git a/usr/src/man/man3c/dlsym.3c b/usr/src/man/man3c/dlsym.3c new file mode 100644 index 0000000000..94ee17b99e --- /dev/null +++ b/usr/src/man/man3c/dlsym.3c @@ -0,0 +1,219 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dlsym 3C "26 Sep 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +dlsym \- get the address of a symbol in a shared object or executable +.SH SYNOPSIS +.LP +.nf +#include <dlfcn.h> + +\fBvoid *\fR\fBdlsym\fR(\fBvoid *restrict\fR \fIhandle\fR, \fBconst char *restrict\fR \fIname\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBdlsym()\fR function allows a process to obtain the address of a symbol +that is defined within a shared object or executable. The \fIhandle\fR argument +is either the value returned from a call to \fBdlopen()\fR or one of a family +of special handles. The \fIname\fR argument is the symbol's name as a character +string. +.sp +.LP +If \fIhandle\fR is returned from \fBdlopen()\fR, the associated shared object +must not have been closed using \fBdlclose()\fR. A \fIhandle\fR can be obtained +from \fBdlopen()\fR using the \fBRTLD_FIRST\fR mode. With this mode, the +\fBdlsym()\fR function searches for the named symbol in the initial object +referenced by \fIhandle\fR. Without this mode, the \fBdlsym()\fR function +searches for the named symbol in the group of shared objects loaded +automatically as a result of loading the object referenced by \fIhandle\fR. See +\fBdlopen\fR(3C) and NOTES. +.sp +.LP +The following special handles are supported. +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_DEFAULT\fR\fR +.ad +.RS 16n +.rt +Instructs \fBdlsym()\fR to search for the named symbol starting with the first +object loaded, typically the dynamic executable. The search continues through +the list of initial dependencies that are loaded with the process, followed by +any objects obtained with \fBdlopen\fR(3C). This search follows the default +model that is used to relocate all objects within the process. +.sp +This model also provides for transitioning into a lazy loading environment. If +a symbol can not be found in the presently loaded objects, any pending lazy +loaded objects are processed in an attempt to locate the symbol. This loading +compensates for objects that have not fully defined their dependencies. +However, this compensation can undermine the advantages of lazy loading. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_PROBE\fR\fR +.ad +.RS 16n +.rt +Instructs \fBdlsym()\fR to search for the named symbol in the same manner as +occurs with a \fIhandle\fR of \fBRTLD_DEFAULT\fR. However, this model only +searches for symbols in the presently loaded objects, together with any lazy +loadable objects specifically identified by the caller to provide the named +symbol. This handle does not trigger an exhaustive load of any lazy loadable +symbols in an attempt to find the named symbol. This handle can provide a more +optimal search than would occur using \fBRTLD_DEFAULT\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_NEXT\fR\fR +.ad +.RS 16n +.rt +Instructs \fBdlsym()\fR to search for the named symbol in the objects that were +loaded following the object from which the \fBdlsym()\fR call is being made. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRTLD_SELF\fR\fR +.ad +.RS 16n +.rt +Instructs \fBdlsym()\fR to search for the named symbol in the objects that were +loaded starting with the object from which the \fBdlsym()\fR call is being +made. +.RE + +.sp +.LP +When used with a special handle, \fBdlsym()\fR is selective in searching +objects that have been loaded using \fBdlopen()\fR. These objects are searched +for symbols if one of the following conditions are true. +.RS +4 +.TP +.ie t \(bu +.el o +The object is part of the same local \fBdlopen()\fR dependency hierarchy as the +calling object. See the \fILinker and Libraries Guide\fR for a description of +\fBdlopen()\fR dependency hierarchies. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The object has global search access. See \fBdlopen\fR(3C) for a discussion of +the \fBRTLD_GLOBAL\fR mode. +.RE +.SH RETURN VALUES +.sp +.LP +The \fBdlsym()\fR function returns \fINULL\fR if \fIhandle\fR does not refer to +a valid object opened by \fBdlopen()\fR or is not one of the special handles. +The function also returns \fINULL\fR if the named symbol cannot be found within +any of the objects associated with \fIhandle\fR. Additional diagnostic +information is available through \fBdlerror\fR(3C). +.SH EXAMPLES +.LP +\fBExample 1 \fRUse \fBdlopen()\fR and \fBdlsym()\fR to access a function or +data objects. +.sp +.LP +The following code fragment demonstrates how to use \fBdlopen()\fR and +\fBdlsym()\fR to access either function or data objects. For simplicity, error +checking has been omitted. + +.sp +.in +2 +.nf +void *handle; +int *iptr, (*fptr)(int); + +/* open the needed object */ +handle = dlopen("/usr/home/me/libfoo.so.1", RTLD_LAZY); + +/* find the address of function and data objects */ +fptr = (int (*)(int))dlsym(handle, "my_function"); +iptr = (int *)dlsym(handle, "my_object"); + +/* invoke function, passing value of integer as a parameter */ +(*fptr)(*iptr); +.fi +.in -2 + +.LP +\fBExample 2 \fRUse \fBdlsym()\fR to verify that a particular function is +defined. +.sp +.LP +The following code fragment shows how to use \fBdlsym()\fR to verify that a +function is defined. If the function exists, the function is called. + +.sp +.in +2 +.nf +int (*fptr)(); + +if ((fptr = (int (*)())dlsym(RTLD_DEFAULT, + "my_function")) != NULL) { + (*fptr)(); +} +.fi +.in -2 + +.SH USAGE +.sp +.LP +The \fBdlsym()\fR function is one of a family of functions that give the user +direct access to the dynamic linking facilities. These facilities are available +to dynamically-linked processes only. See the \fILinker and Libraries Guide\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBld\fR(1), \fBld.so.1\fR(1), \fBdladdr\fR(3C), \fBdlclose\fR(3C), +\fBdldump\fR(3C), \fBdlerror\fR(3C), \fBdlinfo\fR(3C), \fBdlopen\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) +.sp +.LP +\fILinker and Libraries Guide\fR +.SH NOTES +.sp +.LP +If an object is acting as a filter, care should be taken when interpreting the +address of any symbol obtained using a handle to this object. For example, +using dlsym(3C) to obtain the symbol \fI_end\fR for this object, results in +returning the address of the symbol \fI_end\fR within the filtee, not the +filter. For more information on filters see the \fILinker and Libraries +Guide\fR. diff --git a/usr/src/man/man3c/door_bind.3c b/usr/src/man/man3c/door_bind.3c new file mode 100644 index 0000000000..cc00575aa1 --- /dev/null +++ b/usr/src/man/man3c/door_bind.3c @@ -0,0 +1,207 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH door_bind 3C "22 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +door_bind, door_unbind \- bind or unbind the current thread with the door +server pool +.SH SYNOPSIS +.LP +.nf +\fBcc\fR \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <door.h> + +\fBint\fR \fBdoor_bind\fR(\fBint\fR \fIdid\fR); +.fi + +.LP +.nf +\fBint\fR \fBdoor_unbind\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBdoor_bind()\fR function associates the current thread with a door server +pool. A door server pool is a private pool of server threads that is available +to serve door invocations associated with the door \fIdid\fR. +.sp +.LP +The \fBdoor_unbind()\fR function breaks the association of \fBdoor_bind()\fR by +removing any private door pool binding that is associated with the current +thread. +.sp +.LP +Normally, door server threads are placed in a global pool of available threads +that invocations on any door can use to dispatch a door invocation. A door that +has been created with \fBDOOR_PRIVATE\fR only uses server threads that have +been associated with the door by \fBdoor_bind()\fR. It is therefore necessary +to bind at least one server thread to doors created with \fBDOOR_PRIVATE\fR. +.sp +.LP +The server thread create function, \fBdoor_server_create()\fR, is initially +called by the system during a \fBdoor_create()\fR operation. See +\fBdoor_server_create\fR(3C) and \fBdoor_create\fR(3C). +.sp +.LP +The current thread is added to the private pool of server threads associated +with a door during the next \fBdoor_return()\fR (that has been issued by the +current thread after an associated \fBdoor_bind()\fR). See +\fBdoor_return\fR(3C). A server thread performing a \fBdoor_bind()\fR on a +door that is already bound to a different door performs an implicit +\fBdoor_unbind()\fR of the previous door. +.sp +.LP +If a process containing threads that have been bound to a door calls +\fBfork\fR(2), the threads in the child process will be bound to an invalid +door, and any calls to \fBdoor_return\fR(3C) will result in an error. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, a \fB0\fR is returned. Otherwise, \fB\(mi1\fR is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBdoor_bind()\fR and \fBdoor_unbind()\fR functions fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIdid\fR argument is not a valid door. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fBdoor_unbind()\fR function was called by a thread that is currently not +bound. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +\fIdid\fR was not created with the \fBDOOR_PRIVATE\fR attribute. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRUse \fBdoor_bind()\fR to create private server pools for two +doors. +.sp +.LP +The following example shows the use of \fBdoor_bind()\fR to create private +server pools for two doors, \fBd1\fR and \fBd2\fR. Function \fBmy_create()\fR +is called when a new server thread is needed; it creates a thread running +function, \fBmy_server_create()\fR, which binds itself to one of the two doors. + +.sp +.in +2 +.nf +#include <door.h> +#include <thread.h> +#include <pthread.h> +thread_key_t door_key; +int d1 = -1; +int d2 = -1; +cond_t cv; /* statically initialized to zero */ +mutex_t lock; /* statically initialized to zero */ + +extern void foo(void *, char *, size_t, door_desc_t *, uint_t); +extern void bar(void *, char *, size_t, door_desc_t *, uint_t); + +static void * +my_server_create(void *arg) +{ + /* wait for d1 & d2 to be initialized */ + mutex_lock(&lock); + while (d1 == -1 || d2 == -1) + cond_wait(&cv, &lock); + mutex_unlock(&lock); + + if (arg == (void *)foo){ + /* bind thread with pool associated with d1 */ + thr_setspecific(door_key, (void *)foo); + if (door_bind(d1) < 0) { + perror("door_bind"); exit (-1); + } + } else if (arg == (void *)bar) { + /* bind thread with pool associated with d2 */ + thr_setspecific(door_key, (void *)bar); + if (door_bind(d2) < 0) { + /* bind thread to d2 thread pool */ + perror("door_bind"); exit (-1); + } + } + pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL); + door_return(NULL, 0, NULL, 0); /* Wait for door invocation */ +} + +static void +my_create(door_info_t *dip) +{ + /* Pass the door identity information to create function */ + thr_create(NULL, 0, my_server_create, (void *)dip->di_proc, + THR_BOUND | THR_DETACHED, NULL); +} + +main() +{ + (void) door_server_create(my_create); + if (thr_keycreate(&door_key, NULL) != 0) { + perror("thr_keycreate"); + exit(1); + } + mutex_lock(&lock); + d1 = door_create(foo, NULL, DOOR_PRIVATE); /* Private pool */ + d2 = door_create(bar, NULL, DOOR_PRIVATE); /* Private pool */ + cond_signal(&cv); + mutex_unlock(&lock); + while (1) + pause(); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Architectureall +_ +Interface StabilityStable +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfork\fR(2),\fBdoor_create\fR(3C), \fBdoor_return\fR(3C), +\fBdoor_server_create\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/door_call.3c b/usr/src/man/man3c/door_call.3c new file mode 100644 index 0000000000..90a4c9851d --- /dev/null +++ b/usr/src/man/man3c/door_call.3c @@ -0,0 +1,347 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH door_call 3C "22 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +door_call \- invoke the function associated with a door descriptor +.SH SYNOPSIS +.LP +.nf +\fBcc\fR \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <door.h> + +\fBint\fR \fBdoor_call\fR(\fBint\fR \fId\fR, \fBdoor_arg_t *\fR\fIparams\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBdoor_call()\fR function invokes the function associated with the door +descriptor \fId\fR, and passes the arguments (if any) specified in +\fIparams\fR. All of the \fIparams\fR members are treated as in/out parameters +during a door invocation and may be updated upon returning from a door call. +Passing \fINULL\fR for \fIparams\fR indicates there are no arguments to be +passed and no results expected. +.sp +.LP +Arguments are specified using the \fBdata_ptr\fR and \fBdesc_ptr\fR members of +\fIparams\fR. The size of the argument data in bytes is passed in +\fBdata_size\fR and the number of argument descriptors is passed in +\fBdesc_num\fR. +.sp +.LP +Results from the door invocation are placed in the buffer, \fBrbuf\fR. See +\fBdoor_return\fR(3C). The \fBdata_ptr\fR and \fBdesc_ptr\fR members of +\fIparams\fR are updated to reflect the location of the results within the +\fBrbuf\fR buffer. The size of the data results and number of descriptors +returned are updated in the \fBdata_size\fR and \fBdesc_num\fR members. It is +acceptable to use the same buffer for input argument data and results, so +\fBdoor_call()\fR may be called with \fBdata_ptr\fR and \fBdesc_ptr\fR pointing +to the buffer \fBrbuf\fR. +.sp +.LP +If the results of a door invocation exceed the size of the buffer specified by +\fBrsize\fR, the system automatically allocates a new buffer in the caller's +address space and updates the \fBrbuf\fR and \fBrsize\fR members to reflect +this location. In this case, the caller is responsible for reclaiming this +area using \fBmunmap(rbuf, rsize)\fR when the buffer is no longer required. +See \fBmunmap\fR(2). +.sp +.LP +Descriptors passed in a \fBdoor_desc_t\fR structure are identified by the +\fBd_attributes\fR member. The client marks the \fBd_attributes\fR member with +the type of object being passed by logically OR-ing the value of object type. +Currently, the only object type that can be passed or returned is a file +descriptor, denoted by the \fBDOOR_DESCRIPTOR\fR attribute. Additionally, the +\fBDOOR_RELEASE\fR attribute can be set, causing the descriptor to be closed +in the caller's address space after it is passed to the target. The descriptor +will be closed even if \fBdoor_call()\fR returns an error, unless that error +is \fBEFAULT\fR or \fBEBADF\fR. +.sp +.LP +The \fBdoor_desc_t\fR structure includes the following members: +.sp +.in +2 +.nf +typedef struct { + door_attr_t d_attributes; /* Describes the parameter */ + union { + struct { + int d_descriptor; /* Descriptor */ + door_id_t d_id; /* Unique door id */ + } d_desc; + } d_data; + } door_desc_t; +.fi +.in -2 + +.sp +.LP +When file descriptors are passed or returned, a new descriptor is created in +the target address space and the \fBd_descriptor\fR member in the target +argument is updated to reflect the new descriptor. In addition, the system +passes a system-wide unique number associated with each door in the +\fBdoor_id\fR member and marks the \fBd_attributes\fR member with other +attributes associated with a door including the following: +.sp +.ne 2 +.mk +.na +\fB\fBDOOR_LOCAL\fR\fR +.ad +.RS 20n +.rt +The door received was created by this process using \fBdoor_create()\fR. See +\fBdoor_create\fR(3C). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDOOR_PRIVATE\fR\fR +.ad +.RS 20n +.rt +The door received has a private pool of server threads associated with the +door. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDOOR_UNREF\fR\fR +.ad +.RS 20n +.rt +The door received is expecting an unreferenced notification. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDOOR_UNREF_MULTI\fR\fR +.ad +.RS 20n +.rt +Similar to \fBDOOR_UNREF\fR, except multiple unreferenced notifications may be +delivered for the same door. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDOOR_REFUSE_DESC\fR\fR +.ad +.RS 20n +.rt +This door does not accept argument descriptors. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDOOR_NO_CANCEL\fR\fR +.ad +.RS 20n +.rt +This door does not cancel the server thread upon client abort. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDOOR_REVOKED\fR\fR +.ad +.RS 20n +.rt +The door received has been revoked by the server. +.RE + +.sp +.LP +The \fBdoor_call()\fR function is not a restartable system call. It returns +\fBEINTR\fR if a signal was caught and handled by this thread. If the door +invocation is not idempotent the caller should mask any signals that may be +generated during a \fBdoor_call()\fR operation. If the client aborts in the +middle of a \fBdoor_call()\fR and the door was not created with the +\fBDOOR_NO_CANCEL\fR flag, the server thread is notified using the POSIX (see +\fBstandards\fR(5)) thread cancellation mechanism. See \fBcancellation\fR(5). +.sp +.LP +The descriptor returned from \fBdoor_create()\fR is marked as close on +\fBexec(FD_CLOEXEC)\fR. Information about a door is available for all clients +of a door using \fBdoor_info()\fR. Applications concerned with security should +not place secure information in door data that is accessible by +\fBdoor_info()\fR. In particular, secure data should not be stored in the data +item \fIcookie\fR. See \fBdoor_info\fR(3C). +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBdoor_call()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBE2BIG\fR\fR +.ad +.RS 13n +.rt +Arguments were too big for server thread stack. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 13n +.rt +Server was out of available resources. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 13n +.rt +Invalid door descriptor was passed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 13n +.rt +Argument pointers pointed outside the allocated address space. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 13n +.rt +A signal was caught in the client, the client called \fBfork\fR(2), or the +server exited during invocation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 13n +.rt +Bad arguments were passed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 13n +.rt +The client or server has too many open descriptors. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENFILE\fR\fR +.ad +.RS 13n +.rt +The \fIdesc_num\fR argument is larger than the door's \fBDOOR_PARAM_DESC_MAX\fR +parameter (see \fBdoor_getparam\fR(3C)), and the door does not have the +\fBDOOR_REFUSE_DESC\fR set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOBUFS\fR\fR +.ad +.RS 13n +.rt +The \fIdata_size\fR argument is larger than the door's +\fBDOOR_PARAM_DATA_MAX\fR parameter, or smaller than the door's +\fBDOOR_PARAM_DATA_MIN\fR parameter (see \fBdoor_getparam\fR(3C)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSUP\fR\fR +.ad +.RS 13n +.rt +The \fIdesc_num\fR argument is non-zero and the door has the +\fBDOOR_REFUSE_DESC\fR flag set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOVERFLOW\fR\fR +.ad +.RS 13n +.rt +System could not create overflow area in caller for results. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Architectureall +_ +Interface StabilityStable +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBmunmap\fR(2), \fBdoor_create\fR(3C), \fBdoor_getparam\fR(3C), +\fBdoor_info\fR(3C), \fBdoor_return\fR(3C), \fBlibdoor\fR(3LIB), +\fBattributes\fR(5), \fBcancellation\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/door_create.3c b/usr/src/man/man3c/door_create.3c new file mode 100644 index 0000000000..b3907ecff7 --- /dev/null +++ b/usr/src/man/man3c/door_create.3c @@ -0,0 +1,240 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH door_create 3C "22 Jan 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +door_create \- create a door descriptor +.SH SYNOPSIS +.LP +.nf +\fBcc\fR \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <door.h> + +\fBint\fR \fBdoor_create\fR(\fBvoid (*\fR\fIserver_procedure\fR) (void *\fIcookie\fR, \fBchar *\fR\fIargp\fR, + \fBsize_t\fR \fIarg_size\fR, \fBdoor_desc_t *\fR\fIdp\fR, \fBuint_t\fR \fIn_desc\fR), \fBvoid *\fR\fIcookie\fR, + \fBuint_t\fR \fIattributes\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBdoor_create()\fR function creates a door descriptor that describes the +procedure specified by the function \fIserver_procedure\fR. The data item, +\fIcookie\fR, is associated with the door descriptor, and is passed as an +argument to the invoked function \fIserver_procedure\fR during +\fBdoor_call\fR(3C) invocations. Other arguments passed to +\fIserver_procedure\fR from an associated \fBdoor_call()\fR are placed on the +stack and include \fIargp\fR and \fIdp\fR. The \fIargp\fR argument points to +\fIarg_size\fR bytes of data and the \fIdp\fR argument points to \fIn_desc\fR +\fBdoor_desc_t\fR structures. The \fIattributes\fR argument specifies +attributes associated with the newly created door. Valid values for +\fIattributes\fR are constructed by OR-ing one or more of the following values: +.sp +.ne 2 +.mk +.na +\fB\fBDOOR_UNREF\fR\fR +.ad +.sp .6 +.RS 4n +Delivers a special invocation on the door when the number of descriptors that +refer to this door drops to one. In order to trigger this condition, more +than one descriptor must have referred to this door at some time. +\fBDOOR_UNREF_DATA\fR designates an unreferenced invocation, as the \fIargp\fR +argument passed to \fIserver_procedure\fR. In the case of an unreferenced +invocation, the values for \fIarg_size\fR, \fIdp\fR and \fIn_did\fR are +\fB0\fR. Only one unreferenced invocation is delivered on behalf of a door. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDOOR_UNREF_MULTI\fR\fR +.ad +.sp .6 +.RS 4n +Similar to \fBDOOR_UNREF\fR, except multiple unreferenced invocations can be +delivered on the same door if the number of descriptors referring to the door +drops to one more than once. Since an additional reference may have been +passed by the time an unreferenced invocation arrives, the \fBDOOR_IS_UNREF\fR +attribute returned by the \fBdoor_info\fR(3C) call can be used to determine if +the door is still unreferenced. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDOOR_PRIVATE\fR\fR +.ad +.sp .6 +.RS 4n +Maintains a separate pool of server threads on behalf of the door. Server +threads are associated with a door's private server pool using +\fBdoor_bind\fR(3C). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDOOR_REFUSE_DESC\fR\fR +.ad +.sp .6 +.RS 4n +Any attempt to call \fBdoor_call\fR(3C) on this door with argument descriptors +will fail with \fBENOTSUP\fR. When this flag is set, the door's server +procedure will always be invoked with an \fIn_desc\fR argument of 0. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDOOR_NO_CANCEL\fR\fR +.ad +.sp .6 +.RS 4n +Clients which abort calls to \fBdoor_call()\fR on this door will not cause the +cancellation of the server thread handling the request. See +\fBcancellation\fR(5). +.RE + +.sp +.LP +The descriptor returned from \fBdoor_create()\fR will be marked as close on +exec (\fBFD_CLOEXEC\fR). Information about a door is available for all clients +of a door using \fBdoor_info()\fR. Applications concerned with security should +not place secure information in door data that is accessible by +\fBdoor_info()\fR. In particular, secure data should not be stored in the data +item \fIcookie\fR. +.sp +.LP +By default, additional threads are created as needed to handle concurrent +\fBdoor_call()\fR invocations. See \fBdoor_server_create\fR(3C) for +information on how to change this behavior. +.sp +.LP +A process can advertise a door in the file system name space using +\fBfattach\fR(3C). +.sp +.LP +After creation, \fBdoor_setparam\fR(3C) can be used to set limits on the amount +of data and descriptors clients can send over the door. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBdoor_create()\fR returns a non-negative value. +Otherwise, \fBdoor_create\fR returns \fB\(mi1\fR and sets \fBerrno\fR to +indicate the error. +.SH ERRORS +.sp +.LP +The \fBdoor_create()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +Invalid attributes are passed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 10n +.rt +The process has too many open descriptors. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRCreate a door and use \fBfattach()\fR to advertise the door in +the file system namespace. +.sp +.LP +The following example creates a door and uses \fBfattach()\fR to advertise the +door in the file system namespace. + +.sp +.in +2 +.nf +void +server(void *cookie, char *argp, size_t arg_size, door_desc_t *dp, + uint_t n_desc) +{ + door_return(NULL, 0, NULL, 0); + /* NOTREACHED */ +} + +int +main(int argc, char *argv[]) +{ + int did; + struct stat buf; + + if ((did = door_create(server, 0, 0)) < 0) { + perror("door_create"); + exit(1); + } + + /* make sure file system location exists */ + if (stat("/tmp/door", &buf) < 0) { + int newfd; + if ((newfd = creat("/tmp/door", 0444)) < 0) { + perror("creat"); + exit(1); + } + (void) close(newfd); + } + + /* make sure nothing else is attached */ + (void) fdetach("/tmp/door"); + + /* attach to file system */ + if (fattach(did, "/tmp/door") < 0) { + perror("fattach"); + exit(2); + } + [...] +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Architectureall +_ +Interface StabilityCommitted +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdoor_bind\fR(3C), \fBdoor_call\fR(3C), \fBdoor_info\fR(3C), +\fBdoor_revoke\fR(3C), \fBdoor_setparam\fR(3C), \fBdoor_server_create\fR(3C), +\fBfattach\fR(3C), \fBlibdoor\fR(3LIB), \fBattributes\fR(5), +\fBcancellation\fR(5) diff --git a/usr/src/man/man3c/door_cred.3c b/usr/src/man/man3c/door_cred.3c new file mode 100644 index 0000000000..3d699eeffa --- /dev/null +++ b/usr/src/man/man3c/door_cred.3c @@ -0,0 +1,104 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH door_cred 3C "22 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +door_cred \- return credential information associated with the client +.SH SYNOPSIS +.LP +.nf +\fBcc\fR \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <door.h> + +\fBint\fR \fBdoor_cred\fR(\fBdoor_cred_t *\fR\fIinfo\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBdoor_cred()\fR function returns credential information associated with +the client (if any) of the current door invocation. +.sp +.LP +The contents of the \fIinfo\fR argument include the following fields: +.sp +.in +2 +.nf +uid_t dc_euid; /* Effective uid of client */ +gid_t dc_egid; /* Effective gid of client */ +uid_t dc_ruid; /* Real uid of client */ +gid_t dc_rgid; /* Real gid of client */ +pid_t dc_pid; /* pid of client */ +.fi +.in -2 + +.sp +.LP +The credential information associated with the client refers to the information +from the immediate caller; not necessarily from the first thread in a chain of +door calls. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBdoor_cred()\fR returns \fB0\fR. Otherwise, +\fBdoor_cred()\fR returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the +error. +.SH ERRORS +.sp +.LP +The \fBdoor_cred()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +.rt +The address of the \fIinfo\fR argument is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +There is no associated door client. +.RE + +.SH USAGE +.sp +.LP +The \fBdoor_cred()\fR function is obsolete. Applications should use the +\fBdoor_ucred\fR(3C) function in place of \fBdoor_cred()\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Architectureall +_ +Interface StabilityObsolete +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdoor_call\fR(3C), \fBdoor_create\fR(3C), \fBdoor_ucred\fR(3C), +\fBattributes\fR(5) diff --git a/usr/src/man/man3c/door_getparam.3c b/usr/src/man/man3c/door_getparam.3c new file mode 100644 index 0000000000..0c2bddf96e --- /dev/null +++ b/usr/src/man/man3c/door_getparam.3c @@ -0,0 +1,262 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH door_getparam 3C "22 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +door_getparam, door_setparam \- retrieve and set door parameters +.SH SYNOPSIS +.LP +.nf +\fBcc\fR \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <door.h> + +\fBint\fR \fBdoor_getparam\fR(\fBint\fR \fId\fR, \fBint\fR \fIparam\fR, \fBsize_t *\fR\fIout\fR); +.fi + +.LP +.nf +\fBint\fR \fBdoor_setparam\fR(\fBint\fR \fId\fR, \fBint\fR \fIparam\fR, \fBsize_t\fR \fIval\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBdoor_getparam()\fR function retrieves the value of \fIparam\fR for the +door descriptor \fId\fR and writes it through the pointer \fIout\fR. The +\fBdoor_setparam()\fR function sets the value of \fIparam\fR for the door +descriptor \fId\fR to \fIval\fR. The \fIparam\fR argument names the parameter +to view or change and can be one of the following values: +.sp +.ne 2 +.mk +.na +\fB\fBDOOR_PARAM_DATA_MAX\fR\fR +.ad +.RS 23n +.rt +This parameter represents the maximum amount of data that can be passed to the +door routine. Any attempt to call \fBdoor_call\fR(3C) on a door with a +\fIdata_size\fR value larger than the door's \fBDOOR_PARAM_DATA_MAX\fR +parameter will fail with \fBENOBUFS\fR. At door creation time, this parameter +is initialized to \fBSIZE_MAX\fR and can be set to any value from 0 to +\fBSIZE_MAX\fR, inclusive. This parameter must be greater than or equal to the +\fBDOOR_PARAM_DATA_MIN\fR parameter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDOOR_PARAM_DATA_MIN\fR\fR +.ad +.RS 23n +.rt +This parameter represents the the minimum amount of data that can be passed to +the door routine. Any attempt to call \fBdoor_call\fR(3C) on a door with a +\fIdata_size\fR value smaller than the door's \fBDOOR_PARAM_DATA_MIN\fR +parameter will fail with \fBENOBUFS\fR. At door creation time, this parameter +is initialized to 0, and can be set to any value from 0 to \fBSIZE_MAX\fR, +inclusive. This parameter must be less than or equal to the +\fBDOOR_PARAM_DATA_MAX\fR parameter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDOOR_PARAM_DESC_MAX\fR\fR +.ad +.RS 23n +.rt +This parameter represents the the maximum number of argument descriptors that +can be passed to the door routine. Any attempt to call \fBdoor_call\fR(3C) on a +door with a \fIdesc_nu\fRm value larger than the door's +\fBDOOR_PARAM_DESC_MAX\fR parameter will fail with \fBENFILE\fR. If the door +was created with the \fBDOOR_REFUSE_DESC\fR flag, this parameter is initialized +to 0 and cannot be changed to any other value. Otherwise, it is initialized to +\fBINT_MAX\fR and can be set to any value from 0 to \fBINT_MAX\fR, inclusive. +.RE + +.sp +.LP +The \fBdoor_setparam()\fR function can only affect doors that were created by +the current process. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, 0 is returned. Otherwise, -1 is returned and +\fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBdoor_getparam()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 13n +.rt +The \fId\fR argument is not a door descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 13n +.rt +The \fIout\fR argument is not a valid address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 13n +.rt +The \fIparam\fR argument is not a recognized parameter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOVERFLOW\fR\fR +.ad +.RS 13n +.rt +The value of the parameter is larger than the \fBSIZE_MAX\fR. This condition +can occur only if the calling process is 32-bit and the door targets a 64-bit +process or the kernel. +.RE + +.sp +.LP +The \fBdoor_setparam()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 11n +.rt +The \fId\fR argument is not a door descriptor or has been revoked. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 11n +.rt +The \fIparam\fR argument is not a recognized parameter, or the requested change +would make \fBDOOR_PARAM_DATA_MIN\fR greater than \fBDOOR_PARAM_DATA_MAX\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSUP\fR\fR +.ad +.RS 11n +.rt +The \fIparam\fR argument is \fBDOOR_PARAM_DESC_MAX\fR, \fId\fR was created with +the \fBDOOR_REFUSE_DESC\fR flag, and \fIval\fR is not zero. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 11n +.rt +The \fId\fR argument was not created by this process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBERANGE\fR\fR +.ad +.RS 11n +.rt +The \fIval\fR argument is not in supported range of \fIparam\fR. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRSet up a door with a fixed request size. +.sp +.in +2 +.nf +typedef struct my_request { + int request; +ar buffer[4096]; +} my_request_t; + +fd = door_create(my_handler, DOOR_REFUSE_DESC); +if (fd < 0) + /* handle error */ + +if (door_setparam(fd, DOOR_PARAM_DATA_MIN, + sizeof (my_request_t)) < 0 || + door_setparam(fd, DOOR_PARAM_DATA_MAX, + sizeof (my_request_t)) < 0) + /* handle error */ + +/* + * the door will only accept door_call(3DOOR)s with a + * data_size which is exactly sizeof (my_request_t). + */ +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStable +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdoor_call\fR(3C), \fBdoor_create\fR(3C), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +The parameters that can be manipulated by \fBdoor_setparam()\fR are not the +only limitation on the size of requests. If the door server thread's stack size +is not large enough to hold all of the data requested plus room for processing +the request, the door call will fail with \fBE2BIG\fR. +.sp +.LP +The \fBDOOR_PARAM_DATA_MIN\fR parameter will not prevent \fBDOOR_UNREF_DATA\fR +notifications from being sent to the door. diff --git a/usr/src/man/man3c/door_info.3c b/usr/src/man/man3c/door_info.3c new file mode 100644 index 0000000000..4abb8c5395 --- /dev/null +++ b/usr/src/man/man3c/door_info.3c @@ -0,0 +1,203 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH door_info 3C "22 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +door_info \- return information associated with a door descriptor +.SH SYNOPSIS +.LP +.nf +\fBcc\fR \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <door.h> + +\fBint\fR \fBdoor_info\fR(\fBint\fR \fId\fR, \fBstruct door_info *\fR\fIinfo\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBdoor_info()\fR function returns information associated with a door +descriptor. It obtains information about the door descriptor \fId\fR and places +the information that is relevant to the door in the structure pointed to by the +\fIinfo\fR argument. +.sp +.LP +The \fBdoor_info\fR structure pointed to by the \fIinfo\fR argument contains +the following members: +.sp +.in +2 +.nf +pid_t di_target; /* door server pid */ +door_ptr_t di_proc; /* server function */ +door_ptr_t di_data; /* data cookie for invocation */ +door_attr_t di_attributes; /* door attributes */ +door_id_t di_uniquifier; /* unique id among all doors */ +.fi +.in -2 + +.sp +.LP +The \fBdi_target\fR member is the process \fBID\fR of the door server, or +\fB\(mi1\fR if the door server process has exited. +.sp +.LP +The values for \fBdi_attributes\fR may be composed of the following: +.sp +.ne 2 +.mk +.na +\fB\fBDOOR_LOCAL\fR\fR +.ad +.RS 20n +.rt +The door descriptor refers to a service procedure in this process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDOOR_UNREF\fR\fR +.ad +.RS 20n +.rt +The door has requested notification when all but the last reference has gone +away. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDOOR_UNREF_MULTI\fR\fR +.ad +.RS 20n +.rt +Similar to \fBDOOR_UNREF\fR, except multiple unreferenced notifications may be +delivered for this door. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDOOR_IS_UNREF\fR\fR +.ad +.RS 20n +.rt +There is currently only one descriptor referring to the door. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDOOR_REFUSE_DESC\fR\fR +.ad +.RS 20n +.rt +The door refuses any attempt to \fBdoor_call\fR(3C) it with argument +descriptors. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDOOR_NO_CANCEL\fR\fR +.ad +.RS 20n +.rt +Clients who abort a \fBdoor_call\fR(3C) call on this door will not cause the +\fBcancellation\fR(5) of the server thread handling the request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDOOR_REVOKED\fR\fR +.ad +.RS 20n +.rt +The door descriptor refers to a door that has been revoked. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDOOR_PRIVATE\fR\fR +.ad +.RS 20n +.rt +The door has a separate pool of server threads associated with it. +.RE + +.sp +.LP +The \fBdi_proc\fR and \fBdi_data\fR members are returned as \fBdoor_ptr_t\fR +objects rather than \fBvoid\fR \fB*\fR pointers to allow clients and servers to +interoperate in environments where the pointer sizes may vary in size (for +example, 32-bit clients and 64-bit servers). Each door has a system-wide unique +number associated with it that is set when the door is created by +\fBdoor_create()\fR. This number is returned in \fBdi_uniquifier\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBdoor_info()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +.rt +The address of argument \fIinfo\fR is an invalid address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +\fId\fR is not a door descriptor. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Architectureall +_ +Interface StabilityStable +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdoor_bind\fR(3C), \fBdoor_call\fR(3C), \fBdoor_create\fR(3C), +\fBdoor_server_create\fR(3C), \fBattributes\fR(5), \fBcancellation\fR(5) diff --git a/usr/src/man/man3c/door_return.3c b/usr/src/man/man3c/door_return.3c new file mode 100644 index 0000000000..d6c828792f --- /dev/null +++ b/usr/src/man/man3c/door_return.3c @@ -0,0 +1,109 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH door_return 3C "22 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +door_return \- return from a door invocation +.SH SYNOPSIS +.LP +.nf +\fBcc\fR \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <door.h> + +\fBint\fR \fBdoor_return\fR(\fBchar *\fR\fIdata_ptr\fR, \fBsize_t\fR \fIdata_size\fR, \fBdoor_desc_t *\fR\fIdesc_ptr\fR, + \fBuint_t\fR \fInum_desc\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBdoor_return()\fR function returns from a door invocation. It returns +control to the thread that issued the associated \fBdoor_call()\fR and blocks +waiting for the next door invocation. See \fBdoor_call\fR(3C). Results, if any, +from the door invocation are passed back to the client in the buffers pointed +to by \fIdata_ptr\fR and \fIdesc_ptr\fR. If there is not a client associated +with the \fBdoor_return()\fR, the calling thread discards the results, releases +any passed descriptors with the \fBDOOR_RELEASE\fR attribute, and blocks +waiting for the next door invocation. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBdoor_return()\fR does not return to the calling +process. Otherwise, \fBdoor_return()\fR returns \fB\(mi1\fR to the calling +process and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBdoor_return()\fR function fails and returns to the calling process if: +.sp +.ne 2 +.mk +.na +\fB\fBE2BIG\fR\fR +.ad +.RS 10n +.rt +Arguments were too big for client. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +.rt +The address of \fIdata_ptr\fR or \fIdesc_ptr\fR is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +Invalid \fBdoor_return()\fR arguments were passed or a thread is bound to a +door that no longer exists. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 10n +.rt +The client has too many open descriptors. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Architectureall +_ +Interface StabilityStable +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdoor_call\fR(3C),\fBattributes\fR(5) diff --git a/usr/src/man/man3c/door_revoke.3c b/usr/src/man/man3c/door_revoke.3c new file mode 100644 index 0000000000..03355baed6 --- /dev/null +++ b/usr/src/man/man3c/door_revoke.3c @@ -0,0 +1,86 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH door_revoke 3C "22 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +door_revoke \- revoke access to a door descriptor +.SH SYNOPSIS +.LP +.nf +\fBcc\fR \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <door.h> + +\fBint\fR \fBdoor_revoke\fR(\fBint\fR \fId\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBdoor_revoke()\fR function revokes access to a door descriptor. Door +descriptors are created with \fBdoor_create\fR(3C). The \fBdoor_revoke()\fR +function performs an implicit call to \fBclose\fR(2), marking the door +descriptor \fId\fR as invalid. +.sp +.LP +A door descriptor can be revoked only by the process that created it. Door +invocations that are in progress during a \fBdoor_revoke()\fR invocation are +allowed to complete normally. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBdoor_revoke()\fR returns \fB0\fR. Otherwise, +\fBdoor_revoke()\fR returns \(mi1 and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBdoor_revoke()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 9n +.rt +An invalid door descriptor was passed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 9n +.rt +The door descriptor was not created by this process (with +\fBdoor_create\fR(3C)). +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Architectureall +_ +Interface StabilityStable +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBclose\fR(2), \fBdoor_create\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/door_server_create.3c b/usr/src/man/man3c/door_server_create.3c new file mode 100644 index 0000000000..f2a59a828b --- /dev/null +++ b/usr/src/man/man3c/door_server_create.3c @@ -0,0 +1,152 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH door_server_create 3C "22 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +door_server_create \- specify an alternative door server thread creation +function +.SH SYNOPSIS +.LP +.nf +\fBcc\fR \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <door.h> + +\fBvoid (*) ()\fR \fBdoor_server_create\fR(\fBvoid (*\fR\fIcreate_proc\fR)(door_info_t*)); +.fi + +.SH DESCRIPTION +.sp +.LP +Normally, the doors library creates new door server threads in response to +incoming concurrent door invocations automatically. There is no pre-defined +upper limit on the number of server threads that the system creates in +response to incoming invocations (1 server thread for each active door +invocation). These threads are created with the default thread stack size and +POSIX (see \fBstandards\fR(5)) threads cancellation disabled. The created +threads also have the \fBTHR_BOUND\fR | \fBTHR_DETACHED\fR attributes for +Solaris threads and the \fBPTHREAD_SCOPE_SYSTEM\fR | +\fBPTHREAD_CREATE_DETACHED\fR attributes for POSIX threads. The signal +disposition, and scheduling class of the newly created thread are inherited +from the calling thread (initially from the thread calling +\fBdoor_create()\fR, and subsequently from the current active door server +thread). +.sp +.LP +The \fBdoor_server_create()\fR function allows control over the creation of +server threads needed for door invocations. The procedure \fIcreate_proc\fR is +called every time the available server thread pool is depleted. In the case of +private server pools associated with a door (see the \fBDOOR_PRIVATE\fR +attribute in \fBdoor_create()\fR), information on which pool is depleted is +passed to the create function in the form of a \fBdoor_info_t\fR structure. +The \fBdi_proc\fR and \fBdi_data\fR members of the \fBdoor_info_t\fR structure +can be used as a door identifier associated with the depleted pool. The +\fIcreate_proc\fR procedure may limit the number of server threads created and +may also create server threads with appropriate attributes (stack size, +thread-specific data, POSIX thread cancellation, signal mask, scheduling +attributes, and so forth) for use with door invocations. +.sp +.LP +The overall amount of data and argument descriptors that can be sent through a +door is limited by both the server thread's stack size and by the parameters of +the door itself. See \fBdoor_setparam\fR(3C). +.sp +.LP +The specified server creation function should create user level threads using +\fBthr_create()\fR with the \fBTHR_BOUND\fR flag, or in the case of POSIX +threads, \fBpthread_create()\fR with the \fBPTHREAD_SCOPE_SYSTEM\fR attribute. +The server threads make themselves available for incoming door invocations on +this process by issuing a \fBdoor_return\fR(\fBNULL, 0, NULL, 0\fR). In this +case, the \fBdoor_return()\fR arguments are ignored. See \fBdoor_return\fR(3C) +and \fBthr_create\fR(3C). +.sp +.LP +The server threads created by default are enabled for POSIX thread +cancellations which may lead to unexpected thread terminations while holding +resources (such as locks) if the client aborts the associated +\fBdoor_call()\fR. See \fBdoor_call\fR(3C). Unless the server code is truly +interested in notifications of client aborts during a door invocation and is +prepared to handle such notifications using cancellation handlers, POSIX +thread cancellation should be disabled for server threads using +\fBpthread_setcancelstate\fR (\fBPTHREAD_CANCEL_DISABLE\fR, \fINULL\fR). If all +doors are created with the \fBDOOR_NO_CANCEL\fR flag (see +\fBdoor_create\fR(3C)), the threads will never be cancelled by an aborted +\fBdoor_call()\fR call +.sp +.LP +The \fIcreate_proc\fR procedure need not create any additional server threads +if there is at least one server thread currently active in the process (perhaps +handling another door invocation) or it may create as many as seen fit each +time it is called. If there are no available server threads during an incoming +door invocation, the associated \fBdoor_call()\fR blocks until a server thread +becomes available. The \fIcreate_proc\fR procedure must be MT-Safe. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBdoor_server_create()\fR returns a pointer to the +previous server creation function. This function has no failure mode (it cannot +fail). +.SH EXAMPLES +.LP +\fBExample 1 \fRCreating door server threads. +.sp +.LP +The following example creates door server threads with cancellation disabled +and an 8k stack instead of the default stack size: + +.sp +.in +2 +.nf +#include <door.h> +#include <pthread.h> +#include <thread.h> + +void * +my_thread(void *arg) +{ + pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL); + door_return(NULL, 0, NULL, 0); +} +void +my_create(door_info_t *dip) +{ + thr_create(NULL, 8192, my_thread, NULL, + THR_BOUND | THR_DETACHED, NULL); +} +main(\|) +{ + (void)door_server_create(my_create); + \|.\|.\|. +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Architectureall +_ +Interface StabilityStable +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdoor_bind\fR(3C), \fBdoor_call\fR(3C), \fBdoor_create\fR(3C), +\fBdoor_return\fR(3C), \fBpthread_create\fR(3C), +\fBpthread_setcancelstate\fR(3C), \fBthr_create\fR(3C), \fBattributes\fR(5), +\fBcancellation\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/door_ucred.3c b/usr/src/man/man3c/door_ucred.3c new file mode 100644 index 0000000000..552e72eaf5 --- /dev/null +++ b/usr/src/man/man3c/door_ucred.3c @@ -0,0 +1,120 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH door_ucred 3C "22 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +door_ucred \- return credential information associated with the client +.SH SYNOPSIS +.LP +.nf +\fBcc\fR \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <door.h> + +\fBint\fR \fBdoor_ucred\fR(\fBucred_t **\fR\fIinfo\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBdoor_ucred()\fR function returns credential information associated with +the client, if any, of the current door invocation. +.sp +.LP +When successful, \fBdoor_ucred()\fR writes a pointer to a user credential to +the location pointed to by \fIinfo\fR if that location was previously +\fINULL\fR. If that location was non-null, \fBdoor_ucred()\fR assumes that +\fIinfo\fR points to a previously allocated \fBucred_t\fR which is then reused. +The location pointed to by \fIinfo\fR can be used multiple times before being +freed. The value returned in \fIinfo\fR must be freed using +\fBucred_free\fR(3C). +.sp +.LP +The resulting user credential includes information about the effective user and +group ID, the real user and group ID, all privilege sets and the calling PID. +.sp +.LP +The credential information associated with the client refers to the information +from the immediate caller, not necessarily from the first thread in a chain of +door calls. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBdoor_ucred()\fR returns 0. Otherwise, -1 is +returned and \fBerrno\fR is set to indicate the error, in which case the memory +location pointed to by the \fIinfo\fR argument is unchanged. +.SH ERRORS +.sp +.LP +The \fBdoor_ucred()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +The location pointed to by \fIinfo\fR was \fINULL\fR and allocating memory +sufficient to hold a ucred failed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +.rt +The address of the \fIinfo\fR argument is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +There is no associated door client. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +The location pointed to by \fIinfo\fR was \fINULL\fR and allocating memory +sufficient to hold a ucred failed. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStable +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdoor_call\fR(3C), \fBdoor_create\fR(3C), \fBucred_get\fR(3C), +\fBattributes\fR(5) diff --git a/usr/src/man/man3c/drand48.3c b/usr/src/man/man3c/drand48.3c new file mode 100644 index 0000000000..0c427cebd6 --- /dev/null +++ b/usr/src/man/man3c/drand48.3c @@ -0,0 +1,175 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH drand48 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, lcong48 +\- generate uniformly distributed pseudo-random numbers +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBdouble\fR \fBdrand48\fR(void) +.fi + +.LP +.nf +\fBdouble\fR \fBerand48\fR(\fBunsigned short\fR \fIx\fR(i)[3]); +.fi + +.LP +.nf +\fBlong\fR \fBlrand48\fR(void) +.fi + +.LP +.nf +\fBlong\fR \fBnrand48\fR(\fBunsigned short\fR \fIx\fR(i)[3]); +.fi + +.LP +.nf +\fBlong\fR \fBmrand48\fR(void) +.fi + +.LP +.nf +\fBlong\fR \fBjrand48\fR(\fBunsigned short\fR \fIx\fR(i)[3]); +.fi + +.LP +.nf +\fBvoid\fR \fBsrand48\fR(\fBlong\fR \fIseedval\fR); +.fi + +.LP +.nf +\fBunsigned short *\fR\fBseed48\fR(\fBunsigned short\fR \fIseed16v\fR[3]); +.fi + +.LP +.nf +\fBvoid\fR \fBlcong48\fR(\fBunsigned short\fR \fIparam\fR[7]); +.fi + +.SH DESCRIPTION +.sp +.LP +This family of functions generates pseudo-random numbers using the well-known +linear congruential algorithm and 48-bit integer arithmetic. +.sp +.LP +Functions \fBdrand48()\fR and \fBerand48()\fR return non-negative +double-precision floating-point values uniformly distributed over the interval +[0.0, 1.0). +.sp +.LP +Functions \fBlrand48()\fR and \fBnrand48()\fR return non-negative long integers +uniformly distributed over the interval [0, 2 ^31 ]. +.sp +.LP +Functions \fBmrand48()\fR and \fBjrand48()\fR return signed long integers +uniformly distributed over the interval [-2 ^31 , 2 ^31 ]. +.sp +.LP +Functions \fBsrand48()\fR, \fBseed48()\fR, and \fBlcong48()\fR are +initialization entry points, one of which should be invoked before either +\fBdrand48()\fR, \fBlrand48()\fR, or \fBmrand48()\fR is called. (Although it is +not recommended practice, constant default initializer values will be supplied +automatically if \fBdrand48()\fR, \fBlrand48()\fR, or \fBmrand48()\fR is called +without a prior call to an initialization entry point.) Functions +\fBerand48(\|),\fR \fBnrand48(\|),\fR and \fBjrand48()\fR do not require an +initialization entry point to be called first. +.sp +.LP +All the routines work by generating a sequence of 48-bit integer values, X(i ), +according to the linear congruential formula +.sp +.LP +X(n+1)= (aX (n)+c)(mod m) n>=0. +.sp +.LP +The parameter \fIm\fR = 2^48; hence 48-bit integer arithmetic is performed. +Unless \fBlcong48()\fR has been invoked, the multiplier value \fIa\fRand the +addend value \fIc\fRare given by +.br +.in +2 +\fIa\fR = 5DEECE66D(16) = 273673163155(8) +.in -2 +.br +.in +2 +\fIc\fR = B(16) = 13(8) +.in -2 +.sp +.LP +The value returned by any of the functions \fBdrand48()\fR, \fBerand48()\fR, +\fBlrand48()\fR, \fBnrand48()\fR, \fBmrand48()\fR, or \fBjrand48()\fR 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. +.sp +.LP +The functions \fBdrand48()\fR, \fBlrand48()\fR, and \fBmrand48()\fR store the +last 48-bit X(i) generated in an internal buffer. X(i) must be initialized +prior to being invoked. The functions \fBerand48()\fR, \fBnrand48()\fR, and +\fBjrand48()\fR 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. These routines do not have to be initialized; the calling program +must place the desired initial value of X(i) into the array and pass it as an +argument. By using different arguments, functions \fBerand48()\fR, +\fBnrand48()\fR, and \fBjrand48()\fR allow separate modules of a large program +to generate several \fIindependent\fR streams of pseudo-random numbers, that +is, the sequence of numbers in each stream will \fInot\fR depend upon how many +times the routines have been called to generate numbers for the other streams. +.sp +.LP +The initializer function \fBsrand48()\fR sets the high-order 32 bits of X(i) to +the 32 bits contained in its argument. The low-order 16 bits of X(i) are set to +the arbitrary value 330E(16) . +.sp +.LP +The initializer function \fBseed48()\fR sets the value of X(i) to the 48-bit +value specified in the argument array. In addition, the previous value of X(i) +is copied into a 48-bit internal buffer, used only by \fBseed48()\fR, and a +pointer to this buffer is the value returned by \fBseed48()\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 \(em use the pointer to get +at and store the last X(i) value, and then use this value to reinitialize using +\fBseed48()\fR when the program is restarted. +.sp +.LP +The initialization function \fBlcong48()\fR allows the user to specify the +initial X(i) the multiplier value \fIa\fR, and the addend value \fIc\fR. +Argument array elements \fIparam[0-2]\fR specify X(i), \fIparam[3-5]\fR specify +the multiplier \fIa\fR, and \fIparam\fR[6] specifies the 16-bit addend \fIc\fR. +After \fBlcong48()\fR has been called, a subsequent call to either +\fBsrand48()\fR or \fBseed48()\fR will restore the ``standard'' multiplier and +addend values, \fIa\fR and \fIc\fR, specified above. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityStandard +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBrand\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/dup2.3c b/usr/src/man/man3c/dup2.3c new file mode 100644 index 0000000000..5e1282d9b5 --- /dev/null +++ b/usr/src/man/man3c/dup2.3c @@ -0,0 +1,112 @@ +'\" te +.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dup2 3C "19 Dec 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +dup2 \- duplicate an open file descriptor +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> + +\fBint\fR \fBdup2\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIfildes2\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBdup2()\fR function causes the file descriptor \fIfildes2\fR to refer to +the same file as \fIfildes\fR. The \fIfildes\fR argument is a file descriptor +referring to an open file, and \fIfildes2\fR is a non-negative integer less +than the current value for the maximum number of open file descriptors allowed +the calling process. See \fBgetrlimit\fR(2). If \fIfildes2\fR already refers +to an open file, not \fIfildes\fR, it is closed first. If \fIfildes2\fR refers +to \fIfildes\fR, or if \fIfildes\fR is not a valid open file descriptor, +\fIfildes2\fR will not be closed first. +.sp +.LP +The \fBdup2()\fR function is equivalent to \fBfcntl\fR(\fIfildes\fR, +\fBF_DUP2FD\fR, \fIfildes2\fR). +.SH RETURN VALUES +.sp +.LP +Upon successful completion a non-negative integer representing the file +descriptor is returned. Otherwise, \fB\(mi1\fR is returned and \fBerrno\fR is +set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBdup2()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIfildes\fR argument is not a valid open file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIfildes2\fR argument is negative or is not less than the current resource +limit returned by \fBgetrlimit(RLIMIT_NOFILE, .\|.\|.)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 10n +.rt +A signal was caught during the \fBdup2()\fR call. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 10n +.rt +The process has too many open files. See \fBfcntl\fR(2). +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelAsync-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBclose\fR(2), \fBcreat\fR(2), \fBexec\fR(2), \fBfcntl\fR(2), +\fBgetrlimit\fR(2), \fBopen\fR(2), \fBpipe\fR(2), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/econvert.3c b/usr/src/man/man3c/econvert.3c new file mode 100644 index 0000000000..b62be6a180 --- /dev/null +++ b/usr/src/man/man3c/econvert.3c @@ -0,0 +1,151 @@ +'\" te +.\" Copyright (c) 1999, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH econvert 3C "3 May 1999" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +econvert, fconvert, gconvert, seconvert, sfconvert, sgconvert, qeconvert, +qfconvert, qgconvert \- output conversion +.SH SYNOPSIS +.LP +.nf +#include <floatingpoint.h> + +\fBchar *\fR\fBeconvert\fR(\fBdouble\fR \fIvalue\fR, \fBint\fR \fIndigit\fR, \fBint *\fR\fIdecpt\fR, \fBint *\fR\fIsign\fR, + \fBchar *\fR\fIbuf\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBfconvert\fR(\fBdouble\fR \fIvalue\fR, \fBint\fR \fIndigit\fR, \fBint *\fR\fIdecpt\fR, \fBint *\fR\fIsign\fR, + \fBchar *\fR\fIbuf\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBgconvert\fR(\fBdouble\fR \fIvalue\fR, \fBint\fR \fIndigit\fR, \fBint\fR \fItrailing\fR, \fBchar *\fR\fIbuf\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBseconvert\fR(\fBsingle *\fR\fIvalue\fR, \fBint\fR \fIndigit\fR, \fBint *\fR\fIdecpt\fR, \fBint *\fR\fIsign\fR, + \fBchar *\fR\fIbuf\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBsfconvert\fR(\fBsingle *\fR\fIvalue\fR, \fBint\fR \fIndigit\fR, \fBint *\fR\fIdecpt\fR, \fBint *\fR\fIsign\fR, + \fBchar *\fR\fIbuf\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBsgconvert\fR(\fBsingle *\fR\fIvalue\fR, \fBint\fR \fIndigit\fR, \fBint\fR \fItrailing\fR, \fBchar *\fR\fIbuf\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBqeconvert\fR(\fBquadruple *\fR\fIvalue\fR, \fBint\fR \fIndigit\fR, \fBint *\fR\fIdecpt\fR, \fBint *\fR\fIsign\fR, + \fBchar *\fR\fIbuf\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBqfconvert\fR(\fBquadruple *\fR\fIvalue\fR, \fBint\fR \fIndigit\fR, \fBint *\fR\fIdecpt\fR, \fBint *\fR\fIsign\fR + \fBchar *\fR\fIbuf\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBqgconvert\fR(\fBquadruple *\fR\fIvalue\fR, \fBint\fR \fIndigit\fR, \fBint\fR \fItrailing\fR, \fBchar *\fR\fIbuf\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBeconvert()\fR function converts the \fIvalue\fR to a null-terminated +string of \fIndigit\fR \fBASCII\fR digits in \fIbuf\fR and returns a pointer to +\fIbuf\fR. \fIbuf\fR should contain at least \fIndigit+1\fR characters. The +position of the decimal point relative to the beginning of the string is stored +indirectly through \fIdecpt\fR. Thus \fIbuf\fR == "314" and \fI*decpt\fR == 1 +corresponds to the numerical value 3.14, while \fIbuf\fR == "314" and +\fI*decpt\fR == \(mi1 corresponds to the numerical value .0314. If the sign of +the result is negative, the word pointed to by \fIsign\fR is nonzero; otherwise +it is zero. The least significant digit is rounded. +.sp +.LP +The \fBfconvert()\fR function works much like \fBeconvert()\fR, except that the +correct digit has been rounded as if for \fBsprintf(%w.nf)\fR output with +\fIn\fR=\fIndigit\fR digits to the right of the decimal point. \fIndigit\fR can +be negative to indicate rounding to the left of the decimal point. The return +value is a pointer to \fIbuf\fR. \fIbuf\fR should contain at least +\fI310+max(0,ndigit)\fR characters to accomodate any double-precision +\fIvalue\fR. +.sp +.LP +The \fBgconvert()\fR function converts the \fIvalue\fR to a null-terminated +\fBASCII\fR string in \fIbuf\fR and returns a pointer to \fIbuf\fR. It produces +\fIndigit\fR significant digits in fixed-decimal format, like +\fBsprintf(%w.nf)\fR, if possible, and otherwise in floating-decimal format, +like \fBsprintf(%w.ne)\fR; in either case \fIbuf\fR is ready for printing, +with sign and exponent. The result corresponds to that obtained by +.sp +.in +2 +.nf +(void) sprintf(buf,``%w.ng'',value) ; +.fi +.in -2 + +.sp +.LP +If \fItrailing\fR = 0, trailing zeros and a trailing point are suppressed, as +in \fBsprintf(%g)\fR. If \fItrailing\fR != 0, trailing zeros and a trailing +point are retained, as in \fBsprintf(%#g)\fR. +.sp +.LP +The \fBseconvert()\fR, \fBsfconvert()\fR, and \fBsgconvert()\fR functions are +single-precision versions of these functions, and are more efficient than the +corresponding double-precision versions. A pointer rather than the value itself +is passed to avoid C's usual conversion of single-precision arguments to +double. +.sp +.LP +The \fBqeconvert()\fR, \fBqfconvert()\fR, and \fBqgconvert()\fR functions are +quadruple-precision versions of these functions. The \fBqfconvert()\fR function +can overflow the \fIdecimal_record\fR field \fIds\fR if \fIvalue\fR is too +large. In that case, \fIbuf\fR[0] is set to zero. +.sp +.LP +The \fBecvt()\fR, \fBfcvt()\fR and \fBgcvt()\fR functions are versions of +\fBeconvert()\fR, \fBfconvert()\fR, and \fBgconvert()\fR, respectively, that +are documented on the \fBecvt\fR(3C) manual page. They constitute the default +implementation of these functions and conform to the X/Open CAE Specification, +System Interfaces and Headers, Issue 4, Version 2. +.SH USAGE +.sp +.LP +\fBIEEE\fR Infinities and NaNs are treated similarly by these functions. +``NaN'' is returned for NaN, and ``Inf'' or ``Infinity'' for Infinity. The +longer form is produced when \fIndigit\fR >= 8. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBecvt\fR(3C),\fBsprintf\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/ecvt.3c b/usr/src/man/man3c/ecvt.3c new file mode 100644 index 0000000000..e8ae911e92 --- /dev/null +++ b/usr/src/man/man3c/ecvt.3c @@ -0,0 +1,120 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. Portions Copyright (c) 1992, X/Open Company Limited, All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ecvt 3C "18 May 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +ecvt, fcvt, gcvt \- convert floating-point number to string +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBchar *\fR\fBecvt\fR(\fBdouble\fR \fIvalue\fR, \fBint\fR \fIndigit\fR, \fBint *restrict\fR \fIdecpt\fR, \fBint *restrict\fR \fIsign\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBfcvt\fR(\fBdouble\fR \fIvalue\fR, \fBint\fR \fIndigit\fR, \fBint *restrict\fR \fIdecpt\fR, \fBint *restrict\fR \fIsign\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBgcvt\fR(\fBdouble\fR \fIvalue\fR, \fBint\fR \fIndigit\fR, \fBchar *\fR\fIbuf\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBecvt()\fR, \fBfcvt()\fR and \fBgcvt()\fR functions convert +floating-point numbers to null-terminated strings. +.SS "\fBecvt()\fR" +.sp +.LP +The \fBecvt()\fR function converts \fIvalue\fR to a null-terminated string of +\fIndigit\fR digits (where \fIndigit\fR is reduced to an unspecified limit +determined by the precision of a \fBdouble\fR) and returns a pointer to the +string. The high-order digit is non-zero, unless the value is 0. The +low-order digit is rounded. The position of the radix character relative to +the beginning of the string is stored in the integer pointed to by \fIdecpt\fR +(negative means to the left of the returned digits). The radix character is not +included in the returned string. If the sign of the result is negative, the +integer pointed to by \fIsign\fR is non-zero, otherwise it is 0. +.sp +.LP +If the converted value is out of range or is not representable, the contents of +the returned string are unspecified. +.SS "\fBfcvt()\fR" +.sp +.LP +The \fBfcvt()\fR function is identical to \fBecvt()\fR except that \fIndigit\fR +specifies the number of digits desired after the radix point. The total number +of digits in the result string is restricted to an unspecified limit as +determined by the precision of a \fBdouble\fR. +.SS "\fBgcvt()\fR" +.sp +.LP +The \fBgcvt()\fR function converts \fIvalue\fR to a null-terminated string +(similar to that of the \fB%g\fR format of \fBprintf\fR(3C)) in the array +pointed to by \fIbuf\fR and returns \fIbuf\fR. It produces \fIndigit\fR +significant digits (limited to an unspecified value determined by the precision +of a \fBdouble\fR) in \fB%f\fR if possible, or \fB%e\fR (scientific notation) +otherwise. A minus sign is included in the returned string if \fIvalue\fR is +less than 0. A radix character is included in the returned string if +\fIvalue\fR is not a whole number. Trailing zeros are suppressed where +\fIvalue\fR is not a whole number. The radix character is determined by the +current locale. If \fBsetlocale\fR(3C) has not been called successfully, the +default locale, POSIX, is used. The default locale specifies a period +(\fB\&.\fR) as the radix character. The \fBLC_NUMERIC\fR category determines +the value of the radix character within the current locale. +.SH RETURN VALUES +.sp +.LP +The \fBecvt()\fR and \fBfcvt()\fR functions return a pointer to a +null-terminated string of digits. +.sp +.LP +The \fBgcvt()\fR function returns \fIbuf\fR. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH USAGE +.sp +.LP +The return values from \fBecvt()\fR and \fBfcvt()\fR might point to +thread-specific data that can be overwritten by subsequent calls to these +functions by the same thread. +.sp +.LP +For portability to implementations conforming to earlier versions of Solaris, +\fBsprintf\fR(3C) is preferred over this function. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBprintf\fR(3C), \fBsetlocale\fR(3C), \fBsprintf\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/enable_extended_FILE_stdio.3c b/usr/src/man/man3c/enable_extended_FILE_stdio.3c new file mode 100644 index 0000000000..7ffb1c144b --- /dev/null +++ b/usr/src/man/man3c/enable_extended_FILE_stdio.3c @@ -0,0 +1,297 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH enable_extended_FILE_stdio 3C "18 Apr 2006" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +enable_extended_FILE_stdio \- enable extended FILE facility within standard I/O +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> +#include <stdio_ext.h> +#include <signal.h> + +\fBint\fR \fBenable_extended_FILE_stdio\fR(\fBint\fR \fIlow_fd\fR, \fBint\fR \fIsignal_action\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBenable_extended_FILE_stdio()\fR function enables the use of the extended +FILE facility (see NOTES) and determines which, if any, signal will be sent +when an application uses \fBFILE\fR->\fI_file\fR inappropriately. +.sp +.LP +The \fIlow_fd\fR argument specifies the lowest file descriptor in the range 3 +through 255 that the application wants to be selected as the unallocatable file +descriptor. File descriptors 0, 1, and 2 cannot be used because they are +reserved for use as the default file descriptors underlying the \fBstdin\fR, +\fBstdout\fR, and \fBstderr\fR standard I/O streams. The \fIlow_fd\fR argument +can also be set to \(mi1 to request that \fBenable_extended_FILE_stdio()\fR +select a "reasonable" unallocatable file descriptor. In this case, +\fBenable_extended_FILE_stdio()\fR will first attempt to reserve a relatively +large file descriptor, but will keep trying to find an unallocatable file +descriptor until it is known that no file descriptor can be reserved. +.sp +.LP +The \fIsignal_action\fR argument specifies the signal that will be sent to the +process when the unallocatable file descriptor is used as a file descriptor +argument to any system call except \fBclose\fR(2). If \fIsignal_action\fR is +\(mi1, the default signal (\fBSIGABRT\fR) will be sent. If \fIsignal_action\fR +is 0, no signal will be sent. Otherwise, the signal specified by +\fIsignal_action\fR will be sent. +.sp +.LP +The \fBenable_extended_FILE_stdio()\fR function calls +.sp +.in +2 +.nf +unallocatablefd = fcntl(low_fd, F_BADFD, action); +.fi +.in -2 + +.sp +.LP +to reserve the unallocatable file descriptor and set the signal to be sent if +the unallocatable file descriptor is used in a system call. If the +\fBfcntl\fR(2) call succeeds, the extended FILE facility is enabled and the +unallocatable file descriptor is saved for later use by the standard I/O +functions. When an attempt is made to open a standard I/O stream (see +\fBfdopen\fR(3C), \fBfopen\fR(3C), and \fBpopen\fR(3C)) with an underlying file +descriptor greater than 255, the file descriptor is stored in an auxiliary +location and the field formerly known as \fBFILE\fR->\fI_file\fR is set to the +unallocatable file descriptor. +.sp +.LP +If the file descriptor limit for the process is less than or equal to 256 (the +system default), the application needs to raise the limit (see +\fBgetrlimit\fR(2)) for the extended FILE facility to be useful. The +\fBenable_extended_FILE_stdio()\fR function does not attempt to change the file +descriptor limit. +.sp +.LP +This function is used by the \fBextendedFILE\fR(5) preloadable library to +enable the extended FILE facility. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBenable_extended_FILE_stdio()\fR returns 0. +Otherwise, \(mi1 is returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBenable_extended_FILE_stdio()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +All file descriptors in the inclusive range 3 through 255 refer to files that +are currently open in the process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIlow_fd\fR argument is greater than 255, or is less than 3 and not equal +to -1. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEEXIST\fR\fR +.ad +.RS 10n +.rt +A file descriptor has already been marked by an earlier call to \fBfcntl()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIsignal_action\fR argument is not \(mi1, is not 0, and is not a valid +signal number. +.RE + +.SH USAGE +.sp +.LP +The \fBenable_extended_FILE_stdio()\fR function is available only in the 32-bit +compilation environment. +.sp +.LP +The \fBfdopen\fR(3C), \fBfopen\fR(3C), and \fBpopen\fR(3C) functions all enable +the use of the extended FILE facility. For source changes, a trailing \fBF\fR +character in the \fImode\fR argument can be used with any of these functions if +the \fBFILE *\fR\fIfptr\fR is used only within the context of a single function +or group of functions and not meant to be returned to a caller. All of the +source code to the application must then be recompiled, thereby exposing any +improper usage of the \fBFILE\fR structure fields. +.sp +.LP +The \fBF\fR character must not be used if the \fBFILE *\fR\fIfptr\fR is to be +returned to a caller. The calling application might not understand how to +process it. Alternatively, the \fBenable_extended_FILE_stdio()\fR function can +be used at a higher level in the code. +.sp +.LP +Use \fBextendedFILE\fR(5) for binary relief. +.SH EXAMPLES +.LP +\fBExample 1 \fRIncrease the file limit and enable the extended FILE facility. +.sp +.LP +The following example demonstrates how to programmatically increase the file +limit and enable extended FILE facility. + +.sp +.in +2 +.nf +(void) getrlimit(RLIMIT_NOFILE, &rlp); +rlp.rlim_cur = 1000; /* set the desired number of file descriptors */ +retval = setrlimit(RLIMIT_NOFILE, &lrp); +if (retval == -1) { + /* error */ +} + +/* enable extended FILE facility */ +retval = enable_extended_FILE_stdio(-1, SIGABRT); +if (retval == -1) { + /* error */ +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBclose\fR(2), \fBfcntl\fR(2), \fBgetrlimit\fR(2), \fBfdopen\fR(3C), +\fBfopen\fR(3C), \fBpopen\fR(3C), \fBsignal.h\fR(3HEAD), \fBstdio\fR(3C), +\fBattributes\fR(5), \fBextendedFILE\fR(5) +.SH NOTES +.sp +.LP +Historically, 32-bit Solaris applications have been limited to using only the +file descriptors 0 through 255 with the standard I/O functions (see +\fBstdio\fR(3C)) in the C library. The extended FILE facility allows +well-behaved 32-bit applications to use any valid file descriptor with the +standard I/O functions. +.sp +.LP +For the purposes of the extended FILE facility, a well-behaved application is +one that: +.RS +4 +.TP +.ie t \(bu +.el o +does not directly access any fields in the \fBFILE\fR structure pointed to by +the \fBFILE\fR pointer associated with any standard I/O stream, +.RE +.RS +4 +.TP +.ie t \(bu +.el o +checks all return values from standard I/O functions for error conditions, and +.RE +.RS +4 +.TP +.ie t \(bu +.el o +behaves appropriately when an error condition is reported. +.RE +.sp +.LP +The extended FILE facility generates \fBEBADF\fR error returns and optionally +delivers a signal to the calling process on most attempts to use the file +descriptor formerly stored in \fBFILE\fR->\fI_file\fR as an argument to a +system call when a file descriptor value greater than 255 is being used to +access the file underlying the corresponding \fBFILE\fR pointer. The only +exception is that calls to the \fBclose()\fR system call will return an +\fBEBADF\fR error in this case, but will not deliver the signal. The +\fBFILE\fR->\fI_file\fR has been renamed to help applications quickly detect +code that needs to be updated. +.sp +.LP +The extended FILE facility should only be used by well-behaved applications. +Although the extended FILE facility reports errors, applications that directly +reference \fBFILE\fR->\fI_file\fR should be updated to use public interfaces +rather than rely on implementation details that no longer work as the +application expects (see \fB__fbufsize\fR(3C) and \fBfileno\fR(3C). +.sp +.LP +This facility takes great care to avoid problems in well-behaved applications +while maintaining maximum compatibility. It also attempts to catch dangerous +behavior in applications that are not well-behaved as soon as possible and to +notify those applications as soon as bad behavior is detected. +.sp +.LP +There are, however, limitations. For example, if an application enables this +facility and is linked with an object file that had a standard I/O stream using +an extended \fBFILE\fR pointer, and then used the sequence +.sp +.in +2 +.nf +(void) close(FILE->_file); +FILE->_file = myfd; +.fi +.in -2 + +.sp +.LP +to attempt to change the file descriptor associated with the stream, undesired +results can occur. The \fBclose()\fR function will fail, but since this usage +ignores the return status, the application proceeds to perform low level I/O on +\fBFILE\fR->\fI_file\fR while calls to standard I/O functions would continue to +use the original, extended \fBFILE\fR pointer. If the application continues +using standard I/O functions after changing \fBFILE\fR->\fI_file\fR, silent +data corruption could occur because the application thinks it has changed file +descriptors with the above assignment but the actual standard I/O file +descriptor is stored in the auxiliary location. The chances for corruption are +even higher if \fImyfd\fR has a value greater than 255 and is truncated by the +assignment to the 8-bit \fI_file\fR field. +.sp +.LP +Since the\fI_file\fR field has been renamed, attempts to recompile this code +will fail. The application should be changed not to use this field in the +\fBFILE\fR structure. +.sp +.LP +The application should not use this facility if it uses \fI_file\fR directly, +including using the \fBfileno()\fR macro that was provided in +\fBstdio.h\fR(3HEAD) in Solaris 2.0 through 2.7. diff --git a/usr/src/man/man3c/encrypt.3c b/usr/src/man/man3c/encrypt.3c new file mode 100644 index 0000000000..44cab1d42e --- /dev/null +++ b/usr/src/man/man3c/encrypt.3c @@ -0,0 +1,99 @@ +'\" te +.\" Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH encrypt 3C "2 May 2001" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +encrypt \- encoding function +.SH SYNOPSIS +.LP +.nf +#include <crypt.h> + +\fBvoid\fR \fBencrypt\fR(\fBchar\fR \fIblock[64]\fR, \fBint\fR \fIedflag\fR); +.fi + +.SS "Standard conforming" +.LP +.nf +#include <unistd.h> + +\fBvoid\fR \fBencrypt\fR(\fBchar\fR \fIblock[64]\fR, \fBint\fR \fIedflag\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBencrypt()\fR function provides (rather primitive) access to the hashing +algorithm employed by the \fBcrypt\fR(3C) function. The key generated by +\fBsetkey\fR(3C) is used to encrypt the string \fIblock\fR with +\fBencrypt()\fR. +.sp +.LP +The \fIblock\fR argument to \fBencrypt()\fR is an array of length 64 bytes +containing only the bytes with numerical value of 0 and 1. The array is +modified in place to a similar array using the key set by \fBsetkey\fR(3C). If +\fIedflag\fR is 0, the argument is encoded. If \fIedflag\fR is 1, the argument +may be decoded (see the \fBUSAGE\fR section below); if the argument is not +decoded, \fBerrno\fR will be set to \fBENOSYS\fR. +.SH RETURN VALUES +.sp +.LP +The \fBencrypt()\fR function returns no value. +.SH ERRORS +.sp +.LP +The \fBencrypt()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR\fR +.ad +.RS 10n +.rt +The functionality is not supported on this implementation. +.RE + +.SH USAGE +.sp +.LP +In some environments, decoding may not be implemented. This is related to U.S. +Government restrictions on encryption and decryption routines: the \fBDES\fR +decryption algorithm cannot be exported outside the U.S.A. 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 +\fBencrypt()\fR does encoding but not decoding. +.sp +.LP +Because \fBencrypt()\fR does not return a value, applications wishing to check +for errors should set \fBerrno\fR to 0, call \fBencrypt()\fR, then test +\fBerrno\fR and, if it is non-zero, assume an error has occurred. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBcrypt\fR(3C), \fBsetkey\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/end.3c b/usr/src/man/man3c/end.3c new file mode 100644 index 0000000000..3152ee0f71 --- /dev/null +++ b/usr/src/man/man3c/end.3c @@ -0,0 +1,88 @@ +'\" te +.\" Copyright 1989 AT&T. +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH end 3C "31 Mar 2006" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +end, _end, etext, _etext, edata, _edata \- last locations in program +.SH SYNOPSIS +.LP +.nf +\fBextern int \fR\fI_etext\fR\fB;\fR +.fi + +.LP +.nf +\fBextern int \fR\fI_edata\fR\fB;\fR +.fi + +.LP +.nf +\fBextern int \fR\fI_end\fR\fB;\fR +.fi + +.SH DESCRIPTION +.sp +.LP +These names refer neither to routines nor to locations with interesting +contents; only their addresses are meaningful. +.sp +.ne 2 +.mk +.na +\fB\fB_etext\fR\fR +.ad +.RS 10n +.rt +The address of \fB_etext\fR is the first location after the last read-only +loadable segment. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_edata\fR\fR +.ad +.RS 10n +.rt +The address of \fB_edata\fR is the first location after the last read-write +loadable segment. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_end\fR\fR +.ad +.RS 10n +.rt +If the address of \fB_edata\fR is greater than the address of \fB_etext\fR, the +address of _end is same as the address of \fB_edata\fR. +.sp +If the address of \fB_etext\fR is greater than the address of \fB_edata\fR, the +address of \fB_end\fR is set to the page boundary after the address pointed to +by \fB_etext\fR. +.RE + +.SH USAGE +.sp +.LP +When execution begins, the program break (the first location beyond the data) +coincides with \fB_end\fR, but the program break can be reset by the +\fBbrk\fR(2), \fBmalloc\fR(3C), and the standard input/output library (see +\fBstdio\fR(3C)), functions by the profile (\fB-p\fR) option of \fBcc\fR, and +so on. Thus, the current value of the program break should be determined by +\fBsbrk ((char *)0)\fR. +.sp +.LP +References to \fBend\fR, \fBetext\fR, and \fBedata\fR, without a preceding +underscore will be aliased to the associated symbol that begins with the +underscore. +.SH SEE ALSO +.sp +.LP +\fBbrk\fR(2), \fBmalloc\fR(3C), \fBstdio\fR(3C) diff --git a/usr/src/man/man3c/err.3c b/usr/src/man/man3c/err.3c new file mode 100644 index 0000000000..ea217cd170 --- /dev/null +++ b/usr/src/man/man3c/err.3c @@ -0,0 +1,156 @@ +'\" te +.\" Copyright (c) 1996-2001 Wolfram Schneider. Berlin. +.\" Copyright (c) 1993-1995 Berkeley Software Design, Inc. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH err 3C "20 Aug 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +err, verr, errx, verrx, warn, vwarn, warnx, vwarnx \- formatted error messages +.SH SYNOPSIS +.LP +.nf +#include <err.h> + +\fBvoid\fR \fBerr\fR(\fBint\fR \fIeval\fR, \fBconst char *\fR\fIfmt\fR, ...); +.fi + +.LP +.nf +\fBvoid\fR \fBverr\fR(\fBint\fR \fIeval\fR, \fBconst char *\fR\fIfmt\fR, \fBva_list\fR \fIargs\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBerrx\fR(\fBint\fR \fIeval\fR, \fBconst char *\fR\fIfmt\fR, ...); +.fi + +.LP +.nf +\fBvoid\fR \fBverrx\fR\fB(int\fR \fIeval\fR, \fBconst char *\fR\fIfmt\fR, \fBva_list\fR \fIargs\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBwarn\fR(\fBconst char *\fR\fIfmt\fR, ...); +.fi + +.LP +.nf +\fBvoid\fR \fBvwarn\fR(\fBconst char *\fR\fIfmt\fR, \fBva_list\fR \fIargs\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBwarnx\fR(\fBconst char *\fR\fIfmt\fR, ...); +.fi + +.LP +.nf +\fBvoid\fR \fBvwarnx\fR(\fBconst char *\fR\fIfmt\fR, \fBva_list\fR \fIargs\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBerr()\fR and \fBwarn()\fR family of functions display a formatted error +message on the standard error output. In all cases, the last component of the +program name, followed by a colon character and a space, are output. If the +\fIfmt\fR argument is not \fINULL\fR, the formatted error message is output. In +the case of the \fBerr()\fR, \fBverr()\fR, \fBwarn()\fR, and \fBvwarn()\fR +functions, the error message string affiliated with the current value of the +global variable \fBerrno\fR is output next, preceded by a colon character and a +space if \fIfmt\fR is not \fINULL\fR. In all cases, the output is followed by a +newline character. The \fBerrx()\fR, \fBverrx()\fR, \fBwarnx()\fR, and +\fBvwarnx()\fR functions will not output this error message string. +.sp +.LP +The \fBerr()\fR, \fBverr()\fR, \fBerrx()\fR, and \fBverrx()\fR functions do not +return, but instead cause the program to terminate with the status value given +by the argument status. +.SH EXAMPLES +.LP +\fBExample 1 \fRDisplay the current \fBerrno\fR information string and +terminate with status indicating failure. +.sp +.in +2 +.nf +if ((p = malloc(size)) == NULL) + err(EXIT_FAILURE, NULL); +if ((fd = open(file_name, O_RDONLY, 0)) == -1) + err(EXIT_FAILURE, "%s", file_name); +.fi +.in -2 + +.LP +\fBExample 2 \fRDisplay an error message and terminate with status indicating +failure. +.sp +.in +2 +.nf +if (tm.tm_hour < START_TIME) + errx(EXIT_FAILURE, "too early, wait until %s", start_time_string); +.fi +.in -2 + +.LP +\fBExample 3 \fRWarn of an error. +.sp +.in +2 +.nf +if ((fd = open(raw_device, O_RDONLY, 0)) == -1) + warnx("%s: %s: trying the block device", + raw_device, strerror(errno)); +if ((fd = open(block_device, O_RDONLY, 0)) == -1) + warn("%s", block_device); +.fi +.in -2 + +.SH WARNINGS +.sp +.LP +It is important never to pass a string with user-supplied data as a format +without using `%s'. An attacker can put format specifiers in the string to +mangle the stack, leading to a possible security hole. This holds true even if +the string has been built ``by hand'' using a function like \fBsnprintf\fR(3C), +as the resulting string can still contain user-supplied conversion specifiers +for later interpolation by the \fBerr()\fR and \fBwarn()\fR functions. +.sp +.LP +Always be sure to use the proper secure idiom: +.sp +.in +2 +.nf +err(1, "%s", string); +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelSafe with Exceptions +.TE + +.sp +.LP +These functions are safe to use in multithreaded applications as long as +\fBsetlocale\fR(3C) is not being called to change the locale. +.SH SEE ALSO +.sp +.LP +\fBexit\fR(3C), \fBgetexecname\fR(3C), \fBsetlocale\fR(3C), \fBstrerror\fR(3C), +\fBattributes\fR(5) diff --git a/usr/src/man/man3c/euclen.3c b/usr/src/man/man3c/euclen.3c new file mode 100644 index 0000000000..603cfb7790 --- /dev/null +++ b/usr/src/man/man3c/euclen.3c @@ -0,0 +1,74 @@ +'\" te +.\" Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH euclen 3C "20 Dec 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +euclen, euccol, eucscol \- get byte length and display width of EUC characters +.SH SYNOPSIS +.LP +.nf +#include <euc.h> + +\fBint\fR \fBeuclen\fR(\fBconst unsigned char *\fR\fIs\fR); +.fi + +.LP +.nf +\fBint\fR \fBeuccol\fR(\fBconst unsigned char *\fR\fIs\fR); +.fi + +.LP +.nf +\fBint\fR \fBeucscol\fR(\fBconst unsigned char *\fR\fIstr\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBeuclen()\fR function returns the length in bytes of the Extended Unix +Code (EUC) character pointed to by \fIs\fR, including single-shift characters, +if present. +.sp +.LP +The \fBeuccol()\fR function returns the screen column width of the \fBEUC\fR +character pointed to by \fIs\fR. +.sp +.LP +The \fBeucscol()\fR function returns the screen column width of the \fBEUC\fR +string pointed to by \fIstr\fR. +.sp +.LP +For the \fBeuclen()\fR and \fBeuccol()\fR, functions, \fIs\fR points to the +first byte of the character. This byte is examined to determine its codeset. +The character type table for the current \fIlocale\fR is used for codeset byte +length and display width information. +.SH USAGE +.sp +.LP +These functions will work only with \fBEUC\fR locales. +.sp +.LP +These functions can be used safely in multithreaded applications, as long as +\fBsetlocale\fR(3C) is not called to change the locale. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +MT-LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBgetwidth\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/exit.3c b/usr/src/man/man3c/exit.3c new file mode 100644 index 0000000000..294de4a471 --- /dev/null +++ b/usr/src/man/man3c/exit.3c @@ -0,0 +1,66 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH exit 3C "1 Mar 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +exit, _exithandle \- terminate process +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBvoid\fR \fBexit\fR(\fBint\fR \fIstatus\fR); +.fi + +.LP +.nf +\fBvoid\fR \fB_exithandle\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBexit()\fR function terminates a process by calling first +\fB_exithandle()\fR and then \fB_exit()\fR (see \fBexit\fR(2)). +.sp +.LP +The \fB_exithandle()\fR function calls any functions registered through the +\fBatexit\fR(3C) function in the reverse order of their registration. This +action includes executing all finalization code from the \fI\&.fini\fR sections +of all objects that are part of the process. +.sp +.LP +The \fB_exithandle()\fR function is intended for use \fIonly\fR with +\fB_exit()\fR, and allows for specialized processing such as \fBdldump\fR(3C) +to be performed. Normal process execution should not be continued after a call +to \fB_exithandle()\fR has occurred, as internal data structures may have been +torn down due to \fBatexit()\fR or \fI\&.fini\fR processing. +.sp +.LP +The symbols \fBEXIT_SUCCESS\fR and \fBEXIT_FAILURE\fR are defined in the header +<\fBstdlib.h\fR> and may be used as the value of \fIstatus\fR to indicate +successful or unsuccessful termination, respectively. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBexit\fR(2), \fBatexit\fR(3C), \fBdldump\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/fattach.3c b/usr/src/man/man3c/fattach.3c new file mode 100644 index 0000000000..ff69f99be2 --- /dev/null +++ b/usr/src/man/man3c/fattach.3c @@ -0,0 +1,191 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH fattach 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +fattach \- attach a STREAMS- or doors-based file descriptor to an object in the +file system name space +.SH SYNOPSIS +.LP +.nf +#include <stropts.h> + +\fBint\fR \fBfattach\fR(\fBint\fR \fIfildes\fR, \fBconst char *\fR\fIpath\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBfattach()\fR function attaches a STREAMS- or doors-based file descriptor +to an object in the file system name space, effectively associating a name with +\fIfildes\fR. The \fIfildes\fR argument must be a valid open file descriptor +representing a STREAMS or doors file. The \fIpath\fR argument is a path name of +an existing object and the user must have appropriate privileges or be the +owner of the file and have write permissions. All subsequent operations on +\fIpath\fR will operate on the STREAMS or doors file until the STREAMS or doors +file is detached from the node. The \fIfildes\fR argument can be attached to +more than one \fIpath\fR, that is, a stream or door can have several names +associated with it. +.sp +.LP +The attributes of the named stream or door (see \fBstat\fR(2)), are initialized +as follows: the permissions, user ID, group ID, and times are set to those of +\fIpath\fR, the number of links is set to 1, and the size and device identifier +are set to those of the streams or doors device associated with \fIfildes\fR. +If any attributes of the named stream or door are subsequently changed (for +example, \fBchmod\fR(2)), the attributes of the underlying object are not +affected. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBfattach()\fR returns \fB0\fR. Otherwise it +returns \fB\(mi1\fR and sets \fBerrno\fR to indicate an error. +.SH ERRORS +.sp +.LP +The \fBfattach()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 16n +.rt +The user is the owner of \fIpath\fR but does not have write permissions on +\fIpath\fR or \fIfildes\fR is locked. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 16n +.rt +The \fIfildes\fR argument is not a valid open file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBUSY\fR\fR +.ad +.RS 16n +.rt +The \fIpath\fR argument is currently a mount point or has a STREAMS or doors +file descriptor attached to it. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 16n +.rt +The \fIpath\fR argument is a file in a remotely mounted directory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 16n +.rt +The \fIfildes\fR argument does not represent a STREAMS or doors file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBELOOP\fR\fR +.ad +.RS 16n +.rt +Too many symbolic links were encountered in translating \fIpath\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +The size of \fIpath\fR exceeds {\fB\fR\fBPATH\fR\fB_MAX\fR}, or the component +of a path name is longer than {\fBNAME_MAX\fR} while {\fB_POSIX_NO_TRUNC\fR} is +in effect. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 16n +.rt +The \fIpath\fR argument does not exist. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTDIR\fR\fR +.ad +.RS 16n +.rt +A component of a path prefix is not a directory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 16n +.rt +The effective user ID is not the owner of \fIpath\fR or a user with the +appropriate privileges. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfdetach\fR(1M), \fBchmod\fR(2), \fBmount\fR(2), \fBstat\fR(2), +\fBdoor_create\fR(3C), \fBfdetach\fR(3C), \fBisastream\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5), \fBstreamio\fR(7I) +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man3c/fclose.3c b/usr/src/man/man3c/fclose.3c new file mode 100644 index 0000000000..90eaca3603 --- /dev/null +++ b/usr/src/man/man3c/fclose.3c @@ -0,0 +1,176 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH fclose 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +fclose \- close a stream +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBint\fR \fBfclose\fR(\fBFILE *\fR\fIstream\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBfclose()\fR function causes the stream pointed to by \fIstream\fR to be +flushed and the associated file to be closed. Any unwritten buffered data for +the stream is written to the file; any unread buffered data is discarded. The +stream is disassociated from the file. If the associated buffer was +automatically allocated, it is deallocated. +.sp +.LP +The \fBfclose()\fR function marks for update the \fBst_ctime\fR and +\fBst_mtime\fR fields of the underlying file if the stream is writable and if +buffered data has not yet been written to the file. It will perform a +\fBclose\fR(2) operation on the file descriptor that is associated with the +stream pointed to by \fIstream\fR. +.sp +.LP +After the call to \fBfclose()\fR, any use of \fIstream\fR causes undefined +behavior. +.sp +.LP +The \fBfclose()\fR function is performed automatically for all open files upon +calling \fBexit\fR(2). +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBfclose()\fR returns \fB0\fR. Otherwise, it +returns \fBEOF\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBfclose()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +The \fBO_NONBLOCK\fR flag is set for the file descriptor underlying +\fIstream\fR and the process would be delayed in the write operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The file descriptor underlying stream is not valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFBIG\fR\fR +.ad +.RS 10n +.rt +An attempt was made to write a file that exceeds the maximum file size or the +process's file size limit; or the file is a regular file and an attempt was +made to write at or beyond the offset maximum associated with the corresponding +stream. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 10n +.rt +The \fBfclose()\fR function was interrupted by a signal. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 10n +.rt +The process is a member of a background process group attempting to write to +its controlling terminal, \fBTOSTOP\fR is set, the process is neither ignoring +nor blocking \fBSIGTTOU\fR and the process group of the process is orphaned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSPC\fR\fR +.ad +.RS 10n +.rt +There was no free space remaining on the device containing the file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPIPE\fR\fR +.ad +.RS 10n +.rt +An attempt is made to write to a pipe or \fBFIFO\fR that is not open for +reading by any process. A \fBSIGPIPE\fR signal will also be sent to the calling +thread. +.RE + +.sp +.LP +The \fBfclose()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENXIO\fR\fR +.ad +.RS 9n +.rt +A request was made of a non-existent device, or the request was beyond the +limits of the device. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBclose\fR(2), \fBexit\fR(2), \fBgetrlimit\fR(2), \fBulimit\fR(2), +\fBfopen\fR(3C), \fBstdio\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/fdatasync.3c b/usr/src/man/man3c/fdatasync.3c new file mode 100644 index 0000000000..dc0e5543ee --- /dev/null +++ b/usr/src/man/man3c/fdatasync.3c @@ -0,0 +1,108 @@ +'\" te +.\" Copyright (c) 1997, The Open Group. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH fdatasync 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +fdatasync \- synchronize a file's data +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> + +\fBint\fR \fBfdatasync\fR(\fBint\fR \fIfildes\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBfdatasync()\fR function forces all currently queued I/O operations +associated with the file indicated by file descriptor \fIfildes\fR to the +synchronized I/O completion state. +.sp +.LP +The functionality is as described for \fBfsync\fR(3C) (with the symbol +\fB_XOPEN_REALTIME\fR defined), with the exception that all I/O operations are +completed as defined for synchronised I/O data integrity completion. +.SH RETURN VALUES +.sp +.LP +If successful, the \fBfdatasync()\fR function returns \fB0\fR. Otherwise, the +function returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the error. If the +\fBfdatasync()\fR function fails, outstanding I/O operations are not guaranteed +to have been completed. +.SH ERRORS +.sp +.LP +The \fBfdatasync()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIfildes\fR argument is not a valid file descriptor open for writing. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The system does not support synchronized I/O for this file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR\fR +.ad +.RS 10n +.rt +The function \fBfdatasync()\fR is not supported by the system. +.RE + +.sp +.LP +In the event that any of the queued I/O operations fail, \fBfdatasync()\fR +returns the error conditions defined for \fBread\fR(2) and \fBwrite\fR(2). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelAsync-Signal-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBfcntl\fR(2), \fBopen\fR(2), \fBread\fR(2), \fBwrite\fR(2), \fBfsync\fR(3C), +\fBaio_fsync\fR(3C), \fBfcntl.h\fR(3HEAD), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/fdetach.3c b/usr/src/man/man3c/fdetach.3c new file mode 100644 index 0000000000..f775900e16 --- /dev/null +++ b/usr/src/man/man3c/fdetach.3c @@ -0,0 +1,170 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH fdetach 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +fdetach \- detach a name from a STREAMS-based file descriptor +.SH SYNOPSIS +.LP +.nf +#include <stropts.h> + +\fBint\fR \fBfdetach\fR(\fBconst char *\fR\fIpath\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBfdetach()\fR function detaches a STREAMS-based file from the file to +which it was attached by a previous call to \fBfattach\fR(3C). The \fIpath\fR +argument points to the pathname of the attached \fBSTREAMS\fR file. The process +must have appropriate privileges or be the owner of the file. A successful call +to \fBfdetach()\fR causes all pathnames that named the attached \fBSTREAMS\fR +file to again name the file to which the \fBSTREAMS\fR file was attached. All +subsequent operations on \fIpath\fR will operate on the underlying file and not +on the \fBSTREAMS\fR file. +.sp +.LP +All open file descriptions established while the \fBSTREAMS\fR file was +attached to the file referenced by \fIpath\fR, will still refer to the +\fBSTREAMS\fR file after the \fBfdetach()\fR has taken effect. +.sp +.LP +If there are no open file descriptors or other references to the \fBSTREAMS\fR +file, then a successful call to \fBfdetach()\fR has the same effect as +performing the last \fBclose\fR(2) on the attached file. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBfdetach()\fR returns \fB0\fR. Otherwise, it +returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBfdetach()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 16n +.rt +Search permission is denied on a component of the path prefix. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 16n +.rt +The effective user \fBID\fR is not the owner of \fIpath\fR and the process does +not have appropriate privileges. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTDIR\fR\fR +.ad +.RS 16n +.rt +A component of the path prefix is not a directory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 16n +.rt +A component of \fIpath\fR does not name an existing file or \fIpath\fR is an +empty string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 16n +.rt +The \fIpath\fR argument names a file that is not currently attached. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +The size of a pathname exceeds \fBPATH_MAX\fR, or a pathname component is +longer than \fBNAME_MAX\fR while \fB_POSIX_NO_TRUNC\fR is in effect. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBELOOP\fR\fR +.ad +.RS 16n +.rt +Too many symbolic links were encountered in resolving \fIpath\fR. +.RE + +.sp +.LP +The \fBfdetach()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +Pathname resolution of a symbolic link produced an intermediate result whose +length exceeds \fBPATH_MAX\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityStandard +.TE + +.SH SEE ALSO +.sp +.LP +\fBfdetach\fR(1M), \fBclose\fR(2), \fBfattach\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5), \fBstreamio\fR(7I) +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man3c/fdopen.3c b/usr/src/man/man3c/fdopen.3c new file mode 100644 index 0000000000..fd1d5e0350 --- /dev/null +++ b/usr/src/man/man3c/fdopen.3c @@ -0,0 +1,179 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH fdopen 3C "18 Apr 2006" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +fdopen \- associate a stream with a file descriptor +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBFILE *\fR\fBfdopen\fR(\fBint\fR \fIfildes\fR, \fBconst char *\fR\fImode\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBfdopen()\fR function associates a stream with a file descriptor +\fIfildes\fR. +.sp +.LP +The \fImode\fR argument is a character string having one of the following +values: +.sp + +.sp +.TS +tab(); +lw(1.9i) lw(3.6i) +lw(1.9i) lw(3.6i) +. +\fBr\fR or \fBrb\fROpen a file for reading. +\fBw\fR or \fBwb\fROpen a file for writing. +\fBa\fR or \fBab\fROpen a file for writing at end of file. +\fBr+\fR, \fBrb+\fR or \fBr+b\fRT{ +Open a file for update (reading and writing). +T} +\fBw+\fR, \fBwb+\fR or \fBw+b\fRT{ +Open a file for update (reading and writing). +T} +\fBa+\fR, \fBab+\fR or \fBa+b\fRT{ +Open a file for update (reading and writing) at end of file. +T} +.TE + +.sp +.LP +The meaning of these flags is exactly as specified for the \fBfopen\fR(3C) +function, except that modes beginning with \fIw\fR do not cause truncation of +the file. A trailing \fBF\fR character can also be included in the \fImode\fR +argument as described in \fBfopen\fR(3C) to enable extended FILE facility. +.sp +.LP +The mode of the stream must be allowed by the file access mode of the open +file. The file position indicator associated with the new stream is set to the +position indicated by the file offset associated with the file descriptor. +.sp +.LP +The \fBfdopen()\fR function preserves the offset maximum previously set for the +open file description corresponding to \fIfildes\fR. +.sp +.LP +The error and end-of-file indicators for the stream are cleared. The +\fBfdopen()\fR function may cause the \fBst_atime\fR field of the underlying +file to be marked for update. +.sp +.LP +If \fIfildes\fR refers to a shared memory object, the result of the +\fBfdopen()\fR function is unspecified. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBfdopen()\fR returns a pointer to a stream. +Otherwise, a null pointer is returned and \fBerrno\fR is set to indicate the +error. +.sp +.LP +The \fBfdopen()\fR function may fail and not set \fBerrno\fR if there are no +free \fBstdio\fR streams. +.SH ERRORS +.sp +.LP +The \fBfdopen()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIfildes\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fImode\fR argument is not a valid mode. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 10n +.rt +{\fBFOPEN_MAX\fR} streams are currently open in the calling process. +.sp +{\fBSTREAM_MAX\fR} streams are currently open in the calling process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +There is insufficient space to allocate a buffer. +.RE + +.SH USAGE +.sp +.LP +A process is allowed to have at least {\fBFOPEN_MAX\fR} \fBstdio\fR streams +open at a time. For 32-bit applications, however, the underlying ABIs formerly +required that no file descriptor used to access the file underlying a +\fBstdio\fR stream have a value greater than 255. To maintain binary +compatibility with earlier Solaris releases, this limit still constrains 32-bit +applications. +.sp +.LP +File descriptors are obtained from calls like \fBopen\fR(2), \fBdup\fR(2), +\fBcreat\fR(2) or \fBpipe\fR(2), which open files but do not return streams. +Streams are necessary input for almost all of the standard I/O library +functions. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilitySee below. +_ +MT-LevelMT-Safe +.TE + +.sp +.LP +The \fBF\fR character in the \fImode\fR argument is Evolving. In all other +respects this function is Standard. +.SH SEE ALSO +.sp +.LP +\fBcreat\fR(2), \fBdup\fR(2), \fBopen\fR(2), \fBpipe\fR(2), \fBfclose\fR(3C), +\fBfopen\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/ferror.3c b/usr/src/man/man3c/ferror.3c new file mode 100644 index 0000000000..3e3f04c4ae --- /dev/null +++ b/usr/src/man/man3c/ferror.3c @@ -0,0 +1,74 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ferror 3C "17 Feb 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +ferror, feof, clearerr, fileno \- stream status inquiries +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBint\fR \fBferror\fR(\fBFILE *\fR\fIstream\fR); +.fi + +.LP +.nf +\fBint\fR \fBfeof\fR(\fBFILE *\fR\fIstream\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBclearerr\fR(\fBFILE *\fR\fIstream\fR); +.fi + +.LP +.nf +\fBint\fR \fBfileno\fR(\fBFILE *\fR\fIstream\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBferror()\fR function returns a non-zero value when an error has +previously occurred reading from or writing to the named \fIstream\fR (see +\fBIntro\fR(3)). It returns \fB0\fR otherwise. +.sp +.LP +The \fBfeof()\fR function returns a non-zero value when \fBEOF\fR has +previously been detected reading the named input \fIstream\fR. It returns +\fB0\fR otherwise. +.sp +.LP +The \fBclearerr()\fR function resets the error indicator and \fBEOF\fR +indicator to 0 on the named \fIstream\fR. +.sp +.LP +The \fBfileno()\fR function returns the integer file descriptor associated with +the named \fIstream\fR; see \fBopen\fR(2). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBopen\fR(2), \fBIntro\fR(3), \fBfopen\fR(3C), \fBstdio\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/fflush.3c b/usr/src/man/man3c/fflush.3c new file mode 100644 index 0000000000..0a9cb328b4 --- /dev/null +++ b/usr/src/man/man3c/fflush.3c @@ -0,0 +1,175 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH fflush 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +fflush \- flush a stream +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBint\fR \fBfflush\fR(\fBFILE *\fR\fIstream\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +If \fIstream\fR points to an output stream or an update stream in which the +most recent operation was not input, \fBfflush()\fR causes any unwritten data +for that stream to be written to the file, and the \fBst_ctime\fR and +\fBst_mtime\fR fields of the underlying file are marked for update. +.sp +.LP +If \fIstream\fR points to an input stream or an update stream into which the +most recent operation was input, that stream is flushed if it is seekable and +is not already at end-of-file. Flushing an input stream discards any buffered +input and adjusts the file pointer such that the next input operation accesses +the byte after the last one read. A stream is seekable if the underlying file +is not a pipe, FIFO, socket, or TTY device. +.sp +.LP +If \fIstream\fR is a null pointer, \fBfflush()\fR performs this flushing action +on all streams for which the behavior is defined above. +.sp +.LP +An input stream, seekable or non-seekable, can be flushed by explicitly calling +\fBfflush()\fR with a non-null argument specifying that stream. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBfflush()\fR returns \fB0\fR. Otherwise, it +returns \fBEOF\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBfflush()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +The \fBO_NONBLOCK\fR flag is set for the file descriptor underlying +\fIstream\fR and the process would be delayed in the write operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The file descriptor underlying \fIstream\fR is not valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFBIG\fR\fR +.ad +.RS 10n +.rt +An attempt was made to write a file that exceeds the maximum file size or the +process's file size limit; or the file is a regular file and an attempt was +made to write at or beyond the offset maximum associated with the corresponding +stream. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 10n +.rt +The \fBfflush()\fR function was interrupted by a signal. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 10n +.rt +The process is a member of a background process group attempting to write to +its controlling terminal, \fBTOSTOP\fR is set, the process is neither ignoring +nor blocking \fBSIGTTOU\fR, and the process group of the process is orphaned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSPC\fR\fR +.ad +.RS 10n +.rt +There was no free space remaining on the device containing the file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPIPE\fR\fR +.ad +.RS 10n +.rt +An attempt is made to write to a pipe or \fBFIFO\fR that is not open for +reading by any process. A \fBSIGPIPE\fR signal will also be sent to the calling +process. +.RE + +.sp +.LP +The \fBfflush()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENXIO\fR\fR +.ad +.RS 9n +.rt +A request was made of a non-existent device, or the request was beyond the +limits of the device. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgetrlimit\fR(2), \fBulimit\fR(2), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/ffs.3c b/usr/src/man/man3c/ffs.3c new file mode 100644 index 0000000000..97c4538a68 --- /dev/null +++ b/usr/src/man/man3c/ffs.3c @@ -0,0 +1,58 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ffs 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +ffs \- find first set bit +.SH SYNOPSIS +.LP +.nf +#include <strings.h> + +\fBint\fR \fBffs\fR(\fBconst int\fR \fIi\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBffs()\fR function finds the first bit set (beginning with the least +significant bit) and returns the index of that bit. Bits are numbered starting +at one (the least significant bit). +.SH RETURN VALUES +.sp +.LP +The \fBffs()\fR function returns the index of the first bit set. If \fIi\fR is +0, then \fBffs()\fR returns 0. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/fgetattr.3c b/usr/src/man/man3c/fgetattr.3c new file mode 100644 index 0000000000..25c6d1bded --- /dev/null +++ b/usr/src/man/man3c/fgetattr.3c @@ -0,0 +1,327 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH fgetattr 3C "4 Aug 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +fgetattr, fsetattr, getattrat, setattrat \- get and set system attributes +.SH SYNOPSIS +.LP +.nf +#include <fcntl.h> +#include <sys/types.h> +#include <attr.h> +#include <sys/nvpair.h> + +\fBint\fR \fBfgetattr\fR(\fBint\fR fildes, \fBxattr_view_t\fR view,\fBnvlist_t **\fRresponse); +.fi + +.LP +.nf +\fBint\fR \fBfsetattr\fR(\fBint\fR fildes, \fBxattr_view_t\fR view,\fBnvlist_t *\fRrequest) +.fi + +.LP +.nf +\fBint\fR \fBgetattrat\fR(\fBint\fR fildes, \fBxattr_view_t\fR view, \fBconst char *\fRfilename, + \fBnvlist_t **\fRresponse); +.fi + +.LP +.nf +\fBint\fR \fBsetattrat\fR(\fBint\fR fildes, \fBxattr_view_t\fR view, \fBconst char *\fRfilename, + \fBnvlist_t *\fRrequest); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBfgetattr()\fR function obtains an nvlist of system attribute information +about an open file object specified by the file descriptor \fIfildes\fR, +obtained from a successful \fBopen\fR(2), \fBcreat\fR(2), \fBdup\fR(2), +\fBfcntl\fR(2), or \fBpipe\fR(2) function. +.sp +.LP +The \fBgetattrat()\fR function first opens the extended attribute file +specified by \fIfilename\fR in the already opened file directory object +specified by \fIfildes\fR. It then retrieves an nvlist of system attributes and +their values from \fIfilename\fR. +.sp +.LP +The \fIresponse\fR argument is allocated by either \fBfgetattr()\fR or +\fBgetattrat()\fR. The application must call \fBnvlist_free\fR(3NVPAIR) to +deallocate the memory. +.sp +.LP +Upon successful completion, the nvlist will contain one nvpair for each of the +system attributes associated with \fIview\fR. The list of views and the +attributes associated with each view are listed below. Not all underlying file +systems support all views and all attributes. The nvlist will not contain an +nvpair for any attribute not supported by the underlying filesystem. +.sp +.LP +The \fBfsetattr()\fR function uses the nvlist pointed to by \fIrequest\fR to +update one or more of the system attribute's information about an open file +object specified by the file descriptor \fIfildes\fR, obtained from a +successful \fBopen()\fR, \fBcreat()\fR, \fBdup()\fR, \fBfcntl()\fR, or +\fBpipe()\fR function. The \fBsetattrat()\fR function first opens the extended +attribute file specified by \fIfilename\fR in the already opened file directory +object specified by \fIfildes\fR. It then uses the nvlist pointed to by +\fIrequest\fR to update one or more of the system attributes of filename. +.sp +.LP +If completion is not successful then no system attribute information is +updated. +.sp +.LP +The following chart lists the supported views, attributes, and data types for +each view: +.sp + +.sp +.TS +tab(); +cw(1.83i) cw(1.83i) cw(1.83i) +lw(1.83i) lw(1.83i) lw(1.83i) +. +ViewAttributeData type +_ +\fBXATTR_VIEW_READONLY\fR\fBA_FSID\fR\fBuint64_value\fR +\fBA_OPAQUE\fR\fBboolean_value\fR +\fBA_AV_SCANSTAMP\fR\fBuint8_array[]\fR +\fBXATTR_VIEW_READWRITE\fR\fBA_READONLY\fR\fBboolean_value\fR +\fBA_HIDDEN\fR\fBboolean_value\fR +\fBA_SYSTEM\fR\fBboolean_value\fR +\fBA_ARCHIVE\fR\fBboolean_value\fR +\fBA_CRTIME\fR\fBuint64_array\fR[2] +\fBA_NOUNLINK\fR\fBboolean_value\fR +\fBA_IMMUTABLE\fR\fBboolean_value\fR +\fBA_APPENDONLY\fR\fBboolean_value\fR +\fBA_NODUMP\fR\fBboolean_value\fR +\fBA_AV_QUARANTINED\fR\fBboolean_value\fR +\fBA_AV_MODIFIED\fR\fBboolean_value\fR +\fBA_OWNERSID\fRT{ +nvlist composed of \fBuint32_value\fR and \fBstring\fR +T} +\fBA_GROUPSID\fRT{ +nvlist composed of \fBuint32_value\fR and \fBstring\fR +T} +.TE + +.SH RETURN VALUES +.sp +.LP +Upon successful completion, 0 is returned. Otherwise, -1 is returned and +\fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBfgetattr()\fR, \fBgetattrat()\fR, \fBfsetattr()\fR, and +\fBsetattrat()\fR, functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIfildes\fR argument is not a valid open file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The underlying file system does not support extended file attributes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 10n +.rt +An error occurred while reading from the file system. +.RE + +.sp +.LP +The \fBgetattrat()\fR and \fBsetattrat()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 10n +.rt +Search permission or write permission for \fIfilename\fR is denied. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 10n +.rt +The \fIfilename\fR argument does not name an existing file in the extended +attribute directory represented by \fIfildes\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 10n +.rt +There are insufficient privileges to manipulate attributes. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRObtain an nvlist of readonly system attributes for an open file +object. +.sp +.LP +Use \fBfgetattr()\fR to obtain an nvlist of the readonly system attributes for +the open file object represented by file descriptor \fIfildes\fR. + +.sp +.in +2 +.nf +#include <fcntl.h> +#include <sys/types.h> +#include <attr.h> +#include <sys/nvpair.h> + +nvlist_t *response; +nvpair_t *pair = NULL; + +if (fgetattr(fildes, XATTR_VIEW_READONLY, &response)) { + exit(1); +} +while (pair = nvlist_next_nvpair(response, pair)) { + . + . + . +} +nvlist_free(response); +.fi +.in -2 + +.LP +\fBExample 2 \fRSet the \fBA_READONLY\fR system attribute on an open file +object. +.sp +.LP +Use \fBfsetattr()\fR to set the \fBA_OPAQUE\fR system attribute on the open +file object represented by file descriptor \fIfildes\fR. + +.sp +.in +2 +.nf +nvlist_t *request; +nvpair_t *pair = NULL; + +if (nvlist_alloc(&request, NV_UNIQUE_NAME, 0) != 0) { + exit(1); +} +if (nvlist_add_boolean_value(request, A_READONLY, 1) != 0) { + exit(1); +} +if (fsetattr(fildes, XATTR_VIEW_READWRITE, request)) { + exit(1); +} +.fi +.in -2 + +.LP +\fBExample 3 \fRObtain an nvlist of the read/write system attributes for a +file. +.sp +.LP +Use \fBgetattrat()\fR to obtain an nvlist of the read/write system attributes +for the file named \fBxattrfile\fR in the extended attribute directory of the +open file represented by file descriptor \fIfildes\fR. + +.sp +.in +2 +.nf +nvlist_t *response; +nvpair_t *pair = NULL; + +if (getattrat(fildes, XATTR_VIEW_READWRITE, "file", &response)) { + exit(1); +} +while (pair = nvlist_next_nvpair(response, pair)) { + . + . + . +} +nvlist_free(response); +.fi +.in -2 + +.LP +\fBExample 4 \fRSet the \fBA_APPENDONLY\fR system attribute on a file. +.sp +.LP +Use \fBsetattrat()\fR to set the \fBA_APPENDONLY\fR system attribute on the +file named \fBfile\fR in the extended attribute directory of the open file +represented by file descriptor \fIfildes\fR. + +.sp +.in +2 +.nf +nvlist_t *request; +nvpair_t *pair = NULL; + +if (nvlist_alloc(&request, NV_UNIQUE_NAME, 0) != 0) { + exit(1); +} +if (nvlist_add_boolean_value(request, A_APPENDONLY, 1) != 0) { + exit(1); +} +if (setattrat(fildes, XATTR_VIEW_READWRITE, "file", request)) { + exit(1); + } +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBcreat\fR(2), \fBdup\fR(2), \fBfcntl\fR(2), \fBfstat\fR(2), \fBfstatat\fR(2), +\fBopen\fR(2), \fBpipe\fR(2), \fBlibnvpair\fR(3LIB), \fBattributes\fR(5), +\fBfsattr\fR(5) diff --git a/usr/src/man/man3c/fgetc.3c b/usr/src/man/man3c/fgetc.3c new file mode 100644 index 0000000000..e1eee49f3f --- /dev/null +++ b/usr/src/man/man3c/fgetc.3c @@ -0,0 +1,277 @@ +'\" te +.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH fgetc 3C "15 Oct 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +fgetc, getc, getc_unlocked, getchar, getchar_unlocked, getw \- get a byte from +a stream +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBint\fR \fBfgetc\fR(\fBFILE *\fR\fIstream\fR); +.fi + +.LP +.nf +\fBint\fR \fBgetc\fR(\fBFILE *\fR\fIstream\fR); +.fi + +.LP +.nf +\fBint\fR \fBgetc_unlocked\fR(\fBFILE *\fR\fIstream\fR); +.fi + +.LP +.nf +\fBint\fR \fBgetchar\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBint\fR \fBgetchar_unlocked\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBint\fR \fBgetw\fR(\fBFILE *\fR\fIstream\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBfgetc()\fR function obtains the next byte (if present) as an \fBunsigned +char\fR converted to an \fBint\fR, from the input stream pointed to by +\fIstream\fR, and advances the associated file position indicator for the +stream (if defined). +.sp +.LP +For standard-conforming (see \fBstandards\fR(5)) applications, if the +end-of-file indicator for the stream is set, \fBfgetc()\fR returns \fBEOF\fR +whether or not a next byte is present. +.sp +.LP +The \fBfgetc()\fR function may mark the \fBst_atime\fR field of the file +associated with \fIstream\fR for update. The \fBst_atime\fR field will be +marked for update by the first successful execution of \fBfgetc()\fR, +\fBfgets\fR(3C), \fBfread\fR(3C), \fBfscanf\fR(3C), \fBgetc()\fR, +\fBgetchar()\fR, \fBgets\fR(3C) or \fBscanf\fR(3C) using \fIstream\fR that +returns data not supplied by a prior call to \fBungetc\fR(3C) or +\fBungetwc\fR(3C). +.sp +.LP +The \fBgetc()\fR function is functionally identical to \fBfgetc()\fR, except +that it is implemented as a macro. It runs faster than \fBfgetc()\fR, but it +takes up more space per invocation and its name cannot be passed as an argument +to a function call. +.sp +.LP +The \fBgetchar()\fR routine is equivalent to \fBgetc(stdin)\fR. It is +implemented as a macro. +.sp +.LP +The \fBgetc_unlocked()\fR and \fBgetchar_unlocked()\fR routines are variants of +\fBgetc()\fR and \fBgetchar()\fR, respectively, that do not lock the stream. +It is the caller's responsibility to acquire the stream lock before calling +these routines and releasing the lock afterwards; see \fBflockfile\fR(3C) and +\fBstdio\fR(3C). These routines are implemented as macros. +.sp +.LP +The \fBgetw()\fR function reads the next word from the \fIstream\fR. The size +of a word is the size of an \fBint\fR and may vary from environment to +environment. The \fBgetw()\fR function presumes no special alignment in the +file. +.sp +.LP +The \fBgetw()\fR function may mark the \fBst_atime\fR field of the file +associated with \fIstream\fR for update. The \fBst_atime\fR field will be +marked for update by the first successful execution of \fBfgetc()\fR, +\fBfgets\fR(3C), \fBfread\fR(3C), \fBgetc()\fR, \fBgetchar()\fR, +\fBgets\fR(3C), \fBfscanf\fR(3C) or \fBscanf\fR(3C) using \fIstream\fR that +returns data not supplied by a prior call to \fBungetc\fR(3C). +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBfgetc()\fR, \fBgetc()\fR, \fBgetc_unlocked()\fR, +\fBgetchar()\fR, \fBgetchar_unlocked()\fR, and \fBgetw()\fR return the next +byte from the input stream pointed to by \fIstream\fR. If the stream is at +end-of-file, the end-of-file indicator for the stream is set and these +functions return \fBEOF\fR. For standard-conforming (see \fBstandards\fR(5)) +applications, if the end-of-file indicator for the stream is set, these +functions return \fBEOF\fR whether or not the stream is at end-of-file. If a +read error occurs, the error indicator for the stream is set, \fBEOF\fR is +returned, and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBfgetc()\fR, \fBgetc()\fR, \fBgetc_unlocked()\fR, \fBgetchar()\fR, +\fBgetchar_unlocked()\fR, and \fBgetw()\fR functions will fail if data needs to +be read and: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 13n +.rt +The \fBO_NONBLOCK\fR flag is set for the file descriptor underlying +\fIstream\fR and the process would be delayed in the \fBfgetc()\fR operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 13n +.rt +The file descriptor underlying \fIstream\fR is not a valid file descriptor open +for reading. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 13n +.rt +The read operation was terminated due to the receipt of a signal, and no data +was transferred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 13n +.rt +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 process +is ignoring or blocking the \fBSIGTTIN\fR signal or the process group is +orphaned. This error may also be generated for implementation-dependent +reasons. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOVERFLOW\fR\fR +.ad +.RS 13n +.rt +The file is a regular file and an attempt was made to read at or beyond the +offset maximum associated with the corresponding stream. +.RE + +.sp +.LP +The \fBfgetc()\fR, \fBgetc()\fR, \fBgetc_unlocked()\fR, \fBgetchar()\fR, +\fBgetchar_unlocked()\fR, and \fBgetw()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient storage space is available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENXIO\fR\fR +.ad +.RS 10n +.rt +A request was made of a non-existent device, or the request was outside the +capabilities of the device. +.RE + +.SH USAGE +.sp +.LP +If the integer value returned by \fBfgetc()\fR, \fBgetc()\fR, +\fBgetc_unlocked()\fR, \fBgetchar()\fR, \fBgetchar_unlocked()\fR, and +\fBgetw()\fR is stored into a variable of type \fBchar\fR and then compared +against the integer constant EOF, the comparison may never succeed, because +sign-extension of a variable of type \fBchar\fR on widening to integer is +implementation-dependent. +.sp +.LP +The \fBferror\fR(3C) or \fBfeof\fR(3C) functions must be used to distinguish +between an error condition and an end-of-file condition. +.sp +.LP +Functions exist for the \fBgetc()\fR, \fBgetc_unlocked()\fR, \fBgetchar()\fR, +and \fBgetchar_unlocked()\fR macros. To get the function form, the macro name +must be undefined (for example, \fB#undef getc\fR). +.sp +.LP +When the macro forms are used, \fBgetc()\fR and \fBgetc_unlocked()\fR evaluate +the \fIstream\fR argument more than once. In particular, +\fBgetc(*\fR\fIf++\fR\fB);\fR does not work sensibly. The \fBfgetc()\fR +function should be used instead when evaluating the \fIstream\fR argument has +side effects. +.sp +.LP +Because of possible differences in word length and byte ordering, files written +using \fBgetw()\fR are machine-dependent, and may not be read using +\fBgetw()\fR on a different processor. +.sp +.LP +The \fBgetw()\fR function is inherently byte stream-oriented and is not tenable +in the context of either multibyte character streams or wide-character streams. +Application programmers are recommended to use one of the character-based input +functions instead. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityT{ +\fBfgetc()\fR, \fBgetc()\fR, \fBgetc_unlocked()\fR, \fBgetchar()\fR, and \fBgetchar_unlocked()\fR are Standard. +T} +_ +MT-LevelSee \fBNOTES\fR below. +.TE + +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(3), \fB__fsetlocking\fR(3C), \fBfclose\fR(3C), \fBfeof\fR(3C), +\fBfgets\fR(3C), \fBfgetwc\fR(3C), \fBfgetws\fR(3C), \fBflockfile\fR(3C), +\fBfopen\fR(3C), \fBfread\fR(3C), \fBfscanf\fR(3C), \fBgets\fR(3C), +\fBputc\fR(3C), \fBscanf\fR(3C), \fBstdio\fR(3C), \fBungetc\fR(3C), +\fBungetwc\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +The \fBfgetc()\fR, \fBgetc()\fR, \fBgetchar()\fR, and \fBgetw()\fR routines are +MT-Safe in multithreaded applications. The \fBgetc_unlocked()\fR and +\fBgetchar_unlocked()\fR routines are unsafe in multithreaded applications. diff --git a/usr/src/man/man3c/fgetpos.3c b/usr/src/man/man3c/fgetpos.3c new file mode 100644 index 0000000000..4c991b3110 --- /dev/null +++ b/usr/src/man/man3c/fgetpos.3c @@ -0,0 +1,99 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH fgetpos 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +fgetpos \- get current file position information +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBint\fR \fBfgetpos\fR(\fBFILE *\fR\fIstream\fR, \fBfpos_t *\fR\fIpos\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBfgetpos()\fR function stores the current value of the file position +indicator for the stream pointed to by \fIstream\fR in the object pointed to by +\fIpos\fR. The value stored contains unspecified information usable by +\fBfsetpos\fR(3C) for repositioning the stream to its position at the time of +the call to \fBfgetpos()\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBfgetpos()\fR returns \fB0\fR. Otherwise, it +returns a non-zero value and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBfgetpos()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 13n +.rt +The file descriptor underlying \fIstream\fR is not valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBESPIPE\fR\fR +.ad +.RS 13n +.rt +The file descriptor underlying \fIstream\fR is associated with a pipe, a FIFO, +or a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOVERFLOW\fR\fR +.ad +.RS 13n +.rt +The current value of the file position cannot be represented correctly in an +object of type \fBfpos_t\fR. +.RE + +.SH USAGE +.sp +.LP +The \fBfgetpos()\fR function has a transitional interface for 64-bit file +offsets. See \fBlf64\fR(5). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityStandard +.TE + +.SH SEE ALSO +.sp +.LP +\fBfopen\fR(3C), \fBfsetpos\fR(3C), \fBftell\fR(3C), \fBrewind\fR(3C), +\fBungetc\fR(3C), \fBattributes\fR(5), \fBlf64\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/fgetwc.3c b/usr/src/man/man3c/fgetwc.3c new file mode 100644 index 0000000000..2ab2fb84af --- /dev/null +++ b/usr/src/man/man3c/fgetwc.3c @@ -0,0 +1,198 @@ +'\" te +.\" Copyright (c) 2003, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH fgetwc 3C "15 Oct 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +fgetwc \- get a wide-character code from a stream +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> +#include <wchar.h> + +\fBwint_t\fR \fBfgetwc\fR(\fBFILE*\fR\fIstream\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBfgetwc()\fR function obtains the next character (if present) from the +input stream pointed to by \fIstream\fR, converts that to the corresponding +wide-character code and advances the associated file position indicator for the +stream (if defined). +.sp +.LP +If an error occurs, the resulting value of the file position indicator for the +stream is indeterminate. +.sp +.LP +The \fBfgetwc()\fR function may mark the \fBst_atime\fR field of the file +associated with \fIstream\fR for update. The \fBst_atime\fR field will be +marked for update by the first successful execution of \fBfgetwc()\fR, +\fBfgetc\fR(3C), \fBfgets\fR(3C), \fBfgetws\fR(3C), \fBfread\fR(3C), +\fBfscanf\fR(3C), \fBgetc\fR(3C), \fBgetchar\fR(3C), \fBgets\fR(3C), or +\fBscanf\fR(3C) using \fIstream\fR that returns data not supplied by a prior +call to \fBungetc\fR(3C) or \fBungetwc\fR(3C). +.SH RETURN VALUES +.sp +.LP +Upon successful completion the \fBfgetwc()\fR function returns the +wide-character code of the character read from the input stream pointed to by +\fIstream\fR converted to a type \fBwint_t\fR. +.sp +.LP +For standard-conforming (see \fBstandards\fR(5)) applications, if the +end-of-file indicator for the stream is set, \fBfgetwc()\fR returns \fBWEOF\fR +whether or not the stream is at end-of-file. +.sp +.LP +If a read error occurs, the error indicator for the stream is set, +\fBfgetwc()\fR returns \fBWEOF\fR and sets \fBerrno\fR to indicate the error. +.sp +.LP +If an encoding error occurs, the error indicator for the stream is set, +\fBfgetwc()\fR returns \fBWEOF\fR, and \fBerrno\fR is set to indicate the +error. +.SH ERRORS +.sp +.LP +The \fBfgetwc()\fR function will fail if data needs to be read and: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 14n +.rt +The \fBO_NONBLOCK\fR flag is set for the file descriptor underlying +\fIstream\fR and the process would be delayed in the \fBfgetwc()\fR operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 14n +.rt +The file descriptor underlying \fIstream\fR is not a valid file descriptor open +for reading. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 14n +.rt +The read operation was terminated due to the receipt of a signal, and no data +was transferred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 14n +.rt +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 process +is ignoring or blocking the \fBSIGTTIN\fR signal or the process group is +orphaned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOVERFLOW\fR \fR +.ad +.RS 14n +.rt +The file is a regular file and an attempt was made to read at or beyond the +offset maximum associated with the corresponding \fIstream\fR. +.RE + +.sp +.LP +The \fBfgetwc()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient storage space is available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENXIO\fR\fR +.ad +.RS 10n +.rt +A request was made of a non-existent device, or the request was outside the +capabilities of the device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEILSEQ\fR\fR +.ad +.RS 10n +.rt +The data obtained from the input stream does not form a valid character. +.RE + +.SH USAGE +.sp +.LP +The \fBferror\fR(3C) or \fBfeof\fR(3C) functions must be used to distinguish +between an error condition and an end-of-file condition. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +CSIEnabled +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBfeof\fR(3C), \fBferror\fR(3C), \fBfgetc\fR(3C), \fBfgets\fR(3C), +\fBfgetws\fR(3C), \fBfopen\fR(3C), \fBfread\fR(3C), \fBfscanf\fR(3C), +\fBgetc\fR(3C), \fBgetchar\fR(3C), \fBgets\fR(3C), \fBscanf\fR(3C), +\fBsetlocale\fR(3C), \fBungetc\fR(3C), \fBungetwc\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/floating_to_decimal.3c b/usr/src/man/man3c/floating_to_decimal.3c new file mode 100644 index 0000000000..d4ee81f55a --- /dev/null +++ b/usr/src/man/man3c/floating_to_decimal.3c @@ -0,0 +1,128 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH floating_to_decimal 3C "7 Jun 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +floating_to_decimal, single_to_decimal, double_to_decimal, extended_to_decimal, +quadruple_to_decimal \- convert floating-point value to decimal record +.SH SYNOPSIS +.LP +.nf +#include <floatingpoint.h> + +\fBvoid\fR \fBsingle_to_decimal\fR(\fBsingle *\fR\fIpx\fR, \fBdecimal_mode *\fR\fIpm\fR, + \fBdecimal_record *\fR\fIpd\fR, \fBfp_exception_field_type *\fR\fIps\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBdouble_to_decimal\fR(\fBdouble *\fR\fIpx\fR, \fBdecimal_mode *\fR\fIpm\fR, + \fBdecimal_record *\fR\fIpd\fR, \fBfp_exception_field_type *\fR\fIps\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBextended_to_decimal\fR(\fBextended *\fR\fIpx\fR, \fBdecimal_mode *\fR\fIpm\fR, + \fBdecimal_record *\fR\fIpd\fR, \fBfp_exception_field_type *\fR\fIps\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBquadruple_to_decimal\fR(\fBquadruple *\fR\fIpx\fR, \fBdecimal_mode *\fR\fIpm\fR, + \fBdecimal_record *\fR\fIpd\fR, \fBfp_exception_field_type *\fR\fIps\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBfloating_to_decimal\fR functions convert the floating-point value at +\fI*px\fR into a decimal record at *\fIpd\fR, observing the modes specified in +*\fIpm\fR and setting exceptions in *\fIps\fR. If there are no IEEE exceptions, +*\fIps\fR will be zero. +.sp +.LP +If *\fIpx\fR is zero, infinity, or NaN, then only \fIpd\fR\(->\fIsign\fR and +\fIpd\fR\(->\fIfpclass\fR are set. Otherwise \fIpd\fR\(->\fIexponent\fR and +\fIpd\fR\(->\fIds\fR are also set so that +.sp +.in +2 +.nf +(sig)*(pd->ds)*10**(pd->exponent) +.fi +.in -2 + +.sp +.LP +is a correctly rounded approximation to *\fIpx\fR, where \fIsig\fR is +1 or +\(mi1, depending upon whether \fIpd\fR\(->\fIsign\fR is 0 or \(mi1. +\fIpd\fR\(->\fIds\fR has at least one and no more than +\fBDECIMAL_STRING_LENGTH\fR-1 significant digits because one character is used +to terminate the string with a null. +.sp +.LP +\fIpd\fR\(->\fIds\fR is correctly rounded according to the IEEE rounding modes +in \fIpm\fR\(->\fIrd\fR. *\fIps\fR has \fIfp_inexact\fR set if the result was +inexact, and has \fIfp_overflow\fR set if the string result does not fit in +\fIpd\fR\(->\fIds\fR because of the limitation \fBDECIMAL_STRING_LENGTH\fR. +.sp +.LP +If \fIpm\fR\(->\fIdf\fR == \fIfloating_form\fR, then \fIpd\fR\(->\fIds\fR +always contains \fIpm\fR\(->\fIndigits\fR significant digits. Thus if *\fIpx\fR +== 12.34 and \fIpm\fR\(->\fIndigits\fR == 8, then \fIpd\fR\(->\fIds\fR will +contain 12340000 and \fIpd\fR\(->\fIexponent\fR will contain \(mi6. +.sp +.LP +If \fIpm\fR\(->\fIdf\fR == \fIfixed_form\fR and \fIpm\fR\(->\fIndigits\fR >= 0, +then the decimal value is rounded at \fIpm\fR\(->\fIndigits\fR digits to the +right of the decimal point. For example, if *\fIpx\fR == 12.34 and +\fIpm\fR\(->\fIndigits\fR == 1, then \fIpd\fR\(->\fIds\fR will contain 123 and +\fIpd\fR\(->\fIexponent\fR will be set to \(mi1. +.sp +.LP +If \fIpm\fR\(->\fIdf\fR == \fIfixed_form\fR and \fIpm\fR\(->\fIndigits\fR< 0, +then the decimal value is rounded at \(mi\fIpm\fR\(->\fIndigits\fR digits to +the left of the decimal point, and \fIpd\fR\(->\fIds\fR is padded with trailing +zeros up to the decimal point. For example, if *\fIpx\fR == 12.34 and +\fIpm\fR\(->\fIn\fR digits == \(mi1, then \fIpd\fR\(->\fIds\fR will contain 10 +and \fIpd\fR\(->\fIexponent\fR will be set to 0. +.sp +.LP +When \fIpm\fR\(->\fIdf\fR == \fIfixed_form\fR and the value to be converted is +large enough that the resulting string would contain more than +\fBDECIMAL_STRING_LENGTH\fR\(mi1 digits, then the string placed in +\fIpd\fR\(->\fIds\fR is limited to exactly \fBDECIMAL_STRING_LENGTH\fR-1 digits +(by moving the place at which the value is rounded further left if need be), +\fIpd\fR\(->\fIexponent\fR is adjusted accordingly and the overflow flag is set +in *\fIps\fR. +.sp +.LP +\fIpd->more\fR is not used. +.sp +.LP +The \fBeconvert\fR(3C), \fBfconvert\fR(3C), \fBgconvert\fR(3C), +\fBprintf\fR(3C), and \fBsprintf\fR(3C) functions all use +\fBdouble_to_decimal()\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBeconvert\fR(3C), \fBfconvert\fR(3C), \fBgconvert\fR(3C), \fBprintf\fR(3C), +\fBsprintf\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/flockfile.3c b/usr/src/man/man3c/flockfile.3c new file mode 100644 index 0000000000..d78d57a517 --- /dev/null +++ b/usr/src/man/man3c/flockfile.3c @@ -0,0 +1,124 @@ +'\" te +.\" Copyright (c) 2003 Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH flockfile 3C "10 Sep 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +flockfile, funlockfile, ftrylockfile \- acquire and release stream lock +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBvoid\fR \fBflockfile\fR(\fBFILE *\fR\fIstream\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBfunlockfile\fR(\fBFILE *\fR\fIstream\fR); +.fi + +.LP +.nf +\fBint\fR \fBftrylockfile\fR(\fBFILE *\fR\fIstream\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBflockfile()\fR function acquires an internal lock of a stream +\fIstream\fR. If the lock is already acquired by another thread, the thread +calling \fBflockfile()\fR is suspended until it can acquire the lock. In the +case that the stream lock is available, \fBflockfile()\fR not only acquires the +lock, but keeps track of the number of times it is being called by the current +thread. This implies that the stream lock can be acquired more than once by +the same thread. +.sp +.LP +The \fBfunlockfile()\fR function releases the lock being held by the current +thread. In the case of recursive locking, this function must be called the +same number of times \fBflockfile()\fR was called. After the number of +\fBfunlockfile()\fR calls is equal to the number of \fBflockfile()\fR calls, +the stream lock is available for other threads to acquire. +.sp +.LP +The \fBftrylockfile()\fR function acquires an internal lock of a stream +\fIstream\fR, only if that object is available. In essence +\fBftrylockfile()\fR is a non-blocking version of \fBflockfile()\fR. +.SH RETURN VALUES +.sp +.LP +The \fBftrylockfile()\fR function returns \fB0\fR on success and non-zero to +indicate a lock cannot be acquired. +.SH EXAMPLES +.LP +\fBExample 1 \fRA sample program of \fBflockfile()\fR. +.sp +.LP +The following example prints everything out together, blocking other threads +that might want to write to the same file between calls to \fBfprintf\fR(3C): + +.sp +.in +2 +.nf +FILE iop; +flockfile(iop); +fprintf(iop, "hello "); +fprintf(iop, "world); +fputc(iop, 'a'); +funlockfile(iop); +.fi +.in -2 + +.sp +.LP +An unlocked interface is available in case performance is an issue. For +example: + +.sp +.in +2 +.nf +flockfile(iop); +while (!feof(iop)) { + *c++ = getc_unlocked(iop); +} +funlockfile(iop); +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(3), \fB__fsetlocking\fR(3C), \fBferror\fR(3C), \fBfprintf\fR(3C), +\fBgetc\fR(3C), \fBputc\fR(3C), \fBstdio\fR(3C), \fBungetc\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +The interfaces on this page are as specified in IEEE Std 1003.1:2001. See +\fBstandards\fR(5). diff --git a/usr/src/man/man3c/fmtmsg.3c b/usr/src/man/man3c/fmtmsg.3c new file mode 100644 index 0000000000..36e14dfa82 --- /dev/null +++ b/usr/src/man/man3c/fmtmsg.3c @@ -0,0 +1,524 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH fmtmsg 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +fmtmsg \- display a message on stderr or system console +.SH SYNOPSIS +.LP +.nf +#include <fmtmsg.h> + +\fBint\fR \fBfmtmsg\fR(\fBlong\fR \fIclassification\fR, \fBconst char *\fR\fIlabel\fR, \fBint\fR \fIseverity\fR, +\fBconst char *\fR\fItext\fR, \fBconst char *\fR\fIaction\fR, \fBconst char *\fR\fItag\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBfmtmsg()\fR function writes a formatted message to \fBstderr\fR, to the +console, or to both, on a message's classification component. It can be used +instead of the traditional \fBprintf\fR(3C) interface to display messages to +\fBstderr\fR, and in conjunction with \fBgettxt\fR(3C), provides a simple +interface for producing language-independent applications. +.sp +.LP +A formatted message consists of up to five standard components ( \fIlabel\fR, +\fIseverity\fR, \fItext\fR, \fIaction\fR, and \fItag\fR) as described below. +The \fIclassification\fR component is not part of the standard message +displayed to the user, but rather defines the source of the message and directs +the display of the formatted message. +.sp +.ne 2 +.mk +.na +\fB\fIclassification\fR\fR +.ad +.RS 18n +.rt +Contains identifiers from the following groups of major classifications and +subclassifications. Any one identifier from a subclass may be used in +combination by ORing the values together 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 \fBstderr\fR and the system console). +.RS +4 +.TP +.ie t \(bu +.el o +"Major classifications" identify the source of the condition. Identifiers are: +\fBMM_HARD\fR (hardware), \fBMM_SOFT\fR (software), and \fBMM_FIRM\fR +(firmware). +.RE +.RS +4 +.TP +.ie t \(bu +.el o +"Message source subclassifications" identify the type of software in which the +problem is spotted. Identifiers are: \fBMM_APPL\fR (application), \fBMM_UTIL\fR +(utility), and \fBMM_OPSYS\fR (operating system). +.RE +.RS +4 +.TP +.ie t \(bu +.el o +"Display subclassifications" indicate where the message is to be displayed. +Identifiers are: \fBMM_PRINT\fR to display the message on the standard error +stream, \fBMM_CONSOLE\fR to display the message on the system console. Neither, +either, or both identifiers may be used. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +"Status subclassifications" indicate whether the application will recover from +the condition. Identifiers are: \fBMM_RECOVER\fR (recoverable) and +\fBMM_NRECOV\fR (non-recoverable). +.RE +.RS +4 +.TP +.ie t \(bu +.el o +An additional identifier, \fBMM_NULLMC\fR, indicates that no classification +component is supplied for the message. +.RE +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlabel\fR\fR +.ad +.RS 18n +.rt +Identifies the source of the message. The format of this component is two +fields separated by a colon. The first field is up to 10 characters long; the +second is up to 14 characters. Suggested usage is that \fIlabel\fR identifies +the package in which the application resides as well as the program or +application name. For example, the \fIlabel\fR \fBUX:cat\fR indicates the +\fBUNIX\fR System V package and the \fBcat\fR(1) utility. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIseverity\fR\fR +.ad +.RS 18n +.rt +Indicates the seriousness of the condition. Identifiers for the standard levels +of \fIseverity\fR are: +.RS +4 +.TP +.ie t \(bu +.el o +\fBMM_HALT\fR indicates that the application has encountered a severe fault and +is halting. Produces the print string \fBHALT\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBMM_ERROR\fR indicates that the application has detected a fault. Produces +the print string \fBERROR\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBMM_WARNING\fR indicates a condition out of the ordinary that might be a +problem and should be watched. Produces the print string \fBWARNING\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBMM_INFO\fR provides information about a condition that is not in error. +Produces the print string \fBINFO\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBMM_NOSEV\fR indicates that no severity level is supplied for the message. +.RE +Other severity levels may be added by using the \fBaddseverity()\fR routine. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItext\fR\fR +.ad +.RS 18n +.rt +Describes the condition that produced the message. The \fItext\fR string is not +limited to a specific size. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaction\fR\fR +.ad +.RS 18n +.rt +Describes the first step to be taken in the error recovery process. +\fBfmtmsg()\fR precedes each action string with the prefix: \fBTO\fRFIX\fB:.\fR +The \fIaction\fR string is not limited to a specific size. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItag\fR\fR +.ad +.RS 18n +.rt +An identifier which 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 \fBUX:cat:146\fR. +.RE + +.SS "Environment Variables" +.sp +.LP +The \fBMSGVERB\fR and \fBSEV_LEVEL\fR environment variables control the +behavior of \fBfmtmsg()\fR as follows: +.sp +.ne 2 +.mk +.na +\fB\fBMSGVERB\fR\fR +.ad +.RS 13n +.rt +This variable determines which message components \fBfmtmsg()\fR selects when +writing messages to \fBstderr\fR. Its value is a colon-separated list of +optional keywords and can be set as follows: +.sp +.in +2 +.nf +\fBMSGVERB=\fR[\fIkeyword\fR[\fB:\fR\fIkeyword\fR[\fB:\fR\|.\|.\|.]]] +\fBexport MSGVERB\fR +.fi +.in -2 + +Valid \fIkeywords\fR are: \fBlabel\fR, \fBseverity\fR, \fBtext\fR, +\fBaction\fR, and \fBtag\fR. If \fBMSGVERB\fR contains a keyword for a +component and the component's value is not the component's null value, +\fBfmtmsg()\fR includes that component in the message when writing the message +to \fBstderr\fR. If \fBMSGVERB\fR does not include a keyword for a message +component, that component is not included in the display of the message. The +keywords may appear in any order. If \fBMSGVERB\fR 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, \fBfmtmsg()\fR +selects all components. +.sp +The first time \fBfmtmsg()\fR is called, it examines \fBMSGVERB\fR to determine +which message components are to be selected when generating a message to write +to the standard error stream, \fBstderr\fR. The values accepted on the initial +call are saved for future calls. +.sp +The \fBMSGVERB\fR environment variable affects only those components that are +selected for display to the standard error stream. All message components are +included in console messages. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSEV_LEVEL\fR\fR +.ad +.RS 13n +.rt +This variable defines severity levels and associates print strings with them +for use by \fBfmtmsg()\fR. The standard severity levels listed below cannot be +modified. Additional severity levels can also be defined, redefined, and +removed using \fBaddseverity()\fR (see \fBaddseverity\fR(3C)). If the same +severity level is defined by both \fBSEV_LEVEL\fR and \fBaddseverity()\fR, the +definition by \fBaddseverity()\fR takes precedence. +.sp +.ne 2 +.mk +.na +\fB0\fR +.ad +.RS 5n +.rt +(no severity is used) +.RE + +.sp +.ne 2 +.mk +.na +\fB1\fR +.ad +.RS 5n +.rt +\fBHALT\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB2\fR +.ad +.RS 5n +.rt +\fBERROR\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB3\fR +.ad +.RS 5n +.rt +\fBWARNING\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB4\fR +.ad +.RS 5n +.rt +\fBINFO\fR +.RE + +The \fBSEV_LEVEL\fR variable can be set as follows: +.sp +.in +2 +.nf +\fBSEV_LEVEL=\fR[\fIdescription\fR[\fB:\fR\fIdescription\fR[\fB:\fR\|.\|.\|.]]] +\fBexport SEV_LEVEL\fR +.fi +.in -2 + +where \fIdescription\fR is a comma-separated list containing three fields: +.sp +\fIdescription\fR=\fIseverity_keyword\fR,\fIlevel\fR,\fIprintstring\fR +.sp +The \fIseverity_keyword\fR field is a character string that is used as the +keyword on the \fB\fR\fB-s\fR\fB \fR\fIseverity\fR option to the +\fBfmtmsg\fR(1) utility. (This field is not used by the \fBfmtmsg()\fR +function.) +.sp +The \fIlevel\fR field is a character string that evaluates to a positive +integer (other than 0, 1, 2, 3, or 4, which are reserved for the standard +severity levels). If the keyword \fIseverity_keyword\fR is used, \fIlevel\fR is +the severity value passed on to the \fBfmtmsg()\fR function. +.sp +The \fIprintstring\fR field is the character string used by \fBfmtmsg()\fR in +the standard message format whenever the severity value \fIlevel\fR is used. +.sp +If a \fIdescription\fR in the colon list is not a three-field comma list, or if +the second field of a comma list does not evaluate to a positive integer, that +\fIdescription\fR in the colon list is ignored. +.sp +The first time \fBfmtmsg()\fR is called, it examines the \fBSEV_LEVEL\fR +environment variable, if defined, to determine whether the environment expands +the levels of severity beyond the five standard levels and those defined using +\fBaddseverity()\fR. The values accepted on the initial call are saved for +future calls. +.RE + +.SS "Use in Applications" +.sp +.LP +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. +.sp +.LP +The table below indicates the null values and identifiers for \fBfmtmsg()\fR +arguments. +.sp + +.sp +.TS +tab() box; +lw(1.38i) lw(1.38i) lw(1.38i) lw(1.38i) +lw(1.38i) lw(1.38i) lw(1.38i) lw(1.38i) +. +ArgumentTypeNull-ValueIdentifier +\fIlabel\fR\fBchar*\fR\fB(char*) NULL\fR\fBMM_NULLLBL\fR +\fIseverity\fR\fBint\fR\fB0\fR\fBMM_NULLSEV\fR +\fIclass\fR\fBlong\fR\fB0L\fR\fBMM_NULLMC\fR +\fItext\fR\fBchar*\fR\fB(char*) NULL\fR\fBMM_NULLTXT\fR +\fIaction\fR\fBchar*\fR\fB(char*) NULL\fR\fBMM_NULLACT\fR +\fItag\fR\fBchar*\fR\fB(char*) NULL\fR\fBMM_NULLTAG\fR +.TE + +.sp +.LP +Another means of systematically omitting a component is by omitting the +component keyword(s) when defining the \fBMSGVERB\fR environment variable (see +the \fBEnvironment Variables\fR section above). +.SH RETURN VALUES +.sp +.LP +The \fBfmtmsg()\fR returns the following values: +.sp +.ne 2 +.mk +.na +\fB\fBMM_OK\fR\fR +.ad +.RS 12n +.rt +The function succeeded. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMM_NOTOK\fR\fR +.ad +.RS 12n +.rt +The function failed completely. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMM_NOMSG\fR\fR +.ad +.RS 12n +.rt +The function was unable to generate a message on the standard error stream, but +otherwise succeeded. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMM_NOCON\fR\fR +.ad +.RS 12n +.rt +The function was unable to generate a console message, but otherwise succeeded. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRThe following example of \fBfmtmsg()\fR: +.sp +.in +2 +.nf +fmtmsg(MM_PRINT, "UX:cat", MM_ERROR, "invalid syntax", +"refer to manual", "UX:cat:001") +.fi +.in -2 + +.sp +.LP +produces a complete message in the standard message format: + +.sp +.in +2 +.nf +UX:cat: ERROR: invalid syntax +TO FIX: refer to manual UX:cat:001 +.fi +.in -2 + +.LP +\fBExample 2 \fRWhen the environment variable \fBMSGVERB\fR is set as follows: +.sp +.in +2 +.nf +MSGVERB=severity:text:action +.fi +.in -2 + +.sp +.LP +and the Example 1 is used, \fBfmtmsg()\fR produces: + +.sp +.in +2 +.nf +ERROR: invalid syntax +TO FIX: refer to manual +.fi +.in -2 + +.LP +\fBExample 3 \fRWhen the environment variable \fBSEV_LEVEL\fR is set as +follows: +.sp +.in +2 +.nf +SEV_LEVEL=note,5,NOTE +.fi +.in -2 + +.sp +.LP +the following call to \fBfmtmsg()\fR + +.sp +.in +2 +.nf +fmtmsg(MM_UTIL | MM_PRINT, "UX:cat", 5, "invalid syntax", +"refer to manual", "UX:cat:001") +.fi +.in -2 + +.sp +.LP +produces + +.sp +.in +2 +.nf +UX:cat: NOTE: invalid syntax +TO FIX: refer to manual UX:cat:001 +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfmtmsg\fR(1), \fBaddseverity\fR(3C), \fBgettxt\fR(3C), \fBprintf\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/fnmatch.3c b/usr/src/man/man3c/fnmatch.3c new file mode 100644 index 0000000000..075bd6fd55 --- /dev/null +++ b/usr/src/man/man3c/fnmatch.3c @@ -0,0 +1,145 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH fnmatch 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +fnmatch \- match filename or path name +.SH SYNOPSIS +.LP +.nf +#include <fnmatch.h> + +\fBint\fR \fBfnmatch\fR(\fBconst char *\fR\fIpattern\fR, \fBconst char *\fR\fIstring\fR, \fBint\fR \fIflags\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBfnmatch()\fR function matches patterns as described on the +\fBfnmatch\fR(5) manual page. It checks the \fIstring\fR argument to see if it +matches the \fIpattern\fR argument. +.sp +.LP +The \fIflags\fR argument modifies the interpretation of \fIpattern\fR and +\fIstring\fR. It is the bitwise inclusive \fBOR\fR of zero or more of the +following flags defined in the header <\fBfnmatch.h\fR>. +.sp +.ne 2 +.mk +.na +\fB\fBFNM_PATHNAME\fR \fR +.ad +.RS 18n +.rt +If set, a slash (\fB/\fR) character in \fIstring\fR will be explicitly matched +by a slash in \fIpattern\fR; it will not be matched by either the asterisk +(\fB*\fR) or question-mark (\fB?\fR) special characters, nor by a bracket +(\fB[\|]\fR) expression. +.sp +If not set, the slash character is treated as an ordinary character. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFNM_NOESCAPE\fR\fR +.ad +.RS 18n +.rt +If not set, a backslash character (\fB\e\fR) in \fIpattern\fR followed by any +other character will match that second character in \fIstring\fR. In +particular, "\fB\e\e\fR" will match a backslash in \fIstring\fR. +.sp +If set, a backslash character will be treated as an ordinary character. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFNM_PERIOD\fR\fR +.ad +.RS 18n +.rt +If set, a leading period in \fIstring\fR will match a period in \fIpattern\fR; +where the location of "leading" is indicated by the value of +\fBFNM_PATHNAME\fR: +.RS +4 +.TP +.ie t \(bu +.el o +If \fBFNM_PATHNAME\fR is set, a period is "leading" if it is the first +character in \fIstring\fR or if it immediately follows a slash. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If \fBFNM_PATHNAME\fR is not set, a period is "leading" only if it is the first +character of \fIstring\fR. +.RE +.RE + +.sp +.LP +If not set, no special restrictions are placed on matching a period. +.SH RETURN VALUES +.sp +.LP +If \fIstring\fR matches the pattern specified by \fIpattern\fR, then +\fBfnmatch()\fR returns \fB0\fR. If there is no match, \fBfnmatch()\fR returns +\fBFNM_NOMATCH\fR, which is defined in the header <\fBfnmatch.h\fR>. If an +error occurs, \fBfnmatch()\fR returns another non-zero value. +.SH USAGE +.sp +.LP +The \fBfnmatch()\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 \fBfind\fR(1) utility is an example of this. It can +also be used by the \fBpax\fR(1) utility to process its \fIpattern\fR operands, +or by applications that need to match strings in a similar manner. +.sp +.LP +The name \fBfnmatch()\fR is intended to imply \fIfilename\fR match, rather than +\fIpathname\fR match. The default action of this function is to match +filenames, rather than path names, since it gives no special significance to +the slash character. With the \fBFNM_PATHNAME\fR flag, \fBfnmatch()\fR does +match path names, but without tilde expansion, parameter expansion, or special +treatment for period at the beginning of a filename. +.sp +.LP +The \fBfnmatch()\fR function can be used safely in multithreaded applications, +as long as \fBsetlocale\fR(3C) is not being called to change the locale. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +CSIEnabled +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBfind\fR(1), \fBpax\fR(1), \fBglob\fR(3C), \fBsetlocale\fR(3C), +\fBwordexp\fR(3C), \fBattributes\fR(5), \fBfnmatch\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/fopen.3c b/usr/src/man/man3c/fopen.3c new file mode 100644 index 0000000000..df3a9ad119 --- /dev/null +++ b/usr/src/man/man3c/fopen.3c @@ -0,0 +1,444 @@ +'\" te +.\" Copyright 1989 AT&T. +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH fopen 3C "18 Apr 2006" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +fopen \- open a stream +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBFILE *\fR\fBfopen\fR(\fBconst char *\fR\fIfilename\fR, \fBconst char *\fR\fImode\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBfopen()\fR function opens the file whose pathname is the string pointed +to by \fIfilename\fR, and associates a stream with it. +.sp +.LP +The argument \fImode\fR points to a string beginning with one of the following +sequences: +.sp +.ne 2 +.mk +.na +\fB\fBr\fR or \fBrb\fR\fR +.ad +.RS 20n +.rt +Open file for reading. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBw\fR or \fBwb\fR\fR +.ad +.RS 20n +.rt +Truncate to zero length or create file for writing. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBa\fR or \fBab\fR\fR +.ad +.RS 20n +.rt +Append; open or create file for writing at end-of-file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBr+\fR or \fBrb+\fR or \fBr+b\fR\fR +.ad +.RS 20n +.rt +Open file for update (reading and writing). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBw+\fR or \fBwb+\fR or \fBw+b\fR\fR +.ad +.RS 20n +.rt +Truncate to zero length or create file for update. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBa+\fR or \fBab+\fR or \fBa+b\fR\fR +.ad +.RS 20n +.rt +Append; open or create file for update, writing at end-of-file. +.RE + +.sp +.LP +The character \fBb\fR has no effect, but is allowed for ISO C standard +conformance (see \fBstandards\fR(5)). Opening a file with read mode (\fBr\fR as +the first character in the \fImode\fR argument) fails if the file does not +exist or cannot be read. +.sp +.LP +Opening a file with append mode (\fBa\fR as the first character in the +\fImode\fR argument) causes all subsequent writes to the file to be forced to +the then current end-of-file, regardless of intervening calls to +\fBfseek\fR(3C). If two separate processes open the same file for append, each +process may write freely to the file without fear of destroying output being +written by the other. The output from the two processes will be intermixed in +the file in the order in which it is written. +.sp +.LP +When a file is opened with update mode (\fB+\fR as the second or third +character in the \fImode\fR argument), both input and output may be performed +on the associated stream. However, output must not be directly followed by +input without an intervening call to \fBfflush\fR(3C) or to a file positioning +function ( \fBfseek\fR(3C), \fBfsetpos\fR(3C) or \fBrewind\fR(3C)), and input +must not be directly followed by output without an intervening call to a file +positioning function, unless the input operation encounters end-of-file. +.sp +.LP +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 are cleared. +.sp +.LP +If \fImode\fR begins with \fIw\fR or \fBa\fR and the file did not previously +exist, upon successful completion, \fBfopen()\fR function will mark for update +the \fBst_atime\fR, \fBst_ctime\fR and \fBst_mtime\fR fields of the file and +the \fBst_ctime\fR and \fBst_mtime\fR fields of the parent directory. +.sp +.LP +If \fImode\fR begins with \fIw\fR and the file did previously exist, upon +successful completion, \fBfopen()\fR will mark for update the \fBst_ctime\fR +and \fBst_mtime\fR fields of the file. The \fBfopen()\fR function will +allocate a file descriptor as \fBopen\fR(2) does. +.sp +.LP +Normally, 32-bit applications return an \fBEMFILE\fR error when attempting to +associate a stream with a file accessed by a file descriptor with a value +greater than 255. If the last character of \fImode\fR is \fBF\fR, 32-bit +applications will be allowed to associate a stream with a file accessed by a +file descriptor with a value greater than 255. A \fBFILE\fR pointer obtained in +this way must never be used by any code that might directly access fields in +the \fBFILE\fR structure. If the fields in the \fBFILE\fR structure are used +directly by 32-bit applications when the last character of mode is \fBF\fR, +data corruption could occur. See the USAGE section of this manual page and the +\fBenable_extended_FILE_stdio\fR(3C) manual page for other options for enabling +the extended FILE facility. +.sp +.LP +In 64-bit applications, the last character of \fImode\fR is silently ignored if +it is \fBF\fR. 64-bit applications are always allowed to associate a stream +with a file accessed by a file descriptor with any value. +.sp +.LP +The largest value that can be represented correctly in an object of type +\fBoff_t\fR will be established as the offset maximum in the open file +description. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBfopen()\fR returns a pointer to the object +controlling the stream. Otherwise, a null pointer is returned and \fBerrno\fR +is set to indicate the error. +.sp +.LP +The \fBfopen()\fR function may fail and not set \fBerrno\fR if there are no +free \fBstdio\fR streams. +.SH ERRORS +.sp +.LP +The \fBfopen()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 16n +.rt +Search permission is denied on a component of the path prefix, or the file +exists and the permissions specified by \fImode\fR are denied, or the file does +not exist and write permission is denied for the parent directory of the file +to be created. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 16n +.rt +A signal was caught during the execution of \fBfopen()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEISDIR\fR\fR +.ad +.RS 16n +.rt +The named file is a directory and \fImode\fR requires write access. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBELOOP\fR\fR +.ad +.RS 16n +.rt +Too many symbolic links were encountered in resolving \fIpath\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 16n +.rt +There are {\fBOPEN_MAX\fR} file descriptors currently open in the calling +process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +The length of the \fIfilename\fR exceeds \fIPATH_MAX\fR or a pathname component +is longer than \fINAME_MAX\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENFILE\fR\fR +.ad +.RS 16n +.rt +The maximum allowable number of files is currently open in the system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 16n +.rt +A component of \fIfilename\fR does not name an existing file or \fIfilename\fR +is an empty string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSPC\fR\fR +.ad +.RS 16n +.rt +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. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTDIR\fR\fR +.ad +.RS 16n +.rt +A component of the path prefix is not a directory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENXIO\fR\fR +.ad +.RS 16n +.rt +The named file is a character special or block special file, and the device +associated with this special file does not exist. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOVERFLOW\fR\fR +.ad +.RS 16n +.rt +The current value of the file position cannot be represented correctly in an +object of type \fBfpos_t\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEROFS\fR\fR +.ad +.RS 16n +.rt +The named file resides on a read-only file system and \fImode\fR requires write +access. +.RE + +.sp +.LP +The \fBfopen()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 16n +.rt +The value of the \fImode\fR argument is not valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 16n +.rt +{\fBFOPEN_MAX\fR} streams are currently open in the calling process. +.sp +{\fBSTREAM_MAX\fR} streams are currently open in the calling process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +Pathname resolution of a symbolic link produced an intermediate result whose +length exceeds {\fBPATH_MAX\fR}. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 16n +.rt +Insufficient storage space is available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBETXTBSY\fR\fR +.ad +.RS 16n +.rt +The file is a pure procedure (shared text) file that is being executed and +\fImode\fR requires write access. +.RE + +.SH USAGE +.sp +.LP +A process is allowed to have at least {\fBFOPEN_MAX\fR} \fBstdio\fR streams +open at a time. For 32-bit applications, however, the underlying ABIs formerly +required that no file descriptor used to access the file underlying a +\fBstdio\fR stream have a value greater than 255. To maintain binary +compatibility with earlier Solaris releases, this limit still constrains 32-bit +applications. However, when a 32-bit application is aware that no code that has +access to the \fBFILE\fR pointer returned by \fBfopen()\fR will use the +\fBFILE\fR pointer to directly access any fields in the \fBFILE\fR structure, +the \fBF\fR character can be used as the last character in the \fImode\fR +argument to circumvent this limit. Because it could lead to data corruption, +the \fBF\fR character in \fImode\fR must never be used when the \fBFILE\fR +pointer might later be used by binary code unknown to the user. The \fBF\fR +character in \fImode\fR is intended to be used by library functions that need a +\fBFILE\fR pointer to access data to process a user request, but do not need to +pass the \fBFILE\fR pointer back to the user. 32-bit applications that have +been inspected can use the extended FILE facility to circumvent this limit if +the inspection shows that no \fBFILE\fR pointers will be used to directly +access \fBFILE\fR structure contents. +.sp +.LP +The \fBfopen()\fR function has a transitional interface for 64-bit file +offsets. See \fBlf64\fR(5). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilitySee below. +_ +MT-LevelMT-Safe +.TE + +.sp +.LP +The \fBF\fR character in the \fImode\fR argument is Evolving. In all other +respects this function is Standard. +.SH SEE ALSO +.sp +.LP +\fBenable_extended_FILE_stdio\fR(3C), \fBfclose\fR(3C), \fBfdopen\fR(3C), +\fBfflush\fR(3C), \fBfreopen\fR(3C), \fBfsetpos\fR(3C), \fBrewind\fR(3C), +\fBattributes\fR(5), \fBlf64\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/fpgetround.3c b/usr/src/man/man3c/fpgetround.3c new file mode 100644 index 0000000000..142e199da9 --- /dev/null +++ b/usr/src/man/man3c/fpgetround.3c @@ -0,0 +1,178 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH fpgetround 3C "29 Dec 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +fpgetround, fpsetround, fpgetmask, fpsetmask, fpgetsticky, fpsetsticky \- IEEE +floating-point environment control +.SH SYNOPSIS +.LP +.nf +#include <ieeefp.h> + +\fBfp_rnd\fR \fBfpgetround\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBfp_rnd\fR \fBfpsetround\fR(\fBfp_rnd\fR \fIrnd_dir\fR); +.fi + +.LP +.nf +\fBfp_except\fR \fBfpgetmask\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBfp_except\fR \fBfpsetmask\fR(\fBfp_except\fR \fImask\fR); +.fi + +.LP +.nf +\fBfp_except\fR \fBfpgetsticky\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBfp_except\fR \fBfpsetsticky\fR(\fBfp_except\fR \fIsticky\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +There are five floating-point exceptions: +.RS +4 +.TP +.ie t \(bu +.el o +divide-by-zero, +.RE +.RS +4 +.TP +.ie t \(bu +.el o +overflow, +.RE +.RS +4 +.TP +.ie t \(bu +.el o +underflow, +.RE +.RS +4 +.TP +.ie t \(bu +.el o +imprecise (inexact) result, and +.RE +.RS +4 +.TP +.ie t \(bu +.el o +invalid operation. +.RE +.sp +.LP +When a floating-point exception occurs, the corresponding sticky bit is set +(1), and if the mask bit is enabled (1), the trap takes place. These routines +let the user change the behavior on occurrence of any of these exceptions, as +well as change the rounding mode for floating-point operations. +.sp +.LP +The \fImask\fR argument is formed by the logical OR operation of the following +floating-point exception masks: +.sp +.in +2 +.nf +\fBFP_X_INV /* invalid operation exception */ +FP_X_OFL /* overflow exception */ +FP_X_UFL /* underflow exception */ +FP_X_DZ /* divide-by-zero exception */ +FP_X_IMP /* imprecise (loss of precision) */\fR +.fi +.in -2 + +.sp +.LP +The following floating-point rounding modes are passed to \fBfpsetround\fR and +returned by \fBfpgetround()\fR. +.sp +.in +2 +.nf +FP_RN /* round to nearest representative number */ +FP_RP /* round to plus infinity */ +FP_RM /* round to minus infinity */ +FP_RZ /* round to zero (truncate) */ +.fi +.in -2 + +.sp +.LP +The default environment is rounding mode set to nearest (\fBFP_RN\fR) and all +traps disabled. +.sp +.LP +The \fBfpsetsticky()\fR function modifies all sticky flags. The +\fBfpsetmask()\fR function changes all mask bits. The \fBfpsetmask()\fR +function clears the sticky bit corresponding to any exception being enabled. +.SH RETURN VALUES +.sp +.LP +The \fBfpgetround()\fR function returns the current rounding mode. +.sp +.LP +The \fBfpsetround()\fR function sets the rounding mode and returns the previous +rounding mode. +.sp +.LP +The \fBfpgetmask()\fR function returns the current exception masks. +.sp +.LP +The \fBfpsetmask()\fR function sets the exception masks and returns the +previous setting. +.sp +.LP +The \fBfpgetsticky()\fR function returns the current exception sticky flags. +.sp +.LP +The \fBfpsetsticky()\fR function sets (clears) the exception sticky flags and +returns the previous setting. +.SH USAGE +.sp +.LP +The C programming language requires truncation (round to zero) for floating +point to integral conversions. The current rounding mode has no effect on these +conversions. +.sp +.LP +The sticky bit must be cleared to recover from the trap and proceed. If the +sticky bit is not cleared before the next trap occurs, a wrong exception type +may be signaled. +.sp +.LP +Individual bits may be examined using the constants defined in +\fB<ieeefp.h>\fR\&. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBisnand\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/fputc.3c b/usr/src/man/man3c/fputc.3c new file mode 100644 index 0000000000..03f1b8a563 --- /dev/null +++ b/usr/src/man/man3c/fputc.3c @@ -0,0 +1,300 @@ +'\" te +.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH fputc 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +fputc, putc, putc_unlocked, putchar, putchar_unlocked, putw \- put a byte on a +stream +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBint\fR \fBfputc\fR(\fBint\fR \fIc\fR, \fBFILE *\fR\fIstream\fR); +.fi + +.LP +.nf +\fBint\fR \fBputc\fR(\fBint\fR \fIc\fR, \fBFILE *\fR\fIstream\fR); +.fi + +.LP +.nf +\fBint\fR \fBputc_unlocked\fR(\fBint\fR \fIc\fR, \fBFILE *\fR\fIstream\fR); +.fi + +.LP +.nf +\fBint\fR \fBputchar\fR(\fBint\fR \fIc\fR); +.fi + +.LP +.nf +\fBint\fR \fBputchar_unlocked\fR(\fBint\fR \fIc\fR); +.fi + +.LP +.nf +\fBint\fR \fBputw\fR(\fBint\fR \fIw\fR, \fBFILE *\fR\fIstream\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBfputc()\fR function writes the byte specified by \fIc\fR (converted to +an \fBunsigned char\fR) to the output stream pointed to by \fIstream\fR, 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 byte is +appended to the output stream. +.sp +.LP +The \fBst_ctime\fR and \fBst_mtime\fR fields of the file will be marked for +update between the successful execution of \fBfputc()\fR and the next +successful completion of a call to \fBfflush\fR(3C) or \fBfclose\fR(3C) on the +same stream or a call to \fBexit\fR(3C) or \fBabort\fR(3C). +.sp +.LP +The \fBputc()\fR routine behaves like \fBfputc()\fR, except that it is +implemented as a macro. It runs faster than \fBfputc()\fR, but it takes up more +space per invocation and its name cannot be passed as an argument to a function +call. +.sp +.LP +The call \fBputchar(\fR\fIc\fR\fB)\fR is equivalent to \fBputc(\fR\fIc\fR\fB, +\fR\fIstdout\fR\fB).\fR The \fBputchar()\fR routine is implemented as a macro. +.sp +.LP +The \fBputc_unlocked()\fR and \fBputchar_unlocked()\fR routines are variants of +\fBputc()\fR and \fBputchar()\fR, respectively, that do not lock the stream. +It is the caller's responsibility to acquire the stream lock before calling +these routines and releasing the lock afterwards; see \fBflockfile\fR(3C) and +\fBstdio\fR(3C). These routines are implemented as macros. +.sp +.LP +The \fBputw()\fR function writes the word (that is, type \fBint\fR) \fIw\fR to +the output \fIstream\fR (at the position at which the file offset, if defined, +is pointing). The size of a word is the size of a type \fBint\fR and varies +from machine to machine. The \fBputw()\fR function neither assumes nor causes +special alignment in the file. +.sp +.LP +The \fBst_ctime\fR and \fBst_mtime\fR fields of the file will be marked for +update between the successful execution of \fBputw()\fR and the next successful +completion of a call to \fBfflush\fR(3C) or \fBfclose\fR(3C) on the same stream +or a call to \fBexit\fR(3C) or \fBabort\fR(3C). +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBfputc()\fR, \fBputc()\fR, \fBputc_unlocked()\fR, +\fBputchar()\fR, and \fBputchar_unlocked()\fR return the value that was +written. Otherwise, these functions return EOF, the error indicator for the +stream is set, and \fBerrno\fR is set to indicate the error. +.sp +.LP +Upon successful completion, \fBputw()\fR returns \fB0\fR. Otherwise, it returns +a non-zero value, sets the error indicator for the associated \fIstream\fR, and +sets \fBerrno\fR to indicate the error. +.sp +.LP +An unsuccessful completion will occur, for example, if the file associated with +\fIstream\fR is not open for writing or if the output file cannot grow. +.SH ERRORS +.sp +.LP +The \fBfputc()\fR, \fBputc()\fR, \fBputc_unlocked()\fR, \fBputchar()\fR, +\fBputchar_unlocked()\fR, and \fBputw()\fR functions will fail if either the +\fIstream\fR is unbuffered or the \fIstream\fR's buffer needs to be flushed, +and: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +The \fBO_NONBLOCK\fR flag is set for the file descriptor underlying +\fIstream\fR and the process would be delayed in the write operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The file descriptor underlying \fIstream\fR is not a valid file descriptor open +for writing. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFBIG\fR\fR +.ad +.RS 10n +.rt +An attempt was made to write to a file that exceeds the maximum file size or +the process' file size limit. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFBIG\fR\fR +.ad +.RS 10n +.rt +The file is a regular file and an attempt was made to write at or beyond the +offset maximum. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 10n +.rt +The write operation was terminated due to the receipt of a signal, and no data +was transferred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 10n +.rt +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, \fBTOSTOP\fR is +set, the process is neither ignoring nor blocking \fBSIGTTOU\fR and the process +group of the process is orphaned. This error may also be returned under +implementation-dependent conditions. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSPC\fR\fR +.ad +.RS 10n +.rt +There was no free space remaining on the device containing the file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPIPE\fR\fR +.ad +.RS 10n +.rt +An attempt is made to write to a pipe or \fBFIFO\fR that is not open for +reading by any process. A \fBSIGPIPE\fR signal will also be sent to the calling +thread. +.RE + +.sp +.LP +The \fBfputc()\fR, \fBputc()\fR, \fBputc_unlocked()\fR, \fBputchar()\fR, +\fBputchar_unlocked()\fR, and \fBputw()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient storage space is available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENXIO\fR\fR +.ad +.RS 10n +.rt +A request was made of a non-existent device, or the request was outside the +capabilities of the device. +.RE + +.SH USAGE +.sp +.LP +Functions exist for the \fBputc()\fR, \fBputc_unlocked()\fR, \fBputchar()\fR, +and \fBputchar_unlocked()\fR macros. To get the function form, the macro name +must be undefined (for example, \fB#undef putc\fR). +.sp +.LP +When the macro forms are used, \fBputc()\fR and \fBputc_unlocked()\fR evaluate +the \fIstream\fR argument more than once. In particular, \fBputc(\fR\fIc\fR\fB, +\fR\fI*f++\fR\fB);\fR does not work sensibly. The \fBfputc()\fR function +should be used instead when evaluating the \fIstream\fR argument has side +effects. +.sp +.LP +Because of possible differences in word length and byte ordering, files written +using \fBputw()\fR are implementation-dependent, and possibly cannot be read +using \fBgetw\fR(3C) by a different application or by the same application +running in a different environment. +.sp +.LP +The \fBputw()\fR function is inherently byte stream oriented and is not tenable +in the context of either multibyte character streams or wide-character streams. +Application programmers are encouraged to use one of the character-based output +functions instead. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityT{ +\fBfputc()\fR, \fBputc()\fR, \fBputc_unlocked()\fR, \fBputchar()\fR, and \fBputchar_unlocked()\fR are Standard. +T} +_ +MT-LevelSee \fBNOTES\fR below. +.TE + +.SH SEE ALSO +.sp +.LP +\fBgetrlimit\fR(2), \fBulimit\fR(2) \fBwrite\fR(2), \fBIntro\fR(3), +\fBabort\fR(3C), \fBexit\fR(3C), \fBfclose\fR(3C), \fBferror\fR(3C), +\fBfflush\fR(3C), \fBflockfile\fR(3C), \fBfopen\fR(3UCB), \fBprintf\fR(3C), +\fBputc\fR(3C), \fBputs\fR(3C), \fBsetbuf\fR(3C), \fBstdio\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +The \fBfputc()\fR, \fBputc()\fR, \fBputchar()\fR, and \fBputw()\fR routines are +MT-Safe in multithreaded applications. The \fBputc_unlocked()\fR and +\fBputchar_unlocked()\fR routines are unsafe in multithreaded applications. diff --git a/usr/src/man/man3c/fputwc.3c b/usr/src/man/man3c/fputwc.3c new file mode 100644 index 0000000000..1ddeb4395d --- /dev/null +++ b/usr/src/man/man3c/fputwc.3c @@ -0,0 +1,233 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH fputwc 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +fputwc, putwc, putwchar \- put wide-character code on a stream +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> +#include <wchar.h> + +\fBwint_t\fR \fBfputwc\fR(\fBwchar_t\fR \fIwc\fR, \fBFILE*\fR\fIstream\fR); +.fi + +.LP +.nf +\fBwint_t\fR \fBputwc\fR(\fBwchar_t\fR \fIwc\fR, \fBFILE*\fR\fIstream\fR); +.fi + +.LP +.nf +#include <wchar.h> + +\fBwint_t\fR \fBputwchar\fR(\fBwchar_t\fR \fIwc\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBfputwc()\fR function writes the character corresponding to the +wide-character code \fIwc\fR to the output stream pointed to by \fIstream\fR, +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. +.sp +.LP +The \fBst_ctime\fR and \fBst_mtime\fR fields of the file will be marked for +update between the successful execution of \fBfputwc()\fR and the next +successful completion of a call to \fBfflush\fR(3C) or \fBfclose\fR(3C) on the +same stream or a call to \fBexit\fR(2) or \fBabort\fR(3C). +.sp +.LP +The \fBputwc()\fR function is equivalent to \fBfputwc()\fR, except that it is +implemented as a macro. +.sp +.LP +The call \fBputwchar(\fR\fIwc\fR\fB)\fR is equivalent to +\fBputwc(\fR\fIwc,\fR\fB stdout)\fR\fI\&.\fR The \fBputwchar()\fR routine is +implemented as a macro. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBfputwc()\fR, \fBputwc()\fR, and \fBputwchar()\fR +return \fIwc\fR. Otherwise, they return \fBWEOF\fR, the error indicator for the +stream is set, and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBfputwc()\fR, \fBputwc()\fR, and \fBputwchar()\fR functions will fail if +either the stream is unbuffered or data in the \fIstream\fR's buffer needs to +be written, and: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +The \fBO_NONBLOCK\fR flag is set for the file descriptor underlying +\fIstream\fR and the process would be delayed in the write operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The file descriptor underlying \fIstream\fR is not a valid file descriptor open +for writing. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFBIG\fR\fR +.ad +.RS 10n +.rt +An attempt was made to write to a file that exceeds the maximum file size or +the process's file size limit; or the file is a regular file and an attempt was +made to write at or beyond the offset maximum associated with the corresponding +stream. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 10n +.rt +The write operation was terminated due to the receipt of a signal, and no data +was transferred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 10n +.rt +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, \fBTOSTOP\fR is +set, the process is neither ignoring nor blocking \fBSIGTTOU\fR, and the +process group of the process is orphaned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSPC\fR\fR +.ad +.RS 10n +.rt +There was no free space remaining on the device containing the file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPIPE\fR\fR +.ad +.RS 10n +.rt +An attempt is made to write to a pipe or \fBFIFO\fR that is not open for +reading by any process. A \fBSIGPIPE\fR signal will also be sent to the calling +thread. +.RE + +.sp +.LP +The \fBfputwc()\fR, \fBputwc()\fR, and \fBputwchar()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient storage space is available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENXIO\fR\fR +.ad +.RS 10n +.rt +A request was made of a non-existent device, or the request was outside the +capabilities of the device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEILSEQ\fR\fR +.ad +.RS 10n +.rt +The wide-character code \fIwc\fR does not correspond to a valid character. +.RE + +.SH USAGE +.sp +.LP +Functions exist for the \fBputwc()\fR and \fBputwchar()\fR macros. To get the +function form, the macro name must be undefined (for example, \fB#undef +putc\fR). +.sp +.LP +When the macro form is used, \fBputwc()\fR evaluates the \fIstream\fR argument +more than once. In particular, \fBputwc(\fR\fIwc\fR\fB, \fR\fI*f++\fR\fB)\fR +does not work sensibly. The \fBfputwc()\fR function should be used instead +when evaluating the \fIstream\fR argument has side effects. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBexit\fR(2), \fBulimit\fR(2), \fBabort\fR(3C), \fBfclose\fR(3C), +\fBferror\fR(3C), \fBfflush\fR(3C), \fBfopen\fR(3C), \fBsetbuf\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/fputws.3c b/usr/src/man/man3c/fputws.3c new file mode 100644 index 0000000000..a0f2668776 --- /dev/null +++ b/usr/src/man/man3c/fputws.3c @@ -0,0 +1,68 @@ +'\" te +.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH fputws 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +fputws \- put wide character string on a stream +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> +#include <wchar.h> + +\fBint\fR \fBfputws\fR(\fBconst wchar_t *restrict\fR \fIs\fR, \fBFILE *restrict\fR \fIstream\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBfputws()\fR function writes a character string corresponding to the +(null-terminated) wide character string pointed to by \fIws\fR to the stream +pointed to by \fIstream\fR. No character corresponding to the terminating null +wide-character code is written, nor is a \fBNEWLINE\fR character appended. +.sp +.LP +The \fBst_ctime\fR and \fBst_mtime\fR fields of the file will be marked for +update between the successful execution of \fBfputws()\fR and the next +successful completion of a call to \fBfflush\fR(3C) or \fBfclose\fR(3C) on the +same stream or a call to \fBexit\fR(2) or \fBabort\fR(3C). +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBfputws()\fR returns a non-negative value. +Otherwise, it returns \fB\(mi1\fR, sets an error indicator for the stream, and +sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +Refer to \fBfputwc\fR(3C). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBexit\fR(2), \fBabort\fR(3C), \fBfclose\fR(3C), \fBfflush\fR(3C), +\fBfopen\fR(3C), \fBfputwc\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/fread.3c b/usr/src/man/man3c/fread.3c new file mode 100644 index 0000000000..8e16e43dee --- /dev/null +++ b/usr/src/man/man3c/fread.3c @@ -0,0 +1,114 @@ +'\" te +.\" Copyright (c) 1997, The Open Group. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH fread 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +fread \- binary input +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBsize_t\fR \fBfread\fR(\fBvoid *\fR\fIptr\fR, \fBsize_t\fR \fIsize\fR, \fBsize_t\fR \fInitems\fR, \fBFILE *\fR\fIstream\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBfread()\fR function reads into the array pointed to by \fIptr\fR up to +\fInitems\fR elements whose size is specified by \fIsize\fR in bytes, from the +stream pointed to by \fIstream\fR. For each object, \fIsize\fR calls are made +to the \fBfgetc\fR(3C) function and the results stored, in the order read, in +an array of \fBunsigned char\fR exactly overlaying the object. The +file-position indicator for the stream (if defined) is 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. +.sp +.LP +The \fBfread()\fR function may mark the \fBst_atime\fR field of the file +associated with \fIstream\fR for update. The \fBst_atime\fR field will be +marked for update by the first successful execution of \fBfgetc\fR(3C), +\fBfgets\fR(3C), \fBfgetwc\fR(3C), \fBfgetws\fR(3C), \fBfread()\fR, +\fBfscanf\fR(3C), \fBgetc\fR(3C), \fBgetchar\fR(3C), \fBgets\fR(3C), or +\fBscanf\fR(3C) using \fIstream\fR that returns data not supplied by a prior +call to \fBungetc\fR(3C) or \fBungetwc\fR(3C). +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBfread()\fR returns the number of elements +successfully read, which is less than \fInitems\fR only if a read error or +end-of-file is encountered. If \fIsize\fR or \fInitems\fR is 0, \fBfread()\fR +returns 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 is set and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +Refer to \fBfgetc\fR(3C). +.SH EXAMPLES +.LP +\fBExample 1 \fRReading from a Stream +.sp +.LP +The following example reads a single element from the \fIfp\fR stream into the +array pointed to by \fIbuf\fR. + +.sp +.in +2 +.nf +#include <stdio.h> +\&... +size_t bytes_read; +char buf[100]; +FILE *fp; +\&... +bytes_read = fread(buf, sizeof(buf), 1, fp); +\&... +.fi +.in -2 + +.SH USAGE +.sp +.LP +The \fBferror()\fR or \fBfeof()\fR functions must be used to distinguish +between an error condition and end-of-file condition. See \fBferror\fR(3C). +.sp +.LP +Because of possible differences in element length and byte ordering, files +written using \fBfwrite\fR(3C) are application-dependent, and possibly cannot +be read using \fBfread()\fR by a different application or by the same +application on a different processor. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBread\fR(2), \fBfclose\fR(3C), \fBferror\fR(3C), \fBfopen\fR(3C), +\fBgetc\fR(3C), \fBgets\fR(3C), \fBprintf\fR(3C), \fBputc\fR(3C), +\fBputs\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/freopen.3c b/usr/src/man/man3c/freopen.3c new file mode 100644 index 0000000000..c1ec395061 --- /dev/null +++ b/usr/src/man/man3c/freopen.3c @@ -0,0 +1,364 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH freopen 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +freopen \- open a stream +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBFILE *\fR\fBfreopen\fR(\fBconst char *\fR\fIfilename\fR, \fBconst char *\fR\fImode\fR, \fBFILE *\fR\fIstream\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBfreopen()\fR function first attempts to flush the stream and close any +file descriptor associated with \fIstream\fR. Failure to flush or close the +file successfully is ignored. The error and end-of-file indicators for the +stream are cleared. +.sp +.LP +The \fBfreopen()\fR function opens the file whose pathname is the string +pointed to by \fIfilename\fR and associates the stream pointed to by +\fIstream\fR with it. The \fImode\fR argument is used just as in +\fBfopen\fR(3C). +.sp +.LP +If \fIfilename\fR is a null pointer and the application comforms to SUSv3 (see +\fBstandards\fR(5)), the \fBfreopen()\fR function attempts to change the mode +of the stream to that specified by \fImode\fR, as though the name of the file +currently associated with the \fIstream\fR had been used. The following +changes of mode are permitted, depending upon the access mode of the file +descriptor underlying the stream: +.RS +4 +.TP +.ie t \(bu +.el o +When \fB+\fR is specified, the file descriptor mode must be \fBO_RDWR\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +When \fBr\fR is specified, the file descriptor mode must be \fBO_RDONLY\fR or +\fBO_RDWR\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +When \fBa\fR or \fBw\fR is specified, the file descriptor mode must be +\fBO_WRONLY\fR or \fBO_RDWR\fR. +.RE +.sp +.LP +If the filename is a null pointer and the application does not comform to +SUSv3, \fBfreopen()\fR returns a null pointer. +.sp +.LP +The original stream is closed regardless of whether the subsequent open +succeeds. +.sp +.LP +After a successful call to the \fBfreopen()\fR function, the orientation of the +stream is cleared, the encoding rule is cleared, and the associated +\fBmbstate_t\fR object is set to describe an initial conversion state. +.sp +.LP +The largest value that can be represented correctly in an object of type +\fBoff_t\fR will be established as the offset maximum in the open file +description. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBfreopen()\fR returns the value of \fIstream\fR. +Otherwise, a null pointer is returned and \fBerrno\fR is set to indicate the +error. +.SH ERRORS +.sp +.LP +The \fBfreopen()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 16n +.rt +Search permission is denied on a component of the path prefix, or the file +exists and the permissions specified by \fImode\fR are denied, or the file does +not exist and write permission is denied for the parent directory of the file +to be created. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 16n +.rt +The application comforms to SUSv3, the \fIfilename\fR argument is a null +pointer, and either the underlying file descriptor is not valid or the mode +specified when the underlying file descriptor was opened does not support the +file access modes requested by the \fImode\fR argument. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 16n +.rt +The application does not comform to SUSv3 and the \fIfilename\fR argument is a +null pointer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 16n +.rt +A signal was caught during \fBfreopen()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEISDIR\fR\fR +.ad +.RS 16n +.rt +The named file is a directory and \fImode\fR requires write access. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBELOOP\fR\fR +.ad +.RS 16n +.rt +Too many symbolic links were encountered in resolving \fIpath\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 16n +.rt +There are {\fBOPEN_MAX\fR} file descriptors currently open in the calling +process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +The length of the \fIfilename\fR exceeds {\fIPATH_MAX\fR} or a pathname +component is longer than {\fINAME_MAX\fR}. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENFILE\fR\fR +.ad +.RS 16n +.rt +The maximum allowable number of files is currently open in the system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 16n +.rt +A component of \fIfilename\fR does not name an existing file or \fIfilename\fR +is an empty string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSPC\fR\fR +.ad +.RS 16n +.rt +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. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTDIR\fR\fR +.ad +.RS 16n +.rt +A component of the path prefix is not a directory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENXIO\fR\fR +.ad +.RS 16n +.rt +The named file is a character special or block special file, and the device +associated with this special file does not exist. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOVERFLOW\fR\fR +.ad +.RS 16n +.rt +The current value of the file position cannot be represented correctly in an +object of type \fBoff_t\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEROFS\fR\fR +.ad +.RS 16n +.rt +The named file resides on a read-only file system and \fImode\fR requires write +access. +.RE + +.sp +.LP +The \fBfreopen()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 16n +.rt +The value of the \fImode\fR argument is not valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +Pathname resolution of a symbolic link produced an intermediate result whose +length exceeds {\fIPATH_MAX\fR}. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 16n +.rt +Insufficient storage space is available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENXIO\fR\fR +.ad +.RS 16n +.rt +A request was made of a non-existent device, or the request was outside the +capabilities of the device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBETXTBSY\fR\fR +.ad +.RS 16n +.rt +The file is a pure procedure (shared text) file that is being executed and +\fImode\fR requires write access. +.RE + +.SH USAGE +.sp +.LP +The \fBfreopen()\fR function is typically used to attach the preopened +\fIstreams\fR associated with \fBstdin\fR, \fBstdout\fR and \fBstderr\fR to +other files. By default \fBstderr\fR is unbuffered, but the use of +\fBfreopen()\fR will cause it to become buffered or line-buffered. +.sp +.LP +The \fBfreopen()\fR function has a transitional interface for 64-bit file +offsets. See \fBlf64\fR(5). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfclose\fR(3C), \fBfdopen\fR(3C), \fBfopen\fR(3C), \fBstdio\fR(3C), +\fBattributes\fR(5), \fBlf64\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/fseek.3c b/usr/src/man/man3c/fseek.3c new file mode 100644 index 0000000000..41007501b1 --- /dev/null +++ b/usr/src/man/man3c/fseek.3c @@ -0,0 +1,304 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 20023, Sun Microsystems, Inc. All Rights Reserved. Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH fseek 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +fseek, fseeko \- reposition a file-position indicator in a stream +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBint\fR \fBfseek\fR(\fBFILE *\fR\fIstream\fR, \fBlong\fR \fIoffset\fR, \fBint\fR \fIwhence\fR); +.fi + +.LP +.nf +\fBint\fR \fBfseeko\fR(\fBFILE *\fR\fIstream\fR, \fBoff_t\fR \fIoffset\fR, \fBint\fR \fIwhence\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBfseek()\fR function sets the file-position indicator for the stream +pointed to by \fIstream\fR. The \fBfseeko()\fR function is identical to +\fBfseek()\fR except for the type of \fIoffset\fR. +.sp +.LP +The new position, measured in bytes from the beginning of the file, is obtained +by adding \fIoffset\fR to the position specified by \fIwhence\fR, whose values +are defined in <\fBstdio.h\fR> as follows: +.sp +.ne 2 +.mk +.na +\fB\fBSEEK_SET\fR\fR +.ad +.RS 12n +.rt +Set position equal to \fIoffset\fR bytes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSEEK_CUR\fR\fR +.ad +.RS 12n +.rt +Set position to current location plus \fIoffset\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSEEK_END\fR\fR +.ad +.RS 12n +.rt +Set position to \fBEOF\fR plus \fIoffset\fR. +.RE + +.sp +.LP +If the stream is to be used with wide character input/output functions, +\fIoffset\fR must either be 0 or a value returned by an earlier call to +\fBftell\fR(3C) on the same stream and \fIwhence\fR must be \fBSEEK_SET\fR. +.sp +.LP +A successful call to \fBfseek()\fR clears the end-of-file indicator for the +stream and undoes any effects of \fBungetc\fR(3C) and \fBungetwc\fR(3C) on the +same stream. After an \fBfseek()\fR call, the next operation on an update +stream may be either input or output. +.sp +.LP +If the most recent operation, other than \fBftell\fR(3C), on a given stream is +\fBfflush\fR(3C), the file offset in the underlying open file description will +be adjusted to reflect the location specified by \fBfseek()\fR. +.sp +.LP +The \fBfseek()\fR function allows 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 will return bytes with the value 0 until +data is actually written into the gap. +.sp +.LP +The value of the file offset returned by \fBfseek()\fR on devices which are +incapable of seeking is undefined. +.sp +.LP +If the stream is writable and buffered data had not been written to the +underlying file, \fBfseek()\fR will cause the unwritten data to be written to +the file and mark the \fBst_ctime\fR and \fBst_mtime\fR fields of the file for +update. +.SH RETURN VALUES +.sp +.LP +The \fBfseek()\fR and \fBfseeko()\fR functions return \fB0\fR on success; +otherwise, they returned \fB\(mi1\fR and set \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBfseek()\fR and \fBfseeko()\fR functions will fail if, either the +\fIstream\fR is unbuffered or the \fIstream\fR's buffer needed to be flushed, +and the call to \fBfseek()\fR or \fBfseeko()\fR causes an underlying +\fBlseek\fR(2) or \fBwrite\fR(2) to be invoked: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +The \fBO_NONBLOCK\fR flag is set for the file descriptor and the process would +be delayed in the write operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +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. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFBIG\fR\fR +.ad +.RS 10n +.rt +An attempt was made to write a file that exceeds the maximum file size or the +process's file size limit, or the file is a regular file and an attempt was +made to write at or beyond the offset maximum associated with the corresponding +stream. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 10n +.rt +The write operation was terminated due to the receipt of a signal, and no data +was transferred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIwhence\fR argument is invalid. The resulting file-position indicator +would be set to a negative value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 10n +.rt +A physical I/O error has occurred; or the process is a member of a background +process group attempting to perform a \fBwrite\fR(2) operation to its +controlling terminal, \fBTOSTOP\fR is set, the process is neither ignoring nor +blocking \fBSIGTTOU\fR, and the process group of the process is orphaned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSPC\fR\fR +.ad +.RS 10n +.rt +There was no free space remaining on the device containing the file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENXIO\fR\fR +.ad +.RS 10n +.rt +A request was made of a non-existent device, or the request was outside the +capabilities of the device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPIPE\fR\fR +.ad +.RS 10n +.rt +The file descriptor underlying \fIstream\fR is associated with a pipe or FIFO. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPIPE\fR\fR +.ad +.RS 10n +.rt +An attempt was made to write to a pipe or \fBFIFO\fR that is not open for +reading by any process. A \fBSIGPIPE\fR signal will also be sent to the calling +thread. +.RE + +.sp +.LP +The \fBfseek()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEOVERFLOW\fR\fR +.ad +.RS 13n +.rt +The resulting file offset would be a value which cannot be represented +correctly in an object of type \fBlong\fR. +.RE + +.sp +.LP +The \fBfseeko()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEOVERFLOW\fR\fR +.ad +.RS 13n +.rt +The resulting file offset would be a value which cannot be represented +correctly in an object of type \fBoff_t\fR. +.RE + +.SH USAGE +.sp +.LP +Although on the UNIX system an offset returned by \fBftell()\fR or +\fBftello()\fR (see \fBftell\fR(3C)) is measured in bytes, and it is +permissible to seek to positions relative to that offset, portability to +non-UNIX systems requires that an offset be used by \fBfseek()\fR directly. +Arithmetic may not meaningfully be performed on such an offset, which is not +necessarily measured in bytes. +.sp +.LP +The \fBfseeko()\fR function has a transitional interface for 64-bit file +offsets. See \fBlf64\fR(5). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgetrlimit\fR(2), \fBulimit\fR(2), \fBfopen\fR(3UCB), \fBftell\fR(3C), +\fBrewind\fR(3C), \fBungetc\fR(3C), \fBungetwc\fR(3C), \fBattributes\fR(5), +\fBlf64\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/fsetpos.3c b/usr/src/man/man3c/fsetpos.3c new file mode 100644 index 0000000000..8c8c4723d3 --- /dev/null +++ b/usr/src/man/man3c/fsetpos.3c @@ -0,0 +1,95 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH fsetpos 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +fsetpos \- reposition a file pointer in a stream +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBint\fR \fBfsetpos\fR(\fBFILE *\fR\fIstream\fR, \fBconst fpos_t *\fR\fIpos\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBfsetpos()\fR function sets the file position indicator for the stream +pointed to by \fIstream\fR according to the value of the object pointed to by +\fIpos\fR, which must be a value obtained from an earlier call to +\fBfgetpos\fR(3C) on the same stream. +.sp +.LP +A successful call to \fBfsetpos()\fR function clears the end-of-file indicator +for the stream and undoes any effects of \fBungetc\fR(3C) on the same stream. +After an \fBfsetpos()\fR call, the next operation on an update stream may be +either input or output. +.SH RETURN VALUES +.sp +.LP +The \fBfsetpos()\fR function returns \fB0\fR if it succeeds; otherwise it +returns a non-zero value and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBfsetpos()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The file descriptor underlying \fIstream\fR is not valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBESPIPE\fR\fR +.ad +.RS 10n +.rt +The file descriptor underlying \fIstream\fR is associated with a pipe, a FIFO, +or a socket. +.RE + +.SH USAGE +.sp +.LP +The \fBfsetpos()\fR function has a transitional interface for 64-bit file +offsets. See \fBlf64\fR(5). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlseek\fR(2), \fBfgetpos\fR(3C), \fBfopen\fR(3C), \fBfseek\fR(3C), +\fBftell\fR(3C), \fBrewind\fR(3C), \fBungetc\fR(3C), \fBattributes\fR(5), +\fBlf64\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/fsync.3c b/usr/src/man/man3c/fsync.3c new file mode 100644 index 0000000000..695e4e1b27 --- /dev/null +++ b/usr/src/man/man3c/fsync.3c @@ -0,0 +1,144 @@ +'\" te +.\" Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH fsync 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +fsync \- synchronize changes to a file +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> + +\fBint\fR \fBfsync\fR(\fBint\fR \fIfildes\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBfsync()\fR function moves all modified data and attributes of the file +descriptor \fIfildes\fR to a storage device. When \fBfsync()\fR returns, all +in-memory modified copies of buffers associated with \fIfildes\fR have been +written to the physical medium. The \fBfsync()\fR function is different from +\fBsync()\fR, which schedules disk I/O for all files but returns before the +I/O completes. The \fBfsync()\fR function forces all outstanding data +operations to synchronized file integrity completion (see \fBfcntl.h\fR(3HEAD) +definition of \fBO_SYNC\fR.) +.sp +.LP +The \fBfsync()\fR function forces all currently queued I/O operations +associated with the file indicated by the file descriptor \fIfildes\fR to the +synchronized I/O completion state. All I/O operations are completed as defined +for synchronized I/O file integrity completion. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is +returned and \fBerrno\fR is set to indicate the error. If the \fBfsync()\fR +function fails, outstanding I/O operations are not guaranteed to have been +completed. +.SH ERRORS +.sp +.LP +The \fBfsync()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 13n +.rt +The \fIfildes\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 13n +.rt +A signal was caught during execution of the \fBfsync()\fR function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 13n +.rt +An I/O error occurred while reading from or writing to the file system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSPC\fR\fR +.ad +.RS 13n +.rt +There was no free space remaining on the device containing the file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBETIMEDOUT\fR\fR +.ad +.RS 13n +.rt +Remote connection timed out. This occurs when the file is on an \fBNFS\fR file +system mounted with the \fIsoft\fR option. See \fBmount_nfs\fR(1M). +.RE + +.sp +.LP +In the event that any of the queued I/O operations fail, \fBfsync()\fR returns +the error conditions defined for \fBread\fR(2) and \fBwrite\fR(2). +.SH USAGE +.sp +.LP +The \fBfsync()\fR function should be used by applications that require that a +file be in a known state. For example, an application that contains a simple +transaction facility might use \fBfsync()\fR to ensure that all changes to a +file or files caused by a given transaction were recorded on a storage medium. +.sp +.LP +The manner in which the data reach the physical medium depends on both +implementation and hardware. The \fBfsync()\fR function returns when notified +by the device driver that the write has taken place. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelAsync-Signal-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBmount_nfs\fR(1M), \fBread\fR(2), \fBsync\fR(2), \fBwrite\fR(2), +\fBfcntl.h\fR(3HEAD), \fBfdatasync\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/ftell.3c b/usr/src/man/man3c/ftell.3c new file mode 100644 index 0000000000..060539fd75 --- /dev/null +++ b/usr/src/man/man3c/ftell.3c @@ -0,0 +1,124 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ftell 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +ftell, ftello \- return a file offset in a stream +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBlong\fR \fBftell\fR(\fBFILE *\fR\fIstream\fR); +.fi + +.LP +.nf +\fBoff_t\fR \fBftello\fR(\fBFILE *\fR\fIstream\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBftell()\fR function obtains the current value of the file-position +indicator for the stream pointed to by \fIstream\fR. The \fBftello()\fR +function is identical to \fBftell()\fR except for the return type. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBftell()\fR and \fBftello()\fR functions +return the current value of the file-position indicator for the stream measured +in bytes from the beginning of the file. Otherwise, they return \fB\(mi1\fR and +sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBftell()\fR and \fBftello()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The file descriptor underlying \fIstream\fR is not an open file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBESPIPE\fR\fR +.ad +.RS 10n +.rt +The file descriptor underlying \fIstream\fR is associated with a pipe, a FIFO, +or a socket. +.RE + +.sp +.LP +The \fBftell()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEOVERFLOW\fR\fR +.ad +.RS 13n +.rt +The current file offset cannot be represented correctly in an object of type +\fBlong\fR. +.RE + +.sp +.LP +The \fBftello()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEOVERFLOW\fR\fR +.ad +.RS 13n +.rt +The current file offset cannot be represented correctly in an object of type +\fBoff_t\fR. +.RE + +.SH USAGE +.sp +.LP +The \fBftello()\fR function has a transitional interface for 64-bit file +offsets. See \fBlf64\fR(5). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlseek\fR(2), \fBfopen\fR(3C), \fBfseek\fR(3C), \fBattributes\fR(5), , +\fBstandards\fR(5), \fBlf64\fR(5) diff --git a/usr/src/man/man3c/ftime.3c b/usr/src/man/man3c/ftime.3c new file mode 100644 index 0000000000..fd5ef1f7f7 --- /dev/null +++ b/usr/src/man/man3c/ftime.3c @@ -0,0 +1,91 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ftime 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +ftime \- get date and time +.SH SYNOPSIS +.LP +.nf +#include <sys/timeb.h> + +\fBint\fR \fBftime\fR(\fBstruct timeb *\fR\fItp\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBftime()\fR function sets the \fBtime\fR and \fBmillitm\fR members of the +\fBtimeb\fR structure pointed to by \fItp\fR. The structure is defined in +<\fBsys/timeb.h\fR> and contains the following members: +.sp +.in +2 +.nf +time_t time; +unsigned short millitm; +short timezone; +short dstflag; +.fi +.in -2 + +.sp +.LP +The \fBtime\fR and \fBmillitm\fR members contain the seconds and milliseconds +portions, respectively, of the current time in seconds since 00:00:00 UTC +(Coordinated Universal Time), January 1, 1970. +.sp +.LP +The \fBtimezone\fR member contains the local time zone. The \fBdstflag\fR +member contains a flag that, if non-zero, indicates that Daylight Saving time +applies locally during the appropriate part of the year. +.sp +.LP +The contents of the \fBtimezone\fR and \fBdstflag\fR members of \fItp\fR after +a call to \fBftime()\fR are unspecified. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBftime()\fR function returns \fB0\fR. +Otherwise \fB\(mi1\fR is returned. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH USAGE +.sp +.LP +For portability to implementations conforming to earlier versions of this +document, \fBtime\fR(2) is preferred over this function. +.sp +.LP +The millisecond value usually has a granularity greater than one due to the +resolution of the system clock. Depending on any granularity (particularly a +granularity of one) renders code non-portable. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityStandard +.TE + +.SH SEE ALSO +.sp +.LP +\fBdate\fR(1), \fBtime\fR(2), \fBctime\fR(3C), \fBgettimeofday\fR(3C), +\fBtimezone\fR(4), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/ftok.3c b/usr/src/man/man3c/ftok.3c new file mode 100644 index 0000000000..f466f86d4d --- /dev/null +++ b/usr/src/man/man3c/ftok.3c @@ -0,0 +1,169 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ftok 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +ftok \- generate an IPC key +.SH SYNOPSIS +.LP +.nf +#include <sys/ipc.h> + +\fBkey_t\fR \fBftok\fR(\fBconst char *\fR\fIpath\fR, \fBint\fR \fIid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBftok()\fR function returns a key based on \fIpath\fR and \fIid\fR that +is usable in subsequent calls to \fBmsgget\fR(2), \fBsemget\fR(2) and +\fBshmget\fR(2). The \fIpath\fR argument must be the pathname of an existing +file that the process is able to \fBstat\fR(2). +.sp +.LP +The \fBftok()\fR function will return the same key value for all paths that +name the same file, when called with the same \fIid\fR value, and will return +different key values when called with different \fIid\fR values. +.sp +.LP +If the file named by \fIpath\fR is removed while still referred to by a key, a +call to \fBftok()\fR with the same \fIpath\fR and \fIid\fR returns an error. If +the same file is recreated, then a call to \fBftok()\fR with the same +\fIpath\fR and \fIid\fR is likely to return a different key. +.sp +.LP +Only the low order 8-bits of \fBid\fR are significant. The behavior of +\fBftok()\fR is unspecified if these bits are 0. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBftok()\fR returns a key. Otherwise, +\fBftok()\fR returns \fB(key_t)\(mi1\fR and sets \fBerrno\fR to indicate the +error. +.SH ERRORS +.sp +.LP +The \fBftok()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 16n +.rt +Search permission is denied for a component of the path prefix. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBELOOP\fR\fR +.ad +.RS 16n +.rt +Too many symbolic links were encountered in resolving \fIpath\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +The length of the \fIpath\fR argument exceeds \fB{\fR\fBPATH\fR\fB_MAX} \fR or +a pathname component is longer than \fB{NAME_MAX}\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 16n +.rt +A component of \fIpath\fR does not name an existing file or \fIpath\fR is an +empty string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTDIR\fR\fR +.ad +.RS 16n +.rt +A component of the path prefix is not a directory. +.RE + +.sp +.LP +The \fBftok()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +Pathname resolution of a symbolic link produced an intermediate result whose +length exceeds \fB{PATH_MAX} \fR. +.RE + +.SH USAGE +.sp +.LP +For maximum portability, \fIid\fR should be a single-byte character. +.sp +.LP +Another way to compose keys is to include the project ID in the most +significant byte and to use the remaining portion as a sequence number. There +are many other ways to form keys, but it is necessary for each system to define +standards for forming them. If some standard is not adhered to, it will be +possible for unrelated processes to unintentionally interfere with each other's +operation. It is still possible to interfere intentionally. Therefore, it is +strongly suggested that the most significant byte of a key in some sense refer +to a project so that keys do not conflict across a given system. +.SH NOTES +.sp +.LP +Since the \fBftok()\fR function returns a value based on the \fIid\fR given and +the file serial number of the file named by \fIpath\fR in a type that is no +longer large enough to hold all file serial numbers, it may return the same key +for paths naming different files on large filesystems. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBmsgget\fR(2), \fBsemget\fR(2), \fBshmget\fR(2), \fBstat\fR(2), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/ftw.3c b/usr/src/man/man3c/ftw.3c new file mode 100644 index 0000000000..224d1aee47 --- /dev/null +++ b/usr/src/man/man3c/ftw.3c @@ -0,0 +1,599 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ftw 3C "30 Jan 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +ftw, nftw \- walk a file tree +.SH SYNOPSIS +.LP +.nf +#include <ftw.h> + +\fBint\fR \fBftw\fR(\fBconst char *\fR\fIpath\fR, \fBint\fR (*\fIfn\fR) (\fBconst char *\fR, + \fBconst struct stat *\fR, \fBint\fR), \fBint\fR \fIdepth\fR); +.fi + +.LP +.nf +\fBint\fR \fBnftw\fR(\fBconst char *\fR\fIpath\fR, \fBint (*\fR\fIfn\fR) (\fBconst char *\fR, + \fBconst struct stat *\fR, \fBint\fR, \fBstruct FTW *\fR), \fBint\fR \fIdepth\fR, + \fBint\fR \fIflags\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBftw()\fR function recursively descends the directory hierarchy rooted in +\fIpath\fR. For each object in the hierarchy, \fBftw()\fR calls the +user-defined function \fIfn\fR, passing it a pointer to a null-terminated +character string containing the name of the object, a pointer to a \fBstat\fR +structure (see \fBstat\fR(2)) containing information about the object, and an +integer. Possible values of the integer, defined in the <\fBftw.h\fR> header, +are: +.sp +.ne 2 +.mk +.na +\fB\fBFTW_F\fR\fR +.ad +.RS 11n +.rt +The object is a file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFTW_D\fR\fR +.ad +.RS 11n +.rt +The object is a directory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFTW_DNR\fR\fR +.ad +.RS 11n +.rt +The object is a directory that cannot be read. Descendants of the directory are +not processed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFTW_NS\fR\fR +.ad +.RS 11n +.rt +The \fBstat()\fR function failed on the object because of lack of appropriate +permission or the object is a symbolic link that points to a non-existent file. +The \fBstat\fR buffer passed to \fIfn\fR is undefined. +.RE + +.sp +.LP +The \fBftw()\fR function visits a directory before visiting any of its +descendants. +.sp +.LP +The tree traversal continues until the tree is exhausted, an invocation of +\fIfn\fR returns a non-zero value, or some error is detected within \fBftw()\fR +(such as an I/O error). If the tree is exhausted, \fBftw()\fR returns \fB0\fR. +If \fIfn\fR returns a non-zero value, \fBftw()\fR stops its tree traversal and +returns whatever value was returned by \fIfn\fR. +.sp +.LP +The \fBnftw()\fR function is similar to \fBftw()\fR except that it takes the +additional argument \fIflags\fR, which is a bitwise-inclusive OR of zero or +more of the following flags: +.sp +.ne 2 +.mk +.na +\fB\fBFTW_CHDIR\fR\fR +.ad +.RS 13n +.rt +If set, \fBnftw()\fR changes the current working directory to each directory as +it reports files in that directory. If clear, \fBnftw()\fR does not change the +current working directory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFTW_DEPTH\fR\fR +.ad +.RS 13n +.rt +If set, \fBnftw()\fR reports all files in a directory before reporting the +directory itself. If clear, \fBnftw()\fR reports any directory before reporting +the files in that directory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFTW_MOUNT\fR\fR +.ad +.RS 13n +.rt +If set, \fBnftw()\fR reports only files in the same file system as path. If +clear, \fBnftw()\fR reports all files encountered during the walk. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFTW_PHYS\fR\fR +.ad +.RS 13n +.rt +If set, \fBnftw()\fR performs a physical walk and does not follow symbolic +links. +.RE + +.sp +.LP +If \fBFTW_PHYS\fR is clear and \fBFTW_DEPTH\fR is set, \fBnftw()\fR follows +links instead of reporting them, but does not report any directory that would +be a descendant of itself. If \fBFTW_PHYS\fR is clear and \fBFTW_DEPTH\fR is +clear, \fBnftw()\fR follows links instead of reporting them, but does not +report the contents of any directory that would be a descendant of itself. +.sp +.LP +At each file it encounters, \fBnftw()\fR calls the user-supplied function +\fIfn\fR with four arguments: +.RS +4 +.TP +.ie t \(bu +.el o +The first argument is the pathname of the object. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The second argument is a pointer to the \fBstat\fR buffer containing +information on the object. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The third argument is an integer giving additional information. Its value is +one of the following: +.RS + +.sp +.ne 2 +.mk +.na +\fB\fBFTW_F\fR\fR +.ad +.RS 11n +.rt +The object is a file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFTW_D\fR\fR +.ad +.RS 11n +.rt +The object is a directory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFTW_DP\fR\fR +.ad +.RS 11n +.rt +The object is a directory and subdirectories have been visited. (This condition +only occurs if the FTW_DEPTH flag is included in flags.) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFTW_SL\fR\fR +.ad +.RS 11n +.rt +The object is a symbolic link. (This condition only occurs if the FTW_PHYS flag +is included in flags.) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFTW_SLN\fR\fR +.ad +.RS 11n +.rt +The object is a symbolic link that points to a non-existent file. (This +condition only occurs if the FTW_PHYS flag is not included in flags.) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFTW_DNR\fR\fR +.ad +.RS 11n +.rt +The object is a directory that cannot be read. The user-defined function +\fIfn\fR will not be called for any of its descendants. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFTW_NS\fR\fR +.ad +.RS 11n +.rt +The \fBstat()\fR function failed on the object because of lack of appropriate +permission. The stat buffer passed to \fIfn\fR is undefined. Failure of +\fBstat()\fR for any other reason is considered an error and \fBnftw()\fR +returns \(mi1. +.RE + +.RE + +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The fourth argument is a pointer to an \fBFTW\fR structure that contains the +following members: +.sp +.in +2 +.nf +int base; +int level; +.fi +.in -2 + +The \fBbase\fR member is the offset of the object's filename in the pathname +passed as the first argument to \fIfn\fR(). The value of \fBlevel\fR indicates +the depth relative to the root of the walk, where the root level is 0. +.sp +The results are unspecified if the application-supplied \fIfn\fR() function +does not preserve the current working directory. +.RE +.sp +.LP +Both \fBftw()\fR and \fBnftw()\fR use one file descriptor for each level in the +tree. The \fIdepth\fR argument limits the number of file descriptors used. If +\fIdepth\fR is zero or negative, the effect is the same as if it were 1. It +must not be greater than the number of file descriptors currently available for +use. The \fBftw()\fR function runs faster if \fIdepth\fR is at least as large +as the number of levels in the tree. Both \fBftw()\fR and \fBnftw()\fR are able +to descend to arbitrary depths in a file hierarchy and do not fail due to path +length limitations unless either the length of the path name pointed to by the +\fIpath\fR argument exceeds {\fBPATH_MAX\fR} requirements, or for \fBftw()\fR, +the specified depth is less than 2, or for \fBnftw()\fR, the specified depth is +less than 2 and \fBFTW_CHDIR\fR is not set. When \fBftw()\fR and \fBnftw()\fR +return, they close any file descriptors they have opened; they do not close any +file descriptors that might have been opened by \fIfn\fR. +.SH RETURN VALUES +.sp +.LP +If the tree is exhausted, \fBftw()\fR and \fBnftw()\fR return \fB0\fR. If the +function pointed to by \fIfn\fR returns a non-zero value, \fBftw()\fR and +\fBnftw()\fR stop their tree traversal and return whatever value was returned +by the function pointed to by \fIfn\fR. If \fBftw()\fR and \fBnftw()\fR detect +an error, they return \fB\(mi1\fR and set \fBerrno\fR to indicate the error. +.sp +.LP +If \fBftw()\fR and \fBnftw()\fR encounter an error other than \fBEACCES\fR (see +\fBFTW_DNR\fR and \fBFTW_NS\fR above), they return \fB\(mi1\fR and set +\fBerrno\fR to indicate the error. The external variable \fBerrno\fR can +contain any error value that is possible when a directory is opened or when one +of the \fBstat\fR functions is executed on a directory or file. +.SH ERRORS +.sp +.LP +The \fBftw()\fR and \fBnftw()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBELOOP\fR\fR +.ad +.RS 16n +.rt +A loop exists in symbolic links encountered during resolution of the \fIpath\fR +argument +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +The length of the path name pointed to by the \fIpath\fR argument exceeds +{\fBPATH_MAX\fR}, or a path name component is longer than {\fBNAME_MAX\fR}. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 16n +.rt +A component of \fIpath\fR does not name an existing file or \fIpath\fR is an +empty string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTDIR\fR\fR +.ad +.RS 16n +.rt +A component of \fIpath\fR is not a directory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOVERFLOW\fR\fR +.ad +.RS 16n +.rt +A field in the \fBstat\fR structure cannot be represented correctly in the +current programming environment for one or more files found in the file +hierarchy. +.RE + +.sp +.LP +The \fBftw()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 16n +.rt +Search permission is denied for any component of \fIpath\fR or read permission +is denied for \fIpath\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +The \fBftw()\fR function has descended to a path that exceeds {\fBPATH_MAX\fR} +and the depth argument specified by the application is less than 2 and +\fBFTW_CHDIR\fR is not set. +.RE + +.sp +.LP +The \fBnftw()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 10n +.rt +Search permission is denied for any component of \fIpath\fR or read permission +is denied for \fIpath\fR, or \fIfn\fR() returns \(mi1 and does not reset +\fBerrno\fR. +.RE + +.sp +.LP +The \fBnftw()\fR and \fBftw()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBELOOP\fR\fR +.ad +.RS 16n +.rt +Too many symbolic links were encountered during resolution of the \fIpath\fR +argument. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +Pathname resolution of a symbolic link in the path name pointed to by the +\fIpath\fR argument produced an intermediate result whose length exceeds +{\fBPATH_MAX\fR}. +.RE + +.sp +.LP +The \fBftw()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of the \fIdepth\fR argument is invalid. +.RE + +.sp +.LP +The \fBnftw()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 10n +.rt +There are {\fBOPEN_MAX\fR} file descriptors currently open in the calling +process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENFILE\fR\fR +.ad +.RS 10n +.rt +Too many files are currently open in the system. +.RE + +.sp +.LP +If the function pointed to by \fIfn\fR encounters system errors, \fBerrno\fR +may be set accordingly. +.SH EXAMPLES +.LP +\fBExample 1 \fRWalk a directory structure using \fBftw()\fR. +.sp +.LP +The following example walks the current directory structure, calling the +\fIfn\fR() function for every directory entry, using at most 10 file +descriptors: + +.sp +.in +2 +.nf +#include <ftw.h> +\&... +if (ftw(".", fn, 10) != 0) { + perror("ftw"); exit(2); +} +.fi +.in -2 + +.LP +\fBExample 2 \fRWalk a directory structure using \fBnftw()\fR. +.sp +.LP +The following example walks the \fB/tmp\fR directory and its subdirectories, +calling the \fBnftw()\fR function for every directory entry, to a maximum of 5 +levels deep. + +.sp +.in +2 +.nf +#include <ftw.h> +\&... +int nftwfunc(const char *, const struct stat *, int, struct FTW *); +int nftwfunc(const char *filename, const struct stat *statptr, + int fileflags, struct FTW *pfwt) +{ + return 0; +} +\&... +char *startpath = "/tmp"; +int depth = 5; +int flags = FTW_CHDIR | FTW_DEPTH | FTW_MOUNT; +int ret; +ret = nftw(startpath, nftwfunc, depth, flags); +.fi +.in -2 + +.SH USAGE +.sp +.LP +Because \fBftw()\fR and \fBnftw()\fR are recursive, they can terminate with a +memory fault when applied by a thread with a small stack to very deep file +structures. +.sp +.LP +The \fBftw()\fR and \fBnftw()\fR functions allocate resources (memory, file +descriptors) during their operation. If \fBftw()\fR they are forcibly +terminated, such as by \fBlongjmp\fR(3C) being executed by \fIfn\fR or an +interrupt routine, they will not have a chance to free those resources, so they +remain permanently allocated. A safe way to handle interrupts is to store the +fact that an interrupt has occurred and arrange to have \fIfn\fR return a +non-zero value at its next invocation. +.sp +.LP +The \fBftw()\fR and \fBnftw()\fR functions have transitional interfaces for +64-bit file offsets. See \fBlf64\fR(5). +.sp +.LP +The \fBftw()\fR function is safe in multithreaded applications. The +\fBnftw()\fR function is safe in multithreaded applications when the +\fBFTW_CHDIR\fR flag is not set. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBstat\fR(2), \fBlongjmp\fR(3C), \fBattributes\fR(5), \fBlf64\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/fwide.3c b/usr/src/man/man3c/fwide.3c new file mode 100644 index 0000000000..108e76ca4c --- /dev/null +++ b/usr/src/man/man3c/fwide.3c @@ -0,0 +1,88 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH fwide 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +fwide \- set stream orientation +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> +#include <wchar.h> + +\fBint\fR \fBfwide\fR(\fBFILE *\fR\fIstream\fR, \fBint\fR \fImode\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBfwide()\fR function determines the orientation of the stream pointed to +by \fIstream\fR. If \fImode\fR is greater than 0, the function first attempts +to make the stream wide-orientated. If \fImode\fR is less than 0, the function +first attempts to make the stream byte-orientated. Otherwise, \fImode\fR is 0 +and the function does not alter the orientation of the stream. +.sp +.LP +If the orientation of the stream has already been determined, \fBfwide()\fR +does not change it. +.sp +.LP +Because no return value is reserved to indicate an error, an application +wishing to check for error situations should set \fBerrno\fR to 0, then call +\fBfwide()\fR, then check \fBerrno\fR and if it is non-zero, assume an error +has occurred. +.SH RETURN VALUES +.sp +.LP +The \fBfwide()\fR function returns a value greater than 0 if, after the call, +the stream has wide-orientation, a value less than 0 if the stream has +byte-orientation, or 0 if the stream has no orientation. +.SH ERRORS +.sp +.LP +The \fBfwide()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 9n +.rt +The \fIstream\fR argument is not a valid stream. +.RE + +.SH USAGE +.sp +.LP +A call to \fBfwide()\fR with \fImode\fR set to 0 can be used to determine the +current orientation of a stream. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/fwprintf.3c b/usr/src/man/man3c/fwprintf.3c new file mode 100644 index 0000000000..24cd7c1bb6 --- /dev/null +++ b/usr/src/man/man3c/fwprintf.3c @@ -0,0 +1,865 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH fwprintf 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +fwprintf, wprintf, swprintf \- print formatted wide-character output +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> +#include <wchar.h> + +\fBint\fR \fBfwprintf\fR(\fBFILE *restrict\fR \fIstream\fR, \fBconst wchar_t *restrict\fR \fIformat\fR, + \fB\fR\fI\&...\fR); +.fi + +.LP +.nf +\fBint\fR \fBwprintf\fR(\fBconst wchar_t *restrict\fR \fIformat\fR, \fB\fR\fI\&...\fR); +.fi + +.LP +.nf +\fBint\fR \fBswprintf\fR(\fBwchar_t *restrict\fR \fIs\fR, \fBsize_t\fR \fIn\fR, \fBconst wchar_t *restrict\fR \fIformat\fR, + \fB\fR\fI\&...\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBfwprintf()\fR function places output on the named output \fIstream\fR. +The \fBwprintf()\fR function places output on the standard output stream +\fBstdout\fR. The \fBswprintf()\fR function places output followed by the null +wide-character in consecutive wide-characters starting at \fI*s\fR; no more +than \fIn\fR wide-characters are written, including a terminating null +wide-character, which is always added (unless \fIn\fR is zero). +.sp +.LP +Each of these functions converts, formats and prints its arguments under +control of the \fIformat\fR wide-character string. The \fIformat\fR is composed +of zero or more directives: \fBordinary wide-characters\fR, which are simply +copied to the output stream and \fBconversion specifications\fR, each of which +results in the fetching of zero or more arguments. The results are undefined if +there are insufficient arguments for the \fIformat\fR. If the \fIformat\fR is +exhausted while arguments remain, the excess arguments are evaluated but are +otherwise ignored. +.sp +.LP +Conversions can be applied to the \fIn\fRth argument after the \fIformat\fR in +the argument list, rather than to the next unused argument. In this case, the +conversion wide-character \fB%\fR (see below) is replaced by the sequence +\fB%\fR\fIn\fR\fB$\fR, where \fIn\fR is a decimal integer in the range [1, +\fBNL_ARGMAX\fR], giving the position of the argument in the argument list. +This feature provides for the definition of format wide-character strings that +select arguments in an order appropriate to specific languages (see the +\fBEXAMPLES\fR section). +.sp +.LP +In format wide-character strings containing the \fB%\fR\fIn\fR\fB$\fR form of +conversion specifications, numbered arguments in the argument list can be +referenced from the format wide-character string as many times as required. +.sp +.LP +In format wide-character strings containing the \fB%\fR form of conversion +specifications, each argument in the argument list is used exactly once. +.sp +.LP +All forms of the \fBfwprintf()\fR functions allow for the insertion of a +language-dependent radix character in the output string, output as a +wide-character value. The radix character is defined in the program's locale +(category \fBLC_NUMERIC\fR). In the POSIX locale, or in a locale where the +radix character is not defined, the radix character defaults to a period +(\|.\|). +.sp +.LP +Each conversion specification is introduced by the \fB%\fR wide-character or by +the wide-character sequence \fB%\fR\fIn\fR\fB$\fR, after which the following +appear in sequence: +.RS +4 +.TP +.ie t \(bu +.el o +Zero or more \fIflags\fR (in any order), which modify the meaning of the +conversion specification. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +An optional minimum \fIfield width\fR. If the converted value has fewer +wide-characters than the field width, it will be padded with spaces by default +on the left; it will be padded on the right, if the left-adjustment flag +(\fB\(mi\fR), described below, is given to the field width. The field width +takes the form of an asterisk (*), described below, or a decimal integer. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +An optional \fIprecision\fR that gives the minimum number of digits to appear +for the \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, and \fBX\fR conversions; +the number of digits to appear after the radix character for the \fBa\fR, +\fBA\fR, \fBe\fR, \fBE\fR, \fBf\fR, and \fBF\fR conversions; the maximum number +of significant digits for the \fBg\fR and \fBG\fR conversions; or the maximum +number of wide-characters to be printed from a string in \fBs\fR conversions. +The precision takes the form of a period (.) followed by either an asterisk +(*), 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. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +An optional length modifier that specifies the size of the argument. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +A \fIconversion specifier\fR wide character that indicates the type of +conversion to be applied. +.RE +.sp +.LP +A field width, or precision, or both, may be indicated by an asterisk (*). In +this case an argument of type \fBint\fR supplies the field width or precision. +Arguments specifying field width, or precision, or both must appear in that +order before the argument, if any, to be converted. A negative field width is +taken as a \fB\(mi\fR flag followed by a positive field width. A negative +precision is taken as if the precision were omitted. In format wide-character +strings containing the \fB%\fR\fIn\fR\fB$\fR form of a conversion +specification, a field width or precision may be indicated by the sequence +\fB*\fR\fIm\fR\fB$\fR, where \fIm\fR is a decimal integer in the range [1, +\fBNL_ARGMAX\fR] giving the position in the argument list (after the format +argument) of an integer argument containing the field width or precision, for +example: +.sp +.in +2 +.nf +wprintf(L"%1$d:%2$.*3$d:%4$.*3$d\en", hour, min, precision, sec); +.fi +.in -2 + +.sp +.LP +The \fIformat\fR can contain either numbered argument specifications (that is, +\fB%\fR\fIn\fR\fB$\fR and \fB*\fR\fIm\fR\fB$),\fR or unnumbered argument +specifications (that is, \fB%\fR and \fB*\fR), but normally not both. The only +exception to this is that \fB%%\fR can be mixed with the \fB%\fR\fIn\fR\fB$\fR +form. The results of mixing numbered and unnumbered argument specifications in +a \fIformat\fR wide-character string are undefined. When numbered argument +specifications are used, specifying the \fIN\fRth argument requires that all +the leading arguments, from the first to the (\fIN\(mi1\fR)th, are specified in +the format wide-character string. +.sp +.LP +The flag wide-characters and their meanings are: +.sp +.ne 2 +.mk +.na +\fB\fB\&'\fR\fR +.ad +.RS 9n +.rt +The integer portion of the result of a decimal conversion (\fB%i\fR, \fB%d\fR, +\fB%u\fR, \fB%f\fR, \fB%F\fR, \fB%g\fR, or \fB%G\fR) will be formatted with +thousands' grouping wide-characters. For other conversions the behavior is +undefined. The non-monetary grouping wide-character is used. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\(mi\fR\fR +.ad +.RS 9n +.rt +The result of the conversion will be left-justified within the field. The +conversion will be right-justified if this flag is not specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB+\fR\fR +.ad +.RS 9n +.rt +The result of a signed conversion will always begin with a sign (\fB+\fR or +\fB\(mi\fR). The conversion will begin with a sign only when a negative value +is converted if this flag is not specified. +.RE + +.sp +.ne 2 +.mk +.na +\fBspace\fR +.ad +.RS 9n +.rt +If the first wide-character of a signed conversion is not a sign or if a signed +conversion results in no wide-characters, a space will be prefixed to the +result. This means that if the space and \fB+\fR flags both appear, the space +flag will be ignored. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB#\fR\fR +.ad +.RS 9n +.rt +This flag specifies that the value is to be converted to an alternative form. +For \fBo\fR conversion, it increases the precision (if necessary) to force the +first digit of the result to be 0. For \fBx\fR or \fBX\fR conversions, a +non-zero result will have 0x (or 0X) prefixed to it. For \fBa\fR, \fBA\fR, +\fBe\fR, \fBE\fR, \fBf\fR, \fBF\fR, \fBg\fR, or \fBG\fR conversions, the result +will 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 \fBg\fR and \fBG\fR conversions, trailing zeros will +\fInot \fR be removed from the result as they normally are. For other +conversions, the behavior is undefined. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 9n +.rt +For \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, \fBX\fR, \fBa\fR, \fBA\fR, +\fBe\fR, \fBE\fR, \fBf\fR, \fBF\fR, \fBg\fR, and \fBG\fR conversions, leading +zeros (following any indication of sign or base) are used to pad to the field +width; no space padding is performed. If the \fB0\fR and \fB\(mi\fR flags both +appear, the \fB0\fR flag will be ignored. For \fBd\fR, \fBi\fR, \fBo\fR, +\fBu\fR, \fBx\fR, and \fBX\fR conversions, if a precision is specified, the +\fB0\fR flag will be ignored. If the \fB0\fR and \fB\&'\fR flags both appear, +the grouping wide-characters are inserted before zero padding. For other +conversions, the behavior is undefined. +.RE + +.sp +.LP +The length modifiers and their meanings: +.sp +.ne 2 +.mk +.na +\fB\fBhh\fR\fR +.ad +.RS 16n +.rt +Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, or +\fBX\fR conversion specifier applies to a \fBsigned char\fR or \fBunsigned +char\fR argument (the argument will have been promoted according to the integer +promotions, but its value shall be converted to \fBsigned char\fR or +\fBunsigned char\fR before printing); or that a following \fBn\fR conversion +specifier applies to a pointer to a \fBsigned char\fR argument. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBh\fR\fR +.ad +.RS 16n +.rt +Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, or +\fBX\fR conversion specifier applies to a \fBshort\fR or \fBunsigned short\fR +argument (the argument will have been promoted according to the integer +promotions, but its value shall be converted to \fBshort\fR or \fBunsigned +short\fR before printing); or that a following \fBn\fR conversion specifier +applies to a pointer to a \fBshort\fR argument. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBl\fR (ell)\fR +.ad +.RS 16n +.rt +Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, or +\fBX\fR conversion specifier applies to a \fBlong\fR or \fBunsigned long\fR +argument; that a following n conversion specifier applies to a pointer to a +\fBlong\fR argument; that a following \fBc\fR conversion specifier applies to a +\fBwint_t\fR argument; that a following \fBs\fR conversion specifier applies to +a pointer to a \fBwchar_t\fR argument; or has no effect on a following \fBa\fR, +\fBA\fR, \fBe\fR, \fBE\fR, \fBf\fR, \fBF\fR, \fBg\fR, or \fBG\fR conversion +specifier. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBll\fR (ell-ell)\fR +.ad +.RS 16n +.rt +Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, or +\fBX\fR conversion specifier applies to a\fB long long\fR or unsigned \fBlong +long\fR argument; or that a following \fBn\fR conversion specifier applies to a +pointer to a \fBlong long\fR argument. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBj\fR\fR +.ad +.RS 16n +.rt +Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, or +\fBX\fR conversion specifier applies to an \fBintmax_t\fR or \fBuintmax_t\fR +argument; or that a following \fBn\fR conversion specifier applies to a pointer +to an \fBintmax_t\fR argument. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBz\fR\fR +.ad +.RS 16n +.rt +Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, or +\fBX\fR conversion specifier applies to a \fBsize_t\fR or the corresponding +signed integer type argument; or that a following \fBn\fR conversion specifier +applies to a pointer to a signed integer type corresponding to \fBsize_t\fR +argument. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBt\fR\fR +.ad +.RS 16n +.rt +Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, or +\fBX\fR conversion specifier applies to a \fBptrdiff_t\fR or the corresponding +unsigned type argument; or that a following \fBn\fR conversion specifier +applies to a pointer to a \fBptrdiff_t\fR argument. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBL\fR\fR +.ad +.RS 16n +.rt +Specifies that a following \fBa\fR, \fBA\fR, \fBe\fR, \fBE\fR, \fBf\fR, +\fBF\fR, \fBg\fR, or \fBG\fR conversion specifier applies to a long double +argument. +.RE + +.sp +.LP +If a length modifier appears with any conversion specifier other than as +specified above, the behavior is undefined. +.sp +.LP +The conversion wide-characters and their meanings are: +.sp +.ne 2 +.mk +.na +\fB\fBd\fR, \fBi\fR\fR +.ad +.RS 8n +.rt +The \fBint\fR argument is converted to a signed decimal in the style +\fB[\fR\(mi\fB]\fR\fIdddd\fR. The precision specifies the minimum number of +digits to appear; if the value being converted can be represented in fewer +digits, it will be expanded with leading zeros. The default precision is 1. The +result of converting 0 with an explicit precision of 0 is no wide-characters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBo\fR\fR +.ad +.RS 8n +.rt +The \fBunsigned int\fR argument is converted to unsigned octal format in the +style \fIdddd\fR. The precision specifies the minimum number of digits to +appear; if the value being converted can be represented in fewer digits, it +will be expanded with leading zeros. The default precision is 1. The result of +converting 0 with an explicit precision of 0 is no wide-characters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBu\fR\fR +.ad +.RS 8n +.rt +The \fBunsigned int\fR argument is converted to unsigned decimal format in the +style \fIdddd\fR. The precision specifies the minimum number of digits to +appear; if the value being converted can be represented in fewer digits, it +will be expanded with leading zeros. The default precision is 1. The result of +converting 0 with an explicit precision of 0 is no wide-characters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBx\fR\fR +.ad +.RS 8n +.rt +The \fBunsigned int\fR argument is converted to unsigned hexadecimal format in +the style \fIdddd\fR; the letters abcdef are used. The precision specifies the +minimum number of digits to appear; if the value being converted can be +represented in fewer digits, it will be expanded with leading zeros. The +default precision is 1. The result of converting 0 with an explicit precision +of 0 is no wide-characters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBX\fR\fR +.ad +.RS 8n +.rt +Behaves the same as the \fBx\fR conversion wide-character except that letters +"\fBABCDEF\fR" are used instead of "\fBabcdef\fR". +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBf\fR, \fBF\fR\fR +.ad +.RS 8n +.rt +The \fBdouble\fR argument is converted to decimal notation in the style +[\fB\(mi\fR]\fIddd\fR\fB\&.\fR\fIddd\fR, where the number of digits after the +radix character (see \fBsetlocale\fR(3C)) is equal to the precision +specification. If the precision is missing it is taken as 6; if the precision +is explicitly 0 and the \fB#\fR flag is not specified, no radix character +appears. If a radix character appears, at least 1 digit appears before it. The +converted value is rounded to fit the specified output format according to the +prevailing floating point rounding direction mode. If the conversion is not +exact, an inexact exception is raised. +.sp +For the \fBf\fR specifier, a double argument representing an infinity or NaN is +converted in the style of the \fBe\fR conversion specifier, except that for an +infinite argument, "infinity" or "Infinity" is printed when the precision is at +least 8 and "inf" or "Inf" is printed otherwise. +.sp +For the F specifier, a double argument representing an infinity or NaN is +converted in the SUSv3 style of the E conversion specifier, except that for an +infinite argument, "INFINITY" is printed when the precision is at least 8 and +or "INF" is printed otherwise. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBe\fR, \fBE\fR\fR +.ad +.RS 8n +.rt +The \fBdouble\fR argument is converted in the style +\fB[\fR\(mi\fB]\fR\fId.ddd\fRe\|\(+-\|dd, 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 +is taken as 6; if the precision is 0 and no \fB#\fR flag is present, no radix +character appears. The converted value is rounded to fit the specified output +format according to the prevailing floating point rounding direction mode. If +the conversion is not exact, an inexact exception is raised. The \fBE\fR +conversion wide-character will produce a number with \fBE\fR instead of \fBe\fR +introducing the exponent. The exponent always contains at least two digits. If +the value is 0, the exponent is 0. +.sp +Infinity and NaN values are handled in one of the following ways: +.sp +.ne 2 +.mk +.na +\fBSUSv3\fR +.ad +.RS 11n +.rt +For the \fBe\fR specifier, a \fBdouble\fR argument representing an infinity is +printed as "[\(mi]\fBinfinity\fR", when the precision for the conversion is at +least 7 and as "[\(mi]\fBinf\fR" otherwise. A \fBdouble\fR argument +representing a NaN is printed as "[\(mi]\fBnan\fR". For the \fBE\fR specifier, +"\fBINF\fR", "\fBINFINITY\fR", and "\fBNAN\fR" are printed instead of +"\fBinf\fR", "\fBinfinity\fR", and "\fBnan\fR", respectively. Printing of the +sign follows the rules described above. +.RE + +.sp +.ne 2 +.mk +.na +\fBDefault\fR +.ad +.RS 11n +.rt +A \fBdouble\fR argument representing an infinity is printed as +"[\(mi]\fBInfinity\fR", when the precision for the conversion is at least 7 and +as "[\(mi]\fBInf\fR" otherwise. A double argument representing a NaN is printed +as "[\(mi]\fBNaN\fR". Printing of the sign follows the rules described above. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBg\fR, \fBG\fR\fR +.ad +.RS 8n +.rt +The \fBdouble\fR argument is converted in the style \fBf\fR or \fBe\fR (or in +the style \fBE\fR in the case of a \fBG\fR conversion wide-character), with the +precision specifying the number of significant digits. If an explicit precision +is 0, it is taken as 1. The style used depends on the value converted; style +\fBe\fR (or \fBE\fR \fB)\fR will be used only if the exponent resulting from +such a conversion is less than \(mi4 or greater than or equal to the precision. +Trailing zeros are removed from the fractional portion of the result; a radix +character appears only if it is followed by a digit. +.sp +A \fBdouble\fR argument representing an infinity or NaN is converted in the +style of the \fBe\fR or \fBE\fR conversion specifier, except that for an +infinite argument, "infinity", "INFINITY", or "Infinity" is printed when the +precision is at least 8 and "inf", "INF", or "Inf" is printed otherwise. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBa\fR, \fBA\fR\fR +.ad +.RS 8n +.rt +A double argument representing a floating-point number is converted in the +style "[-]\fB0xh.hhhhp\(+-d\fR", where the single hexadecimal digit preceding +the radix point is 0 if the value converted is zero and 1 otherwise and the +number of hexadecimal digits after it are equal to the precision; if the +precision is missing, the number of digits printed after the radix point is 13 +for the conversion of a double value, 16 for the conversion of a long double +value on x86, and 28 for the conversion of a long double value on SPARC; if the +precision is zero and the '#' flag is not specified, no decimal-point wide +character appears. The letters "abcdef" are used for \fBa\fR conversion and the +letters "ABCDEF" for \fBA\fR conversion. The \fBA\fR conversion specifier +produces a number with 'X' and 'P' instead of 'x' and 'p'. The exponent always +contains 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 is +zero. +.sp +The converted valueis rounded to fit the specified output format according to +the prevailing floating point rounding direction mode. If the conversion is not +exact, an inexact exception is raised. +.sp +A \fBdouble\fR argument representing an infinity or NaN is converted in the +SUSv3 style of an \fBe\fR or \fBE\fR conversion specifier. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBc\fR\fR +.ad +.RS 8n +.rt +If no \fBl\fR (ell) qualifier is present, the \fBint\fR argument is converted +to a wide-character as if by calling the \fBbtowc\fR(3C) function and the +resulting wide-character is written. Otherwise the \fBwint_t\fR argument is +converted to \fBwchar_t\fR, and written. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBs\fR\fR +.ad +.RS 8n +.rt +If no \fBl\fR (ell) qualifier is present, the argument must be a pointer to a +character array containing a character sequence beginning in the initial shift +state. Characters from the array are converted as if by repeated calls to the +\fBmbrtowc\fR(3C) function, with the conversion state described by an +\fBmbstate_t\fR 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 are written. If the precision is not specified or is greater +than the size of the array, the array must contain a null wide-character. +.sp +If an \fBl\fR (ell) qualifier is present, the argument must be a pointer to an +array of type \fBwchar_t\fR. Wide characters from the array are 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 array must contain a +null wide-character. If a precision is specified, no more than that many +wide-characters are written. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBp\fR\fR +.ad +.RS 8n +.rt +The argument must be a pointer to \fBvoid\fR. The value of the pointer is +converted to a sequence of printable wide-characters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBn\fR\fR +.ad +.RS 8n +.rt +The argument must be 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 +\fBfwprintf()\fR functions. No argument is converted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBC\fR\fR +.ad +.RS 8n +.rt +Same as \fBlc\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBS\fR\fR +.ad +.RS 8n +.rt +Same as \fBls\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%\fR\fR +.ad +.RS 8n +.rt +Output a % wide-character; no argument is converted. The entire conversion +specification must be \fB%%\fR. +.RE + +.sp +.LP +If a conversion specification does not match one of the above forms, the +behavior is undefined. +.sp +.LP +In no case does a non-existent or small field width cause truncation of a +field; if the result of a conversion is wider than the field width, the field +is simply expanded to contain the conversion result. Characters generated by +\fBfwprintf()\fR and \fBwprintf()\fR are printed as if \fBfputwc\fR(3C) had +been called. +.sp +.LP +The \fBst_ctime\fR and \fBst_mtime\fR fields of the file will be marked for +update between the call to a successful execution of \fBfwprintf()\fR or +\fBwprintf()\fR and the next successful completion of a call to +\fBfflush\fR(3C) or \fBfclose\fR(3C) on the same stream or a call to +\fBexit\fR(3C) or \fBabort\fR(3C). +.SH RETURN VALUES +.sp +.LP +Upon successful completion, these functions return the number of +wide-characters transmitted excluding the terminating null wide-character in +the case of \fBswprintf()\fR or a negative value if an output error was +encountered. +.sp +.LP +If \fIn\fR or more wide characters were requested to be written, +\fBswprintf()\fR returns a negative value. +.SH ERRORS +.sp +.LP +For the conditions under which \fBfwprintf()\fR and \fBwprintf()\fR will fail +and may fail, refer to \fBfputwc\fR(3C). +.sp +.LP +In addition, all forms of \fBfwprintf()\fR may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEILSEQ\fR\fR +.ad +.RS 10n +.rt +A wide-character code that does not correspond to a valid character has been +detected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +There are insufficient arguments. +.RE + +.sp +.LP +In addition, \fBwprintf()\fR and \fBfwprintf()\fR may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient storage space is available. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRPrint Language-dependent Date and Time Format. +.sp +.LP +To print the language-independent date and time format, the following statement +could be used: + +.sp +.in +2 +.nf +wprintf(format, weekday, month, day, hour, min); +.fi +.in -2 + +.sp +.LP +For American usage, \fIformat\fR could be a pointer to the wide-character +string: + +.sp +.in +2 +.nf +L"%s, %s %d, %d:%.2d\en" +.fi +.in -2 + +.sp +.LP +producing the message: + +.sp +.in +2 +.nf +Sunday, July 3, 10:02 +.fi +.in -2 + +.sp +.LP +whereas for German usage, \fIformat\fR could be a pointer to the wide-character +string: + +.sp +.in +2 +.nf +L"%1$s, %3$d. %2$s, %4$d:%5$.2d\en" +.fi +.in -2 + +.sp +.LP +producing the message: + +.sp +.in +2 +.nf +Sonntag, 3. Juli, 10:02 +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBbtowc\fR(3C), \fBfputwc\fR(3C), \fBfwscanf\fR(3C), \fBmbrtowc\fR(3C), +\fBsetlocale\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +The \fBfwprintf()\fR, \fBwprintf()\fR, and \fBswprintf()\fR functions can be +used safely in multithreaded applications, as long as \fBsetlocale\fR(3C) is +not being called to change the locale. +.sp +.LP +If the \fBj\fR length modifier is used, 32-bit applications that were compiled +using \fBc89\fR on releases prior to Solaris 10 will experience undefined +behavior. diff --git a/usr/src/man/man3c/fwrite.3c b/usr/src/man/man3c/fwrite.3c new file mode 100644 index 0000000000..078ae22b80 --- /dev/null +++ b/usr/src/man/man3c/fwrite.3c @@ -0,0 +1,83 @@ +'\" te +.\" Copyright (c) 1997, The Open Group. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH fwrite 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +fwrite \- binary output +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBsize_t\fR \fBfwrite\fR(\fBconst void *\fR\fIptr\fR, \fBsize_t\fR \fIsize\fR, \fBsize_t\fR \fInitems\fR, \fBFILE *\fR\fIstream\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBfwrite()\fR function writes, from the array pointed to by \fIptr\fR, up +to \fInitems\fR elements whose size is specified by \fIsize\fR, to the stream +pointed to by \fIstream\fR. For each object, \fIsize\fR calls are made to the +\fBfputc\fR(3C) function, taking the values (in order) from an array of +\fBunsigned char\fR exactly overlaying the object. The file-position indicator +for the stream (if defined) is 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. +.sp +.LP +The \fBst_ctime\fR and \fBst_mtime\fR fields of the file will be marked for +update between the successful execution of \fBfwrite()\fR and the next +successful completion of a call to \fBfflush\fR(3C) or \fBfclose\fR(3C) on the +same stream or a call to \fBexit\fR(2) or \fBabort\fR(3C). +.SH RETURN VALUES +.sp +.LP +The \fBfwrite()\fR function returns the number of elements successfully +written, which might be less than \fInitems\fR if a write error is encountered. +If \fIsize\fR or \fInitems\fR is 0, \fBfwrite()\fR returns 0 and the state of +the stream remains unchanged. Otherwise, if a write error occurs, the error +indicator for the stream is set and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +Refer to \fBfputc\fR(3C). +.SH USAGE +.sp +.LP +Because of possible differences in element length and byte ordering, files +written using \fBfwrite()\fR are application-dependent, and possibly cannot be +read using \fBfread\fR(3C) by a different application or by the same +application on a different processor. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBwrite\fR(2), \fBfclose\fR(3C), \fBferror\fR(3C), \fBfopen\fR(3C), +\fBfread\fR(3C), \fBgetc\fR(3C), \fBgets\fR(3C), \fBprintf\fR(3C), +\fBputc\fR(3C), \fBputs\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/fwscanf.3c b/usr/src/man/man3c/fwscanf.3c new file mode 100644 index 0000000000..cadbb988b0 --- /dev/null +++ b/usr/src/man/man3c/fwscanf.3c @@ -0,0 +1,745 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Portions Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH fwscanf 3C "10 Jul 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +fwscanf, wscanf, swscanf, vfwscanf, vwscanf, vswscanf \- convert formatted +wide-character input +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> +#include <wchar.h> + +\fBint\fR \fBfwscanf\fR(\fBFILE *restrict\fR \fIstream\fR, \fBconst wchar_t *restrict\fR \fIformat\fR, \fB\fR\fI\&...\fR); +.fi + +.LP +.nf +\fBint\fR \fBwscanf\fR(\fBconst wchar_t *restrict\fR \fIformat\fR, \fB\fR\fI\&...\fR); +.fi + +.LP +.nf +\fBint\fR \fBswscanf\fR(\fBconst wchar_t *restrict\fR \fIs\fR, \fBconst wchar_t *restrict\fR \fIformat\fR, + \fB\fR\fI\&...\fR); +.fi + +.LP +.nf +#include <stdarg.h> +#include <stdio.h> +#include <wchar.h> + +\fBint\fR \fBvfwscanf\fR(\fBFILE *restrict\fR \fIstream\fR, \fBconst wchar_t *restrict\fR \fIformat\fR, + \fBva_list\fR \fIarg\fR); +.fi + +.LP +.nf +\fBint\fR \fBvswcanf\fR(\fBconst wchar_t *restrict\fR \fIws\fR, \fBconst wchar_t *restrict\fR \fIformat\fR, + \fBva_list\fR \fIarg\fR); +.fi + +.LP +.nf +\fBint\fR \fBvwscanf\fR(\fBconst wchar_t *restrict\fR \fIformat\fR, \fBva_list\fR \fIarg\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBfwscanf()\fR function reads from the named input \fIstream\fR. +.sp +.LP +The \fBwscanf()\fR function reads from the standard input stream \fBstdin\fR. +.sp +.LP +The \fBswscanf()\fR function reads from the wide-character string \fIs\fR. +.sp +.LP +The \fBvfwscanf()\fR, \fBvswscanf()\fR, and \fBvwscanf()\fR functions are +equivalent to the \fBfwscanf()\fR, \fBswscanf()\fR, and \fBwscanf()\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 the +<\fBstdarg.h\fR> header . These functions do not invoke the \fBva_end()\fR +macro. Applications using these functions should call \fBva_end\fR(\fIap\fR) +afterwards to clean up. +.sp +.LP +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 \fIformat\fR described below, and a set of \fIpointer\fR +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 are evaluated but are +otherwise ignored. +.sp +.LP +Conversions can be applied to the \fIn\fRth argument after the \fIformat\fR in +the argument list, rather than to the next unused argument. In this case, the +conversion wide-character \fB%\fR (see below) is replaced by the sequence +\fB%\fR\fIn\fR\fB$\fR, where \fIn\fR is a decimal integer in the range [1, +\fBNL_ARGMAX\fR]. This feature provides for the definition of format +wide-character strings that select arguments in an order appropriate to +specific languages. In format wide-character strings containing the +\fB%\fR\fIn\fR\fB$\fR form of conversion specifications, it is unspecified +whether numbered arguments in the argument list can be referenced from the +format wide-character string more than once. +.sp +.LP +The \fIformat\fR can contain either form of a conversion specification, that +is, \fB%\fR or \fB%\fR\fIn\fR\fB$\fR, but the two forms cannot normally be +mixed within a single \fIformat\fR wide-character string. The only exception to +this is that \fB%%\fR or \fB%*\fR can be mixed with the \fB%\fR\fIn\fR\fB$\fR +form. +.sp +.LP +The \fBfwscanf()\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 program's locale +(category \fBLC_NUMERIC\fR). In the POSIX locale, or in a locale where the +radix character is not defined, the radix character defaults to a period (.). +.sp +.LP +The 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 (space, tab, newline, vertical-tab or form-feed characters); +an ordinary wide-character (neither \fB%\fR nor a white-space character); or a +conversion specification. Each conversion specification is introduced by a +\fB%\fR or the sequence \fB%\fR\fIn\fR\fB$\fR after which the following appear +in sequence: +.RS +4 +.TP +.ie t \(bu +.el o +An optional assignment-suppressing character \fB*\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +An optional non-zero decimal integer that specifies the maximum field width. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +An option length modifier that specifies the size of the receiving object. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +A conversion specifier wide-character that specifies the type of conversion to +be applied. The valid conversion wide-characters are described below. +.RE +.sp +.LP +The \fBfwscanf()\fR functions execute each directive of the format in turn. If +a directive fails, as detailed below, the function returns. Failures are +described as input failures (due to the unavailability of input bytes) or +matching failures (due to inappropriate input). +.sp +.LP +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. +.sp +.LP +A directive that is an ordinary wide-character is 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 fails, and the differing and subsequent wide-characters remain +unread. +.sp +.LP +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: +.sp +.LP +Input white-space wide-characters (as specified by \fBiswspace\fR(3C)) are +skipped, unless the conversion specification includes a \fB[\fR, \fBc\fR, or +\fBn\fR conversion character. +.sp +.LP +An item is read from the input unless the conversion specification includes an +\fBn\fR conversion wide-character. The length of the item read is limited to +any specified maximum field width. In Solaris default mode, the input item is +defined as the longest sequence of input wide-characters that forms a matching +sequence. In some cases, \fBfwscanf()\fR might need to read several extra +wide-characters beyond the end of the input item to find the end of a matching +sequence. In C99/SUSv3 mode, the input item is defined as the longest sequence +of input wide-characters that is, or is a prefix of, a matching sequence. With +this definition, \fBfwscanf()\fR need only read at most one wide-character +beyond the end of the input item. Therefore, in C99/SUSv3 mode, some sequences +that are acceptable to \fBwcstod\fR(3C), \fBwcstol\fR(3C), and similar +functions are unacceptable to \fBfwscanf()\fR. In either mode, \fBfwscanf()\fR +attempts to push back any excess bytes read using \fBungetc\fR(3C). Assuming +all such attempts succeed, the first wide-character, if any, after the input +item remains unread. If the length of the input item is 0, the conversion +fails. 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. +.sp +.LP +Except in the case of a \fB%\fR conversion wide-character, the input item (or, +in the case of a \fB%\fR\fIn\fR conversion specification, the count of input +wide-characters) is 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 fails; this condition is a matching failure. +Unless assignment suppression was indicated by a \fB*\fR, the result of the +conversion is placed in the object pointed to by the first argument following +the \fIformat\fR argument that has not already received a conversion result if +the conversion specification is introduced by \fB%\fR, or in the \fIn\fRth +argument if introduced by the wide-character sequence \fB%\fR\fIn\fR\fB$\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. +.sp +.LP +The length modifiers and their meanings are: +.sp +.ne 2 +.mk +.na +\fB\fBhh\fR\fR +.ad +.RS 16n +.rt +Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, +\fBX\fR, or \fBn\fR conversion specifier applies to an argument with type +pointer to \fBsigned char\fR or \fBunsigned char\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBh\fR\fR +.ad +.RS 16n +.rt +Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, +\fBX\fR, or \fBn\fR conversion specifier applies to an argument with type +pointer to \fBshort\fR or \fBunsigned short\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBl\fR (ell)\fR +.ad +.RS 16n +.rt +Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, +\fBX\fR, or \fBn\fR conversion specifier applies to an argument with type +pointer to \fBlong\fR or \fBunsigned long\fR; that a following \fBa\fR, +\fBA\fR, \fBe\fR, \fBE\fR, \fBf\fR, \fBF\fR, \fBg\fR, or \fBG\fR conversion +specifier applies to an argument with type pointer to \fBdouble\fR; or that a +following \fBc\fR, \fBs\fR, or \fB[\fR conversion specifier applies to an +argument with type pointer to \fBwchar_t\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBll\fR (ell-ell)\fR +.ad +.RS 16n +.rt +Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, +\fBX\fR, or \fBn\fR conversion specifier applies to an argument with type +pointer to \fBlong long\fR or \fBunsigned long long\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBj\fR\fR +.ad +.RS 16n +.rt +Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, +\fBX\fR, or \fBn\fR conversion specifier applies to an argument with type +pointer to \fBintmax_t\fR or \fBuintmax_t\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBz\fR\fR +.ad +.RS 16n +.rt +Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, +\fBX\fR, or \fBn\fR conversion specifier applies to an argument with type +pointer to \fBsize_t\fR or the corresponding signed integer type. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBt\fR\fR +.ad +.RS 16n +.rt +Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, +\fBX\fR, or \fBn\fR conversion specifier applies to an argument with type +pointer to \fBptrdiff_t\fR or the corresponding \fBunsigned\fR type. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBL\fR\fR +.ad +.RS 16n +.rt +Specifies that a following \fBa\fR, \fBA\fR, \fBe\fR, \fBE\fR, \fBf\fR, +\fBF\fR, \fBg\fR, or \fBG\fR conversion specifier applies to an argument with +type pointer to \fBlong double\fR. +.RE + +.sp +.LP +If a length modifier appears with any conversion specifier other than as +specified above, the behavior is undefined. +.sp +.LP +The following conversion wide-characters are valid: +.sp +.ne 2 +.mk +.na +\fB\fBd\fR\fR +.ad +.RS 11n +.rt +Matches an optionally signed decimal integer, whose format is the same as +expected for the subject sequence of \fBwcstol\fR(3C) with the value 10 for the +\fIbase\fR argument. In the absence of a size modifier, the corresponding +argument must be a pointer to \fBint\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBi\fR\fR +.ad +.RS 11n +.rt +Matches an optionally signed integer, whose format is the same as expected for +the subject sequence of \fBwcstol\fR(3C) with 0 for the \fIbase\fR argument. In +the absence of a size modifier, the corresponding argument must be a pointer to +\fBint\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBo\fR\fR +.ad +.RS 11n +.rt +Matches an optionally signed octal integer, whose format is the same as +expected for the subject sequence of \fBwcstoul\fR(3C) with the value 8 for the +\fIbase\fR argument. In the absence of a size modifier, the corresponding +argument must be a pointer to \fBunsigned int\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBu\fR\fR +.ad +.RS 11n +.rt +Matches an optionally signed decimal integer, whose format is the same as +expected for the subject sequence of \fBwcstoul\fR(3C) with the value 10 for +the \fIbase\fR argument. In the absence of a size modifier, the corresponding +argument must be a pointer to \fBunsigned int\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBx\fR\fR +.ad +.RS 11n +.rt +Matches an optionally signed hexadecimal integer, whose format is the same as +expected for the subject sequence of \fBwcstoul\fR(3C) with the value 16 for +the \fIbase\fR argument. In the absence of a size modifier, the corresponding +argument must be a pointer to \fBunsigned int\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBa\fR,\fBe\fR,\fBf\fR,\fBg\fR\fR +.ad +.RS 11n +.rt +Matches an optionally signed floating-point number, whose format is the same as +expected for the subject sequence of \fBwcstod\fR(3C). In the absence of a size +modifier, the corresponding argument must be a pointer to \fBfloat\fR. The +\fBe\fR, \fBf\fR, and \fBg\fR specifiers match hexadecimal floating point +values only in C99/SUSv3 (see \fBstandards\fR(5)) mode, but the \fBa\fR +specifier always matches hexadecimal floating point values. +.sp +These conversion specifiers match any subject sequence accepted by +\fBstrtod\fR(3C), including the INF, INFINITY, NAN, and +NAN(\fIn-char-sequence\fR) forms. The result of the conversion is the same as +that of calling \fBstrtod()\fR (or \fBstrtof()\fR or \fBstrtold()\fR) with the +matching sequence, including the raising of floating point exceptions and the +setting of \fBerrno\fR to \fBERANGE\fR, if applicable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBs\fR\fR +.ad +.RS 11n +.rt +Matches a sequence of non white-space wide-characters. If no \fBl\fR (ell) +qualifier is present, characters from the input field are converted as if by +repeated calls to the \fBwcrtomb\fR(3C) function, with the conversion state +described by an \fBmbstate_t\fR object initialized to zero before the first +wide-character is converted. The corresponding argument must be a pointer to a +character array large enough to accept the sequence and the terminating null +character, which will be added automatically. +.sp +Otherwise, the corresponding argument must be a pointer to an array of +\fBwchar_t\fR large enough to accept the sequence and the terminating null +wide-character, which will be added automatically. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB[\fR\fR +.ad +.RS 11n +.rt +Matches a non-empty sequence of wide-characters from a set of expected +wide-characters (the \fIscanset\fR). If no \fBl\fR (ell) qualifier is present, +wide-characters from the input field are converted as if by repeated calls to +the \fBwcrtomb()\fR function, with the conversion state described by an +\fBmbstate_t\fR object initialized to zero before the first wide-character is +converted. The corresponding argument must be a pointer to a character array +large enough to accept the sequence and the terminating null character, which +will be added automatically. +.sp +If an \fBl\fR (ell) qualifier is present, the corresponding argument must be a +pointer to an array of \fBwchar_t\fR large enough to accept the sequence and +the terminating null wide-character, which will be added automatically. +.sp +The conversion specification includes all subsequent widw characters in the +\fIformat\fR string up to and including the matching right square bracket +(\fB]\fR). The wide-characters between the square brackets (the \fIscanlist\fR) +comprise the scanset, unless the wide-character after the left square bracket +is a circumflex (\fB^\fR), in which case the scanset contains all +wide-characters that do not appear in the scanlist between the circumflex and +the right square bracket. If the conversion specification begins with +\fB[\|]\fR or \fB[^],\fR the right square bracket is included in the scanlist +and the next right square bracket is the matching right square bracket that +ends the conversion specification; otherwise the first right square bracket is +the one that ends the conversion specification. If a minus-sign (\fB\(mi\fR) is +in the scanlist and is not the first wide-character, nor the second where the +first wide-character is a \fB^\fR, nor the last wide-character, it indicates a +range of characters to be matched. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBc\fR\fR +.ad +.RS 11n +.rt +Matches a sequence of wide-characters of the number specified by the field +width (1 if no field width is present in the conversion specification). If no +\fBl\fR (ell) qualifier is present, wide-characters from the input field are +converted as if by repeated calls to the \fBwcrtomb()\fR function, with the +conversion state described by an \fBmbstate_t\fR object initialized to zero +before the first wide-character is converted. The corresponding argument must +be a pointer to a character array large enough to accept the sequence. No null +character is added. +.sp +Otherwise, the corresponding argument must be a pointer to an array of +\fBwchar_t\fR large enough to accept the sequence. No null wide-character is +added. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBp\fR\fR +.ad +.RS 11n +.rt +Matches the set of sequences that is the same as the set of sequences that is +produced by the \fB%p\fR conversion of the corresponding \fBfwprintf\fR(3C) +functions. The corresponding argument must be a pointer to a pointer to +\fBvoid\fR. If the input item is a value converted earlier during the same +program execution, the pointer that results will compare equal to that value; +otherwise the behavior of the \fB%p\fR conversion is undefined. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBn\fR\fR +.ad +.RS 11n +.rt +No input is consumed. The corresponding argument must be 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 \fBfwscanf()\fR functions. Execution of a +\fB%n\fR conversion specification does not increment the assignment count +returned at the completion of execution of the function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBC\fR\fR +.ad +.RS 11n +.rt +Same as \fBlc\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBS\fR\fR +.ad +.RS 11n +.rt +Same as \fBls\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%\fR\fR +.ad +.RS 11n +.rt +Matches a single \fB%\fR; no conversion or assignment occurs. The complete +conversion specification must be \fB%%\fR. +.RE + +.sp +.LP +If a conversion specification is invalid, the behavior is undefined. +.sp +.LP +The conversion characters \fBA\fR, \fBE\fR, \fBF\fR, \fBG\fR, and \fBX\fR are +also valid and behave the same as, respectively, \fBa\fR, \fBe\fR, \fBf\fR, +\fBg\fR, and \fBx\fR. +.sp +.LP +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 \fB%n\fR) have been read (other than leading +white-space, where permitted), execution of the current conversion +specification terminates 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) is terminated with +an input failure. +.sp +.LP +Reaching the end of the string in \fBswscanf()\fR is equivalent to encountering +end-of-file for \fBfwscanf()\fR. +.sp +.LP +If conversion terminates on a conflicting input, the offending input is left +unread in the input. Any trailing white space (including newline) is left +unread unless matched by a conversion specification. The success of literal +matches and suppressed assignments is only directly determinable via the %n +conversion specification. +.sp +.LP +The \fBfwscanf()\fR and \fBwscanf()\fR functions may mark the \fBst_atime\fR +field of the file associated with \fIstream\fR for update. The \fBst_atime\fR +field will be marked for update by the first successful execution of +\fBfgetc\fR(3C), \fBfgetwc\fR(3C), \fBfgets\fR(3C), \fBfgetws\fR(3C), +\fBfread\fR(3C), \fBgetc\fR(3C), \fBgetwc\fR(3C), \fBgetchar\fR(3C), +\fBgetwchar\fR(3C), \fBgets\fR(3C), \fBfscanf\fR(3C) or \fBfwscanf()\fR using +\fIstream\fR that returns data not supplied by a prior call to +\fBungetc\fR(3C). +.SH RETURN VALUES +.sp +.LP +Upon successful completion, these functions return the number of successfully +matched and assigned input items; this number can be 0 in the event of an early +matching failure. If the input ends before the first matching failure or +conversion, \fBEOF\fR is returned. If a read error occurs the error indicator +for the stream is set, \fBEOF\fR is returned, and \fBerrno\fR is set to +indicate the error. +.SH ERRORS +.sp +.LP +For the conditions under which the \fBfwscanf()\fR functions will fail and may +fail, refer to \fBfgetwc\fR(3C). +.sp +.LP +In addition, \fBfwscanf()\fR may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEILSEQ\fR\fR +.ad +.RS 10n +.rt +Input byte sequence does not form a valid character. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +There are insufficient arguments. +.RE + +.SH USAGE +.sp +.LP +In format strings containing the \fB%\fR form of conversion specifications, +each argument in the argument list is used exactly once. +.SH EXAMPLES +.LP +\fBExample 1 \fR\fBwscanf()\fR example +.sp +.LP +The call: + +.sp +.in +2 +.nf +int i, n; float x; char name[50]; +n = wscanf(L"%d%f%s", &i, &x, name); +.fi +.in -2 + +.sp +.LP +with the input line: + +.sp +.in +2 +.nf +25 54.32E\(mi1 Hamster +.fi +.in -2 + +.sp +.LP +will assign to \fIn\fR the value 3, to \fIi\fR the value 25, to \fIx\fR the +value 5.432, and \fIname\fR will contain the string Hamster. + +.sp +.LP +The call: + +.sp +.in +2 +.nf +int i; float x; char name[50]; +(void) wscanf(L"%2d%f%*d %[0123456789], &i, &x, name); +.fi +.in -2 + +.sp +.LP +with input: + +.sp +.in +2 +.nf +56789 0123 56a72 +.fi +.in -2 + +.sp +.LP +will assign 56 to \fIi\fR, 789.0 to \fIx\fR, skip 0123, and place the string +56\e0 in \fIname\fR. The next call to \fBgetchar\fR(3C) will return the +character \fBa\fR. + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBfgetc\fR(3C), \fBfgets\fR(3C), \fBfgetwc\fR(3C), \fBfgetws\fR(3C), +\fBfread\fR(3C), \fBfscanf\fR(3C), \fBfwprintf\fR(3C), \fBgetc\fR(3C), +\fBgetchar\fR(3C), \fBgets\fR(3C), \fBgetwc\fR(3C), \fBgetwchar\fR(3C), +\fBsetlocale\fR(3C), \fBstrtod\fR(3C), \fBwcrtomb\fR(3C), \fBwcstod\fR(3C), +\fBwcstol\fR(3C), \fBwcstoul\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +The behavior of the conversion specifier "%%" has changed for all of the +functions described on this manual page. Previously the "%%" specifier accepted +a "%" character from input only if there were no preceding whitespace +characters. The new behavior accepts "%" even if there are preceding +whitespace characters. This new behavior now aligns with the description on +this manual page and in various standards. If the old behavior is desired, the +conversion specification "%*[%]" can be used. diff --git a/usr/src/man/man3c/getcpuid.3c b/usr/src/man/man3c/getcpuid.3c new file mode 100644 index 0000000000..e860c56918 --- /dev/null +++ b/usr/src/man/man3c/getcpuid.3c @@ -0,0 +1,75 @@ +'\" te +.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getcpuid 3C "16 Apr 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getcpuid, gethomelgroup \- obtain information on scheduling decisions +.SH SYNOPSIS +.LP +.nf +#include <sys/processor.h> + +\fBprocessorid_t\fR \fBgetcpuid\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBushort_t\fR \fBgethomelgroup\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetcpuid()\fR function returns the processor ID on which the calling +thread is currently executing. +.sp +.LP +The \fBgethomelgroup()\fR function returns the home locality group ID of the +calling thread. +.SH RETURN VALUES +.sp +.LP +See \fBDESCRIPTION\fR. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH USAGE +.sp +.LP +Both the current CPU and the home locality group can change at any time. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityT{ +\fBgetcpuid()\fR is Stable; \fBgethomelgroup()\fR is Obsolete. +T} +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpsradm\fR(1M), \fBpsrinfo\fR(1M), \fBpsrset\fR(1M), \fBp_online\fR(2), +\fBprocessor_bind\fR(2), \fBprocessor_info\fR(2), \fBpset_assign\fR(2), +\fBpset_bind\fR(2), \fBpset_info\fR(2), \fBmeminfo\fR(2), +\fBlgrp_home\fR(3LGRP), \fBsysconf\fR(3C), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +The \fBgethomelgroup()\fR function is obsolete and might be removed in a future +release. It has been replaced by \fBlgrp_home\fR(3LGRP). diff --git a/usr/src/man/man3c/getcwd.3c b/usr/src/man/man3c/getcwd.3c new file mode 100644 index 0000000000..8586920b86 --- /dev/null +++ b/usr/src/man/man3c/getcwd.3c @@ -0,0 +1,194 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getcwd 3C "18 Oct 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getcwd \- get pathname of current working directory +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> + +\fBchar *\fR\fBgetcwd\fR(\fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIsize\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetcwd()\fR function places an absolute pathname of the current working +directory in the array pointed to by \fIbuf\fR, and returns \fIbuf\fR. The +pathname copied to the array contains no components that are symbolic links. +The \fIsize\fR argument is the size in bytes of the character array pointed to +by \fIbuf\fR and must be at least one greater than the length of the pathname +to be returned. +.sp +.LP +If \fIbuf\fR is not a null pointer, the pathname is stored in the space pointed +to by \fIbuf\fR. +.sp +.LP +If \fIbuf\fR is a null pointer, \fBgetcwd()\fR obtains \fIsize\fR bytes of +space using \fBmalloc\fR(3C). The pointer returned by \fBgetcwd()\fR can be +used as the argument in a subsequent call to \fBfree()\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBgetcwd()\fR returns the \fIbuf\fR argument. If +\fIbuf\fR is an invalid destination buffer address, \fINULL\fR is returned and +\fBerrno\fR is set to \fBEFAULT\fR. Otherwise, a null pointer is returned and +\fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBgetcwd()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +.rt +The \fIbuf\fR argument is an invalid destination buffer address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIsize\fR argument is equal to 0. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBERANGE\fR\fR +.ad +.RS 10n +.rt +The \fIsize\fR argument is greater than 0 and less than the length of the +pathname plus 1. +.RE + +.sp +.LP +The \fBgetcwd()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 10n +.rt +A parent directory cannot be read to get its name. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient storage space is available. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRDetermine the absolute pathname of the current working +directory. +.sp +.LP +The following example returns a pointer to an array that holds the absolute +pathname of the current working directory. The pointer is returned in the +\fIptr\fR variable, which points to the \fIbuf\fR array where the pathname is +stored. + +.sp +.in +2 +.nf +#include <stdlib.h> +#include <unistd.h> +\&... +long size; +char *buf; +char *ptr; +size = pathconf(".", _PC_PATH_MAX); +if ((buf = (char *)malloc((size_t)size)) != NULL) + ptr = getcwd(buf, (size_t)size); +\&... +.fi +.in -2 + +.LP +\fBExample 2 \fRPrint the current working directory. +.sp +.LP +The following example prints the current working directory. + +.sp +.in +2 +.nf +#include <unistd.h> +#include <stdio.h> + +main(\|) +{ + char *cwd; + if ((cwd = getcwd(NULL, 64)) == NULL) { + perror("pwd"); + exit(2); + } + (void)printf("%s\en", cwd); + free(cwd); /* free memory allocated by getcwd() */ + return(0); +} +.fi +.in -2 + +.SH USAGE +.sp +.LP +Applications should exercise care when using \fBchdir\fR(2) in conjunction with +\fBgetcwd()\fR. The current working directory is global to all threads within a +process. If more than one thread calls \fBchdir()\fR to change the working +directory, a subsequent call to \fBgetcwd()\fR could produce unexpected +results. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBchdir\fR(2), \fBmalloc\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/getdate.3c b/usr/src/man/man3c/getdate.3c new file mode 100644 index 0000000000..1afb84ecd5 --- /dev/null +++ b/usr/src/man/man3c/getdate.3c @@ -0,0 +1,923 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getdate 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getdate \- convert user format date and time +.SH SYNOPSIS +.LP +.nf +#include <time.h> + +\fBstruct tm *\fR\fBgetdate\fR(\fBconst char *\fR\fIstring\fR); +extern int getdate_err; +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetdate()\fR function converts user-definable date and/or time +specifications pointed to by \fIstring\fR to a \fBtm\fR structure. The \fBtm\fR +structure is defined in the <\fBtime.h\fR> header. +.sp +.LP +User-supplied templates are used to parse and interpret the input string. The +templates are text files created by the user and identified via the +environment variable \fBDATEMSK\fR. Each line in the template represents an +acceptable date and/or time specification using conversion specifications +similar to those used by \fBstrftime\fR(3C) and \fBstrptime\fR(3C). Dates +before 1902 and after 2037 are illegal. The first line in the template that +matches the input specification is used for interpretation and conversion into +the internal time format. +.SS "Conversion Specifications" +.sp +.LP +The following conversion specifications are supported: +.sp +.ne 2 +.mk +.na +\fB\fB%%\fR\fR +.ad +.RS 6n +.rt +Same as \fB%\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%a\fR\fR +.ad +.RS 6n +.rt +Locale's abbreviated weekday name. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%A\fR\fR +.ad +.RS 6n +.rt +Locale's full weekday name. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%b\fR\fR +.ad +.RS 6n +.rt +Locale's abbreviated month name. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%B\fR\fR +.ad +.RS 6n +.rt +Locale's full month name. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%c\fR\fR +.ad +.RS 6n +.rt +Locale's appropriate date and time representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%C\fR\fR +.ad +.RS 6n +.rt +Century number (the year divided by 100 and truncated to an integer as a +decimal number [1,99]); single digits are preceded by 0; see +\fBstandards\fR(5). If used without the \fB%y\fR specifier, this format +specifier will assume the current year offset in whichever century is +specified. The only valid years are between 1902-2037. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%d\fR\fR +.ad +.RS 6n +.rt +day of month [01,31]; leading zero is permitted but not required. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%D\fR\fR +.ad +.RS 6n +.rt +Date as \fB%m\fR/\fB%d\fR/\fB%y\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%e\fR\fR +.ad +.RS 6n +.rt +Same as \fB%d\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%h\fR\fR +.ad +.RS 6n +.rt +Locale's abbreviated month name. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%H\fR\fR +.ad +.RS 6n +.rt +Hour (24-hour clock) [0,23]; leading zero is permitted but not required. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%I\fR\fR +.ad +.RS 6n +.rt +Hour (12-hour clock) [1,12]; leading zero is permitted but not required. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%j\fR\fR +.ad +.RS 6n +.rt +Day number of the year [1,366]; leading zeros are permitted but not required. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%m\fR\fR +.ad +.RS 6n +.rt +Month number [1,12]; leading zero is permitted but not required. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%M\fR\fR +.ad +.RS 6n +.rt +Minute [0,59]; leading zero is permitted but not required. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%n\fR\fR +.ad +.RS 6n +.rt +Any white space. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%p\fR\fR +.ad +.RS 6n +.rt +Locale's equivalent of either a.m. or p.m. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%r\fR\fR +.ad +.RS 6n +.rt +Appropriate time representation in the 12-hour clock format with \fB%p\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%R\fR\fR +.ad +.RS 6n +.rt +Time as \fB%H\fR:\fB%M\fR. +.RE + +.SS "SUSv3" +.sp +.ne 2 +.mk +.na +\fB\fB%S\fR\fR +.ad +.RS 6n +.rt +Seconds [0,60]; leading zero is permitted but not required. The range of values +is [00,60] rather than [00,59] to allow for the occasional leap second. +.RE + +.SS "Default and other standards" +.sp +.ne 2 +.mk +.na +\fB\fB%S\fR\fR +.ad +.RS 6n +.rt +Seconds [0,61]; leading zero is permitted but not required. The range of values +is [00,61] rather than [00,59] to allow for the occasional leap second and even +more occasional double leap second. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%t\fR\fR +.ad +.RS 6n +.rt +Any white space. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%T\fR\fR +.ad +.RS 6n +.rt +Time as \fB%H\fR:\fB%M\fR:\fB%S\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%U\fR\fR +.ad +.RS 6n +.rt +Week number of the year as a decimal number [0,53], with Sunday as the first +day of the week; leading zero is permitted but not required. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%w\fR\fR +.ad +.RS 6n +.rt +Weekday as a decimal number [0,6], with 0 representing Sunday. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%W\fR\fR +.ad +.RS 6n +.rt +Week number of the year as a decimal number [0,53], with Monday as the first +day of the week; leading zero is permitted but not required. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%x\fR\fR +.ad +.RS 6n +.rt +Locale's appropriate date representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%X\fR\fR +.ad +.RS 6n +.rt +Locale's appropriate time representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%y\fR\fR +.ad +.RS 6n +.rt +Year within century. When a century is not otherwise specified, values in the +range 69-99 refer to years in the twentieth century (1969 to 1999 inclusive); +values in the range 00-68 refer to years in the twenty-first century (2000 to +2068 inclusive). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Y\fR\fR +.ad +.RS 6n +.rt +Year, including the century (for example, 1993). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Z\fR\fR +.ad +.RS 6n +.rt +Time zone name or no characters if no time zone exists. +.RE + +.SS "Modified Conversion Specifications" +.sp +.LP +Some conversion specifications can be modified by the \fBE\fR and \fBO\fR +modifier characters to indicate that an alternative format or specification +should be used rather than the one normally used by the unmodified +specification. If the alternative format or specification does not exist in the +current locale, the behavior be as if the unmodified conversion specification +were used. +.sp +.ne 2 +.mk +.na +\fB\fB%Ec\fR\fR +.ad +.RS 7n +.rt +Locale's alternative appropriate date and time representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%EC\fR\fR +.ad +.RS 7n +.rt +Name of the base year (period) in the locale's alternative representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Ex\fR\fR +.ad +.RS 7n +.rt +Locale's alternative date representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%EX\fR\fR +.ad +.RS 7n +.rt +Locale's alternative time representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Ey\fR\fR +.ad +.RS 7n +.rt +Offset from \fB%EC\fR (year only) in the locale's alternative representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%EY\fR\fR +.ad +.RS 7n +.rt +Full alternative year representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Od\fR\fR +.ad +.RS 7n +.rt +Day of the month using the locale's alternative numeric symbols; leading zeros +are permitted but not required. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Oe\fR\fR +.ad +.RS 7n +.rt +Same as \fB%Od\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%OH\fR\fR +.ad +.RS 7n +.rt +Hour (24-hour clock) using the locale's alternative numeric symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%OI\fR\fR +.ad +.RS 7n +.rt +Hour (12-hour clock) using the locale's alternative numeric symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Om\fR\fR +.ad +.RS 7n +.rt +Month using the locale's alternative numeric symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%OM\fR\fR +.ad +.RS 7n +.rt +Minutes using the locale's alternative numeric symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%OS\fR\fR +.ad +.RS 7n +.rt +Seconds using the locale's alternative numeric symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%OU\fR\fR +.ad +.RS 7n +.rt +Week number of the year (Sunday as the first day of the week) using the +locale's alternative numeric symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Ow\fR\fR +.ad +.RS 7n +.rt +Number of the weekday (Sunday=0) using the locale's alternative numeric +symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%OW\fR\fR +.ad +.RS 7n +.rt +Week number of the year (Monday as the first day of the week) using the +locale's alternative numeric symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Oy\fR\fR +.ad +.RS 7n +.rt +Year (offset from \fB%C\fR) in the locale's alternative representation and +using the locale's alternative numeric symbols. +.RE + +.SS "Internal Format Conversion" +.sp +.LP +The following rules are applied for converting the input specification into the +internal format: +.RS +4 +.TP +.ie t \(bu +.el o +If only the weekday is given, today is assumed if the given day is equal to the +current day and next week if it is less. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If only the month is given, the current month is assumed if the given month is +equal to the current month and next year if it is less and no year is given. +(The first day of month is assumed if no day is given.) +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If only the year is given, the values of the \fBtm_mon\fR, \fBtm_mday\fR, +\fBtm_yday\fR, \fBtm_wday\fR, and \fBtm_isds\fRt members of the returned +\fBtm\fR structure are not specified. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If the century is given, but the year within the century is not given, the +current year within the century is assumed. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If no hour, minute, and second are given, the current hour, minute, and second +are assumed. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If no date is given, today is assumed if the given hour is greater than the +current hour and tomorrow is assumed if it is less. +.RE +.SS "General Specifications" +.sp +.LP +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 conversion specification, the +specification fails, and the differing and subsequent characters remain +unscanned. +.sp +.LP +A series of conversion specifications composed of \fB%n\fR, \fB%t\fR, 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. +.sp +.LP +Any other conversion specification is executed by scanning characters until a +character matching the next conversion specification is scanned, or until no +more characters can be scanned. These characters, except the one matching the +next conversion specification, are then compared to the locale values +associated with the conversion specifier. If a match is found, values for the +appropriate \fItm\fR structure members are set to values corresponding to the +locale information. If no match is found, \fBgetdate()\fR fails and no more +characters are scanned. +.sp +.LP +The month names, weekday names, era names, and alternative numeric symbols can +consist of any combination of upper and lower case letters. The user can +request that the input date or time specification be in a specific language by +setting the \fBLC_TIME\fR category using \fBsetlocale\fR(3C). +.SH RETURN VALUES +.sp +.LP +If successful, \fBgetdate()\fR returns a pointer to a \fBtm\fR structure; +otherwise, it returns \fINULL\fR and sets the global variable \fBgetdate_err\fR +to indicate the error. Subsequent calls to \fBgetdate()\fR alter the contents +of \fBgetdate_err\fR. +.sp +.LP +The following is a complete list of the \fBgetdate_err\fR settings and their +meanings: +.sp +.ne 2 +.mk +.na +\fB\fB1\fR\fR +.ad +.RS 5n +.rt +The \fBDATEMSK\fR environment variable is null or undefined. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB2\fR\fR +.ad +.RS 5n +.rt +The template file cannot be opened for reading. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB3\fR\fR +.ad +.RS 5n +.rt +Failed to get file status information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB4\fR\fR +.ad +.RS 5n +.rt +The template file is not a regular file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB5\fR\fR +.ad +.RS 5n +.rt +An error is encountered while reading the template file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB6\fR\fR +.ad +.RS 5n +.rt +The \fBmalloc()\fR function failed (not enough memory is available). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB7\fR\fR +.ad +.RS 5n +.rt +There is no line in the template that matches the input. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB8\fR\fR +.ad +.RS 5n +.rt +The input specification is invalid (for example, \fBFebruary 31\fR). +.RE + +.SH USAGE +.sp +.LP +The \fBgetdate()\fR function makes explicit use of macros described on the +\fBctype\fR(3C) manual page. +.SH EXAMPLES +.LP +\fBExample 1 \fRExamples of the \fBgetdate()\fR function. +.sp +.LP +The following example shows the possible contents of a template: + +.sp +.in +2 +.nf +%m +%A %B %d %Y, %H:%M:%S +%A +%B +%m/%d/%y %I %p +%d,%m,%Y %H:%M +at %A the %dst of %B in %Y +run job at %I %p,%B %dnd +%A den %d. %B %Y %H.%M Uhr +.fi +.in -2 + +.sp +.LP +The following are examples of valid input specifications for the above +template: + +.sp +.in +2 +.nf +getdate("10/1/87 4 PM") +getdate("Friday") +getdate("Friday September 19 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 +.in -2 + +.sp +.LP +If the \fBLANG\fR environment variable is set to \fBde\fR (German), the +following is valid: + +.sp +.in +2 +.nf +getdate("freitag den 10. oktober 1986 10.30 Uhr") +.fi +.in -2 + +.sp +.LP +Local time and date specification are also supported. The following examples +show how local date and time specification can be defined in the template. + +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +InvocationLine 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 + +.sp +.LP +The following examples illustrate the Internal Format Conversion rules. Assume +that the current date is Mon Sep 22 12:19:47 EDT 1986 and the \fBLANG\fR +environment variable is not set. + +.sp + +.sp +.TS +tab() box; +lw(1.32i) |lw(1.39i) |lw(2.79i) +lw(1.32i) |lw(1.39i) |lw(2.79i) +. +InputTemplate Line Date +_ +\fBMon\fR\fB%a\fRMon Sep 22 12:19:48 EDT 1986 +\fBSun\fR\fB%a\fRSun Sep 28 12:19:49 EDT 1986 +\fBFri\fR\fB%a\fRFri Sep 26 12:19:49 EDT 1986 +\fBSeptember\fR\fB%B\fRMon Sep 1 12:19:49 EDT 1986 +\fBJanuary\fR\fB%B\fRThu Jan 1 12:19:49 EST 1987 +\fBDecember\fR\fB%B\fRMon Dec 1 12:19:49 EDT 1986 +\fBSep Mon\fR\fB%b %a\fRMon Sep 1 12:19:50 EDT 1986 +\fBJan Fri\fR\fB%b %a\fRFri Jan 2 12:19:50 EST 1987 +\fBDec Mon\fR\fB%b %a\fRMon Dec 1 12:19:50 EST 1986 +\fBJan Wed 1989\fR\fB%b\fR \fB%a\fR \fB%Y\fRWed Jan 4 12:19:51 EST 1989 +\fBFri 9\fR\fB%a %H\fRFri Sep 26 09:00:00 EDT 1986 +\fBFeb 10:30\fR\fB%b %H:%S\fRSun Feb 1 10:00:30 EST 1987 +\fB10:30\fR\fB%H:%M\fRTue Sep 23 10:30:00 EDT 1986 +\fB13:30\fR\fB%H:%M\fRMon Sep 22 13:30:00 EDT 1986 +.TE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +CSIEnabled +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBctype\fR(3C), \fBmktime\fR(3C), \fBsetlocale\fR(3C), \fBstrftime\fR(3C), +\fBstrptime\fR(3C), \fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/getdtablesize.3c b/usr/src/man/man3c/getdtablesize.3c new file mode 100644 index 0000000000..845654303a --- /dev/null +++ b/usr/src/man/man3c/getdtablesize.3c @@ -0,0 +1,48 @@ +'\" te +.\" Copyright (c) 1983 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. +.\" Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.TH getdtablesize 3C "1 Mar 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getdtablesize \- get the file descriptor table size +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> + +\fBint\fR \fBgetdtablesize\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetdtablesize()\fR function is equivalent to \fBgetrlimit\fR(2) with the +\fBRLIMIT_NOFILE\fR option. +.SH RETURN VALUES +.sp +.LP +The \fBgetdtablesize()\fR function returns the current soft limit as if +obtained from a call to \fBgetrlimit()\fR with the \fBRLIMIT_NOFILE\fR option. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH USAGE +.sp +.LP +There is no direct relationship between the value returned by +\fBgetdtablesize()\fR and \fBOPEN_MAX\fR defined in <\fBlimits.h\fR>. +.sp +.LP +Each process has a file descriptor table which is guaranteed to have at least +20 slots. The entries in the descriptor table are numbered with small integers +starting at 0. The \fBgetdtablesize()\fR function returns the current maximum +size of this table by calling the \fBgetrlimit()\fR function. +.SH SEE ALSO +.sp +.LP +\fBclose\fR(2), \fBgetrlimit\fR(2), \fBopen\fR(2), \fBsetrlimit\fR(2), +\fBselect\fR(3C) diff --git a/usr/src/man/man3c/getenv.3c b/usr/src/man/man3c/getenv.3c new file mode 100644 index 0000000000..7ca9b00658 --- /dev/null +++ b/usr/src/man/man3c/getenv.3c @@ -0,0 +1,62 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getenv 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getenv \- return value for environment name +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBchar *\fR\fBgetenv\fR(\fBconst char *\fR\fIname\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetenv()\fR function searches the environment list (see +\fBenviron\fR(5)) for a string of the form \fIname\fR\fB=\fR\fIvalue\fR and, if +the string is present, returns a pointer to the \fIvalue\fR in the current +environment. +.SH RETURN VALUES +.sp +.LP +If successful, \fBgetenv()\fR returns a pointer to the \fIvalue\fR in the +current environment; otherwise, it returns a null pointer. +.SH USAGE +.sp +.LP +The \fBgetenv()\fR function can be safely called from a multithreaded +application. Care must be exercised when using both \fBgetenv()\fR and +\fBputenv\fR(3C) in a multithreaded application. These functions examine and +modify the environment list, which is shared by all threads in an application. +The system prevents the list from being accessed simultaneously by two +different threads. It does not, however, prevent two threads from successively +accessing the environment list using \fBgetenv()\fR or \fBputenv\fR(3C). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBexec\fR(2), \fBputenv\fR(3C), \fBattributes\fR(5), \fBenviron\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/getexecname.3c b/usr/src/man/man3c/getexecname.3c new file mode 100644 index 0000000000..38644dee93 --- /dev/null +++ b/usr/src/man/man3c/getexecname.3c @@ -0,0 +1,68 @@ +'\" te +.\" Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getexecname 3C "17 Dec 1997" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getexecname \- return pathname of executable +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBconst char *\fR\fBgetexecname\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetexecname()\fR function returns the pathname (the first argument of +one of the \fBexec\fR family of functions; see \fBexec\fR(2)) of the executable +that started the process. +.sp +.LP +Normally this is an absolute pathname, as the majority of commands are executed +by the shells that append the command name to the user's \fBPATH\fR components. +If this is not an absolute path, the output of \fBgetcwd\fR(3C) can be +prepended to it to create an absolute path, unless the process or one of its +ancestors has changed its root directory or current working directory since the +last successful call to one of the \fBexec\fR family of functions. +.SH RETURN VALUES +.sp +.LP +If successful, \fBgetexecname()\fR returns a pointer to the executables +pathname; otherwise, it returns \fB0\fR. +.SH USAGE +.sp +.LP +The \fBgetexecname()\fR function obtains the executable pathname from the +\fBAT_SUN_EXECNAME\fR aux vector. These vectors are made available to +dynamically linked processes only. +.sp +.LP +A successful call to one of the \fBexec\fR family of functions will always have +\fBAT_SUN_EXECNAME\fR in the aux vector. The associated pathname is guaranteed +to be less than or equal to \fIPATH_MAX\fR, not counting the trailing null byte +that is always present. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBexec\fR(2), \fBgetcwd\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/getgrnam.3c b/usr/src/man/man3c/getgrnam.3c new file mode 100644 index 0000000000..6dad0149bc --- /dev/null +++ b/usr/src/man/man3c/getgrnam.3c @@ -0,0 +1,409 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getgrnam 3C "5 Apr 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getgrnam, getgrnam_r, getgrent, getgrent_r, getgrgid, getgrgid_r, setgrent, +endgrent, fgetgrent, fgetgrent_r \- group database entry functions +.SH SYNOPSIS +.LP +.nf +#include <grp.h> + +\fBstruct group *\fR\fBgetgrnam\fR(\fBconst char *\fR\fIname\fR); +.fi + +.LP +.nf +\fBstruct group *\fR\fBgetgrnam_r\fR(\fBconst char *\fR\fIname\fR, \fBstruct group *\fR\fIgrp\fR, + \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbufsize\fR); +.fi + +.LP +.nf +\fBstruct group *\fR\fBgetgrent\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBstruct group *\fR\fBgetgrent_r\fR(\fBstruct group *\fR\fIgrp\fR, \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbufsize\fR); +.fi + +.LP +.nf +\fBstruct group *\fR\fBgetgrgid\fR(\fBgid_t\fR \fIgid\fR); +.fi + +.LP +.nf +\fBstruct group *\fR\fBgetgrgid_r\fR(\fBgid_t\fR \fIgid\fR, \fBstruct group *\fR\fIgrp\fR, \fBchar *\fR\fIbuffer\fR, + \fBint\fR \fIbufsize\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBsetgrent\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBendgrent\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBstruct group *\fR\fBfgetgrent\fR(\fBFILE *\fR\fIf\fR); +.fi + +.LP +.nf +\fBstruct group *\fR\fBfgetgrent_r\fR(\fBFILE *\fR\fIf\fR, \fBstruct group *\fR\fIgrp\fR, \fBchar *\fR\fIbuffer\fR, + \fBint\fR \fIbufsize\fR); +.fi + +.SS "Standard comforming" +.LP +.nf +cc [ \fIflag\fR... ] \fIfile\fR... \fB-D_POSIX_PTHREAD_SEMANTICS\fR [ \fIlibrary\fR... ] + +\fBint\fR \fBgetgrnam_r\fR(\fBconst char *\fR\fIname\fR, \fBstruct group *\fR\fIgrp\fR, \fBchar *\fR\fIbuffer\fR, + \fBsize_t\fR \fIbufsize\fR, \fBstruct group **\fR\fIresult\fR); +.fi + +.LP +.nf +\fBint\fR \fBgetgrgid_r\fR(\fBgid_t\fR \fIgid\fR, \fBstruct group *\fR\fIgrp\fR, \fBchar *\fR\fIbuffer\fR, + \fBsize_t\fR \fIbufsize\fR, \fBstruct group **\fR\fIresult\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions are used to obtain entries describing user groups. Entries can +come from any of the sources for \fBgroup\fR specified in the +\fB/etc/nsswitch.conf\fR file (see \fBnsswitch.conf\fR(4)). +.sp +.LP +The \fBgetgrnam()\fR function searches the group database for an entry with the +group name specified by the character string parameter \fIname\fR. +.sp +.LP +The \fBgetgrgid()\fR function searches the group database for an entry with the +(numeric) group id specified by \fIgid\fR. +.sp +.LP +The \fBsetgrent()\fR, \fBgetgrent()\fR, and \fBendgrent()\fR functions are used +to enumerate group entries from the database. +.sp +.LP +The \fBsetgrent()\fR function effectively rewinds the group database to allow +repeated searches. It sets (or resets) the enumeration to the beginning of the +set of group entries. This function should be called before the first call to +\fBgetgrent()\fR. +.sp +.LP +The \fBgetgrent()\fR function returns a pointer to a structure containing the +broken-out fields of an entry in the group database. When first called, +\fBgetgrent()\fR returns a pointer to a \fBgroup\fR structure containing the +next group structure in the group database. Successive calls can be used to +search the entire database. +.sp +.LP +The \fBendgrent()\fR function can be called to close the group database and +deallocate resources when processing is complete. It is permissible, though +possibly less efficient, for the process to call more group functions after +calling \fBendgrent()\fR. +.sp +.LP +The \fBfgetgrent()\fR function, unlike the other functions above, does not use +\fBnsswitch.conf\fR. It reads and parses the next line from the stream \fIf\fR, +which is assumed to have the format of the \fBgroup\fR file (see +\fBgroup\fR(4)). +.SS "Reentrant Interfaces" +.sp +.LP +The \fBgetgrnam()\fR, \fBgetgrgid()\fR, \fBgetgrent()\fR, and +\fBfgetgrent()\fR functions use thread-specific storage that is reused in each +call to one of these functions by the same thread, making them safe to use but +not recommended for multithreaded applications. +.sp +.LP +The parallel functions \fBgetgrnam_r()\fR, \fBgetgrgid_r()\fR, +\fBgetgrent_r()\fR, and \fBfgetgrent_r()\fR provide reentrant interfaces for +these operations. +.sp +.LP +Each reentrant interface performs the same operation as its non-reentrant +counterpart, named by removing the \fB_r\fR suffix. The reentrant interfaces, +however, use buffers supplied by the caller to store returned results instead +of using thread-specific data that can be overwritten by each call. They are +safe for use in both single-threaded and multithreaded applications. +.sp +.LP +Each reentrant interface takes the same arguments as its non-reentrant +counterpart, as well as the following additional parameters. The \fIgrp\fR +argument must be a pointer to a \fBstruct group\fR structure allocated by the +caller. On successful completion, the function returns the group entry in this +structure. Storage referenced by the group structure is allocated from the +memory provided with the \fIbuffer\fR argument that is \fIbufsize\fR characters +in size. The maximum size needed for this buffer can be determined with the +\fB_SC_GETGR_R_SIZE_MAX\fR \fBsysconf\fR(3C) parameter. The standard-conforming +versions place a pointer to the modified \fIgrp\fR structure in the +\fIresult\fR parameter, instead of returning a pointer to this structure. A +null pointer is returned at the location pointed to by \fIresult\fR on error or +if the requested entry is not found. +.sp +.LP +For enumeration in multithreaded applications, the position within the +enumeration is a process-wide property shared by all threads. The +\fBsetgrent()\fR function can be used in a multithreaded application but resets +the enumeration position for all threads. If multiple threads interleave calls +to \fBgetgrent_r()\fR, the threads will enumerate disjoint subsets of the group +database. Like their non-reentrant counterparts, \fBgetgrnam_r()\fR and +\fBgetgrgid_r()\fR leave the enumeration position in an indeterminate state. +.SS "group Structure" +.sp +.LP +Group entries are represented by the \fBstruct group\fR structure defined in +<\fBgrp.h\fR>: +.sp +.in +2 +.nf +struct group { + char *gr_name; /* the name of the group */ + char *gr_passwd; /* the encrypted group password */ + gid_t gr_gid; /* the numerical group ID */ + char **gr_mem; /* vector of pointers to member + names */ +}; +.fi +.in -2 + +.SH RETURN VALUES +.sp +.LP +The \fBgetgrnam()\fR, \fBgetgrnam_r()\fR, \fBgetgrgid()\fR, and +\fBgetgrgid_r()\fR functions each return a pointer to a \fBstruct group\fR if +they successfully locate the requested entry. They return a null pointer if +either the requested entry was not found or an error occurred. On error, +\fBerrno\fR is set to indicate the error. The standard-conforming functions +\fBgetgrnam_r()\fR and \fBgetgrgid_r()\fR return \fB0\fR upon success or an +error number in case of failure. +.sp +.LP +The \fBgetgrent()\fR, \fBgetgrent_r()\fR, \fBfgetgrent()\fR, and +\fBfgetgrent_r()\fR functions each return a pointer to a \fBstruct group\fR if +they successfully enumerate an entry; otherwise they return a null pointer on +end-of-file or error. On error, \fBerrno\fR is set to indicate the error. +.sp +.LP +The \fBgetgrnam()\fR, \fBgetgrgid()\fR, \fBgetgrent()\fR, and \fBfgetgrent()\fR +functions use thread-specific data storage, so returned data must be copied +before a subsequent call to any of these functions if the data are to be saved. +.sp +.LP +When the pointer returned by the reentrant functions \fBgetgrnam_r()\fR, +\fBgetgrgid_r()\fR, \fBgetgrent_r()\fR, and \fBfgetgrent_r()\fR is non-null, it +is always equal to the \fIgrp\fR pointer that was supplied by the caller. +.sp +.LP +Applications wishing to check for error situations should set \fBerrno\fR to 0 +before calling \fBgetgrnam()\fR, \fBgetgrnam_r()\fR, \fBgetgrent()\fR, +\fBgetgrent_r()\fR\fBgetgrgid()\fR, \fBgetgrgid_r()\fR, \fBfgetgrent()\fR, and +\fBfgetgrent_r()\fR. If these functions return a null pointer and \fBerrno\fR +is non-zero, an error occurred. +.SH ERRORS +.sp +.LP +The \fBgetgrent_r()\fR, \fBfgetgrent()\fR, and \fBfgetgrent_r()\fR functions +will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 10n +.rt +An I/O error has occurred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBERANGE\fR\fR +.ad +.RS 10n +.rt +Insufficient storage was supplied by \fIbuffer\fR and \fIbufsize\fR to contain +the data to be referenced by the resulting \fBgroup\fR structure. +.RE + +.sp +.LP +The \fBgetgrent_r()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 10n +.rt +There are {\fBOPEN_MAX\fR} file descriptors currently open in the calling +process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENFILE\fR\fR +.ad +.RS 10n +.rt +The maximum allowable number of files is currently open in the system. +.RE + +.sp +.LP +The \fBgetgrnam()\fR, \fBgetgrnam_r()\fR, \fBgetgrgid()\fR, \fBgetgrgid_r()\fR, +and \fBgetgrent()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 10n +.rt +A signal was caught during the operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 10n +.rt +An I/O error has occurred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 10n +.rt +There are {\fBOPEN_MAX\fR} file descriptors currently open in the calling +process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENFILE\fR\fR +.ad +.RS 10n +.rt +The maximum allowable number of files is currently open in the system. +.RE + +.sp +.LP +The \fBgetgrnam_r()\fR and \fBgetgrgid_r()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBERANGE\fR\fR +.ad +.RS 10n +.rt +Insufficient storage was supplied by \fIbuffer\fR and \fIbufsize\fR to contain +the data to be referenced by the resulting \fBgroup\fR structure. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilitySee below. +_ +MT-LevelSee \fBReentrant Interfaces\fR in \fBDESCRIPTION\fR. +.TE + +.sp +.LP +The \fBendgrent()\fR, \fBgetgrent()\fR, \fBgetgrgid()\fR, \fBgetgrgid_r()\fR, +\fBgetgrnam()\fR, \fBgetgrnam_r()\fR, and \fBsetgrent()\fR functions are +Standard. +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(3), \fBgetpwnam\fR(3C), \fBgroup\fR(4), \fBnsswitch.conf\fR(4), +\fBpasswd\fR(4), \fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +When compiling multithreaded programs, see \fBIntro\fR(3). +.sp +.LP +Use of the enumeration interfaces \fBgetgrent()\fR and \fBgetgrent_r()\fR is +discouraged; enumeration is supported for the group file, \fBNIS,\fR and +\fBNIS+,\fR but in general is not efficient and might not be supported for all +database sources. The semantics of enumeration are discussed further in +\fBnsswitch.conf\fR(4). +.sp +.LP +Previous releases allowed the use of ``+'' and ``-'' entries in +\fB/etc/group\fR to selectively include and exclude entries from \fBNIS.\fR The +primary usage of these entries is superseded by the name service switch, so the +``+/-'' form might not be supported in future releases. +.sp +.LP +If required, the ``+/-'' functionality can still be obtained for \fBNIS\fR by +specifying \fBcompat\fR as the source for \fBgroup\fR. +.sp +.LP +If the ``+/-'' functionality is required in conjunction with \fBNIS+,\fR +specify both \fBcompat\fR as the source for \fBgroup\fR and \fBnisplus\fR as +the source for the pseudo-database \fBgroup_compat\fR. See \fBgroup\fR(4), and +\fBnsswitch.conf\fR(4) for details. +.sp +.LP +Solaris 2.4 and earlier releases provided definitions of the \fBgetgrnam_r()\fR +and \fBgetgrgid_r()\fR functions as specified in POSIX.1c Draft 6. The final +POSIX.1c standard changed the interface for these functions. Support for the +Draft 6 interface is provided for compatibility only and might not be supported +in future releases. New applications and libraries should use the +standard-conforming interface. +.sp +.LP +For POSIX.1c-conforming applications, the \fB_POSIX_PTHREAD_SEMANTICS\fR and +\fB_REENTRANT\fR flags are automatically turned on by defining the +\fB_POSIX_C_SOURCE\fR flag with a value \(>=199506L. diff --git a/usr/src/man/man3c/gethostid.3c b/usr/src/man/man3c/gethostid.3c new file mode 100644 index 0000000000..0ab230d20c --- /dev/null +++ b/usr/src/man/man3c/gethostid.3c @@ -0,0 +1,54 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH gethostid 3C "29 Jan 2009" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +gethostid \- get an identifier for the current host +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> + +\fBlong\fR \fBgethostid\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgethostid()\fR function returns the 32-bit identifier for the current +host. If the hardware capability exists, this identifier is taken from +platform-dependent stable storage; otherwise it is a randomly generated number. +It is not guaranteed to be unique. +.sp +.LP +If the calling thread's process is executing within a non-global zone that +emulates a host identifier, then the zone's emulated 32-bit host identifier is +returned. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBhostid\fR(1), \fBsysinfo\fR(2), \fBattributes\fR(5), \fBstandards\fR(5), +\fBzones\fR(5) diff --git a/usr/src/man/man3c/gethostname.3c b/usr/src/man/man3c/gethostname.3c new file mode 100644 index 0000000000..6d8a0bcdda --- /dev/null +++ b/usr/src/man/man3c/gethostname.3c @@ -0,0 +1,93 @@ +'\" te +.\" Copyright (c) 1983 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.TH gethostname 3C "22 Mar 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +gethostname, sethostname \- get or set name of current host +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> + +\fBint\fR \fBgethostname\fR(\fBchar *\fR\fIname\fR, \fBint\fR \fInamelen\fR); +.fi + +.LP +.nf +\fBint\fR \fBsethostname\fR(\fBchar *\fR\fIname\fR, \fBint\fR \fInamelen\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgethostname()\fR function returns the standard host name for the current +processor, as previously set by \fBsethostname()\fR. The \fInamelen\fR +argument specifies the size of the array pointed to by \fIname\fR. The returned +name is null-terminated unless insufficient space is provided. +.sp +.LP +The \fBsethostname()\fR function sets the name of the host machine to be +\fIname\fR, which has length \fInamelen\fR. This call is restricted to the +superuser and is normally used only when the system is bootstrapped. +.sp +.LP +Host names are limited to \fBMAXHOSTNAMELEN\fR characters, currently 256, +defined in the <\fBnetdb.h\fR> header. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBgethostname()\fR and \fBsethostname()\fR return +0. Otherwise, they return \(mi1 and set \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBgethostname()\fR and \fBsethostname()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +.rt +The \fIname\fR or \fInamelen\fR argument gave an invalid address. +.RE + +.sp +.LP +The \fBsethostname()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 9n +.rt +The {\fBPRIV_SYS_ADMIN\fR} privilege was not asserted in the effective set of +the calling process. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBsysinfo\fR(2), \fBuname\fR(2), \fBgethostid\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/gethrtime.3c b/usr/src/man/man3c/gethrtime.3c new file mode 100644 index 0000000000..5e8049c244 --- /dev/null +++ b/usr/src/man/man3c/gethrtime.3c @@ -0,0 +1,88 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH gethrtime 3C "7 Sep 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +gethrtime, gethrvtime \- get high resolution time +.SH SYNOPSIS +.LP +.nf +#include <sys/time.h> + +\fBhrtime_t\fR \fBgethrtime\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBhrtime_t\fR \fBgethrvtime\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgethrtime()\fR function returns the current high-resolution real time. +Time is expressed as nanoseconds since some arbitrary time in the past; it is +not correlated in any way to the time of day, and thus is not subject to +resetting or drifting by way of \fBadjtime\fR(2) or \fBsettimeofday\fR(3C). The +hi-res timer is ideally suited to performance measurement tasks, where cheap, +accurate interval timing is required. +.sp +.LP +The \fBgethrvtime()\fR function returns the current high-resolution LWP virtual +time, expressed as total nanoseconds of execution time. +.sp +.LP +The \fBgethrtime()\fR and \fBgethrvtime()\fR functions both return an +\fBhrtime_t,\fR which is a 64-bit (\fBlong long\fR) signed integer. +.SH EXAMPLES +.sp +.LP +The following code fragment measures the average cost of \fBgetpid\fR(2): +.sp +.in +2 +.nf +\fBhrtime_t start, end; +int i, iters = 100; + +start = gethrtime(); +for (i = 0; i < iters; i++) + getpid(); +end = gethrtime(); + +printf("Avg getpid() time = %lld nsec\en", (end \(mi start) / iters);\fR +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBproc\fR(1), \fBadjtime\fR(2), \fBgettimeofday\fR(3C), +\fBsettimeofday\fR(3C), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +Although the units of hi-res time are always the same (nanoseconds), the actual +resolution is hardware dependent. Hi-res time is guaranteed to be monotonic +(it won't go backward, it won't periodically wrap) and linear (it won't +occasionally speed up or slow down for adjustment, like the time of day can), +but not necessarily unique: two sufficiently proximate calls may return the +same value. diff --git a/usr/src/man/man3c/getloadavg.3c b/usr/src/man/man3c/getloadavg.3c new file mode 100644 index 0000000000..cf82d3457b --- /dev/null +++ b/usr/src/man/man3c/getloadavg.3c @@ -0,0 +1,76 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getloadavg 3C "28 Jun 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getloadavg \- get system load averages +.SH SYNOPSIS +.LP +.nf +#include <sys/loadavg.h> + +\fBint\fR \fBgetloadavg\fR(\fBdouble\fR \fIloadavg\fR[\|], \fBint\fR \fInelem\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetloadavg()\fR function returns the number of processes in the system +run queue averaged over various periods of time. Up to \fInelem\fR samples are +retrieved and assigned to successive elements of \fIloadavg\fR[\|]. The system +imposes a maximum of 3 samples, representing averages over the last 1, 5, and +15 minutes, respectively. The \fBLOADAVG_1MIN\fR, \fBLOADAVG_5MIN\fR, and +\fBLOADAVG_15MIN\fR indices, defined in <\fBsys/loadavg.h\fR>, can be used to +extract the data from the appropriate element of the \fIloadavg\fR\fB[\|]\fR +array. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the number of samples actually retrieved is +returned. If the load average was unobtainable, \fB\(mi1\fR is returned and +\fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBgetloadavg()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The number of elements specified is less than 0. +.RE + +.SH USAGE +.sp +.LP +If the caller is in a non-global zone and the pools facility is active, the +behavior of \fBgetloadavg()\fR is equivalent to that of +\fBpset_getloadavg\fR(3C) called with \fIpsetid\fR set to \fBPS_MYID\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelAsync-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBuptime\fR(1), \fBw\fR(1), \fBpooladm\fR(1M), \fBKstat\fR(3PERL), +\fBpset_getloadavg\fR(3C), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/getlogin.3c b/usr/src/man/man3c/getlogin.3c new file mode 100644 index 0000000000..c097067878 --- /dev/null +++ b/usr/src/man/man3c/getlogin.3c @@ -0,0 +1,207 @@ +'\" te +.\" Copyright (c) 2004 Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getlogin 3C "18 May 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getlogin, getlogin_r \- get login name +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> + +\fBchar *\fR\fBgetlogin\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBgetlogin_r\fR(\fBchar *\fR\fIname\fR, \fBint\fR \fInamelen\fR); +.fi + +.SS "Standard conforming" +.LP +.nf +cc [ \fIflag \fR... ] \fIfile\fR... \fB-D_POSIX_PTHREAD_SEMANTICS\fR [ \fIlibrary \fR... ] + +\fBint\fR \fBgetlogin_r\fR(\fBchar *\fR\fIname\fR, \fBsize_t\fR \fInamesize\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetlogin()\fR function returns a pointer to the login name as found in +\fB/var/adm/utmpx\fR. It can be used in conjunction with \fBgetpwnam\fR(3C) to +locate the correct password file entry when the same user \fBID\fR is shared by +several login names. +.sp +.LP +If \fBgetlogin()\fR is called within a process that is not attached to a +terminal, it returns a null pointer. The correct procedure for determining the +login name is to call \fBcuserid\fR(3C), or to call \fBgetlogin()\fR and if it +fails to call \fBgetpwuid\fR(3C). +.sp +.LP +The \fBgetlogin_r()\fR function has the same functionality as \fBgetlogin()\fR +except that the caller must supply a buffer \fIname\fR with length +\fInamelen\fR to store the result. The \fIname\fR buffer must be at least +\fB_POSIX_LOGIN_NAME_MAX\fR bytes in size (defined in <\fBlimits.h\fR>). The +POSIX version (see \fBstandards\fR(5)) of \fBgetlogin_r()\fR takes a +\fInamesize\fR parameter of type \fBsize_t\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBgetlogin()\fR returns a pointer to the login +name or a null pointer if the user's login name cannot be found. Otherwise it +returns a null pointer and sets \fBerrno\fR to indicate the error. +.sp +.LP +The standard-conforming \fBgetlogin_r()\fR returns \fB0\fR if successful, or +the error number upon failure. +.SH ERRORS +.sp +.LP +The \fBgetlogin_r()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBERANGE\fR\fR +.ad +.RS 10n +.rt +The size of the buffer is smaller than the result to be returned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +And entry for the current user was not found in the \fB/var/adm/utmpx\fR file. +.RE + +.sp +.LP +The \fBgetlogin()\fR and \fBgetlogin_r()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 10n +.rt +There are {\fBOPEN_MAX\fR} file descriptors currently open in the calling +process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENFILE\fR\fR +.ad +.RS 10n +.rt +The maximum allowable number of files is currently open in the system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENXIO\fR\fR +.ad +.RS 10n +.rt +The calling process has no controlling terminal. +.RE + +.sp +.LP +The \fBgetlogin_r()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBERANGE\fR\fR +.ad +.RS 10n +.rt +The size of the buffer is smaller than the result to be returned. +.RE + +.SH USAGE +.sp +.LP +The return value of \fBgetlogin()\fR points to thread-specific data whose +content is overwritten on each call by the same thread. +.sp +.LP +Three names associated with the current process can be determined: +\fBgetpwuid(\fR\fBgeteuid()\fR\fB)\fR returns the name associated with the +effective user ID of the process; \fBgetlogin()\fR returns the name associated +with the current login activity; and \fBgetpwuid(\fR\fBgetuid()\fR\fB)\fR +returns the name associated with the real user ID of the process. +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/var/adm/utmpx\fR\fR +.ad +.RS 18n +.rt +user access and administration information +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSee below. +.TE + +.SH SEE ALSO +.sp +.LP +\fBgeteuid\fR(2), \fBgetuid\fR(2), \fBcuserid\fR(3C), \fBgetgrnam\fR(3C), +\fBgetpwnam\fR(3C), \fBgetpwuid\fR(3C), \fButmpx\fR(4), \fBattributes\fR(5), +\fBstandards\fR(5) +.SH NOTES +.sp +.LP +When compiling multithreaded programs, see \fBIntro\fR(3). +.sp +.LP +The \fBgetlogin()\fR function is safe to use in multithreaded applications, but +is discouraged. The \fBgetlogin_r()\fR function should be used instead. +.sp +.LP +Solaris 2.4 and earlier releases provided a \fBgetlogin_r()\fR as specified in +POSIX.1c Draft 6. The final POSIX.1c standard changed the interface as +described above. Support for the Draft 6 interface is provided for +compatibility only and may not be supported in future releases. New +applications and libraries should use the standard-conforming interface. diff --git a/usr/src/man/man3c/getmntent.3c b/usr/src/man/man3c/getmntent.3c new file mode 100644 index 0000000000..4ebbe0d446 --- /dev/null +++ b/usr/src/man/man3c/getmntent.3c @@ -0,0 +1,189 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getmntent 3C "22 Mar 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getmntent, getmntany, getextmntent, hasmntopt, putmntent, resetmnttab \- get +mounted device information +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> +#include <sys/mnttab.h> + +\fBint\fR \fBgetmntent\fR(\fBFILE *\fR\fIfp\fR, \fBstruct mnttab *\fR\fImp\fR); +.fi + +.LP +.nf +\fBint\fR \fBgetmntany\fR(\fBFILE *\fR\fIfp\fR, \fBstruct mnttab *\fR\fImp\fR, \fBstruct mnttab *\fR\fImpref\fR); +.fi + +.LP +.nf +\fBint\fR \fBgetextmntent\fR(\fBFILE *\fR\fIfp\fR, \fBstruct extmnttab *\fR\fImp\fR, \fBint\fR \fIlen\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBhasmntopt\fR(\fBstruct mnttab *\fR\fImnt\fR, \fBchar *\fR\fIopt\fR); +.fi + +.LP +.nf +\fBint\fR \fBputmntent\fR(\fBFILE *\fR\fIiop\fR, \fBstruct mnttab *\fR\fImp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBresetmnttab\fR(\fBFILE *\fR\fIfp\fR); +.fi + +.SH DESCRIPTION +.SS "\fBgetmntent()\fR and \fBgetmntany()\fR" +.sp +.LP +The \fBgetmntent()\fR and \fBgetmntany()\fR functions each fill in the +structure pointed to by \fImp\fR with the broken-out fields of a line in the +\fBmnttab\fR file. Each line read from the file contains a \fBmnttab\fR +structure, which is defined in the <\fBsys/mnttab.h\fR> header. The structure +contains the following members, which correspond to the broken-out fields from +a line in \fB/etc/mnttab\fR (see \fBmnttab\fR(4)). +.sp +.in +2 +.nf +char *mnt_special; /* name of mounted resource */ +char *mnt_mountp; /* mount point */ +char *mnt_fstype; /* type of file system mounted */ +char *mnt_mntopts; /* options for this mount */ +char *mnt_time; /* time file system mounted */ +.fi +.in -2 + +.sp +.LP +Fields with no actual content in \fB/etc/mnttab\fR are represented in the file +as "-". To clearly distinguish empty fields, \fBgetmntent()\fR set the +corresponding field in \fImp\fR to \fINULL\fR. +.sp +.LP +Each \fBgetmntent()\fR call causes a new line to be read from the \fBmnttab\fR +file. Successive calls can be used to search the entire list. The +\fBgetmntany()\fR function searches the file referenced by \fIfp\fR until a +match is found between a line in the file and \fImpref\fR. A match occurs if +all non-null entries in \fImpref\fR match the corresponding fields in the file. +These functions do not open, close, or rewind the file. +.SS "\fBgetextmntent()\fR" +.sp +.LP +The \fBgetextmntent()\fR function is an extended version of the +\fBgetmntent()\fR function that returns, in addition to the information that +\fBgetmntent()\fR returns, the major and minor number of the mounted resource +to which the line in \fBmnttab\fR corresponds. The \fBgetextmntent()\fR +function also fills in the \fBextmntent\fR structure defined in the +<\fBsys/mnttab.h\fR> header. For \fBgetextmntent()\fR to function properly, it +must be notified when the \fBmnttab\fR file has been reopened or rewound since +a previous \fBgetextmntent()\fR call. This notification is accomplished by +calling \fBresetmnttab()\fR. Otherwise, it behaves exactly as \fBgetmntent()\fR +described above +.sp +.LP +The data pointed to by the \fBmnttab\fR structure members are stored in a +static area and must be copied to be saved between successive calls. +.SS "\fBhasmntopt()\fR" +.sp +.LP +The \fBhasmntopt()\fR function scans the \fBmnt_mntopts\fR member of the +\fBmnttab\fR structure \fImnt\fR for a substring that matches \fIopt\fR. It +returns the address of the substring if a match is found; otherwise it returns +\fB0\fR. Substrings are delimited by commas and the end of the +\fBmnt_mntopts\fR string. +.SS "\fBputmntent()\fR" +.sp +.LP +The \fBputmntent()\fR function is obsolete and no longer has any effect. +Entries appear in \fBmnttab\fR as a side effect of a \fBmount\fR(2) call. The +function name is still defined for transition purposes. +.SS "\fBresetmnttab()\fR" +.sp +.LP +The \fBresetmnttab()\fR function notifies \fBgetextmntent()\fR to reload from +the kernel the device information that corresponds to the new snapshot of the +\fBmnttab\fR information (see \fBmnttab\fR(4)). Subsequent \fBgetextmntent()\fR +calls then return correct \fBextmnttab\fR information. This function should be +called whenever the \fBmnttab\fR file is either rewound or closed and reopened +before any calls are made to \fBgetextmntent()\fR. +.SH RETURN VALUES +.SS "\fBgetmntent()\fR and \fBgetmntany()\fR" +.sp +.LP +If the next entry is successfully read by \fBgetmntent()\fR or a match is found +with \fBgetmntany()\fR, \fB0\fR is returned. If an \fBEOF\fR is encountered on +reading, these functions return \fB\(mi1\fR\&. If an error is encountered, a +value greater than 0 is returned. The following error values are defined in +\fB<sys/mnttab.h>\fR: +.sp +.ne 2 +.mk +.na +\fB\fBMNT_TOOLONG\fR\fR +.ad +.RS 15n +.rt +A line in the file exceeded the internal buffer size of \fBMNT_LINE_MAX\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMNT_TOOMANY\fR\fR +.ad +.RS 15n +.rt +A line in the file contains too many fields. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMNT_TOOFEW\fR\fR +.ad +.RS 15n +.rt +A line in the file contains too few fields. +.RE + +.SS "\fBhasmntopt()\fR" +.sp +.LP +Upon successful completion, \fBhasmntopt()\fR returns the address of the +substring if a match is found. Otherwise, it returns \fB0\fR. +.SS "\fBputmntent()\fR" +.sp +.LP +The \fBputmntent()\fR is obsolete and always returns \fB\(mi1\fR\&. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBmount\fR(2), \fBmnttab\fR(4), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/getnetgrent.3c b/usr/src/man/man3c/getnetgrent.3c new file mode 100644 index 0000000000..9d1a5793f5 --- /dev/null +++ b/usr/src/man/man3c/getnetgrent.3c @@ -0,0 +1,185 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getnetgrent 3C "5 Apr 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getnetgrent, getnetgrent_r, setnetgrent, endnetgrent, innetgr \- get network +group entry +.SH SYNOPSIS +.LP +.nf +#include <netdb.h> + +\fBint\fR \fBgetnetgrent\fR(\fBchar **\fR\fImachinep\fR, \fBchar **\fR\fIuserp\fR, \fBchar **\fR\fIdomainp\fR); +.fi + +.LP +.nf +\fBint\fR \fBgetnetgrent_r\fR(\fBchar **\fR\fImachinep\fR, \fBchar **\fR\fIuserp\fR, \fBchar **\fR\fIdomainp\fR, + \fBchar *\fR\fIbuffer\fR, \fBint\fR\fIbuflen\fR); +.fi + +.LP +.nf +\fBint\fR \fBsetnetgrent\fR(\fBconst char *\fR\fInetgroup\fR); +.fi + +.LP +.nf +\fBint\fR \fBendnetgrent\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBint\fR \fBinnetgr\fR(\fBconst char *\fR\fInetgroup\fR, \fBconst char *\fR\fImachine\fR, + \fBconst char *\fR\fIuser\fR, \fBconst char *\fR\fIdomain\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions are used to test membership in and enumerate members of +``netgroup'' network groups defined in a system database. Netgroups are sets +of (machine,user,domain) triples (see \fBnetgroup\fR(4)). +.sp +.LP +These functions consult the source specified for \fBnetgroup\fR in the +\fB/etc/nsswitch.conf\fR file (see \fBnsswitch.conf\fR(4)). +.sp +.LP +The function \fBinnetgr()\fR returns \fB1\fR if there is a netgroup +\fInetgroup\fR that contains the specified \fImachine,\fR \fIuser,\fR +\fIdomain\fR triple as a member; otherwise it returns \fB0\fR. Any of the +supplied pointers \fImachine\fR, \fIuser\fR, and \fIdomain\fR may be +\fINULL,\fR signifying a "wild card" that matches all values in that position +of the triple. +.sp +.LP +The \fBinnetgr()\fR function is safe for use in single-threaded and +multithreaded applications. +.sp +.LP +The functions \fBsetnetgrent()\fR, \fBgetnetgrent()\fR, and \fBendnetgrent()\fR +are used to enumerate the members of a given network group. +.sp +.LP +The function \fBsetnetgrent()\fR establishes the network group specified in the +parameter \fInetgroup\fR as the current group whose members are to be +enumerated. +.sp +.LP +Successive calls to the function \fBgetnetgrent()\fR will enumerate the members +of the group established by calling \fBsetnetgrent()\fR; each call returns +\fB1\fR if it succeeds in obtaining another member of the network group, or +\fB0\fR if there are no further members of the group. +.sp +.LP +When calling either \fBgetnetgrent()\fR or \fBgetnetgrent_r()\fR, addresses of +the three character pointers are used as arguments, for example: +.sp +.in +2 +.nf +char \fI*mp\fR, \fI*up\fR, \fI*dp\fR; +getnetgrent(\fI&mp\fR, \fI&up\fR, \fI&dp\fR); +.fi +.in -2 + +.sp +.LP +Upon successful return from \fBgetnetgrent()\fR, the pointer \fImp\fR points +to a string containing the name of the machine part of the member triple, +\fIup\fR points to a string containing the user name and \fIdp\fR points to a +string containing the domain name. If the pointer returned for \fImp\fR, +\fIup\fR, or \fIdp\fR is \fINULL,\fR it signifies that the element of the +netgroup contains wild card specifier in that position of the triple. +.sp +.LP +The pointers returned by \fBgetnetgrent()\fR point into a buffer allocated by +\fBsetnetgrent()\fR that is reused by each call. This space is released when an +\fBendnetgrent()\fR call is made, and should not be released by the caller. +This implementation is not safe for use in multi-threaded applications. +.sp +.LP +The function \fBgetnetgrent_r()\fR is similar to \fBgetnetgrent()\fR function, +but it uses a buffer supplied by the caller for the space needed to store the +results. The parameter \fIbuffer\fR should be a pointer to a buffer allocated +by the caller and the length of this buffer should be specified by the +parameter \fIbuflen\fR. The buffer must be large enough to hold the data +associated with the triple. The \fBgetnetgrent_r()\fR function is safe for use +both in single-threaded and multi-threaded applications. +.sp +.LP +The function \fBendnetgrent()\fR frees the space allocated by the previous +\fBsetnetgrent()\fR call. The equivalent of an \fBendnetgrent()\fR implicitly +performed whenever a \fBsetnetgrent()\fR call is made to a new network group. +.sp +.LP +Note that while \fBsetnetgrent()\fR and \fBendnetgrent()\fR are safe for use in +multi-threaded applications, the effect of each is process-wide. Calling +\fBsetnetgrent()\fR resets the enumeration position for all threads. If +multiple threads interleave calls to \fBgetnetgrent_r()\fR each will enumerate +a disjoint subset of the netgroup. Thus the effective use of these functions in +multi-threaded applications may require coordination by the caller. +.SH ERRORS +.sp +.LP +The function \fBgetnetgrent_r()\fR will return \fB0\fR and set \fBerrno\fR to +\fBERANGE\fR if the length of the buffer supplied by caller is not large enough +to store the result. See \fBIntro\fR(2) for the proper usage and +interpretation of \fBerrno\fR in multi-threaded applications. +.sp +.LP +The functions \fBsetnetgrent()\fR and \fBendnetgrent()\fR return \fB0\fR upon +success. +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/etc/nsswitch.conf\fR\fR +.ad +.RS 22n +.rt + +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSee \fBDESCRIPTION\fR section. +.TE + +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(2), \fBIntro\fR(3), \fBnetgroup\fR(4), \fBnsswitch.conf\fR(4), +\fBattributes\fR(5) +.SH WARNINGS +.sp +.LP +The function \fBgetnetgrent_r()\fR is included in this release on an +uncommitted basis only, and is subject to change or removal in future minor +releases. +.SH NOTES +.sp +.LP +Only the Network Information Services, \fBNIS\fR and \fBNIS+,\fR are supported +as sources for the \fBnetgroup\fR database. +.sp +.LP +When compiling multi-threaded applications, see \fBIntro\fR(3), \fINotes On +Multithread Applications\fR, for information about the use of the +\fB_REENTRANT\fR flag. diff --git a/usr/src/man/man3c/getopt.3c b/usr/src/man/man3c/getopt.3c new file mode 100644 index 0000000000..cb93d20637 --- /dev/null +++ b/usr/src/man/man3c/getopt.3c @@ -0,0 +1,434 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getopt 3C "16 Oct 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getopt \- command option parsing +.SH SYNOPSIS +.SS "SVID3, XPG3" +.LP +.nf +#include <stdio.h> + +\fBint\fR \fBgetopt\fR(\fBint\fR \fIargc\fR, \fBchar * const\fR \fIargv\fR[], \fBconst char *\fR\fIoptstring\fR); +.fi + +.LP +.nf +\fBextern char *\fR\fIoptarg\fR; +.fi + +.LP +.nf +\fBextern int\fR \fIoptind\fR, \fIopterr\fR, \fIoptopt\fR; +.fi + +.SS "POSIX.2, XPG4, SUS, SUSv2, SUSv3" +.LP +.nf +#include <unistd.h> + +\fBint\fR \fBgetopt\fR(\fBint\fR \fIargc\fR, \fBchar * const\fR \fIargv\fR[], \fBconst char *\fR\fIoptstring\fR); +.fi + +.LP +.nf +\fBextern char *\fR\fIoptarg\fR; +.fi + +.LP +.nf +\fBextern int\fR \fIoptind\fR, \fIopterr\fR, \fIoptopt\fR; +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetopt()\fR function is a command line parser that can be used by +applications that follow Basic Utility Syntax Guidelines 3, 4, 5, 6, 7, 9, and +10 which parallel those defined by application portability standards (see +intro(1)). It can also be used by applications which additionally follow the +Command Line Interface Paradigm (CLIP) syntax extension guidelines 15, 16, and +17. It partially enforces guideline 18 by requiring that every option has a +short-name, but it allows multiple long-names to be associated with an option. +The remaining guidelines are not addressed by \fBgetopt()\fR and are the +responsibility of the application. +.sp +.LP +The \fIargc\fR and \fIargv\fR arguments are the argument count and argument +array as passed to main (see \fBexec\fR(2)). The \fIoptstring\fR argument +specifies the acceptable options. For utilities wanting to conform to the Basic +Utility Syntax Guidelines, \fIoptstring\fR is a string of recognized option +characters. All option characters allowed by Utility Syntax Guideline 3 are +allowed in \fIoptstring\fR. If a character is followed by a colon (:), the +option is expected to have an option-argument, which can be separated from it +by white space. Utilities wanting to conform to the extended CLIP guidelines +can specify long-option equivalents to short options by following the +short-option character (and optional colon) with a sequence of strings, each +enclosed in parentheses, that specify the long-option aliases. +.sp +.LP +The \fBgetopt()\fR function returns the short-option character in +\fIoptstring\fR that corresponds to the next option found in \fIargv\fR. +.sp +.LP +The \fBgetopt()\fR function places in \fIoptind\fR the \fIargv\fR index of the +next argument to be processed. The \fIoptind\fR variable is external and is +initialized to 1 before the first call to \fBgetopt()\fR. The \fBgetopt()\fR +function sets the variable \fIoptarg\fR to point to the start of the +option-argument as follows: +.RS +4 +.TP +.ie t \(bu +.el o +If the option is a short option and that character is the last character in the +argument, then \fIoptarg\fR contains the next element of \fIargv\fR, and +\fIoptind\fR is incremented by 2. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If the option is a short option and that character is not the last character in +the argument, then \fIoptarg\fR points to the string following the option +character in that argument, and \fIoptind\fR is incremented by 1. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If the option is a long option and the character equals is not found in the +argument, then \fIoptarg\fR contains the next element of \fIargv\fR, and +\fIoptind\fR is incremented by 2. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If the option is a long option and the character equals is found in the +argument, then \fIoptarg\fR points to the string following the equals character +in that argument and \fIoptind\fR is incremented by 1. +.RE +.sp +.LP +In all cases, if the resulting value of \fIoptind\fR is not less than +\fIargc\fR, this indicates a missing option-argument and \fBgetopt()\fR returns +an error indication. +.sp +.LP +When all options have been processed (that is, up to the first operand), +\fBgetopt()\fR returns -1. The special option "--"(two hyphens) can be used to +delimit the end of the options; when it is encountered, -1 is returned and "--" +is skipped. This is useful in delimiting non-option arguments that begin with +"-" (hyphen). +.sp +.LP +If \fBgetopt()\fR encounters a short-option character or a long-option string +not described in the \fIopstring\fR argument, it returns the question-mark (?) +character. If it detects a missing option-argument, it also returns the +question-mark (?) character, unless the first character of the \fIoptstring\fR +argument was a colon (:), in which case \fBgetopt()\fR returns the colon (:) +character. For short options, \fBgetopt()\fR sets the variable \fIoptopt\fR to +the option character that caused the error. For long options, \fIoptopt\fR is +set to the hyphen (-) character and the failing long option can be identified +through \fIargv\fR[\fIoptind\fR-1]. If the application has not set the variable +\fIopterr\fR to 0 and the first character of \fIoptstring\fR is not a colon +(:), \fBgetopt()\fR also prints a diagnostic message to \fBstderr\fR. +.SH RETURN VALUES +.sp +.LP +The \fBgetopt()\fR function returns the short-option character associated with +the option recognized. +.sp +.LP +A colon (:) is returned if \fBgetopt()\fR detects a missing argument and the +first character of \fIoptstring\fR was a colon (:). +.sp +.LP +A question mark (?) is returned if \fBgetopt()\fR encounters an option not +specified in \fIoptstring\fR or detects a missing argument and the first +character of \fIoptstring\fR was not a colon (:). +.sp +.LP +Otherwise, \fBgetopt()\fR returns -1 when all command line options are parsed. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH EXAMPLES +.LP +\fBExample 1 \fRParsing Command Line Options +.sp +.LP +The following code fragment shows how you might process the arguments for a +utility that can take the mutually-exclusive options \fBa\fR and \fBb\fR and +the options \fBf\fR and \fBo\fR, both of which require arguments: + +.sp +.in +2 +.nf +#include <unistd.h> + +int +main(int argc, char *argv[ ]) +{ + int c; + int bflg, aflg, errflg; + char *ifile; + char *ofile; + extern char *optarg; + extern int optind, optopt; + . . . + 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++; + bproc(); + } + 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 +.in -2 + +.sp +.LP +This code accepts any of the following as equivalent: + +.sp +.in +2 +.nf +cmd -ao arg path path +cmd -a -o arg path path +cmd -o arg -a path path +cmd -a -o arg -- path path +cmd -a -oarg path path +cmd -aoarg path path +.fi +.in -2 + +.LP +\fBExample 2 \fRCheck Options and Arguments. +.sp +.LP +The following example parses a set of command line options and prints messages +to standard output for each option and argument that it encounters. + +.sp +.in +2 +.nf +#include <unistd.h> +#include <stdio.h> +\&... +int c; +char *filename; +extern char *optarg; +extern int optind, optopt, opterr; +\&... +while ((c = getopt(argc, argv, ":abf:")) != -1) { + switch(c) { + case 'a': + printf("a is set\en"); + break; + case 'b': + printf("b is set\en"); + break; + case 'f': + filename = optarg; + printf("filename is %s\en", filename); + break; + case ':': + printf("-%c without filename\en", optopt); + break; + case '?': + printf("unknown arg %c\en", optopt); + break; + } +} +.fi +.in -2 + +.sp +.LP +This example can be expanded to be CLIP-compliant by substituting the following +string for the \fIoptstring\fR argument: + +.sp +.in +2 +.nf +:a(ascii)b(binary)f:(in-file)o:(out-file)V(version)?(help) +.fi +.in -2 + +.sp +.LP +and by replacing the '?' case processing with: + +.sp +.in +2 +.nf +case 'V': + fprintf(stdout, "cmd 1.1\en"); + exit(0); +case '?': + if (optopt == '?') { + print_help(); + exit(0); + } + if (optopt == '-') + fprintf(stderr, + "unrecognized option: %s\en", argv[optind-1]); + else + fprintf(stderr, + "unrecognized option: -%c\en", optopt); + errflg++; + break; +.fi +.in -2 + +.sp +.LP +and by replacing the ':' case processing with: + +.sp +.in +2 +.nf +case ':': /* -f or -o without operand */ + if (optopt == '-') + fprintf(stderr, + "Option %s requires an operand\en", argv[optind-1]); + else + fprintf(stderr, + "Option -%c requires an operand\en", optopt); + errflg++; + break; +.fi +.in -2 + +.sp +.LP +While not encouraged by the CLIP specification, multiple long-option aliases +can also be assigned as shown in the following example: + +.sp +.in +2 +.nf +:a(ascii)b(binary):(in-file)(input)o:(outfile)(output)V(version)?(help) +.fi +.in -2 + +.SH ENVIRONMENT VARIABLES +.sp +.LP +See \fBenviron\fR(5) for descriptions of the following environment variables +that affect the execution of \fBgetopt()\fR: \fBLANG\fR, \fBLC_ALL\fR, and +\fBLC_MESSAGES\fR. +.sp +.ne 2 +.mk +.na +\fB\fBLC_CTYPE\fR\fR +.ad +.RS 12n +.rt +Determine the locale for the interpretation of sequences of bytes as characters +in \fIoptstring\fR. +.RE + +.SH USAGE +.sp +.LP +The \fBgetopt()\fR function does not fully check for mandatory arguments +because there is no unambiguous algorithm to do so. Given an option string +\fBa\fR:\fBb\fR and the input \fB-a\fR \fB-b\fR, \fBgetopt()\fR assumes that +\fB-b\fR is the mandatory argument to the \fB-a\fR option and not that \fB-a\fR +is missing a mandatory argument. Indeed, the only time a missing +option-argument can be reliably detected is when the option is the final option +on the command line and is not followed by any command arguments. +.sp +.LP +It is a violation of the Basic Utility Command syntax standard (see +\fBIntro\fR(1)) for options with arguments to be grouped with other options, as +in \fBcmd\fR \fB-abo\fR \fIfilename\fR , where \fBa\fR and \fBb\fR are options, +\fBo\fR is an option that requires an argument, and \fIfilename\fR is the +argument to \fBo\fR. Although this syntax is permitted in the current +implementation, it should not be used because it may not be supported in future +releases. The correct syntax to use is: +.sp +.in +2 +.nf +cmd \(miab \(mio filename +.fi +.in -2 +.sp + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelUnsafe +_ +StandardSee below. +.TE + +.sp +.LP +For the Basic Utility Command syntax is Standard, see \fBstandards\fR(5). +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(1), \fBgetopt\fR(1), \fBgetopts\fR(1), \fBgetsubopt\fR(3C), +\fBgettext\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5), \fBenviron\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/getpagesize.3c b/usr/src/man/man3c/getpagesize.3c new file mode 100644 index 0000000000..1fa8b26ece --- /dev/null +++ b/usr/src/man/man3c/getpagesize.3c @@ -0,0 +1,70 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getpagesize 3C "27 Jun 2000" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getpagesize \- get system page size +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> + +\fBint\fR \fBgetpagesize\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetpagesize()\fR function returns the number of bytes in a page. Page +granularity is the granularity of many of the memory management calls. +.sp +.LP +The page size is a system page size and need not be the same as the underlying +hardware page size. +.sp +.LP +The \fBgetpagesize()\fR function is equivalent to \fBsysconf(_SC_PAGE_SIZE)\fR +and \fBsysconf(_SC_PAGESIZE)\fR. See \fBsysconf\fR(3C). +.SH RETURN VALUES +.sp +.LP +The \fBgetpagesize()\fR function returns the current page size. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH USAGE +.sp +.LP +The value returned by \fBgetpagesize()\fR need not be the minimum value that +\fBmalloc\fR(3C) can allocate. Moreover, the application cannot assume that an +object of this size can be allocated with \fBmalloc()\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpagesize\fR(1), \fBbrk\fR(2), \fBgetrlimit\fR(2), \fBmmap\fR(2), +\fBmprotect\fR(2), \fBmunmap\fR(2), \fBmalloc\fR(3C), \fBmsync\fR(3C), +\fBsysconf\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/getpagesizes.3c b/usr/src/man/man3c/getpagesizes.3c new file mode 100644 index 0000000000..558dfcc072 --- /dev/null +++ b/usr/src/man/man3c/getpagesizes.3c @@ -0,0 +1,77 @@ +'\" te +.\" Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getpagesizes 3C "14 May 2001" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getpagesizes \- get system supported page sizes +.SH SYNOPSIS +.LP +.nf +#include <sys/mman.h> + +\fBint\fR \fBgetpagesizes\fR(\fBsize_t\fR \fIpagesize\fR[\|], \fBint\fR \fInelem\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetpagesizes()\fR function returns either the number of different page +sizes supported by the system or the actual sizes themselves. When called with +\fInelem\fR as 0 and pagesize as \fINULL\fR, \fBgetpagesizes()\fR returns the +number of supported page sizes. Otherwise, up to \fInelem\fR page sizes are +retrieved and assigned to successive elements of \fIpagesize\fR[\|]. The +return value is the number of page sizes retrieved and set in +\fIpagesize\fR[\|]. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the number of pagesizes supported or actually +retrieved is returned. Otherwise, \(mi1 is returned and \fBerrno\fR is set to +indicate the error. +.SH ERRORS +.sp +.LP +The \fBgetpagesizes()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fInelem\fR argument is less than 0 or \fIpagesize\fR is \fINULL\fR but +\fInelem\fR is non-zero. +.RE + +.SH USAGE +.sp +.LP +The \fBgetpagesizes()\fR function returns all the page sizes for which the +hardware and system software provide support for the \fBmemcntl\fR(2) command +\fBMC_HAT_ADVISE\fR. Not all processors support all page sizes or combinations +of page sizes with equal efficiency. Applications programmers should take this +into consideration when using \fBgetpagesizes()\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBmemcntl\fR(2), \fBmmap\fR(2), \fBgetpagesize\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/getpass.3c b/usr/src/man/man3c/getpass.3c new file mode 100644 index 0000000000..fe64e16f41 --- /dev/null +++ b/usr/src/man/man3c/getpass.3c @@ -0,0 +1,140 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getpass 3C "2 Sep 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getpass, getpassphrase \- read a string of characters without echo +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBchar *\fR\fBgetpass\fR(\fBconst char *\fR\fIprompt\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBgetpassphrase\fR(\fBconst char *\fR\fIprompt\fR); +.fi + +.SS "XPG4, SUS, SUSv2" +.LP +.nf +#include <unistd.h> + +\fBchar *\fR\fBgetpass\fR(\fBconst char *\fR\fIprompt\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetpass()\fR function opens the process's controlling terminal, writes +to that device the null-terminated string \fIprompt\fR, disables echoing, reads +a string of characters up to the next newline character or EOF, restores the +terminal state and closes the terminal. +.sp +.LP +The \fBgetpassphrase()\fR function is identical to \fBgetpass()\fR, except that +it reads and returns a string of up to 257 characters in length. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBgetpass()\fR returns a pointer to a +null-terminated string of at most 9 bytes that were read from the terminal +device. If an error is encountered, the terminal state is restored and a null +pointer is returned. +.SH ERRORS +.sp +.LP +The \fBgetpass()\fR and \fBgetpassphrase()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 10n +.rt +The function was interrupted by a signal. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 10n +.rt +The process is a member of a background process attempting to read from its +controlling terminal, the process is ignoring or blocking the \fBSIGTTIN\fR +signal or the process group is orphaned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 10n +.rt +\fBOPEN_MAX\fR file descriptors are currently open in the calling process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENFILE\fR\fR +.ad +.RS 10n +.rt +The maximum allowable number of files is currently open in the system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENXIO\fR\fR +.ad +.RS 10n +.rt +The process does not have a controlling terminal. +.RE + +.SH USAGE +.sp +.LP +The return value points to static data whose content may be overwritten by each +call. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface Stability\fBgetpass()\fR is Standard. +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/getpeerucred.3c b/usr/src/man/man3c/getpeerucred.3c new file mode 100644 index 0000000000..61e1830860 --- /dev/null +++ b/usr/src/man/man3c/getpeerucred.3c @@ -0,0 +1,161 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getpeerucred 3C "26 May 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getpeerucred \- get connected socket or stream peer's credentials +.SH SYNOPSIS +.LP +.nf +#include <ucred.h> + +\fBint\fR \fBgetpeerucred\fR(\fBint\fR \fIfd\fR, \fBucred_t **\fR\fIucred\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetpeerucred()\fR function returns the credentials of the peer endpoint +of a connection-oriented socket (\fBSOCK_STREAM\fR) or stream \fIfd\fR at the +time the endpoint was created or the connection was established. A process +that initiates a connection retrieves the credentials of its peer at the time +the peer's endpoint was created. A process that listens for connections +retrieves the credentials of the peer at the time the peer initiated the +connection. +.sp +.LP +When successful, \fBgetpeerucred()\fR stores the pointer to a freshly allocated +\fBucred_t\fR in the memory location pointed to by the \fIucred\fR argument if +that memory location contains the null pointer. If the memory location is +non-null, it will reuse the existing \fBucred_t\fR. +.sp +.LP +When \fIucred\fR is no longer needed, a credential allocated by +\fBgetpeerucred()\fR should be freed with \fBucred_free\fR(3C). +.sp +.LP +It is possible that all fields of the \fBucred_t\fR are not available to all +peer endpoints and all callers. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBgetpeerucred()\fR returns 0. Otherwise, it +returns \(mi1 and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBgetpeerucred()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 12n +.rt +There is not enough memory available to allocate sufficient memory to hold the +user credential. The application can try again later. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 12n +.rt +The \fIfd\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 12n +.rt +The pointer location pointed to by the \fBucred_t **\fR argument points to an +invalid, non-null address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 12n +.rt +The socket is connected but the peer credentials are unknown. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 12n +.rt +The physical limits of the system are exceeded by the memory allocation needed +to hold the user credential. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTCONN\fR\fR +.ad +.RS 12n +.rt +The socket or stream is not connected or the stream's peer is unknown. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSUP\fR\fR +.ad +.RS 12n +.rt +This operation is not supported on this file descriptor. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdoor_ucred\fR(3C), \fBucred_get\fR(3C), \fBattributes\fR(5), +\fBconnld\fR(7M) +.SH NOTES +.sp +.LP +The system currently supports both sides of connection endpoints for local +\fBAF_UNIX\fR, \fBAF_INET\fR, and \fBAF_INET6\fR sockets, \fB/dev/tcp\fR, +\fB/dev/ticots\fR, and \fB/dev/ticotsord\fR XTI/TLI connections, and pipe file +descriptors sent using \fBI_SENDFD\fR as a result of the open of a named pipe +with the "connld" module pushed. diff --git a/usr/src/man/man3c/getpriority.3c b/usr/src/man/man3c/getpriority.3c new file mode 100644 index 0000000000..4e13890b56 --- /dev/null +++ b/usr/src/man/man3c/getpriority.3c @@ -0,0 +1,226 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 1980 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.TH getpriority 3C "1 Apr 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getpriority, setpriority \- get and set the nice value +.SH SYNOPSIS +.LP +.nf +#include <sys/resource.h> + +\fBint\fR \fBgetpriority\fR(\fBint\fR \fIwhich\fR, \fBid_t\fR \fIwho\fR); +.fi + +.LP +.nf +\fBint\fR \fBsetpriority\fR(\fBint\fR \fIwhich\fR, \fBid_t\fR \fIwho\fR, \fBint\fR \fIvalue\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetpriority()\fR function obtains the nice value of a process, thread, +or set of processes. The \fBsetpriority()\fR function sets the nice value of a +process, thread, or set of processes to \fIvalue\fR+\fBNZERO\fR, where +\fBNZERO\fR is defined to be 20. +.sp +.LP +Target entities are specified by the values of the \fIwhich\fR and \fIwho\fR +arguments. The \fIwhich\fR argument can be one of the following values: +\fBPRIO_PROCESS\fR, \fBPRIO_PGRP\fR, \fBPRIO_USER\fR, \fBPRIO_GROUP\fR, +\fBPRIO_SESSION\fR, \fBPRIO_LWP\fR, \fBPRIO_TASK\fR, \fBPRIO_PROJECT\fR, +\fBPRIO_ZONE\fR, or \fBPRIO_CONTRACT\fR, indicating that the \fIwho\fR argument +is to be interpreted as a process ID, a process group ID, an effective user ID, +an effective group ID, a session ID, a thread (lwp) ID, a task ID, a project +ID, a zone ID, or a process contract ID, respectively. A 0 value for the +\fIwho\fR argument specifies the current process, process group, or user. A 0 +value for the \fIwho\fR argument is treated as valid group ID, session ID, +thread (lwp) ID, task ID, project ID, zone ID, or process contract ID. A +\fBP_MYID\fR value for the \fIwho\fR argument can be used to specify the +current group, session, thread, task, project, zone, or process contract, +respectively. +.sp +.LP +If a specified process is multi-threaded, the nice value set with +\fBsetpriority()\fR affects all threads in the process. +.sp +.LP +If more than one process is specified, \fBgetpriority()\fR returns \fBNZERO\fR +less than the lowest nice value pertaining to any of the specified entities, +and \fBsetpriority()\fR sets the nice values of all of the specified processes +to \fIvalue\fR+\fBNZERO\fR. +.sp +.LP +The default nice value is \fBNZERO\fR. Lower nice values cause more favorable +scheduling. The range of valid nice values is 0 to \fBNZERO\fR*2-1. If +\fIvalue\fR+\fBNZERO\fR is less than the system's lowest supported nice value, +\fBsetpriority()\fR sets the nice value to the lowest supported value. If +\fIvalue\fR+\fBNZERO\fR is greater than the system's highest supported nice +value, \fBsetpriority()\fR sets the nice value to the highest supported value. +.sp +.LP +Only a process with appropriate privileges can lower the nice value. +.sp +.LP +Any process or thread using \fBSCHED_FIFO\fR or \fBSCHED_RR\fR is unaffected by +a call to \fBsetpriority()\fR. This is not considered an error. A process or +thread that subsequently reverts to \fBSCHED_OTHER\fR will not have its +priority affected by such a \fBsetpriority()\fR call. +.sp +.LP +The effect of changing the nice value varies depending on the scheduling policy +in effect. +.sp +.LP +Since \fBgetpriority()\fR can return the value -1 on successful completion, it +is necessary to set \fBerrno\fR to 0 prior to a call to \fBgetpriority()\fR. If +\fBgetpriority()\fR returns the value -1, then \fBerrno\fR can be checked to +see if an error occurred or if the value is a legitimate nice value. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBgetpriority()\fR returns an integer in the range +from -\fBNZERO\fR to \fBNZERO\fR-1. Otherwise, \fB\(mi1\fR is returned and +\fBerrno\fR is set to indicate the error. +.sp +.LP +Upon successful completion, \fBsetpriority()\fR returns \fB0\fR. Otherwise, +\fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBgetpriority()\fR and \fBsetpriority()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBESRCH\fR\fR +.ad +.RS 10n +.rt +No process or thread could be located using the \fIwhich\fR and \fIwho\fR +argument values specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of the \fIwhich\fR argument was not recognized, or the value of the +\fIwho\fR argument is not a valid process ID, process group ID, user ID, group +ID, session ID, thread (lwp) ID, task ID, project ID, or zone ID. +.RE + +.sp +.LP +In addition, \fBsetpriority()\fR may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 10n +.rt +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. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 10n +.rt +A request was made to change the nice value to a lower numeric value and the +current process does not have appropriate privileges. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRExample using \fBgetpriority()\fR +.sp +.LP +The following example returns the current scheduling priority for the process +ID returned by the call to \fBgetpid\fR(2). + +.sp +.in +2 +.nf +#include <sys/resource.h> +\&... +int which = PRIO_PROCESS; +id_t pid; +int ret; + +pid = getpid(); +ret = getpriority(which, pid); +.fi +.in -2 + +.LP +\fBExample 2 \fRExample using \fBsetpriority()\fR +.sp +.LP +The following example sets the nice value for the current process to 0. + +.sp +.in +2 +.nf +#include <sys/resource.h> +\&... +int which = PRIO_PROCESS; +id_t pid; +int value = -20; +int ret; + +pid = getpid(); +ret = setpriority(which, pid, value); +.fi +.in -2 + +.SH USAGE +.sp +.LP +The \fBgetpriority()\fR and \fBsetpriority()\fR functions work with an offset +nice value (\fIvalue\fR-\fBNZERO\fR). The nice value is in the range 0 to +2*\fBNZERO\fR-1, while the return value for \fBgetpriority()\fR and the third +parameter for \fBsetpriority()\fR are in the range -\fBNZERO\fR to +\fBNZERO\fR-1. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBnice\fR(1), \fBrenice\fR(1), \fBsched_get_priority_max\fR(3C), +\fBsched_setscheduler\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/getpw.3c b/usr/src/man/man3c/getpw.3c new file mode 100644 index 0000000000..bcdabf6570 --- /dev/null +++ b/usr/src/man/man3c/getpw.3c @@ -0,0 +1,59 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getpw 3C "29 Dec 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getpw \- get passwd entry from UID +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBint\fR \fBgetpw\fR(\fBuid_t\fR \fIuid\fR, \fBchar *\fR\fIbuf\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetpw()\fR function searches the user data base for a user id number +that equals \fIuid\fR, copies the line of the password file in which \fIuid\fR +was found into the array pointed to by \fIbuf\fR, and returns 0. \fBgetpw()\fR +returns non-zero if \fIuid\fR cannot be found. +.SH USAGE +.sp +.LP +This function is included only for compatibility with prior systems and should +not be used; the functions described on the \fBgetpwnam\fR(3C) manual page +should be used instead. +.sp +.LP +If the \fB/etc/passwd\fR and the \fB/etc/group\fR files have a plus sign +(\fB+\fR) for the NIS entry, then \fBgetpwent()\fR and \fBgetgrent()\fR will +not return \fINULL\fR when the end of file is reached. See \fBgetpwnam\fR(3C). +.SH RETURN VALUES +.sp +.LP +The \fBgetpw()\fR function returns non-zero on error. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgetpwnam\fR(3C), \fBpasswd\fR(4), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/getpwnam.3c b/usr/src/man/man3c/getpwnam.3c new file mode 100644 index 0000000000..9e6d370e36 --- /dev/null +++ b/usr/src/man/man3c/getpwnam.3c @@ -0,0 +1,471 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical +.\" and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getpwnam 3C "5 Apr 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getpwnam, getpwnam_r, getpwent, getpwent_r, getpwuid, getpwuid_r, setpwent, +endpwent, fgetpwent, fgetpwent_r \- get password entry +.SH SYNOPSIS +.LP +.nf +#include <pwd.h> + +\fBstruct passwd *\fR\fBgetpwnam\fR(\fBconst char *\fR\fIname\fR); +.fi + +.LP +.nf +\fBstruct passwd *\fR\fBgetpwnam_r\fR(\fBconst char *\fR\fIname\fR, \fBstruct passwd *\fR\fIpwd\fR, + \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR); +.fi + +.LP +.nf +\fBstruct passwd *\fR\fBgetpwent\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBstruct passwd *\fR\fBgetpwent_r\fR(\fBstruct passwd *\fR\fIpwd\fR, \fBchar *\fR\fIbuffer\fR, + \fBint\fR \fIbuflen\fR); +.fi + +.LP +.nf +\fBstruct passwd *\fR\fBgetpwuid\fR(\fBuid_t\fR \fIuid\fR); +.fi + +.LP +.nf +\fBstruct passwd *\fR\fBgetpwuid_r\fR(\fBuid_t\fR \fIuid\fR, \fBstruct passwd *\fR\fIpwd\fR, + \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBsetpwent\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBendpwent\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBstruct passwd *\fR\fBfgetpwent\fR(\fBFILE *\fR\fIf\fR); +.fi + +.LP +.nf +\fBstruct passwd *\fR\fBfgetpwent_r\fR(\fBFILE *\fR\fIf\fR, \fBstruct passwd *\fR\fIpwd\fR, + \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR); +.fi + +.SS "Standard conforming" +.LP +.nf +cc [ \fIflag\fR...] \fIfile\fR... \fB-D_POSIX_PTHREAD_SEMANTICS\fR [ \fIlibrary\fR... ] + +\fBint\fR \fBgetpwnam_r\fR(\fBconst char *\fR\fIname\fR, \fBstruct passwd *\fR\fIpwd\fR, \fBchar *\fR\fIbuffer\fR, + \fBsize_t\fR \fIbufsize\fR, \fBstruct passwd **\fR\fIresult\fR); +.fi + +.LP +.nf +\fBint\fR \fBgetpwuid_r\fR(\fBuid_t\fR \fIuid\fR, \fBstruct passwd *\fR\fIpwd\fR, \fBchar *\fR\fIbuffer\fR, + \fBsize_t\fR \fIbufsize\fR, \fBstruct passwd **\fR\fIresult\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions are used to obtain password entries. Entries can come from any +of the sources for \fBpasswd\fR specified in the \fB/etc/nsswitch.conf\fR file +(see \fBnsswitch.conf\fR(4)). +.sp +.LP +The \fBgetpwnam()\fR function searches for a password entry with the login name +specified by the character string parameter \fIname\fR. +.sp +.LP +The \fBgetpwuid()\fR function searches for a password entry with the (numeric) +user \fBID\fR specified by the \fIuid\fR parameter. +.sp +.LP +The \fBsetpwent()\fR, \fBgetpwent()\fR, and \fBendpwent()\fR functions are used +to enumerate password entries from the database. The \fBsetpwent()\fR function +sets (or resets) the enumeration to the beginning of the set of password +entries. This function should be called before the first call to +\fBgetpwent()\fR. Calls to \fBgetpwnam()\fR and \fBgetpwuid()\fR leave the +enumeration position in an indeterminate state. Successive calls to +\fBgetpwent()\fR return either successive entries or a null pointer, indicating +the end of the enumeration. +.sp +.LP +The \fBendpwent()\fR function may be called to indicate that the caller expects +to do no further password retrieval operations; the system may then close the +password file, deallocate resources it was using, and so forth. It is still +allowed, but possibly less efficient, for the process to call more password +functions after calling \fBendpwent()\fR. +.sp +.LP +The \fBfgetpwent()\fR function, unlike the other functions above, does not use +\fBnsswitch.conf\fR but reads and parses the next line from the stream \fIf\fR, +which is assumed to have the format of the \fBpasswd\fR file. See +\fBpasswd\fR(4). +.SS "Reentrant Interfaces" +.sp +.LP +The \fBgetpwnam()\fR, \fBgetpwuid()\fR, \fBgetpwent()\fR, and \fBfgetpwent()\fR +functions use thread-specific data storage that is reused in each call to one +of these functions by the same thread, making them safe to use but not +recommended for multithreaded applications. +.sp +.LP +The parallel functions \fBgetpwnam_r()\fR, \fBgetpwuid_r()\fR, +\fBgetpwent_r()\fR, and \fBfgetpwent_r()\fR provide reentrant interfaces for +these operations. +.sp +.LP +Each reentrant interface performs the same operation as its non-reentrant +counterpart, named by removing the "\|_r\|" suffix. The reentrant interfaces, +however, use buffers supplied by the caller to store returned results instead +of using thread-specific data that can be overwritten by each call. They are +safe for use in both single-threaded and multithreaded applications. +.sp +.LP +Each reentrant interface takes the same parameters as its non-reentrant +counterpart, as well as the following additional parameters. The \fIpwd\fR +parameter must be a pointer to a \fBstruct passwd\fR structure allocated by the +caller. On successful completion, the function returns the password entry in +this structure. The parameter \fIbuffer\fR is a pointer to a buffer supplied by +the caller, used as storage space for the password data. All pointers within +the returned \fBstruct passwd\fR \fIpwd\fR point to data stored within this +buffer; see \fBpasswd Structure\fR below. The buffer must be large enough to +hold all the data associated with the password entry. The parameter +\fIbuflen\fR (or \fIbufsize\fR for the standard-conforming versions; see +\fBstandards\fR(5)) should give the size in bytes of \fIbuffer\fR. The maximum +size needed for this buffer can be determined with the +{\fB_SC_GETPW_R_SIZE_MAX\fR} \fBsysconf\fR(3C) parameter. The +standard-conforming versions place a pointer to the modified \fIpwd\fR +structure in the \fIresult\fR parameter, instead of returning a pointer to this +structure. A null pointer is returned at the location pointed to by +\fIresult\fR on error or if the requested entry is not found. +.sp +.LP +For enumeration in multithreaded applications, the position within the +enumeration is a process-wide property shared by all threads. The +\fBsetpwent()\fR function can be used in a multithreaded application but resets +the enumeration position for all threads. If multiple threads interleave calls +to \fBgetpwent_r()\fR, the threads will enumerate disjoint subsets of the +password database. +.sp +.LP +Like their non-reentrant counterparts, \fBgetpwnam_r()\fR and +\fBgetpwuid_r()\fR leave the enumeration position in an indeterminate state. +.SS "passwd Structure" +.sp +.LP +Password entries are represented by the \fBstruct passwd\fR structure defined +in <\fBpwd.h\fR>: +.sp +.in +2 +.nf +struct passwd { + char *pw_name; /* user's login name */ + char *pw_passwd; /* no longer used */ + uid_t pw_uid; /* user's uid */ + gid_t pw_gid; /* user's gid */ + char *pw_age; /* not used */ + char *pw_comment; /* not used */ + char *pw_gecos; /* typically user's full name */ + char *pw_dir; /* user's home dir */ + char *pw_shell; /* user's login shell */ +}; +.fi +.in -2 + +.sp +.LP +The \fBpw_passwd\fR member should not be used as the encrypted password for the +user; use \fBgetspnam()\fR or \fBgetspnam_r()\fR instead. See +\fBgetspnam\fR(3C). +.SH RETURN VALUES +.sp +.LP +The \fBgetpwnam()\fR, \fBgetpwnam_r()\fR, \fBgetpwuid()\fR, and +\fBgetpwuid_r()\fR functions each return a pointer to a \fBstruct passwd\fR if +they successfully locate the requested entry. A null pointer is returned if the +requested entry is not found, or an error occurs. On error, \fBerrno\fR is set +to indicate the error. +.sp +.LP +Applications wishing to check for error situations should set \fBerrno\fR to 0 +before calling \fBgetpwnam()\fR, \fBgetpwnam_r()\fR, \fBgetpwuid()\fR, +\fBgetpwuid_r()\fR, \fBgetpwent()\fR, \fBgetpwent_r()\fR, \fBfgetpwent()\fR, +and \fBfgetpwent_r()\fR. If these non-reentrant functions return a null pointer +and \fBerrno\fR is non-zero, an error occurred. +.sp +.LP +The standard-conforming functions \fBgetpwnam_r()\fR and \fBgetpwuid_r()\fR can +return \fB0\fR even on an error, particularly in the case where the requested +entry is not found. The application needs to check the return value and that +the \fIpwd\fR pointer is non-null. Otherwise, an error value is returned to +indicate the error. +.sp +.LP +The \fBgetpwent()\fR, \fBgetpwent_r()\fR, \fBfgetpwent()\fR, and +\fBfgetpwent_r()\fR functions each return a pointer to a \fBstruct passwd\fR if +they successfully enumerate an entry; otherwise they return a null pointer on +end-of-file or error. On error, \fBerrno\fR is set to indicate the error. +.sp +.LP +See \fBIntro\fR(2) for the proper usage and interpretation of \fBerrno\fR in +multithreaded applications. +.sp +.LP +The \fBgetpwnam()\fR, \fBgetpwuid()\fR, \fBgetpwent()\fR, and \fBfgetpwent()\fR +functions use thread-specific data storage, so returned data must be copied +before a subsequent call to any of these functions if the data is to be saved. +.sp +.LP +When the pointer returned by the reentrant functions \fBgetpwnam_r()\fR, +\fBgetpwuid_r()\fR, \fBgetpwent_r()\fR, and \fBfgetpwent_r()\fR is non-null, it +is always equal to the \fIpwd\fR pointer that was supplied by the caller. +.SH ERRORS +.sp +.LP +The \fBgetpwent_r()\fR, \fBfgetpwent()\fR, and \fBfgetpwent_r()\fR functions +will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 10n +.rt +An I/O error has occurred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBERANGE\fR\fR +.ad +.RS 10n +.rt +Insufficient storage was supplied by \fIbuffer\fR and \fIbufsize\fR to contain +the data to be referenced by the resulting \fBpasswd\fR structure. +.RE + +.sp +.LP +The \fBgetpwent_r()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 10n +.rt +There are {\fBOPEN_MAX\fR} file descriptors currently open in the calling +process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENFILE\fR\fR +.ad +.RS 10n +.rt +The maximum allowable number of files is currently open in the system. +.RE + +.sp +.LP +The \fBgetpwnam()\fR, \fBgetpwnam_r()\fR, \fBgetpwuid()\fR, \fBgetpwuid_r()\fR, +\fBgetpwent()\fR, \fBsetpwent()\fR, and \fBendpwent()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 7n +.rt +An I/O error has occurred. +.RE + +.sp +.LP +The \fBgetpwnam()\fR, \fBgetpwnam_r()\fR, \fBgetpwuid()\fR, \fBgetpwuid_r()\fR, +\fBgetpwent()\fR, and \fBsetpwent()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 10n +.rt +There are {\fBOPEN_MAX\fR} file descriptors currently open in the calling +process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENFILE\fR\fR +.ad +.RS 10n +.rt +The maximum allowable number of files is currently open in the system. +.RE + +.sp +.LP +The \fBgetpwnam()\fR, \fBgetpwnam_r()\fR, \fBgetpwuid()\fR, and +\fBgetpwuid_r()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 9n +.rt +A signal was caught during the execution of the function call. +.RE + +.sp +.LP +The \fBgetpwnam_r()\fR and \fBgetpwuid_r()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBERANGE\fR\fR +.ad +.RS 10n +.rt +Insufficient storage was supplied by \fIbuffer\fR and \fIbufsize\fR to contain +the data to be referenced by the resulting \fBpasswd\fR structure. +.RE + +.SH USAGE +.sp +.LP +Three names associated with the current process can be determined: +\fBgetpwuid\fR(\fBgeteuid()\fR) returns the name associated with the effective +user ID of the process; \fBgetlogin()\fR returns the name associated with the +current login activity; and \fBgetpwuid\fR(\fBgetuid()\fR) returns the name +associated with the real user ID of the process. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelSee \fBReentrant Interfaces\fR in \fBDESCRIPTION\fR. +_ +StandardSee below. +.TE + +.sp +.LP +For \fBendpwent()\fR, \fBgetpwent()\fR, \fBgetpwnam()\fR, +\fBgetpwnam_r()\fR, \fBgetpwuid()\fR, \fBgetpwuid_r()\fR, and \fBsetpwent()\fR, +see \fBstandards\fR(5). +.SH SEE ALSO +.sp +.LP +\fBnispasswd\fR(1), \fBpasswd\fR(1), \fByppasswd\fR(1), \fBIntro\fR(2), +\fBIntro\fR(3), \fBcuserid\fR(3C), \fBgetgrnam\fR(3C), \fBgetlogin\fR(3C), +\fBgetspnam\fR(3C), \fBnsswitch.conf\fR(4), \fBpasswd\fR(4), \fBshadow\fR(4), +\fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +When compiling multithreaded programs, see \fBIntro\fR(3). +.sp +.LP +Use of the enumeration interfaces \fBgetpwent()\fR and \fBgetpwent_r()\fR is +discouraged; enumeration is supported for the \fBpasswd\fR file, \fBNIS,\fR and +\fBNIS+,\fR but in general is not efficient and might not be supported for all +database sources. The semantics of enumeration are discussed further in +\fBnsswitch.conf\fR(4). +.sp +.LP +Previous releases allowed the use of `+' and `-' entries in \fB/etc/passwd\fR +to selectively include and exclude \fBNIS\fR entries. The primary usage of +these `+/-' entries is superseded by the name service switch, so the `+/-' form +might not be supported in future releases. +.sp +.LP +If required, the `+/-' functionality can still be obtained for \fBNIS\fR by +specifying \fBcompat\fR as the source for \fBpasswd\fR. +.sp +.LP +If the `+/-' functionality is required in conjunction with \fBNIS+,\fR specify +both \fBcompat\fR as the source for \fBpasswd\fR and \fBnisplus\fR as the +source for the pseudo-database \fBpasswd_compat\fR. See \fBpasswd\fR(4), +\fBshadow\fR(4), and \fBnsswitch.conf\fR(4) for details. +.sp +.LP +If the `+/-' is used, both \fB/etc/shadow\fR and \fB/etc/passwd\fR should have +the same `+' and `-' entries to ensure consistency between the password and +shadow databases. +.sp +.LP +If a password entry from any of the sources contains an empty \fIuid\fR or +\fIgid\fR field, that entry will be ignored by the files, \fBNIS\fR, and +\fBNIS+\fR name service switch backends, causing the user to appear unknown to +the system. +.sp +.LP +If a password entry contains an empty \fIgecos\fR, \fIhome directory\fR, or +\fIshell\fR field, \fBgetpwnam()\fR and \fBgetpwnam_r()\fR return a pointer to +a null string in the respective field of the \fBpasswd\fR structure. +.sp +.LP +If the shell field is empty, \fBlogin\fR(1) automatically assigns the default +shell. See \fBlogin\fR(1). +.sp +.LP +Solaris 2.4 and earlier releases provided definitions of the \fBgetpwnam_r()\fR +and \fBgetpwuid_r()\fR functions as specified in POSIX.1c Draft 6. The final +POSIX.1c standard changed the interface for these functions. Support for the +Draft 6 interface is provided for compatibility only and might not be supported +in future releases. New applications and libraries should use the +standard-conforming interface. +.sp +.LP +For POSIX.1c-conforming applications, the \fB_POSIX_PTHREAD_SEMANTICS\fR and +\fB_REENTRANT\fR flags are automatically turned on by defining the +\fB_POSIX_C_SOURCE\fR flag with a value \(>=199506L. diff --git a/usr/src/man/man3c/getrusage.3c b/usr/src/man/man3c/getrusage.3c new file mode 100644 index 0000000000..78ee9b92b1 --- /dev/null +++ b/usr/src/man/man3c/getrusage.3c @@ -0,0 +1,331 @@ +'\" te +.\" Copyright (c) 1980 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved Portions Copyright +.\" (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.TH getrusage 3C "2 Jul 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getrusage \- get information about resource utilization +.SH SYNOPSIS +.LP +.nf +#include <sys/resource.h> + +\fBint\fR \fBgetrusage\fR(\fBint\fR \fIwho\fR, \fBstruct rusage *\fR\fIr_usage\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetrusage()\fR function provides measures of the resources used by the +current process, its terminated and waited-for child processes, or the current +light weight process (LWP). If the value of the \fIwho\fR argument is +\fBRUSAGE_SELF\fR, information is returned about resources used by the current +process. If the value of the \fIwho\fR argument is \fBRUSAGE_CHILDREN\fR, +information is returned about resources used by the terminated and waited-for +children of the current process. If the child is never waited for (for +instance, if the parent has \fBSA_NOCLDWAIT\fR set or sets \fBSIGCHLD\fR to +\fBSIG_IGN\fR), the resource information for the child process is discarded and +not included in the resource information provided by \fBgetrusage()\fR. If the +value of the \fIwho\fR argument is \fBRUSAGE_LWP\fR, information is returned +about resources used by the current LWP. +.sp +.LP +The \fIr_usage\fR argument is a pointer to an object of type \fBstruct\fR +\fBrusage\fR in which the returned information is stored. The members of +\fBrusage\fR are as follows: +.sp +.in +2 +.nf +struct timeval ru_utime; /* user time used */ +struct timeval ru_stime; /* system time used */ +long ru_maxrss; /* maximum resident set size */ +long ru_idrss; /* integral resident set size */ +long ru_minflt; /* page faults not requiring physical + I/O */ +long ru_majflt; /* page faults requiring physical I/O */ +long ru_nswap; /* swaps */ +long ru_inblock; /* block input operations */ +long ru_oublock; /* block output operations */ +long ru_msgsnd; /* messages sent */ +long ru_msgrcv; /* messages received */ +long ru_nsignals; /* signals received */ +long ru_nvcsw; /* voluntary context switches */ +long ru_nivcsw; /* involuntary context switches */ +.fi +.in -2 + +.sp +.LP +The structure members are interpreted as follows: +.sp +.ne 2 +.mk +.na +\fB\fBru_utime\fR\fR +.ad +.RS 15n +.rt +The total amount of time spent executing in user mode. Time is given in seconds +and microseconds. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBru_stime\fR\fR +.ad +.RS 15n +.rt +The total amount of time spent executing in system mode. Time is given in +seconds and microseconds. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBru_maxrss\fR\fR +.ad +.RS 15n +.rt +The maximum resident set size. Size is given in pages (the size of a page, in +bytes, is given by the \fBgetpagesize\fR(3C) function). See the \fBNOTES\fR +section of this page. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBru_idrss\fR\fR +.ad +.RS 15n +.rt +An "integral" value indicating the amount of memory in use by a process while +the process is running. This value is the sum of the resident set sizes of the +process running when a clock tick occurs. The value is given in pages times +clock ticks. It does not take sharing into account. See the \fBNOTES\fR +section of this page. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBru_minflt\fR\fR +.ad +.RS 15n +.rt +The number of page faults serviced which did not require any physical I/O +activity. See the \fBNOTES\fR section of this page. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBru_majflt\fR\fR +.ad +.RS 15n +.rt +The number of page faults serviced which required physical I/O activity. This +could include page ahead operations by the kernel. See the \fBNOTES\fR section +of this page. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBru_nswap\fR\fR +.ad +.RS 15n +.rt +The number of times a process was swapped out of main memory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBru_inblock\fR\fR +.ad +.RS 15n +.rt +The number of times the file system had to perform input in servicing a +\fBread\fR(2) request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBru_oublock\fR\fR +.ad +.RS 15n +.rt +The number of times the file system had to perform output in servicing a +\fBwrite\fR(2) request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBru_msgsnd\fR\fR +.ad +.RS 15n +.rt +The number of messages sent over sockets. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBru_msgrcv\fR\fR +.ad +.RS 15n +.rt +The number of messages received from sockets. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBru_nsignals\fR\fR +.ad +.RS 15n +.rt +The number of signals delivered. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBru_nvcsw\fR\fR +.ad +.RS 15n +.rt +The number of times a context switch resulted due to a process voluntarily +giving up the processor before its time slice was completed (usually to await +availability of a resource). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBru_nivcsw\fR\fR +.ad +.RS 15n +.rt +The number of times a context switch resulted due to a higher priority process +becoming runnable or because the current process exceeded its time slice. +.RE + +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBgetrusage()\fR returns \fB0\fR. Otherwise, +\fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBgetrusage()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +.rt +The address specified by the \fIr_usage\fR argument is not in a valid portion +of the process' address space. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fBwho\fR parameter is not a valid value. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +.TE + +.SH SEE ALSO +.sp +.LP +\fBsar\fR(1M), \fBread\fR(2), \fBtimes\fR(2), \fBwrite\fR(2), +\fBgetpagesize\fR(3C), \fBgettimeofday\fR(3C), \fBwait\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +The \fBru_maxrss\fR, \fBru_ixrss\fR, \fBru_idrss\fR, and \fBru_isrss\fR members +of the \fBrusage\fR structure are set to 0 in this implementation. +.sp +.LP +The numbers \fBru_inblock\fR and \fBru_oublock\fR account only for real I/O, +and are approximate measures at best. Data supplied by the cache mechanism is +charged only to the first process to read and the last process to write the +data. +.sp +.LP +The way resident set size is calculated is an approximation, and could +misrepresent the true resident set size. +.sp +.LP +Page faults can be generated from a variety of sources and for a variety of +reasons. The customary cause for a page fault is a direct reference by the +program to a page which is not in memory. Now, however, the kernel can +generate page faults on behalf of the user, for example, servicing +\fBread\fR(2) and \fBwrite\fR(2) functions. Also, a page fault can be caused by +an absent hardware translation to a page, even though the page is in physical +memory. +.sp +.LP +In addition to hardware detected page faults, the kernel may cause pseudo page +faults in order to perform some housekeeping. For example, the kernel may +generate page faults, even if the pages exist in physical memory, in order to +lock down pages involved in a raw I/O request. +.sp +.LP +By definition, major page faults require physical I/O, while minor page faults +do not require physical I/O. For example, reclaiming the page from the free +list would avoid I/O and generate a minor page fault. More commonly, minor page +faults occur during process startup as references to pages which are already in +memory. For example, if an address space faults on some "hot" executable or +shared library, this results in a minor page fault for the address space. Also, +any one doing a \fBread\fR(2) or \fBwrite\fR(2) to something that is in the +page cache will get a minor page fault(s) as well. +.sp +.LP +There is no way to obtain information about a child process which has not yet +terminated. diff --git a/usr/src/man/man3c/gets.3c b/usr/src/man/man3c/gets.3c new file mode 100644 index 0000000000..ae56bae369 --- /dev/null +++ b/usr/src/man/man3c/gets.3c @@ -0,0 +1,90 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH gets 3C "15 Oct 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +gets, fgets \- get a string from a stream +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBchar *\fR\fBgets\fR(\fBchar *\fR\fIs\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBfgets\fR(\fBchar *\fR\fIs\fR, \fBint\fR \fIn\fR, \fBFILE *\fR\fIstream\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgets()\fR function reads bytes from the standard input stream (see +\fBIntro\fR(3)), \fBstdin\fR, into the array pointed to by \fIs\fR, until a +newline character is read or an end-of-file condition is encountered. The +newline character is discarded and the string is terminated with a null byte. +.sp +.LP +If the length of an input line exceeds the size of \fIs\fR, indeterminate +behavior may result. For this reason, it is strongly recommended that +\fBgets()\fR be avoided in favor of \fBfgets()\fR. +.sp +.LP +The \fBfgets()\fR function reads bytes from the \fIstream\fR into the array +pointed to by \fIs\fR, until \fIn\fR\(mi1 bytes are read, or a newline +character is read and transferred to \fIs\fR, or an end-of-file condition is +encountered. The string is then terminated with a null byte. +.sp +.LP +The \fBfgets()\fR and \fBgets()\fR functions may mark the \fBst_atime\fR field +of the file associated with \fIstream\fR for update. The \fBst_atime\fR field +will be marked for update by the first successful execution of \fBfgetc\fR(3C), +\fBfgets()\fR, \fBfread\fR(3C), \fBfscanf\fR(3C), \fBgetc\fR(3C), +\fBgetchar\fR(3C), \fBgets()\fR, or \fBscanf\fR(3C) using \fIstream\fR that +returns data not supplied by a prior call to \fBungetc\fR(3C) or +\fBungetwc\fR(3C). +.SH RETURN VALUES +.sp +.LP +If end-of-file is encountered and no bytes have been read, no bytes are +transferred to \fIs\fR and a null pointer is returned. For standard-conforming +(see \fBstandards\fR(5)) applications, if the end-of-file indicator for the +stream is set, no bytes are transferred to \fIs\fR and a null pointer is +returned whether or not the stream is at end-of-file. If a read error occurs, +such as trying to use these functions on a file that has not been opened for +reading, a null pointer is returned and the error indicator for the stream is +set. If end-of-file is encountered, the \fBEOF\fR indicator for the stream is +set. Otherwise \fIs\fR is returned. +.SH ERRORS +.sp +.LP +Refer to \fBfgetc\fR(3C). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlseek\fR(2), \fBread\fR(2), \fBferror\fR(3C), \fBfgetc\fR(3C), +\fBfgetwc\fR(3C), \fBfopen\fR(3C), \fBfread\fR(3C), \fBgetchar\fR(3C), +\fBscanf\fR(3C), \fBstdio\fR(3C), \fBungetc\fR(3C), \fBungetwc\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/getspnam.3c b/usr/src/man/man3c/getspnam.3c new file mode 100644 index 0000000000..65e386ec6f --- /dev/null +++ b/usr/src/man/man3c/getspnam.3c @@ -0,0 +1,259 @@ +'\" te +.\" Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getspnam 3C "23 Jan 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getspnam, getspnam_r, getspent, getspent_r, setspent, endspent, fgetspent, +fgetspent_r \- get password entry +.SH SYNOPSIS +.LP +.nf +#include <shadow.h> + +\fBstruct spwd *\fR\fBgetspnam\fR(\fBconst char *\fR\fIname\fR); +.fi + +.LP +.nf +\fBstruct spwd *\fR\fBgetspnam_r\fR(\fBconst char *\fR\fIname\fR, \fBstruct spwd *\fR\fIresult\fR, + \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR); +.fi + +.LP +.nf +\fBstruct spwd *\fR\fBgetspent\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBstruct spwd *\fR\fBgetspent_r\fR(\fBstruct spwd *\fR\fIresult\fR, \fBchar *\fR\fIbuffer\fR, + \fBint\fR \fIbuflen\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBsetspent\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBendspent\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBstruct spwd *\fR\fBfgetspent\fR(\fBFILE *\fR\fIfp\fR); +.fi + +.LP +.nf +\fBstruct spwd *\fR\fBfgetspent_r\fR(\fBFILE *\fR\fIfp\fR, \fBstruct spwd *\fR\fIresult\fR, + \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions are used to obtain shadow password entries. An entry may come +from any of the sources for \fBshadow\fR specified in the +\fB/etc/nsswitch.conf\fR file (see \fBnsswitch.conf\fR(4)). +.sp +.LP +The \fBgetspnam()\fR function searches for a shadow password entry with the +login name specified by the character string argument \fIname\fR. +.sp +.LP +The \fBsetspent()\fR, \fBgetspent()\fR, and \fBendspent()\fR functions are +used to enumerate shadow password entries from the database. +.sp +.LP +The \fBsetspent()\fR function sets (or resets) the enumeration to the beginning +of the set of shadow password entries. This function should be called before +the first call to \fBgetspent()\fR. Calls to \fBgetspnam()\fR leave the +enumeration position in an indeterminate state. +.sp +.LP +Successive calls to \fBgetspent()\fR return either successive entries or +\fINULL\fR, indicating the end of the enumeration. +.sp +.LP +The \fBendspent()\fR function may be called to indicate that the caller expects +to do no further shadow password retrieval operations; the system may then +close the shadow password file, deallocate resources it was using, and so +forth. It is still allowed, but possibly less efficient, for the process to +call more shadow password functions after calling \fBendspent()\fR. +.sp +.LP +The \fBfgetspent()\fR function, unlike the other functions above, does not use +\fBnsswitch.conf\fR; it reads and parses the next line from the stream +\fIfp\fR, which is assumed to have the format of the \fBshadow\fR file (see +\fBshadow\fR(4)). +.SS "Reentrant Interfaces" +.sp +.LP +The \fBgetspnam()\fR, \fBgetspent()\fR, and \fBfgetspent()\fR functions use +thread-specific data storage that is reused in each call to one of these +functions by the same thread, making them safe to use but not recommended for +multithreaded applications. +.sp +.LP +The \fBgetspnam_r()\fR, \fBgetspent_r()\fR, and \fBfgetspent_r()\fR functions +provide reentrant interfaces for these operations. +.sp +.LP +Each reentrant interface performs the same operation as its non-reentrant +counterpart, named by removing the \fB_r\fR suffix. The reentrant interfaces, +however, use buffers supplied by the caller to store returned results, and are +safe for use in both single-threaded and multithreaded applications. +.sp +.LP +Each reentrant interface takes the same argument as its non-reentrant +counterpart, as well as the following additional arguments. The \fIresult\fR +argument must be a pointer to a \fBstruct spwd\fR structure allocated by the +caller. On successful completion, the function returns the shadow password +entry in this structure. The \fIbuffer\fR argument must be a pointer to a +buffer supplied by the caller. This buffer is used as storage space for the +shadow password data. All of the pointers within the returned \fBstruct +spwd\fR \fIresult\fR point to data stored within this buffer (see \fBRETURN +VALUES\fR). The buffer must be large enough to hold all of the data associated +with the shadow password entry. The \fIbuflen\fR argument should give the size +in bytes of the buffer indicated by \fIbuffer.\fR +.sp +.LP +For enumeration in multithreaded applications, the position within the +enumeration is a process-wide property shared by all threads. The +\fBsetspent()\fR function may be used in a multithreaded application but resets +the enumeration position for all threads. If multiple threads interleave calls +to \fBgetspent_r()\fR, the threads will enumerate disjoint subsets of the +shadow password database. +.sp +.LP +Like its non-reentrant counterpart, \fBgetspnam_r()\fR leaves the enumeration +position in an indeterminate state. +.SH RETURN VALUES +.sp +.LP +Password entries are represented by the \fBstruct spwd\fR structure defined in +\fB<shadow.h>\fR: +.sp +.in +2 +.nf +\fBstruct spwd{ + char *sp_namp; /* login name */ + char *sp_pwdp; /* encrypted passwd */ + int sp_lstchg; /* date of last change */ + int sp_min; /* min days to passwd change */ + int sp_max; /* max days to passwd change*/ + int sp_warn; /* warning period */ + int sp_inact; /* max days inactive */ + int sp_expire; /* account expiry date */ + unsigned int sp_flag; /* not used */ +};\fR +.fi +.in -2 + +.sp +.LP +See \fBshadow\fR(4) for more information on the interpretation of this data. +.sp +.LP +The \fBgetspnam()\fRand \fBgetspnam_r()\fR functions each return a pointer to +a \fBstruct spwd\fR if they successfully locate the requested entry; otherwise +they return \fINULL\fR. +.sp +.LP +The \fBgetspent()\fR, \fBgetspent_r()\fR, \fBfgetspent()\fR, and +\fBfgetspent()\fR functions each return a pointer to a \fBstruct spwd\fR if +they successfully enumerate an entry; otherwise they return \fINULL\fR, +indicating the end of the enumeration. +.sp +.LP +The \fBgetspnam()\fR, \fBgetspent()\fR, and \fBfgetspent()\fR functions use +thread-specific data storage, so returned data must be copied before a +subsequent call to any of these functions if the data is to be saved. +.sp +.LP +When the pointer returned by the reentrant functions \fBgetspnam_r()\fR, +\fBgetspent_r()\fR, and \fBfgetspent_r()\fR is non-null, it is always equal to +the \fIresult\fR pointer that was supplied by the caller. +.SH ERRORS +.sp +.LP +The reentrant functions \fBgetspnam_r()\fR, \fBgetspent_r()\fR, and +\fBfgetspent_r()\fR will return \fBNULL\fR and set \fBerrno\fR to \fBERANGE\fR +if the length of the buffer supplied by caller is not large enough to store the +result. See \fBIntro\fR(2) for the proper usage and interpretation of +\fBerrno\fR in multithreaded applications. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelT{ +See "Reentrant Interfaces" in \fBDESCRIPTION\fR. +T} +.TE + +.SH SEE ALSO +.sp +.LP +\fBnispasswd\fR(1), \fBpasswd\fR(1), \fByppasswd\fR(1), \fBIntro\fR(3), +\fBgetlogin\fR(3C), \fBgetpwnam\fR(3C), \fBnsswitch.conf\fR(4), +\fBpasswd\fR(4), \fBshadow\fR(4), \fBattributes\fR(5) +.SH WARNINGS +.sp +.LP +The reentrant interfaces \fBgetspnam_r()\fR, \fBgetspent_r()\fR, and +\fBfgetspent_r()\fR are included in this release on an uncommitted basis only, +and are subject to change or removal in future minor releases. +.SH NOTES +.sp +.LP +When compiling multithreaded applications, see \fBIntro\fR(3), \fINotes On +Multithreaded Applications\fR, for information about the use of the +\fB_REENTRANT\fR flag. +.sp +.LP +Use of the enumeration interfaces \fBgetspent()\fR and \fBgetspent_r()\fR is +not recommended; enumeration is supported for the shadow file, \fBNIS,\fR and +\fBNIS+,\fR but in general is not efficient and may not be supported for all +database sources. The semantics of enumeration are discussed further in +\fBnsswitch.conf\fR(4). +.sp +.LP +Access to shadow password information may be restricted in a manner depending +on the database source being used. Access to the \fB/etc/shadow\fR file is +generally restricted to processes running with the effective uid of the file +owner or the {\fBPRIV_FILE_DAC_READ\fR} privilege. Other database sources may +impose stronger or less stringent restrictions. +.sp +.LP +Empty fields in the database source return -1 values for all fields except +\fBsp_pwdp\fR and \fBsp_flag\fR, where the value returned is 0. +.sp +.LP +When \fBNIS\fR is used as the database source, the information for the shadow +password entries is obtained from the ``passwd.byname'' map. This map stores +only the information for the \fBsp_namp\fR and \fBsp_pwdp\fR fields of the +\fBstruct spwd\fR structure. Shadow password entries obtained from \fBNIS\fR +will contain the value \fB-1\fR in the remainder of the fields. +.sp +.LP +When \fBNIS+\fR is used as the database source, and the caller lacks the +permission needed to retrieve the encrypted password from the \fBNIS+\fR +``passwd.org_dir'' table, the \fBNIS+\fR service returns the string ``*NP*'' +instead of the actual encrypted password string. The functions described on +this page will then return the string ``*NP*'' to the caller as the value of +the member \fBsp_pwdp\fR in the returned shadow password structure. diff --git a/usr/src/man/man3c/getsubopt.3c b/usr/src/man/man3c/getsubopt.3c new file mode 100644 index 0000000000..a24178e3ff --- /dev/null +++ b/usr/src/man/man3c/getsubopt.3c @@ -0,0 +1,223 @@ +'\" te +.\" Copyright (c) 1989 AT&T. +.\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved. +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getsubopt 3C "29 Sep 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getsubopt \- parse suboption arguments from a string +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBint\fR \fBgetsubopt\fR(\fBchar **\fR\fIoptionp\fR, \fBchar * const *\fR\fIkeylistp\fR, \fBchar **\fR\fIvaluep\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetsubopt()\fR function parses suboption arguments in a flag argument. +Such options often result from the use of \fBgetopt\fR(3C). +.sp +.LP +The \fBgetsubopt()\fR argument \fIoptionp\fR is a pointer to a pointer to the +option argument string. The suboption arguments are separated by commas and +each can consist of either a single token or a token-value pair separated by an +equal sign. +.sp +.LP +The \fIkeylistp\fR argument is 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\fR. Since commas delimit +suboption arguments in \fIoptionp\fR, they should not appear in any of the +strings pointed to by \fIkeylistp\fR. Similarly, because an equal sign +separates a token from its value, the application should not include an equal +sign in any of the strings pointed to by \fIkeylistp\fR. +.sp +.LP +The \fIvaluep\fR argument is the address of a value string pointer. +.sp +.LP +If a comma appears in \fIoptionp\fR, it is interpreted as a suboption +separator. After commas have been processed, if there are one or more equal +signs in a suboption string, the first equal sign in any suboption string is +interpreted as a separator between a token and a value. Subsequent equal signs +in a suboption string are interpreted as part of the value. +.sp +.LP +If the string at *\fIoptionp\fR contains only one suboption argument +(equivalently, no commas), \fBgetsubopt()\fR updates *\fIoptionp\fR to point to +the null character at the end of the string. Otherwise, it isolates the +suboption argument by replacing the comma separator with a null character and +updates *\fIoptionp\fR to point to the start of the next suboption argument. If +the suboption argument has an associated value (equivalently, contains an equal +sign), \fBgetsubopt()\fR updates *\fIvaluep\fR to point to the value's first +character. Otherwise, it sets *\fIvaluep\fR to a null pointer. The calling +application can use this information to determine whether the presence or +absence of a value for the suboption is an error. +.sp +.LP +Additionally, when \fBgetsubopt()\fR fails to match the suboption with a token +in the \fIkeylistp\fR array, the calling application should decide if this is +an error or if the unrecognized option should be processed in another way. +.SH RETURN VALUES +.sp +.LP +The \fBgetsubopt()\fR function returns the index of the matched token string or +-1 if no token strings were matched. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH EXAMPLES +.LP +\fBExample 1 \fRUse \fBgetsubopt()\fR to process options. +.sp +.LP +The following example demonstrates the processing of options to the +\fBmount\fR(1M) utility using \fBgetsubopt()\fR. + +.sp +.in +2 +.nf +#include <stdlib.h> + +char *myopts[] = { +#define READONLY 0 + "ro", +#define READWRITE 1 + "rw", +#define WRITESIZE 2 + "wsize", +#define READSIZE 3 + "rsize", + NULL}; + +main(argc, argv) + int argc; + char **argv; +{ + int sc, c, errflag; + char *options, *value; + extern char *optarg; + extern int optind; + . + . + . + while((c = getopt(argc, argv, "abf:o:")) != -1) { + switch (c) { + case 'a': /* process a option */ + break; + case 'b': /* process b option */ + break; + case 'f': + ofile = optarg; + break; + case '?': + errflag++; + break; + case 'o': + options = optarg; + while (*options != '\e0') { + switch(getsubopt(&options,myopts,&value)){ + case READONLY : /* process ro option */ + break; + case READWRITE : /* process rw option */ + break; + case WRITESIZE : /* process wsize option */ + if (value == NULL) { + error_no_arg(); + errflag++; + } else + write_size = atoi(value); + break; + case READSIZE : /* process rsize option */ + if (value == NULL) { + error_no_arg(); + errflag++; + } else + read_size = atoi(value); + break; + default : + /* process unknown token */ + error_bad_token(value); + errflag++; + break; + } + } + break; + } + } + if (errflag) { + /* print usage instructions etc. */ + } + for (; optind<argc; optind++) { + /* process remaining arguments */ + } + . + . + . +} +.fi +.in -2 + +.LP +\fBExample 2 \fRParse suboptions. +.sp +.LP +The following example uses the \fBgetsubopt()\fR function to parse a value +argument in the \fIoptarg\fR external variable returned by a call to +\fBgetopt\fR(3C). + +.sp +.in +2 +.nf +#include <stdlib.h> +\&... +char *tokens[] = {"HOME", "PATH", "LOGNAME", (char *) NULL }; +char *value; +int opt, index; +while ((opt = getopt(argc, argv, "e:")) != -1) { + switch(opt) { + case 'e' : + while ((index = getsubopt(&optarg, tokens, &value)) != -1) { + switch(index) { +\&... + } + break; +\&... + } +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBmount\fR(1M), \fBgetopt\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/gettext.3c b/usr/src/man/man3c/gettext.3c new file mode 100644 index 0000000000..1bc1c56fa1 --- /dev/null +++ b/usr/src/man/man3c/gettext.3c @@ -0,0 +1,360 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH gettext 3C "4 Jun 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +gettext, dgettext, dcgettext, ngettext, dngettext, dcngettext, textdomain, +bindtextdomain, bind_textdomain_codeset \- message handling functions +.SH SYNOPSIS +.SS "Solaris and GNU-compatible" +.LP +.nf +#include <libintl.h> + +\fBchar *\fR\fBgettext\fR(\fBconst char *\fR\fImsgid\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBdgettext\fR(\fBconst char *\fR\fIdomainname\fR, \fBconst char *\fR\fImsgid\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBtextdomain\fR(\fBconst char *\fR\fIdomainname\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBbindtextdomain\fR(\fBconst char *\fR\fIdomainname\fR, \fBconst char *\fR\fIdirname\fR); +.fi + +.LP +.nf +#include <libintl.h> +#include <locale.h> + +\fBchar *\fR\fBdcgettext\fR(\fBconst char *\fR\fIdomainname\fR, \fBconst char *\fR\fImsgid\fR, + \fBint\fR \fIcategory\fR); +.fi + +.SS "GNU-compatible" +.LP +.nf +#include <libintl.h> + +\fBchar *\fR\fBngettext\fR(\fBconst char *\fR\fImsgid1\fR, \fBconst char *\fR\fImsgid2\fR, + \fBunsigned long int\fR \fIn\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBdngettext\fR(\fBconst char *\fR\fIdomainname\fR, \fBconst char *\fR\fImsgid1\fR, + \fBconst char *\fR\fImsgid2\fR, \fBunsigned long int\fR \fIn\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBbind_textdomain_codeset\fR(\fBconst char *\fR\fIdomainname\fR, + \fBconst char *\fR\fIcodeset\fR); +.fi + +.LP +.nf +extern int _nl_msg_cat_cntr; +extern int *_nl_domain_bindings; +.fi + +.LP +.nf +#include <libintl.h> +#include <locale.h> + +\fBchar *\fR\fBdcngettext\fR(\fBconst char *\fR\fIdomainname\fR, \fBconst char *\fR\fImsgid1\fR, + \fBconst char *\fR\fImsgid2\fR, \fBunsigned long int\fR \fIn\fR, \fBint\fR \fIcategory\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgettext()\fR, \fBdgettext()\fR, and \fBdcgettext()\fR functions attempt +to retrieve a target string based on the specified \fImsgid\fR argument within +the context of a specific domain and the current locale. The length of strings +returned by \fBgettext()\fR, \fBdgettext()\fR, and \fBdcgettext()\fR is +undetermined until the function is called. The \fImsgid\fR argument is a +null-terminated string. +.sp +.LP +The \fBngettext()\fR, \fBdngettext()\fR, and \fBdcngettext()\fR functions are +equivalent to \fBgettext()\fR, \fBdgettext()\fR, and \fBdcgettext()\fR, +respectively, except for the handling of plural forms. These functions work +only with GNU-compatible message catalogues. The \fBngettext()\fR, +\fBdngettext()\fR, and \fBdcngettext()\fR functions search for the message +string using the \fImsgid1\fR argument as the key and the \fIn\fR argument to +determine the plural form. If no message catalogues are found, \fImsgid1\fR is +returned if \fIn\fR == 1, otherwise \fImsgid2\fR is returned. +.sp +.LP +The \fBNLSPATH\fR environment variable (see \fBenviron\fR(5)) is searched first +for the location of the \fBLC_MESSAGES\fR catalogue. The setting of the +\fBLC_MESSAGES\fR category of the current locale determines the locale used by +\fBgettext()\fR and \fBdgettext()\fR for string retrieval. The \fIcategory\fR +argument determines the locale used by \fBdcgettext(\|).\fR If \fBNLSPATH\fR is +not defined and the current locale is "C", \fBgettext()\fR, \fBdgettext()\fR, +and \fBdcgettext()\fR simply return the message string that was passed. In a +locale other than "C", if \fBNLSPATH\fR is not defined or if a message +catalogue is not found in any of the components specified by \fBNLSPATH\fR, the +routines search for the message catalogue using the scheme described in the +following paragraph. +.sp +.LP +The \fBLANGUAGE\fR environment variable is examined to determine the +GNU-compatible message catalogues to be used. The value of \fBLANGUAGE\fR is a +list of locale names separated by a colon (':') character. If \fBLANGUAGE\fR +is defined, each locale name is tried in the specified order and if a +GNU-compatible message catalogue is found, the message is returned. If a +GNU-compatible message catalogue is found but failed to find a corresponding +\fImsgid\fR, the \fImsgid\fR string is return. If \fBLANGUAGE\fR is not defined +or if a Solaris message catalogue is found or no GNU-compatible message +catalogue is found in processing \fBLANGUAGE\fR, the pathname used to locate +the message catalogue is +\fIdirname\fR/\fIlocale\fR/\fIcategory\fR/\fIdomainname\fR.mo, where +\fIdirname\fR is the directory specified by \fBbindtextdomain()\fR, +\fIlocale\fR is a locale name, and \fIcategory\fR is either \fBLC_MESSAGES\fR +if \fBgettext()\fR, \fBdgettext()\fR, \fBngettext()\fR, or \fBdngettext()\fR is +called, or \fBLC_XXX\fR where the name is the same as the locale category name +specified by the \fIcategory\fR argument to \fBdcgettext()\fR or +\fBdcngettext()\fR. +.sp +.LP +For \fBgettext()\fR and \fBngettext()\fR, the domain used is set by the last +valid call to \fBtextdomain()\fR. If a valid call to \fBtextdomain()\fR has not +been made, the default domain (called \fBmessages\fR) is used. +.sp +.LP +For \fBdgettext()\fR, \fBdcgettext()\fR, \fBdngettext()\fR, and +\fBdcngettext()\fR, the domain used is specified by the \fIdomainname\fR +argument. The \fIdomainname\fR argument is equivalent in syntax and meaning to +the \fIdomainname\fR argument to \fBtextdomain()\fR, except that the selection +of the domain is valid only for the duration of the \fBdgettext()\fR, +\fBdcgettext()\fR, \fBdngettext()\fR, or \fBdcngettext()\fR function call. +.sp +.LP +The \fBtextdomain()\fR function sets or queries the name of the current domain +of the active \fBLC_MESSAGES\fR locale category. The \fIdomainname\fR argument +is a null-terminated string that can contain only the characters allowed in +legal filenames. +.sp +.LP +The \fIdomainname\fR argument is the unique name of a domain on the system. If +there are multiple versions of the same domain on one system, namespace +collisions can be avoided by using \fBbindtextdomain()\fR. If +\fBtextdomain()\fR is not called, a default domain is selected. The setting of +domain made by the last valid call to \fBtextdomain()\fR remains valid across +subsequent calls to \fBsetlocale\fR(3C), and \fBgettext()\fR. +.sp +.LP +The \fIdomainname\fR argument is applied to the currently active +\fBLC_MESSAGES\fR locale. +.sp +.LP +The current setting of the domain can be queried without affecting the current +state of the domain by calling \fBtextdomain()\fR with \fIdomainname\fR set to +the null pointer. Calling \fBtextdomain()\fR with a \fIdomainname\fR argument +of a null string sets the domain to the default domain (\fBmessages\fR). +.sp +.LP +The \fBbindtextdomain()\fR function binds the path predicate for a message +domain \fIdomainname\fR to the value contained in \fIdirname\fR. If +\fIdomainname\fR is a non-empty string and has not been bound previously, +\fBbindtextdomain()\fR binds \fIdomainname\fR with \fIdirname\fR. +.sp +.LP +If \fIdomainname\fR is a non-empty string and has been bound previously, +\fBbindtextdomain()\fR replaces the old binding with \fIdirname\fR. The +\fIdirname\fR argument can be an absolute or relative pathname being resolved +when \fBgettext()\fR, \fBdgettext()\fR, or \fBdcgettext()\fR are called. If +\fIdomainname\fR is a null pointer or an empty string, \fBbindtextdomain()\fR +returns \fINULL.\fR User defined domain names cannot begin with the string +\fBSYS_\fR. Domain names beginning with this string are reserved for system +use. +.sp +.LP +The \fBbind_textdomain_codeset()\fR function can be used to specify the output +codeset for message catalogues for domain \fIdomainname\fR. The \fIcodeset\fR +argument must be a valid codeset name that can be used for the +\fBiconv_open\fR(3C) function, or a null pointer. If the \fIcodeset\fR argument +is the null pointer, \fBbind_textdomain_codeset()\fR returns the currently +selected codeset for the domain with the name \fIdomainname\fR. It returns a +null pointer if a codeset has not yet been selected. The +\fBbind_textdomain_codeset()\fR function can be used multiple times. If used +multiple times with the same \fIdomainname\fR argument, the later call +overrides the settings made by the earlier one. The +\fBbind_textdomain_codeset()\fR function returns a pointer to a string +containing the name of the selected codeset. The string is allocated internally +in the function and must not be changed by the user. +.sp +.LP +The external variables \fB_nl_msg_cat_cntr\fR and \fB_nl_domain_bindings\fR are +provided for the compatibility with the GNU \fBgettext()\fR implementation. +.SH RETURN VALUES +.sp +.LP +The \fBgettext()\fR, \fBdgettext()\fR, and \fBdcgettext()\fR functions return +the message string if the search succeeds. Otherwise they return the +\fImsgid\fR string. +.sp +.LP +The \fBngettext()\fR, \fBdngettext()\fR, and \fBdcngettext()\fR functions +return the message string if the search succeeds. If the search fails, +\fImsgid1\fR is returned if \fIn\fR == 1. Otherwise \fImsgid2\fR is returned. +.sp +.LP +The individual bytes of the string returned by \fBgettext()\fR, +\fBdgettext()\fR, \fBdcgettext()\fR, \fBngettext()\fR, \fBdngettext()\fR, or +\fBdcngettext()\fR can contain any value other than \fINULL\fR. If \fImsgid\fR +is a null pointer, the return value is undefined. The string returned must not +be modified by the program and can be invalidated by a subsequent call to +\fBbind_textdomain_codeset()\fR or \fBsetlocale\fR(3C). If the +\fIdomainname\fR argument to \fBdgettext()\fR,\fBdcgettext()\fR, +\fBdngettext()\fR, or \fBdcngettext()\fR is a null pointer, the the domain +currently bound by \fBtextdomain()\fR is used. +.sp +.LP +The normal return value from \fBtextdomain()\fR is a pointer to a string +containing the current setting of the domain. If \fIdomainname\fR is a null +pointer, \fBtextdomain()\fR returns a pointer to the string containing the +current domain. If \fBtextdomain()\fR was not previously called and +\fIdomainname\fR is a null string, the name of the default domain is returned. +The name of the default domain is \fBmessages\fR. If \fBtextdomain()\fR fails, +a null pointer is returned. +.sp +.LP +The return value from \fBbindtextdomain()\fR is a null-terminated string +containing \fIdirname\fR or the directory binding associated with +\fIdomainname\fR if \fIdirname\fR is \fINULL.\fR If no binding is found, the +default return value is \fB/usr/lib/locale\fR. If \fIdomainname\fR is a null +pointer or an empty string, \fBbindtextdomain()\fR takes no action and returns +a null pointer. The string returned must not be modified by the caller. If +\fBbindtextdomain()\fR fails, a null pointer is returned. +.SH USAGE +.sp +.LP +These functions impose no limit on message length. However, a text +\fIdomainname\fR is limited to \fBTEXTDOMAINMAX\fR (256) bytes. +.sp +.LP +The \fBgettext()\fR, \fBdgettext()\fR, \fBdcgettext()\fR, \fBngettext()\fR, +\fBdngettext()\fR, \fBdcngettext()\fR, \fBtextdomain()\fR, and +\fBbindtextdomain()\fR functions can be used safely in multithreaded +applications, as long as \fBsetlocale\fR(3C) is not being called to change the +locale. +.sp +.LP +The \fBgettext()\fR, \fBdgettext()\fR, \fBdcgettext()\fR, \fBtextdomain()\fR, +and \fBbindtextdomain()\fR functions work with both Solaris message catalogues +and GNU-compatible message catalogues. The \fBngettext()\fR, +\fBdngettext()\fR, \fBdcngettext()\fR, and \fBbind_textdomain_codeset()\fR +functions work only with GNU-compatible message catalogues. See +\fBmsgfmt\fR(1) for information about Solaris message catalogues and +GNU-compatible message catalogues. +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/locale\fR\fR +.ad +.sp .6 +.RS 4n +default path predicate for message domain files +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/locale/\fR\fIlocale\fR\fB/LC_MESSAGES/\fR\fIdomainname\fR\fB\&.m +o\fR\fR +.ad +.sp .6 +.RS 4n +system default location for file containing messages for language +\fIlocale\fR and \fIdomainname\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/locale/\fR\fIlocale\fR\fB/LC_XXX/\fR\fIdomainname\fR\fB\&.mo\fR\ +fR +.ad +.sp .6 +.RS 4n +system default location for file containing messages for language +\fIlocale\fR and \fIdomainname\fR for \fBdcgettext()\fR calls where +\fBLC_XXX\fR is \fBLC_CTYPE\fR, \fBLC_NUMERIC\fR, \fBLC_TIME\fR, +\fBLC_COLLATE\fR, \fBLC_MONETARY\fR, or \fBLC_MESSAGES\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\fR\fIdirname\fR\fB/\fR\fIlocale\fR\fB/LC_MESSAGES/\fR\fIdomainname\fR\fB +\&.mo\fR\fR +.ad +.sp .6 +.RS 4n +location for file containing messages for domain \fIdomainname\fR and path +predicate \fIdirname\fR after a successful call to \fBbindtextdomain()\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\fR\fIdirname\fR\fB/\fR\fIlocale\fR\fB/LC_XXX/\fR\fIdomainname\fR\fB\&.mo +\fR\fR +.ad +.sp .6 +.RS 4n +location for files containing messages for domain \fIdomainname,\fR language +\fIlocale,\fR and path predicate \fIdirname\fR after a successful call to +\fBbindtextdomain()\fR for \fBdcgettext()\fR calls where \fBLC_XXX\fR is one of +\fBLC_CTYPE\fR, \fBLC_NUMERIC\fR, \fBLC_TIME\fR, \fBLC_COLLATE\fR, +\fBLC_MONETARY\fR, or \fBLC_MESSAGES\fR +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilitySee below. +_ +MT-LevelSafe with exceptions +.TE + +.sp +.LP +The external variables \fB_nl_msg_cat_cntr\fR and \fB_nl_domain_bindings\fR are +Uncommitted. +.SH SEE ALSO +.sp +.LP +\fBmsgfmt\fR(1), \fBxgettext\fR(1), \fBiconv_open\fR(3C), +\fBlibintl.h\fR(3HEAD), \fBsetlocale\fR(3C), \fBattributes\fR(5), +\fBenviron\fR(5) diff --git a/usr/src/man/man3c/gettimeofday.3c b/usr/src/man/man3c/gettimeofday.3c new file mode 100644 index 0000000000..a45d5478db --- /dev/null +++ b/usr/src/man/man3c/gettimeofday.3c @@ -0,0 +1,132 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 1980 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.TH gettimeofday 3C "1 Aug 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +gettimeofday, settimeofday \- get or set the date and time +.SH SYNOPSIS +.LP +.nf +#include <sys/time.h> + +\fBint\fR \fBgettimeofday\fR(\fBstruct timeval *\fR\fItp\fR, \fBvoid *\fR\fItzp\fR); +.fi + +.LP +.nf +\fBint\fR \fBsettimeofday\fR(\fBstruct timeval *\fR\fItp\fR, \fBvoid *\fR\fItzp\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgettimeofday()\fR function gets and the \fBsettimeofday()\fR function +sets the system's notion of the current time. The current time is expressed in +elapsed seconds and microseconds since 00:00 Universal Coordinated Time, +January 1, 1970. The resolution of the system clock is hardware dependent; the +time may be updated continuously or in clock ticks. +.sp +.LP +The \fItp\fR argument points to a \fBtimeval\fR structure, which includes the +following members: +.sp +.in +2 +.nf +long tv_sec; /* seconds since Jan. 1, 1970 */ +long tv_usec; /* and microseconds */ +.fi +.in -2 + +.sp +.LP +If \fItp\fR is a null pointer, the current time information is not returned or +set. +.sp +.LP +The \fBTZ\fR environment variable holds time zone information. See +\fBTIMEZONE\fR(4). +.sp +.LP +The \fItzp\fR argument to \fBgettimeofday()\fR and \fBsettimeofday()\fR is +ignored. +.sp +.LP +Only privileged processes can set the time of day. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBsettimeofday()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The structure pointed to by \fItp\fR specifies an invalid time. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 10n +.rt +The {\fBPRIV_SYS_TIME\fR} privilege was not asserted in the effective set of +the calling process. +.RE + +.sp +.LP +The \fBgettimeofday()\fR function will fail for 32-bit interfaces if: +.sp +.ne 2 +.mk +.na +\fB\fBEOVERFLOW\fR\fR +.ad +.RS 13n +.rt +The system time has progressed beyond 2038, thus the size of the \fBtv_sec\fR +member of the \fBtimeval\fR structure pointed to by \fItp\fR is insufficient to +hold the current time in seconds. +.RE + +.SH USAGE +.sp +.LP +If the \fBtv_usec\fR member of \fItp\fR is > 500000, \fBsettimeofday()\fR +rounds the seconds upward. If the time needs to be set with better than one +second accuracy, call \fBsettimeofday()\fR for the seconds and then +\fBadjtime\fR(2) for finer accuracy. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface Stability\fBgettimeofday()\fR is Standard. +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBadjtime\fR(2), \fBctime\fR(3C), \fBgethrtime\fR(3C), \fBTIMEZONE\fR(4), +\fBattributes\fR(5), \fBprivileges\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/gettxt.3c b/usr/src/man/man3c/gettxt.3c new file mode 100644 index 0000000000..15b84b5c45 --- /dev/null +++ b/usr/src/man/man3c/gettxt.3c @@ -0,0 +1,139 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH gettxt 3C "29 Dec 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +gettxt \- retrieve a text string +.SH SYNOPSIS +.LP +.nf +#include <nl_types.h> + +\fBchar *\fR\fBgettxt\fR(\fBconst char *\fR\fImsgid\fR, \fBconst char *\fR\fIdflt_str\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgettxt()\fR function retrieves a text string from a message file. The +arguments to the function are a message identification \fImsgid\fR and a +default string \fIdflt_str\fR to be used if the retrieval fails. +.sp +.LP +The text strings are in files created by the \fBmkmsgs\fR utility (see +\fBmkmsgs\fR(1)) and installed in directories in +\fB/usr/lib/locale/\fIlocale\fR/LC_MESSAGES\fR. +.sp +.LP +The directory \fBlocale\fR can be viewed as the language in which the text +strings are written. The user can request that messages be displayed in a +specific language by setting the environment variable \fBLC_MESSAGES\fR. If +\fBLC_MESSAGES\fR is not set, the environment variable \fBLANG\fR will be used. +If \fBLANG\fR is not set, the files containing the strings are in +\fB/usr/lib/locale/C/LC_MESSAGES/*\fR. +.sp +.LP +The user can also change the language in which the messages are displayed by +invoking the \fBsetlocale\fR(3C) function with the appropriate arguments. +.sp +.LP +If \fBgettxt()\fR fails to retrieve a message in a specific language it will +try to retrieve the same message in U.S. English. On failure, the processing +depends on what the second argument \fIdflt_str\fR points to. A pointer to the +second argument is returned if the second argument is not the null string. If +\fIdflt_str\fR points to the null string, a pointer to the U.S. English text +string \fB"Message not found!!\en"\fR is returned. +.sp +.LP +The following depicts the acceptable syntax of \fImsgid\fR for a call to +\fBgettxt()\fR. +.sp +.LP +\fI<msgid>\fR\fB = \fR\fI<msgfilename>\fR\fB:\fR\fI<msgnumber>\fR +.sp +.LP +The first field is used to indicate the file that contains the text strings and +must be limited to 14 characters. These characters must be selected from the +set of all character values excluding \e0 (null) and the \fBASCII\fR code for +\fB/\fR (slash) and \fB:\fR (colon). The names of message files must be the +same as the names of files created by \fBmkmsgs\fR and installed in +\fB/usr/lib/locale/\fIlocale\fR/LC_MESSAGES/*\fR. The numeric field indicates +the sequence number of the string in the file. The strings are numbered from 1 +to \fIn\fR where \fIn\fR is the number of strings in the file. +.SH RETURN VALUES +.sp +.LP +Upon failure to pass either the correct \fImsgid\fR or a valid message number +to \fBgettxt()\fR, a pointer to the text string \fB"Message not found!!\en"\fR +is returned. +.SH USAGE +.sp +.LP +It is recommended that \fBgettext\fR(3C) be used in place of this function. +.SH EXAMPLES +.LP +\fBExample 1 \fRExample of \fBgettxt()\fR function. +.sp +.LP +In the following example, + +.sp +.in +2 +.nf +gettxt("UX:10", "hello world\en") +gettxt("UX:10", "") +.fi +.in -2 + +.sp +.LP +\fBUX\fR is the name of the file that contains the messages and \fB10\fR is the +message number. + +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/locale/C/LC_MESSAGES/*\fR\fR +.ad +.sp .6 +.RS 4n +contains default message files created by \fBmkmsgs\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/locale/\fIlocale\fR/LC_MESSAGES/*\fR\fR +.ad +.sp .6 +.RS 4n +contains message files for different languages created by \fBmkmsgs\fR +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBexstr\fR(1), \fBmkmsgs\fR(1), \fBsrchtxt\fR(1), \fBgettext\fR(3C), +\fBfmtmsg\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5), \fBenviron\fR(5) diff --git a/usr/src/man/man3c/getusershell.3c b/usr/src/man/man3c/getusershell.3c new file mode 100644 index 0000000000..7b695cf81b --- /dev/null +++ b/usr/src/man/man3c/getusershell.3c @@ -0,0 +1,77 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 1985 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. +.\" Portions Copyright (c) 1982-2007 AT&T Knowledge Ventures +.TH getusershell 3C "1 Nov 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getusershell, setusershell, endusershell \- get legal user shells +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> + +\fBchar *\fR\fBgetusershell\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBsetusershell\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBendusershell\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetusershell()\fR function returns a pointer to a legal user shell as +defined by the system manager in the file \fB/etc/shells\fR. If +\fB/etc/shells\fR does not exist, the following locations of the standard +system shells are used in its place: +.sp +.in +2 +.nf +\fB/bin/bash\fR \fB/bin/csh\fR +\fB/bin/jsh\fR \fB/bin/ksh\fR +\fB/bin/ksh93\fR \fB/bin/pfcsh\fR +\fB/bin/pfksh\fR \fB/bin/pfsh\fR +\fB/bin/sh\fR \fB/bin/tcsh\fR +\fB/bin/zsh\fR \fB/sbin/jsh\fR +\fB/sbin/pfsh\fR \fB/sbin/sh\fR +\fB/usr/bin/bash\fR \fB/usr/bin/csh\fR +\fB/usr/bin/jsh\fR \fB/usr/bin/ksh\fR +\fB/usr/bin/ksh93\fR \fB/usr/bin/pfcsh\fR +\fB/usr/bin/pfksh\fR \fB/usr/bin/pfsh\fR +\fB/usr/bin/sh\fR \fB/usr/bin/tcsh\fR +\fB/usr/bin/zsh\fR \fB/usr/sfw/bin/zsh\fR +\fB/usr/xpg4/bin/sh\fR +.fi +.in -2 + +.sp +.LP +The \fBgetusershell()\fR function opens the file \fB/etc/shells\fR, if it +exists, and returns the next entry in the list of shells. +.sp +.LP +The \fBsetusershell()\fR function rewinds the file or the list. +.sp +.LP +The \fBendusershell()\fR function closes the file, frees any memory used by +\fBgetusershell()\fR and \fBsetusershell()\fR, and rewinds the file +\fB/etc/shells\fR. +.SH RETURN VALUES +.sp +.LP +The \fBgetusershell()\fR function returns a null pointer on EOF. +.SH BUGS +.sp +.LP +All information is contained in memory that may be freed with a call to +\fBendusershell()\fR, so it must be copied if it is to be saved. +.SH NOTES +.sp +.LP +Restricted shells should not be listed in \fB/etc/shells\fR. diff --git a/usr/src/man/man3c/getutent.3c b/usr/src/man/man3c/getutent.3c new file mode 100644 index 0000000000..3f5ae8bb9e --- /dev/null +++ b/usr/src/man/man3c/getutent.3c @@ -0,0 +1,201 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getutent 3C "27 Oct 1998" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getutent, getutid, getutline, pututline, setutent, endutent, utmpname \- user +accounting database functions +.SH SYNOPSIS +.LP +.nf +#include <utmp.h> + +\fBstruct utmp *\fR\fBgetutent\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBstruct utmp *\fR\fBgetutid\fR(\fBconst struct utmp *\fR\fIid\fR); +.fi + +.LP +.nf +\fBstruct utmp *\fR\fBgetutline\fR(\fBconst struct utmp *\fR\fIline\fR); +.fi + +.LP +.nf +\fBstruct utmp *\fR\fBpututline\fR(\fBconst struct utmp *\fR\fIutmp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBsetutent\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBendutent\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBint\fR \fButmpname\fR(\fBconst char *\fR\fIfile\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions provide access to the user accounting database, \fButmp\fR. +Entries in the database are described by the definitions and data structures in +\fB<utmp.h>\fR\&. +.sp +.LP +The \fButmp\fR structure contains the following members: +.sp +.in +2 +.nf +char ut_user[8]; /* user login name */ +char ut_id[4]; /* /sbin/inittab id */ + /* (usually line #) */ +char ut_line[12]; /* device name (console, lnxx) */ +short ut_pid; /* process id */ +short ut_type; /* type of entry */ +struct exit_status ut_exit; /* exit status of a process */ + /* marked as DEAD_PROCESS */ +time_t ut_time; /* time entry was made */ +.fi +.in -2 + +.sp +.LP +The structure \fBexit_status\fR includes the following members: +.sp +.in +2 +.nf +short e_termination; /* termination status */ +short e_exit; /* exit status */ +.fi +.in -2 + +.SS "\fBgetutent()\fR" +.sp +.LP +The \fBgetutent()\fR function reads in the next entry from a \fButmp\fR +database. If the database is not already open, it opens it. If it reaches the +end of the database, it fails. +.SS "\fBgetutid()\fR" +.sp +.LP +The \fBgetutid()\fR function searches forward from the current point in the +\fButmp\fR database until it finds an entry with a \fBut_type\fR matching +\fIid\fR->\fBut_type\fR if the type specified is \fBRUN_LVL\fR, +\fBBOOT_TIME\fR, \fBDOWN_TIME\fR, \fBOLD_TIME\fR, or \fBNEW_TIME\fR. If the +type specified in \fIid\fR is \fBINIT_PROCESS\fR, \fBLOGIN_PROCESS\fR, +\fBUSER_PROCESS\fR, or \fBDEAD_PROCESS\fR, then \fBgetutid()\fR will return a +pointer to the first entry whose type is one of these four and whose +\fBut_id\fR member matches \fIid\fR->\fBut_id\fR. If the end of database is +reached without a match, it fails. +.SS "\fBgetutline()\fR" +.sp +.LP +The \fBgetutline()\fR function searches forward from the current point in the +\fButmp\fR database until it finds an entry of the type \fBLOGIN_PROCESS\fR or +\fBut_line\fR string matching the \fIline\fR->\fBut_line\fR string. If the end +of database is reached without a match, it fails. +.SS "\fBpututline()\fR" +.sp +.LP +The \fBpututline()\fR function writes the supplied \fButmp\fR structure into +the \fButmp\fR database. It uses \fBgetutid()\fR to search forward for the +proper place if it finds that it is not already at the proper place. It is +expected that normally the user of \fBpututline()\fR will have searched for the +proper entry using one of the these functions. If so, \fBpututline()\fR will +not search. If \fBpututline()\fR does not find a matching slot for the new +entry, it will add a new entry to the end of the database. It returns a +pointer to the \fButmp\fR structure. When called by a non-root user, +\fBpututline()\fR invokes a \fBsetuid()\fR root program to verify and write the +entry, since the \fButmp\fR database is normally writable only by root. In +this event, the \fBut_name\fR member must correspond to the actual user name +associated with the process; the \fBut_type\fR member must be either +\fBUSER_PROCESS\fR or \fBDEAD_PROCESS\fR; and the \fBut_line\fR member must be +a device special file and be writable by the user. +.SS "\fBsetutent()\fR" +.sp +.LP +The \fBsetutent()\fR function resets the input stream to the beginning. This +reset should be done before each search for a new entry if it is desired that +the entire database be examined. +.SS "\fBendutent()\fR" +.sp +.LP +The \fBendutent()\fR function closes the currently open database. +.SS "\fButmpname()\fR" +.sp +.LP +The \fButmpname()\fR function allows the user to change the name of the +database file examined to another file. If the file does not exist, this will +not be apparent until the first attempt to reference the file is made. The +\fButmpname()\fR function does not open the file but closes the old file if it +is currently open and saves the new file name. +.SH RETURN VALUES +.sp +.LP +A null pointer is returned upon failure to read, whether for permissions or +having reached the end of file, or upon failure to write. If the file name +given is longer than 79 characters, \fButmpname()\fR returns \fB0\fR. +Otherwise, it returns \fB1\fR. +.SH USAGE +.sp +.LP +These functions use buffered standard I/O for input, but \fBpututline()\fR uses +an unbuffered non-standard write to avoid race conditions between processes +trying to modify the \fButmp\fR and \fBwtmp\fR databases. +.sp +.LP +Applications should not access the \fButmp\fR and \fBwtmp\fR databases +directly, but should use these functions to ensure that these databases are +maintained consistently. Using these functions, however, may cause applications +to fail if user accounting data cannot be represented properly in the +\fButmp\fR structure (for example, on a system where PIDs can exceed 32767). +Use the functions described on the \fBgetutxent\fR(3C) manual page instead. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgetutxent\fR(3C), \fBttyslot\fR(3C), \fButmpx\fR(4), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +The most current entry is saved in a static structure. Multiple accesses +require that it be copied before further accesses are made. On each call to +either \fBgetutid()\fR or \fBgetutline()\fR, the function examines the static +structure before performing more I/O. If the contents of the static structure +match what it is searching for, it looks no further. For this reason, to use +\fBgetutline()\fR to search for multiple occurrences, it would be necessary to +zero out the static area after each success, or \fBgetutline()\fR would just +return the same structure over and over again. There is one exception to the +rule about emptying the structure before further reads are done. The implicit +read done by \fBpututline()\fR (if it finds that it is not already at the +correct place in the file) will not hurt the contents of the static structure +returned by the \fBgetutent()\fR, \fBgetutid()\fR or \fBgetutline()\fR +functions, if the user has just modified those contents and passed the pointer +back to \fBpututline()\fR. diff --git a/usr/src/man/man3c/getutxent.3c b/usr/src/man/man3c/getutxent.3c new file mode 100644 index 0000000000..2024dc89b2 --- /dev/null +++ b/usr/src/man/man3c/getutxent.3c @@ -0,0 +1,347 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2004 Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getutxent 3C "27 Jul 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getutxent, getutxid, getutxline, pututxline, setutxent, endutxent, utmpxname, +getutmp, getutmpx, updwtmp, updwtmpx \- user accounting database functions +.SH SYNOPSIS +.LP +.nf +#include <utmpx.h> + +\fBstruct utmpx *\fR\fBgetutxent\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBstruct utmpx *\fR\fBgetutxid\fR(\fBconst struct utmpx *\fR\fIid\fR); +.fi + +.LP +.nf +\fBstruct utmpx *\fR\fBgetutxline\fR(\fBconst struct utmpx *\fR\fIline\fR); +.fi + +.LP +.nf +\fBstruct utmpx *\fR\fBpututxline\fR(\fBconst struct utmpx *\fR\fIutmpx\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBsetutxent\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBendutxent\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBint\fR \fButmpxname\fR(\fBconst char *\fR\fIfile\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBgetutmp\fR(\fBstruct utmpx *\fR\fIutmpx\fR, \fBstruct utmp *\fR\fIutmp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBgetutmpx\fR(\fBstruct utmp *\fR\fIutmp\fR, \fBstruct utmpx *\fR\fIutmpx\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBupdwtmp\fR(\fBchar *\fR\fIwfile\fR, \fBstruct utmp *\fR\fIutmp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBupdwtmpx\fR(\fBchar *\fR\fIwfilex\fR, \fBstruct utmpx *\fR\fIutmpx\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions provide access to the user accounting database, \fButmpx\fR +(see \fButmpx\fR(4)). Entries in the database are described by the definitions +and data structures in \fB<utmpx.h>\fR\&. +.sp +.LP +The \fButmpx\fR structure contains the following members: +.sp +.in +2 +.nf +char ut_user[32]; /* user login name */ +char ut_id[4]; /* /etc/inittab id */ + /* (usually line #) */ +char ut_line[32]; /* device name */ + /* (console, lnxx) */ +pid_t ut_pid; /* process id */ +short ut_type; /* type of entry */ +struct exit_status ut_exit; /* exit status of a process */ + /* marked as DEAD_PROCESS */ +struct timeval ut_tv; /* time entry was made */ +int ut_session; /* session ID, used for */ + /* windowing */ +short ut_syslen; /* significant length of */ + /* ut_host */ + /* including terminating null */ +char ut_host[257]; /* host name, if remote */ +.fi +.in -2 + +.sp +.LP +The \fBexit_status\fR structure includes the following members: +.sp +.in +2 +.nf +short e_termination; /* termination status */ +short e_exit; /* exit status */ +.fi +.in -2 + +.SS "\fBgetutxent()\fR" +.sp +.LP +The \fBgetutxent()\fR function reads in the next entry from a \fButmpx\fR +database. If the database is not already open, it opens it. If it reaches the +end of the database, it fails. +.SS "\fBgetutxid()\fR" +.sp +.LP +The \fBgetutxid()\fR function searches forward from the current point in the +\fButmpx\fR database until it finds an entry with a \fBut_type\fR matching +\fIid\fR->\fBut_type\fR, if the type specified is \fBRUN_LVL\fR, +\fBBOOT_TIME\fR, \fBDOWN_TIME\fR, \fBOLD_TIME\fR, or \fBNEW_TIME\fR. If the +type specified in \fIid\fR is \fBINIT_PROCESS\fR, \fBLOGIN_PROCESS\fR, +\fBUSER_PROCESS\fR, or \fBDEAD_PROCESS\fR, then \fBgetutxid()\fR will return a +pointer to the first entry whose type is one of these four and whose +\fBut_id\fR member matches \fIid\fR->\fBut_id\fR. If the end of database is +reached without a match, it fails. +.SS "\fBgetutxline()\fR" +.sp +.LP +The \fBgetutxline()\fR function searches forward from the current point in the +\fButmpx\fR database until it finds an entry of the type \fBLOGIN_PROCESS\fR or +\fBUSER_PROCESS\fR which also has a \fIut_line\fR string matching the +\fIline\fR->\fBut_line\fR string. If the end of the database is reached +without a match, it fails. +.SS "\fBpututxline()\fR" +.sp +.LP +The \fBpututxline()\fR function writes the supplied \fButmpx\fR structure into +the \fButmpx\fR database. It uses \fBgetutxid()\fR to search forward for the +proper place if it finds that it is not already at the proper place. It is +expected that normally the user of \fBpututxline()\fR will have searched for +the proper entry using one of the \fBgetutx()\fR routines. If so, +\fBpututxline()\fR will not search. If \fBpututxline()\fR does not find a +matching slot for the new entry, it will add a new entry to the end of the +database. It returns a pointer to the \fButmpx\fR structure. When called by a +non-root user, \fBpututxline()\fR invokes a \fBsetuid()\fR root program to +verify and write the entry, since the \fButmpx\fR database is normally writable +only by root. In this event, the \fBut_name\fR member must correspond to the +actual user name associated with the process; the \fBut_type\fR member must be +either \fBUSER_PROCESS\fR or \fBDEAD_PROCESS\fR; and the \fBut_line\fR member +must be a device special file and be writable by the user. +.SS "\fBsetutxent()\fR" +.sp +.LP +The \fBsetutxent()\fR function resets the input stream to the beginning. This +should be done before each search for a new entry if it is desired that the +entire database be examined. +.SS "\fBendutxent()\fR" +.sp +.LP +The \fBendutxent()\fR function closes the currently open database. +.SS "\fButmpxname()\fR" +.sp +.LP +The \fButmpxname()\fR function allows the user to change the name of the +database file examined from \fB/var/adm/utmpx\fR to any other file, most often +\fB/var/adm/wtmpx\fR. If the file does not exist, this will not be apparent +until the first attempt to reference the file is made. The \fButmpxname()\fR +function does not open the file, but closes the old file if it is currently +open and saves the new file name. The new file name must end with the "x" +character to allow the name of the corresponding \fButmp\fR file to be easily +obtainable.; otherwise, an error value of \fB0\fR is returned. The function +returns \fB1\fR on success. +.SS "\fBgetutmp()\fR" +.sp +.LP +The \fBgetutmp()\fR function copies the information stored in the members of +the \fButmpx\fR structure to the corresponding members of the \fButmp\fR +structure. If the information in any member of \fButmpx\fR does not fit in the +corresponding \fButmp\fR member, the data is silently truncated. (See +\fBgetutent\fR(3C) for \fButmp\fR structure) +.SS "\fBgetutmpx()\fR" +.sp +.LP +The \fBgetutmpx()\fR function copies the information stored in the members of +the \fButmp\fR structure to the corresponding members of the \fButmpx\fR +structure. (See \fBgetutent\fR(3C) for \fButmp\fR structure) +.SS "\fBupdwtmp()\fR" +.sp +.LP +The \fBupdwtmp()\fR function can be used in two ways. +.sp +.LP +If \fIwfile\fR is \fB/var/adm/wtmp\fR, the \fButmp\fR format record supplied by +the caller is converted to a \fButmpx \fRformat record and the +\fB/var/adm/wtmpx\fR file is updated (because the \fB/var/adm/wtmp\fR file no +longer exists, operations on \fBwtmp\fR are converted to operations on +\fBwtmpx\fR by the library functions. +.sp +.LP +If \fIwfile\fR is a file other than \fB/var/adm/wtmp\fR, it is assumed to be an +old file in \fButmp\fR format and is updated directly with the \fButmp\fR +format record supplied by the caller. +.SS "\fBupdwtmpx()\fR" +.sp +.LP +The \fBupdwtmpx()\fR function writes the contents of the \fButmpx\fR structure +pointed to by \fIutmpx\fR to the database. +.SS "\fButmpx\fR structure" +.sp +.LP +The values of the \fBe_termination\fR and \fBe_exit\fR members of the +\fBut_exit\fR structure are valid only for records of type \fBDEAD_PROCESS\fR. +For \fButmpx\fR entries created by \fBinit\fR(1M), these values are set +according to the result of the \fBwait()\fR call that \fBinit\fR performs on +the process when the process exits. See the \fBwait\fR(3C), manual page for the +values \fBinit\fR uses. Applications creating \fButmpx\fR entries can set +\fBut_exit\fR values using the following code example: +.sp +.in +2 +.nf +u->ut_exit.e_termination = WTERMSIG(process->p_exit) +u->ut_exit.e_exit = WEXITSTATUS(process->p_exit) +.fi +.in -2 + +.sp +.LP +See \fBwait.h\fR(3HEAD) for descriptions of the \fBWTERMSIG\fR and +\fBWEXITSTATUS\fR macros. +.sp +.LP +The \fBut_session\fR member is not acted upon by the operating system. It is +used by applications interested in creating \fButmpx\fR entries. +.sp +.LP +For records of type \fBUSER_PROCESS\fR, the \fBnonuser()\fR and +\fBnonuserx()\fR macros use the value of the \fBut_exit.e_exit\fR member to +mark \fButmpx\fR entries as real logins (as opposed to multiple xterms started +by the same user on a window system). This allows the system utilities that +display users to obtain an accurate indication of the number of actual users, +while still permitting each \fBpty\fR to have a \fButmpx\fR record (as most +applications expect.). The \fBNONROOT_USER\fR macro defines the value that +\fBlogin\fR places in the \fBut_exit.e_exit\fR member. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBgetutxent()\fR, \fBgetutxid()\fR, and +\fBgetutxline()\fR each return a pointer to a \fButmpx\fR structure containing +a copy of the requested entry in the user accounting database. Otherwise a +null pointer is returned. +.sp +.LP +The return value may point to a static area which is overwritten by a +subsequent call to \fBgetutxid ()\fR or \fBgetutxline()\fR. +.sp +.LP +Upon successful completion, \fBpututxline()\fR returns a pointer to a +\fButmpx\fR structure containing a copy of the entry added to the user +accounting database. Otherwise a null pointer is returned. +.sp +.LP +The \fBendutxent()\fR and \fBsetutxent()\fR functions return no value. +.sp +.LP +A null pointer is returned upon failure to read, whether for permissions or +having reached the end of file, or upon failure to write. +.SH USAGE +.sp +.LP +These functions use buffered standard I/O for input, but \fBpututxline()\fR +uses an unbuffered write to avoid race conditions between processes trying to +modify the \fButmpx\fR and \fBwtmpx\fR files. +.sp +.LP +Applications should not access the \fButmpx\fR and \fBwtmpx\fR databases +directly, but should use these functions to ensure that these databases are +maintained consistently. +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/var/adm/utmpx\fR\fR +.ad +.RS 18n +.rt +user access and accounting information +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/var/adm/wtmpx\fR\fR +.ad +.RS 18n +.rt +history of user access and accounting information +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilitySee below. +_ +MT-LevelUnsafe +.TE + +.sp +.LP +The \fBendutxent()\fR, \fBgetutxent()\fR, \fBgetutxid()\fR, \fBgetutxline()\fR, +\fBpututxline()\fR, and \fBsetutxent()\fR functions are Standard. +.SH SEE ALSO +.sp +.LP +\fBgetutent\fR(3C), \fBttyslot\fR(3C), \fBwait\fR(3C), \fBwait.h\fR(3HEAD), +\fButmpx\fR(4), \fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +The most current entry is saved in a static structure. Multiple accesses +require that it be copied before further accesses are made. On each call to +either \fBgetutxid()\fR or \fBgetutxline()\fR, the routine examines the static +structure before performing more I/O. If the contents of the static structure +match what it is searching for, it looks no further. For this reason, to use +\fBgetutxline()\fR to search for multiple occurrences it would be necessary to +zero out the static after each success, or \fBgetutxline()\fR would just return +the same structure over and over again. There is one exception to the rule +about emptying the structure before further reads are done. The implicit read +done by \fBpututxline()\fR (if it finds that it is not already at the correct +place in the file) will not hurt the contents of the static structure returned +by the \fBgetutxent()\fR, \fBgetutxid()\fR, or \fBgetutxline()\fR routines, if +the user has just modified those contents and passed the pointer back to +\fBpututxline()\fR. diff --git a/usr/src/man/man3c/getvfsent.3c b/usr/src/man/man3c/getvfsent.3c new file mode 100644 index 0000000000..5292a5f483 --- /dev/null +++ b/usr/src/man/man3c/getvfsent.3c @@ -0,0 +1,150 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getvfsent 3C "12 Mar 1997" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getvfsent, getvfsfile, getvfsspec, getvfsany \- get vfstab file entry +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> +#include <sys/vfstab.h> + +\fBint\fR \fBgetvfsent\fR(\fBFILE *\fR\fIfp\fR, \fBstruct vfstab *\fR\fIvp\fR); +.fi + +.LP +.nf +\fBint\fR \fBgetvfsfile\fR(\fBFILE *\fR\fIfp\fR, \fBstruct vfstab *\fR\fIvp\fR, \fBchar *\fR\fIfile\fR); +.fi + +.LP +.nf +\fBint\fR \fBgetvfsspec\fR(\fBFILE *\fR, \fBstruct vfstab *\fR\fIvp\fR, \fBchar *\fR\fIspec\fR); +.fi + +.LP +.nf +\fBint\fR \fBgetvfsany\fR(\fBFILE *\fR, \fBstruct vfstab *\fR\fIvp\fR, \fBstruct vfstab *\fR\fIvref\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetvfsent()\fR, \fBgetvfsfile()\fR, \fBgetvfsspec()\fR, and +\fBgetvfsany()\fR functions each fill in the structure pointed to by \fIvp\fR +with the broken-out fields of a line in the \fB/etc/vfstab\fR file. Each line +in the file contains a \fBvfstab\fR structure, declared in the +<\fBsys/vfstab.h\fR> header, whose following members are described on the +\fBvfstab\fR(4) manual page: +.sp +.in +2 +.nf +\fB char *vfs_special; + char *vfs_fsckdev; + char *vfs_mountp; + char *vfs_fstype; + char *vfs_fsckpass; + char *vfs_automnt; + char *vfs_mntopts;\fR +.fi +.in -2 + +.sp +.LP +The \fBgetvfsent()\fR function returns a pointer to the next \fBvfstab\fR +structure in the file; so successive calls can be used to search the entire +file. +.sp +.LP +The \fBgetvfsfile()\fR function searches the file referenced by \fIfp\fR until +a mount point matching \fBfile\fR is found and fills \fIvp\fR with the fields +from the line in the file. +.sp +.LP +The \fBgetvfsspec()\fR function searches the file referenced by \fIfp\fR until +a special device matching \fIspec\fR is found and fills \fIvp\fR with the +fields from the line in the file. The \fIspec\fR argument will try to match on +device type (block or character special) and major and minor device numbers. If +it cannot match in this manner, then it compares the strings. +.sp +.LP +The \fBgetvfsany()\fR function searches the file referenced by \fIfp\fR until a +match is found between a line in the file and \fIvref\fR. A match occurrs if +all non-null entries in \fIvref\fR match the corresponding fields in the file. +.sp +.LP +Note that these functions do not open, close, or rewind the file. +.SH RETURN VALUES +.sp +.LP +If the next entry is successfully read by \fBgetvfsent()\fR or a match is found +with \fBgetvfsfile()\fR, \fBgetvfsspec()\fR, or \fBgetvfsany()\fR, \fB0\fR is +returned. If an end-of-file is encountered on reading, these functions return +\fB\(mi1\fR\&. If an error is encountered, a value greater than 0 is returned. +The possible error values are: +.sp +.ne 2 +.mk +.na +\fB\fBVFS_TOOLONG\fR\fR +.ad +.RS 15n +.rt +A line in the file exceeded the internal buffer size of \fBVFS_LINE_MAX\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBVFS_TOOMANY\fR\fR +.ad +.RS 15n +.rt +A line in the file contains too many fields. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBVFS_TOOFEW\fR\fR +.ad +.RS 15n +.rt +A line in the file contains too few fields. +.RE + +.SH FILES +.sp +.LP +\fB/etc/vfstab\fR +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBvfstab\fR(4), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +The members of the \fBvfstab\fR structure point to information contained in a +static area, so it must be copied if it is to be saved. diff --git a/usr/src/man/man3c/getwc.3c b/usr/src/man/man3c/getwc.3c new file mode 100644 index 0000000000..4bb039f0b7 --- /dev/null +++ b/usr/src/man/man3c/getwc.3c @@ -0,0 +1,69 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getwc 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getwc \- get wide character from a stream +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> +#include <wchar.h> + +\fBwint_t\fR \fBgetwc\fR(\fBFILE\fR \fI*stream\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetwc()\fR function is equivalent to \fBfgetwc\fR(3C), except that if it +is implemented as a macro it may evaluate \fIstream\fR more than once, so the +argument should never be an expression with side effects. +.SH RETURN VALUES +.sp +.LP +Refer to \fBfgetwc\fR(3C). +.SH ERRORS +.sp +.LP +Refer to \fBfgetwc\fR(3C). +.SH USAGE +.sp +.LP +This interface is provided to align with some current implementations and with +possible future \fBISO\fR standards. +.sp +.LP +Because it may be implemented as a macro, \fBgetwc()\fR may treat incorrectly a +\fIstream\fR argument with side effects. In particular, +\fBgetwc\fR(*\fIf\fR\|++) may not work as expected. Therefore, use of this +function is not recommended; \fBfgetwc\fR(3C) should be used instead. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfgetwc\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/getwchar.3c b/usr/src/man/man3c/getwchar.3c new file mode 100644 index 0000000000..df6a17e91a --- /dev/null +++ b/usr/src/man/man3c/getwchar.3c @@ -0,0 +1,62 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getwchar 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getwchar \- get wide character from stdin stream +.SH SYNOPSIS +.LP +.nf +#include <wchar.h> + +\fBwint_t\fR \fBgetwchar\fR(void) +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetwchar()\fR function is equivalent to \fBgetwc(stdin)\fR. +.SH RETURN VALUES +.sp +.LP +Refer to \fBfgetwc\fR(3C). +.SH ERRORS +.sp +.LP +Refer to \fBfgetwc\fR(3C). +.SH USAGE +.sp +.LP +If the \fBwint_t\fR value returned by \fBgetwchar()\fR is stored into a +variable of type \fBwchar_t\fR and then compared against the \fBwint_t\fR macro +\fBWEOF\fR, the comparison may never succeed because \fBwchar_t\fR is defined +as unsigned. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfgetwc\fR(3C), \fBgetwc\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/getwd.3c b/usr/src/man/man3c/getwd.3c new file mode 100644 index 0000000000..8c23524c3b --- /dev/null +++ b/usr/src/man/man3c/getwd.3c @@ -0,0 +1,69 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getwd 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getwd \- get current working directory pathname +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> + +\fBchar *\fR\fBgetwd\fR(\fBchar *\fR\fIpath_name\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetwd()\fR function determines an absolute pathname of the current +working directory of the calling process, and copies that pathname into the +array pointed to by the \fIpath_name\fR argument. +.sp +.LP +If the length of the pathname of the current working directory is greater than +(\fIPATH_MAX\fR + 1) including the null byte, \fBgetwd()\fR fails and returns a +null pointer. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, a pointer to the string containing the absolute +pathname of the current working directory is returned. Otherwise, +\fBgetwd()\fR returns a null pointer and the contents of the array pointed to +by \fIpath_name\fR are undefined. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH USAGE +.sp +.LP +For portability to implementations conforming to versions of the X/Open +Portability Guide prior to SUS, \fBgetcwd\fR(3C) is preferred over this +function. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityStandard +.TE + +.SH SEE ALSO +.sp +.LP +\fBgetcwd\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/getwidth.3c b/usr/src/man/man3c/getwidth.3c new file mode 100644 index 0000000000..af306a240f --- /dev/null +++ b/usr/src/man/man3c/getwidth.3c @@ -0,0 +1,74 @@ +'\" te +.\" Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getwidth 3C "20 Dec 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getwidth \- get codeset information +.SH SYNOPSIS +.LP +.nf +#include <euc.h> +#include <getwidth.h> + +\fBvoid\fR \fBgetwidth\fR(\fBeucwidth_t *\fR\fIptr\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetwidth()\fR function reads the character class table for the current +locale to get information on the supplementary codesets. \fBgetwidth()\fR sets +this information into the struct \fBeucwidth_t\fR. This struct is defined in +<\fBeuc.h\fR> and has the following members: +.sp +.in +2 +.nf +short int _eucw1,_eucw2,_eucw3; +short int _scrw1,_scrw2,_scrw3; +short int _pcw; +char _multibyte; +.fi +.in -2 + +.sp +.LP +Codeset width values for supplementary codesets 1, 2, and 3 are set in +\fB_eucw1\fR, \fB_eucw2\fR, and \fB_eucw3\fR, respectively. Screen width values +for supplementary codesets 1, 2, and 3 are set in \fB_scrw1\fR, \fB_scrw2\fR, +and \fB_scrw3\fR, respectively. +.sp +.LP +The width of Extended Unix Code (EUC) Process Code is set in \fB_pcw\fR. The +\fB_multibyte\fR entry is set to \fB1\fR if multibyte characters are used, and +set to \fB0\fR if only single-byte characters are used. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +MT-LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBeuclen\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +The \fBgetwidth()\fR function can be used safely in a multithreaded +application, as long as \fBsetlocale\fR(3C) is not being called to change the +locale. +.sp +.LP +The \fBgetwidth()\fR function will only work with \fBEUC\fR locales. diff --git a/usr/src/man/man3c/getws.3c b/usr/src/man/man3c/getws.3c new file mode 100644 index 0000000000..d1dd4ef2f3 --- /dev/null +++ b/usr/src/man/man3c/getws.3c @@ -0,0 +1,95 @@ +'\" te +.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getws 3C "15 Oct 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getws, fgetws \- get a wide-character string from a stream +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> +include <widec.h> + +\fBwchar_t *\fR\fBgetws\fR(\fBwchar_t *\fR\fIws\fR); +.fi + +.LP +.nf +#include <stdio.h> +include <wchar.h> + +\fBwchar_t *\fR\fBfgetws\fR(\fBwchar_t *restrict\fR \fIws\fR, \fBint\fR \fIn\fR, \fBFILE *restrict\fR \fIstream\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetws()\fR function reads a string of characters from the standard input +stream, \fBstdin\fR, converts these characters to the corresponding +wide-character codes, and writes them to the array pointed to by \fIws\fR, +until a newline character is read, converted and transferred to \fIws\fR or an +end-of-file condition is encountered. The wide-character string, \fIws\fR, is +then terminated with a null wide-character code. +.sp +.LP +The \fBfgetws()\fR function reads characters from the \fIstream\fR, converts +them to the corresponding wide-character codes, and places them in the +\fBwchar_t\fR array pointed to by \fIws\fR until \fIn\fR\(mi1 characters are +read, or until a newline character is read, converted and transferred to +\fIws\fR, or an end-of-file condition is encountered. The wide-character +string, \fIws\fR, is then terminated with a null wide-character code. +.sp +.LP +If an error occurs, the resulting value of the file position indicator for the +stream is indeterminate. +.sp +.LP +The \fBfgetws()\fR function may mark the \fBst_atime\fR field of the file +associated with \fIstream\fR for update. The \fBst_atime\fR field will be +marked for update by the first successful execution of \fBfgetc\fR(3C), +\fBfgets\fR(3C), \fBfgetwc\fR(3C), \fBfgetws()\fR, \fBfread\fR(3C), +\fBfscanf\fR(3C), \fBgetc\fR(3C), \fBgetchar\fR(3C), \fBgets\fR(3C), or +\fBscanf\fR(3C) using \fIstream\fR that returns data not supplied by a prior +call to \fBungetc\fR(3C) or \fBungetwc\fR(3C). +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBgetws()\fR and \fBfgetws()\fR return \fIws\fR. +If the stream is at end-of-file, the end-of-file indicator for the stream is +set and \fBfgetws()\fR returns a null pointer. For standard-conforming (see +\fBstandards\fR(5)) applications, if the end-of-file indicator for the stream +is set, \fBfgetws()\fR returns a null pointer whether or not the stream is at +end-of-file. If a read error occurs, the error indicator for the stream is set +and \fBfgetws()\fR returns a null pointer and sets \fBerrno\fR to indicate the +error. +.SH ERRORS +.sp +.LP +See \fBfgetwc\fR(3C) for the conditions that will cause \fBfgetws()\fR to fail. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface Stability\fBfgetws()\fR is Standard. +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBferror\fR(3C), \fBfgetwc\fR(3C), \fBfread\fR(3C), \fBgetwc\fR(3C), +\fBputws\fR(3C), \fBscanf\fR(3C), \fBungetc\fR(3C), +\fBungetwc\fR(3C)\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/getzoneid.3c b/usr/src/man/man3c/getzoneid.3c new file mode 100644 index 0000000000..e87c53d36d --- /dev/null +++ b/usr/src/man/man3c/getzoneid.3c @@ -0,0 +1,141 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getzoneid 3C "1 Nov 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +getzoneid, getzoneidbyname, getzonenamebyid \- map between zone id and name +.SH SYNOPSIS +.LP +.nf +#include <zone.h> + +\fBzoneid_t\fR \fBgetzoneid\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBzoneid_t\fR \fBgetzoneidbyname\fR(\fBconst char *\fR\fIname\fR); +.fi + +.LP +.nf +\fBssize_t\fR \fBgetzonenamebyid\fR(\fBzoneid_t\fR \fIid\fR, \fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIbuflen\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetzoneid()\fR function returns the zone ID of the calling process. +.sp +.LP +The \fBgetzoneidbyname()\fR function returns the zone ID corresponding to the +named zone, if that zone is currently active. If \fIname\fR is \fINULL\fR, the +function returns the zone ID of the calling process. +.sp +.LP +The \fBgetzonenamebyid()\fR function stores the name of the zone with ID +specified by \fIid\fR in the location specified by \fIbuf\fR. The \fIbufsize\fR +argument specifies the size in bytes of the buffer. If the buffer is too small +to hold the complete null-terminated name, the first \fIbufsize\fR bytes of the +name are stored in the buffer. A buffer of size {\fBZONENAME_MAX\fR} is +sufficient to hold any zone name. If \fIbuf\fR is \fINULL\fR or \fIbufsize\fR +is 0, the name is not copied into the buffer. +.SH RETURN VALUES +.sp +.LP +On successful completion, \fBgetzoneid()\fR and \fBgetzoneidbyname()\fR return +a non-negative zone ID. Otherwise, \fBgetzoneidbyname()\fR returns \(mi1 and +sets \fBerrno\fR to indicate the error. +.sp +.LP +On successful completion, the \fBgetzonenamebyid()\fR function returns the +buffer size required to hold the full null-terminated name. Otherwise, it +returns \(mi1 and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBgetzoneidbyname()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 16n +.rt +The \fIname\fR argument is non-null and points to an illegal address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 16n +.rt +A zone with the indicated \fIname\fR is not active. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +The length of the \fIname\fR argument exceeds {\fBZONENAME_MAX\fR}. +.RE + +.sp +.LP +The \fBgetzonenamebyid()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +A zone with the specified ID is not active. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +.rt +The \fIbuf\fR argument points to an illegal address. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(2), \fBchroot\fR(2), \fBmalloc\fR(3C), \fBattributes\fR(5), +\fBzones\fR(5) diff --git a/usr/src/man/man3c/glob.3c b/usr/src/man/man3c/glob.3c new file mode 100644 index 0000000000..3c623b72d8 --- /dev/null +++ b/usr/src/man/man3c/glob.3c @@ -0,0 +1,461 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH glob 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +glob, globfree \- generate path names matching a pattern +.SH SYNOPSIS +.LP +.nf +#include <glob.h> + +\fBint\fR \fBglob\fR(\fBconst char *restrict\fR \fIpattern\fR, \fBint\fR \fIflags\fR, + \fBint(*\fR\fIerrfunc\fR)(const char *\fIepath\fR, int \fIeerrno)\fR, + \fBglob_t *restrict\fR \fIpglob\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBglobfree\fR(\fBglob_t *\fR\fIpglob\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBglob()\fR function is a path name generator. +.sp +.LP +The \fBglobfree()\fR function frees any memory allocated by \fBglob()\fR +associated with \fIpglob\fR. +.SS "\fIpattern\fR Argument" +.sp +.LP +The argument \fIpattern\fR is a pointer to a path name pattern to be expanded. +The \fBglob()\fR function matches all accessible path names against this +pattern and develops a list of all path names that match. In order to have +access to a path name, \fBglob()\fR requires search permission on every +component of a path except the last, and read permission on each directory of +any filename component of \fIpattern\fR that contains any of the following +special characters: +.sp +.in +2 +.nf +* ? [ +.fi +.in -2 + +.SS "\fIpglob\fR Argument" +.sp +.LP +The structure type \fBglob_t\fR is defined in the header \fB<glob.h>\fR and +includes at least the following members: +.sp +.in +2 +.nf +size_t gl_pathc; /* count of paths matched by */ + /* pattern */ +char **gl_pathv; /* pointer to list of matched */ + /* path names */ +size_t gl_offs; /* slots to reserve at beginning */ + /* of gl_pathv */ +.fi +.in -2 + +.sp +.LP +The \fBglob()\fR function stores the number of matched path names into +\fIpglob\(mi>\fR\fBgl_pathc\fR and a pointer to a list of pointers to path +names into \fIpglob\(mi>\fR\fBgl_pathv.\fR The path names are in sort order as +defined by the current setting of the \fBLC_COLLATE\fR category. The first +pointer after the last path name is a \fINULL\fR pointer. If the pattern does +not match any path names, the returned number of matched paths is set to 0, and +the contents of \fIpglob\(mi>\fR\fBgl_pathv\fR are implementation-dependent. +.sp +.LP +It is the caller's responsibility to create the structure pointed to by +\fIpglob\fR. The \fBglob()\fR function allocates other space as needed, +including the memory pointed to by \fBgl_pathv\fR. The \fBglobfree()\fR +function frees any space associated with \fIpglob\fR from a previous call to +\fBglob()\fR. +.SS "\fIflags\fR Argument" +.sp +.LP +The \fIflags\fR argument is used to control the behavior of \fBglob()\fR. The +value of \fIflags\fR is a bitwise inclusive \fBOR\fR of zero or more of the +following constants, which are defined in the header <\fBglob.h\fR>: +.sp +.ne 2 +.mk +.na +\fB\fBGLOB_APPEND\fR\fR +.ad +.RS 17n +.rt +Append path names generated to the ones from a previous call to \fBglob()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBGLOB_DOOFFS\fR\fR +.ad +.RS 17n +.rt +Make use of \fIpglob\(mi>\fR\fBgl_offs\fR\fI\&.\fR If this flag is set, +\fIpglob\(mi>\fR\fBgl_offs\fR is used to specify how many \fINULL\fR pointers +to add to the beginning of \fIpglob\(mi>\fR\fBgl_pathv\fR\fI\&.\fR In other +words, \fIpglob\(mi>\fR\fBgl_pathv\fR will point to +\fIpglob\(mi>\fR\fBgl_offs\fR \fINULL\fR pointers, followed by +\fIpglob\(mi>\fR\fBgl_pathc\fR path name pointers, followed by a \fINULL\fR +pointer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBGLOB_ERR\fR\fR +.ad +.RS 17n +.rt +Causes \fBglob()\fR to return when it encounters a directory that it cannot +open or read. Ordinarily, \fBglob()\fR continues to find matches. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBGLOB_MARK\fR\fR +.ad +.RS 17n +.rt +Each path name that is a directory that matches \fIpattern\fR has a slash +appended. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBGLOB_NOCHECK\fR\fR +.ad +.RS 17n +.rt +If \fIpattern\fR does not match any path name, then \fBglob()\fR returns a list +consisting of only \fIpattern\fR, and the number of matched path names is 1. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBGLOB_NOESCAPE\fR\fR +.ad +.RS 17n +.rt +Disable backslash escaping. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBGLOB_NOSORT\fR\fR +.ad +.RS 17n +.rt +Ordinarily, \fBglob()\fR sorts the matching path names according to the current +setting of the \fBLC_COLLATE\fR category. When this flag is used the order of +path names returned is unspecified. +.RE + +.sp +.LP +The \fBGLOB_APPEND\fR flag can be used to append a new set of path names to +those found in a previous call to \fBglob()\fR. The following rules apply when +two or more calls to \fBglob()\fR are made with the same value of \fIpglob\fR +and without intervening calls to \fBglobfree()\fR: +.RS +4 +.TP +1. +The first such call must not set \fBGLOB_APPEND.\fR All subsequent calls +must set it. +.RE +.RS +4 +.TP +2. +All the calls must set \fBGLOB_DOOFFS,\fR or all must not set it. +.RE +.RS +4 +.TP +3. +After the second call, \fIpglob\(mi>\fR\fBgl_pathv\fR points to a list +containing the following: +.RS +4 +.TP +a. +Zero or more \fINULL\fR pointers, as specified by \fBGLOB_DOOFFS\fR and +\fIpglob\(mi>\fR\fBgl_offs\fR. +.RE +.RS +4 +.TP +b. +Pointers to the path names that were in the \fIpglob\(mi>\fR\fBgl_pathv\fR +list before the call, in the same order as before. +.RE +.RS +4 +.TP +c. +Pointers to the new path names generated by the second call, in the +specified order. +.RE +.RE +.RS +4 +.TP +4. +The count returned in \fIpglob\(mi>\fR\fBgl_pathc\fR will be the total +number of path names from the two calls. +.RE +.RS +4 +.TP +5. +The application can change any of the fields after a call to \fBglob()\fR. +If it does, it must reset them to the original value before a subsequent call, +using the same \fIpglob\fR value, to \fBglobfree()\fR or \fBglob()\fR with the +\fBGLOB_APPEND\fR flag. +.RE +.SS "\fIerrfunc\fR and \fIepath\fR Arguments" +.sp +.LP +If, during the search, a directory is encountered that cannot be opened or read +and \fIerrfunc\fR is not a \fINULL\fR pointer, \fBglob()\fR calls +\fB(\fR\fI*errfunc\fR\fB)\fR with two arguments: +.RS +4 +.TP +1. +The \fIepath\fR argument is a pointer to the path that failed. +.RE +.RS +4 +.TP +2. +The \fIeerrno\fR argument is the value of \fIerrno\fR from the failure, as +set by the \fBopendir\fR(3C), \fBreaddir\fR(3C) or \fBstat\fR(2) functions. +(Other values may be used to report other errors not explicitly documented for +those functions.) +.RE +.sp +.LP +The following constants are defined as error return values for \fBglob()\fR: +.sp +.ne 2 +.mk +.na +\fB\fBGLOB_ABORTED\fR\fR +.ad +.RS 16n +.rt +The scan was stopped because \fBGLOB_ERR\fR was set or +\fB(\fR\fI*errfunc\fR\fB)\fR returned non-zero. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBGLOB_NOMATCH\fR\fR +.ad +.RS 16n +.rt +The pattern does not match any existing path name, and \fBGLOB_NOCHECK\fR was +not set in flags. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBGLOG_NOSPACE\fR\fR +.ad +.RS 16n +.rt +An attempt to allocate memory failed. +.RE + +.sp +.LP +If \fB(\fR\fI*errfunc\fR\fB)\fR is called and returns non-zero, or if the +\fBGLOB_ERR\fR flag is set in \fIflags\fR, \fBglob()\fR stops the scan and +returns \fBGLOB_ABORTED\fR after setting \fIgl_pathc\fR and \fIgl_pathv\fR in +\fIpglob\fR to reflect the paths already scanned. If \fBGLOB_ERR\fR is not set +and either \fIerrfunc\fR is a \fINULL\fR pointer or +\fB(\fR\fI*errfunc\fR\fB)\fR returns 0, the error is ignored. +.SH RETURN VALUES +.sp +.LP +The following values are returned by \fBglob()\fR: +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 12n +.rt +Successful completion. The argument \fIpglob\(mi>\fR\fBgl_pathc\fR returns the +number of matched path names and the argument \fIpglob\(mi>\fR\fBgl_pathv\fR +contains a pointer to a null-terminated list of matched and sorted path names. +However, if \fIpglob\(mi>\fR\fBgl_pathc\fR is 0, the content of +\fIpglob\(mi>\fR\fBgl_pathv\fR is undefined. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnon-zero\fR\fR +.ad +.RS 12n +.rt +An error has occurred. Non-zero constants are defined in <\fBglob.h\fR>. The +arguments \fIpglob\(mi>\fR\fBgl_pathc\fR and \fIpglob\(mi>\fR\fBgl_pathv\fR are +still set as defined above. +.RE + +.sp +.LP +The \fBglobfree()\fR function returns no value. +.SH USAGE +.sp +.LP +This function is not provided for the purpose of enabling utilities to perform +path name 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 path name expansion on strings +obtained from other sources, such as a pattern typed by a user or read from a +file. +.sp +.LP +If a utility needs to see if a path name matches a given pattern, it can use +\fBfnmatch\fR(3C). +.sp +.LP +Note that \fBgl_pathc\fR and \fBgl_pathv\fR have meaning even if \fBglob()\fR +fails. This allows \fBglob()\fR to report partial results in the event of an +error. However, if \fBgl_pathc\fR is 0, \fBgl_pathv\fR is unspecified even if +\fBglob()\fR did not return an error. +.sp +.LP +The \fBGLOB_NOCHECK\fR option could be used when an application wants to expand +a path name if wildcards are specified, but wants to treat the pattern as just +a string otherwise. +.sp +.LP +The new path names generated by a subsequent call with \fBGLOB_APPEND\fR are +not sorted together with the previous path names. This mirrors the way that the +shell handles path name expansion when multiple expansions are done on a +command line. +.sp +.LP +Applications that need tilde and parameter expansion should use the +\fBwordexp\fR(3C) function. +.SH EXAMPLES +.LP +\fBExample 1 \fRExample of \fBglob_doofs\fR function. +.sp +.LP +One use of the \fBGLOB_DOOFFS\fR flag is by applications that build an argument +list for use with the \fBexecv()\fR, \fBexecve()\fR, or \fBexecvp()\fR +functions (see \fBexec\fR(2)). Suppose, for example, that an application wants +to do the equivalent of: + +.sp +.in +2 +.nf +\fBls\fR \fB-l\fR *.c +.fi +.in -2 + +.sp +.LP +but for some reason: + +.sp +.in +2 +.nf +system("ls -l *.c") +.fi +.in -2 + +.sp +.LP +is not acceptable. The application could obtain approximately the same result +using the sequence: + +.sp +.in +2 +.nf +globbuf.gl_offs = 2; +glob ("*.c", GLOB_DOOFFS, NULL, &globbuf); +globbuf.gl_pathv[0] = "ls"; +globbuf.gl_pathv[1] = "-l"; +execvp ("ls", &globbuf.gl_pathv[0]); +.fi +.in -2 + +.sp +.LP +Using the same example: + +.sp +.in +2 +.nf +\fBls\fR \fB-l\fR *.c *.h +.fi +.in -2 + +.sp +.LP +could be approximately simulated using \fBGLOB_APPEND\fR as follows: + +.sp +.in +2 +.nf +\fBglobbuf.gl_offs = 2; +glob ("*.c", GLOB_DOOFFS, NULL, &globbuf); +glob ("*.h", GLOB_DOOFFS|GLOB_APPEND, NULL, &globbuf); +\&.\|.\|.\fR +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBexecv\fR(2), \fBstat\fR(2), \fBfnmatch\fR(3C), \fBopendir\fR(3C), +\fBreaddir\fR(3C), \fBwordexp\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/grantpt.3c b/usr/src/man/man3c/grantpt.3c new file mode 100644 index 0000000000..6b1568d7c6 --- /dev/null +++ b/usr/src/man/man3c/grantpt.3c @@ -0,0 +1,102 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1994, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH grantpt 3C "14 Aug 2006" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +grantpt \- grant access to the slave pseudo-terminal device +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBint\fR \fBgrantpt\fR(\fBint\fR \fIfildes\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgrantpt()\fR function changes the mode and ownership of the slave +pseudo-terminal device associated with its master pseudo-terminal counterpart. +\fIfildes\fR is the file descriptor returned from a successful open of the +master pseudo-terminal device. The user ID of the slave is set to the real UID +of the calling process and the group ID is set to a reserved group. The +permission mode of the slave pseudo-terminal is set to readable and writable by +the owner and writable by the group. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBgrantpt()\fR returns \fB0\fR. Otherwise, it +returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBgrantpt()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIfildes\fR argument is not a valid open file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIfildes\fR argument is not associated with a master pseudo-terminal +device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 10n +.rt +The corresponding slave pseudo-terminal device could not be accessed. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBopen\fR(2), \fBptsname\fR(3C), \fBunlockpt\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man3c/hsearch.3c b/usr/src/man/man3c/hsearch.3c new file mode 100644 index 0000000000..070ec2ff95 --- /dev/null +++ b/usr/src/man/man3c/hsearch.3c @@ -0,0 +1,170 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH hsearch 3C "29 Dec 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +hsearch, hcreate, hdestroy \- manage hash search tables +.SH SYNOPSIS +.LP +.nf +#include <search.h> + +\fBENTRY *\fR\fBhsearch\fR(\fBENTRY\fR \fIitem\fR, \fBACTION\fR \fIaction\fR); +.fi + +.LP +.nf +\fBint\fR \fBhcreate\fR(\fBsize_t\fR \fImekments\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBhdestroy\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBhsearch()\fR function is a hash-table search routine generalized from +Knuth (6.4) Algorithm D. It returns a pointer into a hash table indicating the +location at which an entry can be found. The comparison function used by +\fBhsearch()\fR is \fBstrcmp()\fR (see \fBstring\fR(3C)). The \fIitem\fR +argument is a structure of type \fBENTRY\fR (defined in the \fB<search.h>\fR +header) containing two pointers: \fBitem.key\fR points to the comparison key, +and \fBitem.data\fR points to any other data to be associated with that key. +(Pointers to types other than void should be cast to pointer-to-void.) The +\fIaction\fR argument is a member of an enumeration type \fBACTION\fR (defined +in \fB<search.h>\fR) indicating the disposition of the entry if it cannot be +found in the table. \fBENTER\fR indicates that the item should be inserted in +the table at an appropriate point. Given a duplicate of an existing item, the +new item is not entered and \fBhsearch()\fR returns a pointer to the existing +item. \fBFIND\fR indicates that no entry should be made. Unsuccessful +resolution is indicated by the return of a null pointer. +.sp +.LP +The \fBhcreate()\fR function allocates sufficient space for the table, and must +be called before \fBhsearch()\fR is used. The \fInel\fR argument is an +estimate of the maximum number of entries that the table will contain. This +number may be adjusted upward by the algorithm in order to obtain certain +mathematically favorable circumstances. +.sp +.LP +The \fBhdestroy()\fR function destroys the search table, and may be followed by +another call to \fBhcreate()\fR. +.SH RETURN VALUES +.sp +.LP +The \fBhsearch()\fR function returns a null pointer if either the action is +\fBFIND\fR and the item could not be found or the action is \fBENTER\fR and the +table is full. +.sp +.LP +The \fBhcreate()\fR function returns \fB0\fR if it cannot allocate sufficient +space for the table. +.SH USAGE +.sp +.LP +The \fBhsearch()\fR and \fBhcreate()\fR functions use \fBmalloc\fR(3C) to +allocate space. +.sp +.LP +Only one hash search table may be active at any given time. +.SH EXAMPLES +.LP +\fBExample 1 \fRExample to read in strings. +.sp +.LP +The following example will read in strings followed by two numbers and store +them in a hash table, discarding duplicates. It will then read in strings and +find the matching entry in the hash table and print it. + +.sp +.in +2 +.nf +\fB#include <stdio.h> +#include <search.h> +#include <string.h> +#include <stdlib.h> + +struct info { /* this is the info stored in table */ + int age, room; /* other than the key */ +}; +#define NUM_EMPL 5000 /* # of elements in search table */ +main( ) +{ + /* space to store strings */ + char string_space[NUM_EMPL*20]; + /* space to store employee info */ + struct info info_space[NUM_EMPL]; + /* next avail space in string_space */ + char *str_ptr = string_space; + /* next avail space in info_space */ + struct info *info_ptr = info_space; + ENTRY item, *found_item; + /* name to look for in table */ + char name_to_find[30]; + int i = 0; + + /* create table */ + (void) hcreate(NUM_EMPL); + while (scanf("%s%d%d", str_ptr, &info_ptr\(mi>age, + &info_ptr\(mi>room) != EOF && i++ < NUM_EMPL) { + /* put info in structure, and structure in item */ + item.key = str_ptr; + item.data = (void *)info_ptr; + str_ptr += strlen(str_ptr) + 1; + info_ptr++; + /* put item into table */ + (void) hsearch(item, ENTER); + } + + /* access table */ + item.key = name_to_find; + while (scanf("%s", item.key) != EOF) { + if ((found_item = hsearch(item, FIND)) != NULL) { + /* 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; +}\fR +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBbsearch\fR(3C), \fBlsearch\fR(3C), \fBmalloc\fR(3C), \fBstring\fR(3C), +\fBtsearch\fR(3C), \fBmalloc\fR(3MALLOC), \fBattributes\fR(5), +\fBstandards\fR(5) +.sp +.LP +\fIThe Art of Computer Programming, Volume 3, Sorting and Searching by Donald +E. Knuth, published by Addison-Wesley Publishing Company, 1973.\fR diff --git a/usr/src/man/man3c/iconv.3c b/usr/src/man/man3c/iconv.3c new file mode 100644 index 0000000000..113a37615b --- /dev/null +++ b/usr/src/man/man3c/iconv.3c @@ -0,0 +1,402 @@ +'\" te +.\" Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved . +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH iconv 3C "6 Oct 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +iconv \- code conversion function +.SH SYNOPSIS +.SS "Default" +.LP +.nf +#include <iconv.h> + +\fBextern size_t\fR \fBiconv\fR(\fBiconv_t\fR \fIcd\fR, \fBconst char **restrict\fR \fIinbuf\fR, + \fBsize_t *restrict\fR \fIinbytesleft\fR, \fBchar **restrict\fR \fIoutbuf\fR, + \fBsize_t *restrict\fR \fIoutbytesleft\fR); +.fi + +.SS "SUSv3" +.LP +.nf +#include <iconv.h> + +\fBsize_t\fR \fBiconv\fR(\fBiconv_t\fR \fIcd\fR, \fBchar **restrict\fR \fIinbuf\fR, + \fBsize_t *restrict\fR \fIinbytesleft\fR, \fBchar **restrict\fR \fIoutbuf\fR, + \fBsize_t *restrict\fR \fIoutbytesleft\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBiconv()\fR function converts the sequence of characters from one code +set, in the array specified by \fIinbuf\fR, into a sequence of corresponding +characters in another code set, in the array specified by \fIoutbuf\fR. The +code sets are those specified in the \fIiconv_open\fR(\|) call that returned +the conversion descriptor, \fIcd\fR. The \fIinbuf\fR argument points to a +variable that points to the first character in the input buffer and +\fIinbytesleft\fR indicates the number of bytes to the end of the buffer to be +converted. The \fIoutbuf\fR argument points to a variable that points to the +first available byte in the output buffer and \fIoutbytesleft\fR indicates the +number of the available bytes to the end of the buffer. +.sp +.LP +For state-dependent encodings, the conversion descriptor \fIcd\fR is placed +into its initial shift state by a call for which \fIinbuf\fR is a null pointer, +or for which \fIinbuf\fR points to a null pointer. When \fBiconv()\fR is called +in this way, and if \fIoutbuf\fR is not a null pointer or a pointer to a null +pointer, and \fIoutbytesleft\fR points to a positive value, \fBiconv()\fR will +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, \fBiconv()\fR will fail and set \fIerrno\fR to +\fBE2BIG\fR. Subsequent calls with \fIinbuf\fR 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. +.sp +.LP +If a sequence of input bytes does not form a valid character in the specified +code set, conversion stops after the previous successfully converted +character. If the input buffer ends with an incomplete character or shift +sequence, conversion stops after the previous successfully converted bytes. If +the output buffer is not large enough to hold the entire converted input, +conversion stops just prior to the input bytes that would cause the output +buffer to overflow. The variable pointed to by \fIinbuf\fR is updated to point +to the byte following the last byte successfully used in the conversion. The +value pointed to by \fIinbytesleft\fR is decremented to reflect the number of +bytes still not converted in the input buffer. The variable pointed to by +\fIoutbuf\fR is updated to point to the byte following the last byte of +converted output data. The value pointed to by \fIoutbytesleft\fR is +decremented to reflect the number of bytes still available in the output +buffer. For state-dependent encodings, the conversion descriptor is updated to +reflect the shift state in effect at the end of the last successfully +converted byte sequence. +.sp +.LP +If \fBiconv()\fR encounters a character in the input buffer that is legal, but +for which an identical character does not exist in the target code set, +\fBiconv()\fR performs an implementation-defined conversion on this character. +.SH RETURN VALUES +.sp +.LP +The \fBiconv()\fR function updates the variables pointed to by the arguments +to reflect the extent of the conversion and returns the number of non-identical +conversions performed. If the entire string in the input buffer is converted, +the value pointed to by \fIinbytesleft\fR will be \fB0\fR. If the input +conversion is stopped due to any conditions mentioned above, the value pointed +to by \fIinbytesleft\fR will be non-zero and \fBerrno\fR is set to indicate +the condition. If an error occurs \fBiconv()\fR returns \fB(size_t)\fR +\fB\(mi1\fR and sets \fIerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBiconv()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEILSEQ\fR\fR +.ad +.RS 10n +.rt +Input conversion stopped due to an input byte that does not belong to the input +code set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBE2BIG\fR\fR +.ad +.RS 10n +.rt +Input conversion stopped due to lack of space in the output buffer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +Input conversion stopped due to an incomplete character or shift sequence at +the end of the input buffer. +.RE + +.sp +.LP +The \fBiconv()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 9n +.rt +The \fIcd\fR argument is not a valid open conversion descriptor. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing the \fBiconv()\fR Functions +.sp +.LP +The following example uses the \fBiconv()\fR functions: + +.sp +.in +2 +.nf +#include <stdio.h> +#include <errno.h> +#include <string.h> +#include <iconv.h> +#include <stdlib.h> + +/* + * For state-dependent encodings, changes the state of the + * conversion descriptor to initial shift state. Also, outputs + * the byte sequence to change the state to initial state. + * This code is assuming the iconv call for initializing the + * state will not fail due to lack of space in the output buffer. + */ +#define INIT_SHIFT_STATE(cd, fptr, ileft, tptr, oleft) \e + { \e + fptr = NULL; \e + ileft = 0; \e + tptr = to; \e + oleft = BUFSIZ; \e + (void) iconv(cd, &fptr, &ileft, &tptr, &oleft); \e + (void) fwrite(to, 1, BUFSIZ - oleft, stdout); \e + } + +int +main(int argc, char **argv) +{ + iconv_t cd; + char from[BUFSIZ], to[BUFSIZ]; + char *from_code, *to_code; + char *tptr; + const char *fptr; + size_t ileft, oleft, num, ret; + + + if (argc != 3) { + (void) fprintf(stderr, + "Usage: %s from_codeset to_codeset\e\en", argv[0]); + return (1); + } + + from_code = argv[1]; + to_code = argv[2]; + + cd = iconv_open((const char *)to_code, (const char *)from_code); + if (cd == (iconv_t)-1) { + /* + * iconv_open failed + */ + (void) fprintf(stderr, + "iconv_open(%s, %s) failed\e\en", to_code, from_code); + return (1); + } + + ileft = 0; + while ((ileft += + (num = fread(from + ileft, 1, BUFSIZ - ileft, stdin))) > 0) { + if (num == 0) { + /* + * Input buffer still contains incomplete character + * or sequence. However, no more input character. + */ + + /* + * Initializes the conversion descriptor and outputs + * the sequence to change the state to initial state. + */ + INIT_SHIFT_STATE(cd, fptr, ileft, tptr, oleft); + (void) iconv_close(cd); + + (void) fprintf(stderr, "Conversion error\e\en"); + return (1); + } + + fptr = from; + for (;;) { + tptr = to; + oleft = BUFSIZ; + + ret = iconv(cd, &fptr, &ileft, &tptr, &oleft); + if (ret != (size_t)-1) { + /* + * iconv succeeded + */ + + /* + * Outputs converted characters + */ + (void) fwrite(to, 1, BUFSIZ - oleft, stdout); + break; + } + + /* + * iconv failed + */ + if (errno == EINVAL) { + /* + * Incomplete character or shift sequence + */ + + /* + * Outputs converted characters + */ + (void) fwrite(to, 1, BUFSIZ - oleft, stdout); + /* + * Copies remaining characters in input buffer + * to the top of the input buffer. + */ + (void) memmove(from, fptr, ileft); + /* + * Tries to fill input buffer from stdin + */ + break; + } else if (errno == E2BIG) { + /* + * Lack of space in output buffer + */ + + /* + * Outputs converted characters + */ + (void) fwrite(to, 1, BUFSIZ - oleft, stdout); + /* + * Tries to convert remaining characters in + * input buffer with emptied output buffer + */ + continue; + } else if (errno == EILSEQ) { + /* + * Illegal character or shift sequence + */ + + /* + * Outputs converted characters + */ + (void) fwrite(to, 1, BUFSIZ - oleft, stdout); + /* + * Initializes the conversion descriptor and + * outputs the sequence to change the state to + * initial state. + */ + INIT_SHIFT_STATE(cd, fptr, ileft, tptr, oleft); + (void) iconv_close(cd); + + (void) fprintf(stderr, + "Illegal character or sequence\e\en"); + return (1); + } else if (errno == EBADF) { + /* + * Invalid conversion descriptor. + * Actually, this shouldn't happen here. + */ + (void) fprintf(stderr, "Conversion error\e\en"); + return (1); + } else { + /* + * This errno is not defined + */ + (void) fprintf(stderr, "iconv error\e\en"); + return (1); + } + } + } + + /* + * Initializes the conversion descriptor and outputs + * the sequence to change the state to initial state. + */ + INIT_SHIFT_STATE(cd, fptr, ileft, tptr, oleft); + + (void) iconv_close(cd); + return (0); +} +.fi +.in -2 + +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/iconv/*.so\fR\fR +.ad +.sp .6 +.RS 4n +conversion modules for 32-bit +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/iconv/sparcv9/*.so\fR\fR +.ad +.sp .6 +.RS 4n +conversion modules for 64-bit sparc +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/iconv/amd64/*.so\fR\fR +.ad +.sp .6 +.RS 4n +conversion modules for 64-bit amd64 +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/iconv/geniconvtbl/binarytables/*.bt\fR\fR +.ad +.sp .6 +.RS 4n +conversion binary tables +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgeniconvtbl\fR(1), \fBiconv\fR(1), \fBiconv_close\fR(3C), +\fBiconv_open\fR(3C), \fBgeniconvtbl\fR(4), \fBattributes\fR(5), +\fBiconv\fR(5), \fBiconv_unicode\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/iconv_close.3c b/usr/src/man/man3c/iconv_close.3c new file mode 100644 index 0000000000..ef0c225f72 --- /dev/null +++ b/usr/src/man/man3c/iconv_close.3c @@ -0,0 +1,77 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH iconv_close 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +iconv_close \- code conversion deallocation function +.SH SYNOPSIS +.LP +.nf +#include <iconv.h> + +\fBint\fR \fBiconv_close\fR(\fBiconv_t\fR \fIcd\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBiconv_close()\fR function deallocates the conversion descriptor \fBcd\fR +and all other associated resources allocated by the \fBiconv_open\fR(3C) +function. +.sp +.LP +If a file descriptor is used to implement the type \fBiconv_t\fR, that file +descriptor will be closed. +.sp +.LP +For examples using the \fBiconv_close()\fR function, see \fBiconv\fR(3C). +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBiconv_close()\fR returns \fB0\fR; otherwise, it +returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBiconv_close()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 9n +.rt +The conversion descriptor is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBiconv\fR(3C), \fBiconv_open\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/iconv_open.3c b/usr/src/man/man3c/iconv_open.3c new file mode 100644 index 0000000000..d01fd1f3d3 --- /dev/null +++ b/usr/src/man/man3c/iconv_open.3c @@ -0,0 +1,147 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Portions Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH iconv_open 3C "2 Oct 2001" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +iconv_open \- code conversion allocation function +.SH SYNOPSIS +.LP +.nf +#include <iconv.h> + +\fBiconv_t\fR \fBiconv_open\fR(\fBconst char *\fR\fItocode\fR, \fBconst char *\fR\fIfromcode\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBiconv_open()\fR function returns a conversion descriptor that describes +a conversion from the codeset specified by the string pointed to by the +\fIfromcode\fR argument to the codeset specified by the string pointed to by +the \fItocode\fR argument. For state-dependent encodings, the conversion +descriptor will be in a codeset-dependent initial shift state, ready for +immediate use with the \fBiconv\fR(3C) function. +.sp +.LP +Settings of \fIfromcode\fR and \fItocode\fR and their permitted combinations +are implementation-dependent. +.sp +.LP +The \fBiconv_open()\fR function supports the alias of the encoding name +specified in \fItocode\fR and \fIfromcode\fR. The alias table of the encoding +name is described in the file \fB/usr/lib/iconv/alias\fR. See \fBalias\fR(4). +.sp +.LP +A conversion descriptor remains valid in a process until that process closes +it. +.sp +.LP +For examples using the \fBiconv_open()\fR function, see \fBiconv\fR(3C). +.SH RETURN VALUES +.sp +.LP +Upon successful completion \fBiconv_open()\fR returns a conversion descriptor +for use on subsequent calls to \fBiconv()\fR. Otherwise, \fBiconv_open()\fR +returns \fB(iconv_t)\fR \fB\(mi1\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBiconv_open\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 10n +.rt +\fB{OPEN_MAX}\fR files descriptors are currently open in the calling process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENFILE\fR\fR +.ad +.RS 10n +.rt +Too many files are currently open in the system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient storage space is available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The conversion specified by \fIfromcode\fR and \fItocode\fR is not supported by +the implementation. +.RE + +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/iconv/alias\fR\fR +.ad +.RS 24n +.rt +alias table file of the encoding name +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBexec\fR(2), \fBiconv\fR(3C), \fBiconv_close\fR(3C), \fBmalloc\fR(3C), +\fBalias\fR(4), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +The \fBiconv_open()\fR function uses \fBmalloc\fR(3C) to allocate space for +internal buffer areas. \fBiconv_open()\fR may fail if there is insufficient +storage space to accommodate these buffers. +.sp +.LP +Portable applications must assume that conversion descriptors are not valid +after a call to one of the \fBexec\fR functions (see \fBexec\fR(2)). diff --git a/usr/src/man/man3c/imaxabs.3c b/usr/src/man/man3c/imaxabs.3c new file mode 100644 index 0000000000..336f7aa7be --- /dev/null +++ b/usr/src/man/man3c/imaxabs.3c @@ -0,0 +1,61 @@ +'\" te +.\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved. Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH imaxabs 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +imaxabs \- return absolute value +.SH SYNOPSIS +.LP +.nf +#include <inttypes.h> + +\fBintmax_t\fR \fBimaxabs\fR(\fBintmax_t\fR \fIj\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBimaxabs()\fR function computes the absolute value of an integer \fIj\fR. +If the result cannot be represented, the behavior is undefined. +.SH RETURN VALUES +.sp +.LP +The \fBimaxabs()\fR function returns the absolute value. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH USAGE +.sp +.LP +The absolute value of the most negative number cannot be represented in two's +complement. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBimaxdiv\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/imaxdiv.3c b/usr/src/man/man3c/imaxdiv.3c new file mode 100644 index 0000000000..1c254e75ad --- /dev/null +++ b/usr/src/man/man3c/imaxdiv.3c @@ -0,0 +1,60 @@ +'\" te +.\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved. Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH imaxdiv 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +imaxdiv \- return quotient and remainder +.SH SYNOPSIS +.LP +.nf +#include <inttypes.h> + +\fBimaxdiv_t\fR \fBimaxdiv\fR(\fBimaxdiv_t\fR \fInumer\fR, \fBimaxdiv_t\fR \fIdenom\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBimaxdiv()\fR function computes \fInumer\fR / \fIdenom\fR and \fInumer\fR +% \fIdenom\fR in a single operation. +.SH RETURN VALUES +.sp +.LP +The \fBimaxdiv()\fR function returns a structure of type \fBimaxdiv_t\fR, +comprising both the quotient and the remainder. The structure contains (in +either order) the members \fBquot\fR (the quotient) and \fBrem\fR (the +remainder), each of which has type \fBintmax_t\fR. If either part of the result +cannot be represented, the behavior is undefined. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBimaxabs\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/index.3c b/usr/src/man/man3c/index.3c new file mode 100644 index 0000000000..0dd61808a4 --- /dev/null +++ b/usr/src/man/man3c/index.3c @@ -0,0 +1,78 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH index 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +index, rindex \- string operations +.SH SYNOPSIS +.LP +.nf +#include <strings.h> + +\fBchar *\fR\fBindex\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBrindex\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBindex()\fR and \fBrindex()\fR functions operate on null-terminated +strings. +.sp +.LP +The \fBindex()\fR function returns a pointer to the first occurrence of +character \fIc\fR in string \fIs\fR. +.sp +.LP +The \fBrindex()\fR function returns a pointer to the last occurrence of +character \fIc\fR in string \fIs\fR. +.sp +.LP +Both \fBindex()\fR and \fBrindex()\fR return a null pointer if \fIc\fR does +not occur in the string. The null character terminating a string is considered +to be part of the string. +.SH USAGE +.sp +.LP +On most modern computer systems, you can \fInot\fR use a null pointer to +indicate a null string. A null pointer is an error and results in an abort of +the program. If you wish to indicate a null string, you must use a pointer +that points to an explicit null string. On some machines and with some +implementations of the C programming language, a null pointer, if dereferenced, +would yield a null string. Though often used, this practice is not always +portable. Programmers using a null pointer to represent an empty string should +be aware of this portability issue. Even on machines where dereferencing a +null pointer does not cause an abort of the program, it does not necessarily +yield a null string. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityStandard +.TE + +.SH SEE ALSO +.sp +.LP +\fBbstring\fR(3C), \fBmalloc\fR(3C), \fBstring\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/initgroups.3c b/usr/src/man/man3c/initgroups.3c new file mode 100644 index 0000000000..376970a0fe --- /dev/null +++ b/usr/src/man/man3c/initgroups.3c @@ -0,0 +1,74 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH initgroups 3C "22 Mar 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +initgroups \- initialize the supplementary group access list +.SH SYNOPSIS +.LP +.nf +#include <grp.h> +#include <sys/types.h> + +\fBint\fR \fBinitgroups\fR(\fBconst char *\fR\fIname\fR, \fBgid_t\fR \fIbasegid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBinitgroups()\fR function reads the group database to get the group +membership for the user specified by \fIname\fR, and initializes the +supplementary group access list of the calling process (see \fBgetgrnam\fR(3C) +and \fBgetgroups\fR(2)). The \fIbasegid\fR group ID is also included in the +supplementary group access list. This is typically the real group ID from the +user database. +.sp +.LP +While scanning the group database, if the number of groups, including the +\fIbasegid\fR entry, exceeds \fBNGROUPS_MAX\fR, subsequent group entries are +ignored. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, 0 is returned. Otherwise, \(mi1 is returned and +\fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBinitgroups()\fR function will fail and not change the supplementary +group access list if: +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 9n +.rt +The {\fBPRIV_PROC_SETID\fR} privilege is not asserted in the effective set of +the calling process. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgetgroups\fR(2), \fBgetgrnam\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/insque.3c b/usr/src/man/man3c/insque.3c new file mode 100644 index 0000000000..6026373c49 --- /dev/null +++ b/usr/src/man/man3c/insque.3c @@ -0,0 +1,62 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. Copyright 1989 AT&T Copyright (c) 1983 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. +.TH insque 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +insque, remque \- insert/remove element from a queue +.SH SYNOPSIS +.LP +.nf +include <search.h> + +\fBvoid\fR \fBinsque\fR(\fBstruct qelem *\fR\fIelem\fR, \fBstruct qelem *\fR\fIpred\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBremque\fR(\fBstruct qelem *\fR\fIelem\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBinsque()\fR and \fBremque()\fR functions manipulate queues built from +doubly linked lists. Each element in the queue must be in the following form: +.sp +.in +2 +.nf +struct qelem { + struct qelem *q_forw; + struct qelem *q_back; + char q_data[\|]; +}; +.fi +.in -2 + +.sp +.LP +The \fBinsque()\fR function inserts \fIelem\fR in a queue immediately after +\fIpred\fR. The \fBremque()\fR function removes an entry \fIelem\fR from a +queue. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/is_system_labeled.3c b/usr/src/man/man3c/is_system_labeled.3c new file mode 100644 index 0000000000..c5fa85834d --- /dev/null +++ b/usr/src/man/man3c/is_system_labeled.3c @@ -0,0 +1,48 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH is_system_labeled 3C "24 Mar 2006" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +is_system_labeled \- determine whether Trusted Extensions software is active +.SH SYNOPSIS +.LP +.nf +#include <tsol/label.h> + +\fBint\fR \fBis_system_labeled\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The is_system_labeled function returns \fITRUE\fR (1) if the Trusted Extensions +software is installed and active; otherwise it returns \fIFALSE\fR (0). +.SH RETURN VALUES +.sp +.LP +See DESCRIPTION. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStable +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5) diff --git a/usr/src/man/man3c/isaexec.3c b/usr/src/man/man3c/isaexec.3c new file mode 100644 index 0000000000..9b50d47502 --- /dev/null +++ b/usr/src/man/man3c/isaexec.3c @@ -0,0 +1,105 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH isaexec 3C "20 Mar 1998" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +isaexec \- invoke isa-specific executable +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> + +\fBint\fR \fBisaexec\fR(\fBconst char *\fR\fIpath\fR, \fBchar *const\fR \fIargv[]\fR, \fBchar *const\fR \fIenvp[]\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBisaexec()\fR function takes the path specified as \fIpath\fR and breaks +it into directory and file name components. It enquires from the running system +the list of supported instruction set architectures; see \fBisalist\fR(5). The +function traverses the list for an executable file in named subdirectories of +the original directory. When such a file is located, \fBexecve()\fR is invoked +with \fIargv\fR\fB[\|]\fR and \fIenvp\fR\fB[\|]\fR. See \fBexec\fR(2). +.SH RETURN VALUES +.sp +.LP +If no file is located, \fBisaexec()\fR returns \fBENOENT\fR. Other return +values are the same as for \fBexecve()\fR. +.SH EXAMPLES +.LP +\fBExample 1 \fRExample of \fBisaexec()\fR function. +.sp +.LP +On a system whose \fBisalist\fR is + +.sp +.in +2 +.nf +sparcv7 sparc +.fi +.in -2 + +.sp +.LP +the program + +.sp +.in +2 +.nf +int +main(int argc, char *argv[], char *envp[]) +{ + return (isaexec("/bin/thing", argv, envp)); +} +.fi +.in -2 + +.sp +.LP +will look first for an executable file named \fB/bin/sparcv7/thing\fR, then for +an executable file named \fB/bin/sparc/thing\fR. It will invoke \fBexecve()\fR +on the first executable file it finds named \fBthing\fR. + +.sp +.LP +On that same system, a program called \fB/u/bin/tofu\fR can cause either +\fB/u/bin/sparcv7/tofu\fR or \fB/u/bin/sparc/tofu\fR to be invoked using the +following code: + +.sp +.in +2 +.nf +int +main(int argc, char *argv[], char *envp[]) +{ + return (isaexec(getexecname(), argv, envp)); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +_ +Interface StabilityStable +.TE + +.SH SEE ALSO +.sp +.LP +\fBexec\fR(2), \fBgetexecname\fR(3C), \fBattributes\fR(5), \fBisalist\fR(5) diff --git a/usr/src/man/man3c/isastream.3c b/usr/src/man/man3c/isastream.3c new file mode 100644 index 0000000000..6793113ec4 --- /dev/null +++ b/usr/src/man/man3c/isastream.3c @@ -0,0 +1,68 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH isastream 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +isastream \- test a file descriptor +.SH SYNOPSIS +.LP +.nf +#include <stropts.h> + +\fBint\fR \fBisastream\fR(\fBint\fR \fIfildes\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBisastream()\fR function determines if a file descriptor represents a +STREAMS file. The \fIfildes\fR argument refers to an open file descriptor. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBisastream()\fR returns \fB1\fR if \fIfildes\fR +represents a STREAMS file, and \fB0\fR if it does not. Otherwise, \fB\(mi1\fR +is return and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBisastream()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 9n +.rt +The \fIfildes\fR argument is not a valid file descriptor. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), , \fBstandards\fR(5), \fBstreamio\fR(7I) +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man3c/isatty.3c b/usr/src/man/man3c/isatty.3c new file mode 100644 index 0000000000..75af3abc7e --- /dev/null +++ b/usr/src/man/man3c/isatty.3c @@ -0,0 +1,86 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH isatty 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +isatty \- test for a terminal device +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> + +\fBint\fR \fBisatty\fR(\fBint\fR \fIfildes\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBisatty()\fR function tests whether \fIfildes\fR, an open file +descriptor, is associated with a terminal device. +.SH RETURN VALUES +.sp +.LP +The \fBisatty()\fR function returns \fB1\fR if \fIfildes\fR is associated with +a terminal; otherwise it returns \fB0\fR and may set \fBerrno\fR to indicate +the error. +.SH ERRORS +.sp +.LP +The \fBisatty()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIfildes\fR argument is not a valid open file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTTY\fR\fR +.ad +.RS 10n +.rt +The \fIfildes\fR argument is not associated with a terminal. +.RE + +.SH USAGE +.sp +.LP +The \fBisatty()\fR function does not necessarily indicate that a human being is +available for interaction via \fIfildes\fR. It is quite possible that +non-terminal devices are connected to the communications line. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBttyname\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/isnand.3c b/usr/src/man/man3c/isnand.3c new file mode 100644 index 0000000000..2d5730e2f6 --- /dev/null +++ b/usr/src/man/man3c/isnand.3c @@ -0,0 +1,196 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH isnand 3C "15 Jun 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +isnand, isnanf, finite, fpclass, unordered \- determine type of floating-point +number +.SH SYNOPSIS +.LP +.nf +#include <ieeefp.h> + +\fBint\fR \fBisnand\fR(\fBdouble\fR \fIdsrc\fR); +.fi + +.LP +.nf +\fBint\fR \fBisnanf\fR(\fBfloat\fR \fIfsrc\fR); +.fi + +.LP +.nf +\fBint\fR \fBfinite\fR(\fBdouble\fR \fIdsrc\fR); +.fi + +.LP +.nf +\fBfpclass_t\fR \fBfpclass\fR(\fBdouble\fR \fIdsrc\fR); +.fi + +.LP +.nf +\fBint\fR \fBunordered\fR(\fBdouble\fR \fIdsrc1\fR, \fBdouble\fR \fIdsrc2\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBisnand()\fR and \fBisnanf()\fR functions return \fBTRUE\fR (\fB1\fR) if +the argument \fIdsrc\fR or \fIfsrc\fR is a NaN; otherwise they return +\fBFALSE\fR (\fB0\fR). +.sp +.LP +The \fBfpclass()\fR function returns one of the following classes to which +\fIdsrc\fR belongs: +.sp +.ne 2 +.mk +.na +\fB\fBFP_SNAN\fR\fR +.ad +.RS 14n +.rt +signaling NaN +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFP_QNAN\fR\fR +.ad +.RS 14n +.rt +quiet NaN +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFP_NINF\fR\fR +.ad +.RS 14n +.rt +negative infinity +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFP_PINF\fR\fR +.ad +.RS 14n +.rt +positive infinity +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFP_NDENORM\fR\fR +.ad +.RS 14n +.rt +negative denormalized non-zero +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFP_PDENORM\fR\fR +.ad +.RS 14n +.rt +positive denormalized non-zero +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFP_NZERO\fR\fR +.ad +.RS 14n +.rt +negative zero +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFP_PZERO\fR\fR +.ad +.RS 14n +.rt +positive zero +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFP_NNORM\fR\fR +.ad +.RS 14n +.rt +negative normalized non-zero +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFP_PNORM\fR\fR +.ad +.RS 14n +.rt +positive normalized non-zero +.RE + +.sp +.LP +The \fBfinite()\fR function returns \fBTRUE\fR (\fB1\fR) if the argument +\fIdsrc\fR is neither infinity nor NaN; otherwise it returns \fBFALSE\fR +(\fB0\fR). +.sp +.LP +The \fBunordered()\fR function returns \fBTRUE\fR (\fB1\fR) if one of its two +arguments is unordered with respect to the other argument. This is equivalent +to reporting whether either argument is NaN. If neither argument is NaN, +\fBFALSE\fR (\fB0\fR) is returned. +.sp +.LP +None of these functions generates an exception, even for signaling NaNs. +.SH RETURN VALUES +.sp +.LP +See DESCRIPTION. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfpgetround\fR(3C), \fBisnan\fR(3M), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/iswalpha.3c b/usr/src/man/man3c/iswalpha.3c new file mode 100644 index 0000000000..3765daf2e3 --- /dev/null +++ b/usr/src/man/man3c/iswalpha.3c @@ -0,0 +1,369 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH iswalpha 3C "19 Apr 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +iswalpha, isenglish, isideogram, isnumber, isphonogram, isspecial, iswalnum, +iswascii, iswblank, iswcntrl, iswdigit, iswgraph, iswlower, iswprint, iswpunct, +iswspace, iswupper, iswxdigit \- wide-character code classification functions +.SH SYNOPSIS +.LP +.nf +#include <wchar.h> +#include <wctype.h> + +\fBint\fR \fBiswalpha\fR(\fBwint_t\fR \fIwc\fR); +.fi + +.LP +.nf +\fBint\fR \fBisenglish\fR(\fBwint_t\fR \fIwc\fR); +.fi + +.LP +.nf +\fBint\fR \fBisideogram\fR(\fBwint_t\fR \fIwc\fR); +.fi + +.LP +.nf +\fBint\fR \fBisnumber\fR(\fBwint_t\fR \fIwc\fR); +.fi + +.LP +.nf +\fBint\fR \fBisphonogram\fR(\fBwint_t\fR \fIwc\fR); +.fi + +.LP +.nf +\fBint\fR \fBisspecial\fR(\fBwint_t\fR \fIwc\fR); +.fi + +.LP +.nf +\fBint\fR \fBiswalnum\fR(\fBwint_t\fR \fIwc\fR); +.fi + +.LP +.nf +\fBint\fR \fBiswascii\fR(\fBwint_t\fR \fIwc\fR); +.fi + +.LP +.nf +\fBint\fR \fBiswblank\fR(\fBwint_t\fR \fIwc\fR); +.fi + +.LP +.nf +\fBint\fR \fBiswcntrl\fR(\fBwint_t\fR \fIwc\fR); +.fi + +.LP +.nf +\fBint\fR \fBiswdigit\fR(\fBwint_t\fR \fIwc\fR); +.fi + +.LP +.nf +\fBint\fR \fBiswgraph\fR(\fBwint_t\fR \fIwc\fR); +.fi + +.LP +.nf +\fBint\fR \fBiswlower\fR(\fBwint_t\fR \fIwc\fR); +.fi + +.LP +.nf +\fBint\fR \fBiswprint\fR(\fBwint_t\fR \fIwc\fR); +.fi + +.LP +.nf +\fBint\fR \fBiswpunct\fR(\fBwint_t\fR \fIwc\fR); +.fi + +.LP +.nf +\fBint\fR \fBiswspace\fR(\fBwint_t\fR \fIwc\fR); +.fi + +.LP +.nf +\fBint\fR \fBiswupper\fR(\fBwint_t\fR \fIwc\fR); +.fi + +.LP +.nf +\fBint\fR \fBiswxdigit\fR(\fBwint_t\fR \fIwc\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions test whether \fIwc\fR is a wide-character code representing a +character of a particular class defined in the \fBLC_CTYPE\fR category of the +current locale. +.sp +.LP +In all cases, \fIwc\fR is a \fBwint_t\fR, the value of which must be a +wide-character code corresponding to a valid character in the current locale or +must equal the value of the macro \fBWEOF\fR. If the argument has any other +values, the behavior is undefined. +.sp +.ne 2 +.mk +.na +\fB\fBiswalpha(\fR\fIwc\fR\fB)\fR\fR +.ad +.RS 19n +.rt +Tests whether \fIwc\fR is a wide-character code representing a character of +class "alpha" in the program's current locale. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBisenglish(\fR\fIwc\fR\fB)\fR\fR +.ad +.RS 19n +.rt +Tests whether \fIwc\fR is a wide-character code representing an English +language character, excluding \fBASCII\fR characters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBisideogram(\fR\fIwc\fR\fB)\fR\fR +.ad +.RS 19n +.rt +Tests whether \fIwc\fR is a wide-character code representing an ideographic +language character, excluding \fBASCII\fR characters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBisnumber(\fR\fIwc\fR\fB)\fR\fR +.ad +.RS 19n +.rt +Tests whether \fIwc\fR is a wide-character code representing digit [0\(mi9], +excluding \fBASCII\fR characters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBisphonogram(\fR\fIwc\fR\fB)\fR\fR +.ad +.RS 19n +.rt +Tests whether \fIwc\fR is a wide-character code representing a phonetic +language character, excluding \fBASCII\fR characters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBisspecial(\fR\fIwc\fR\fB)\fR\fR +.ad +.RS 19n +.rt +Tests whether \fIwc\fR is a wide-character code representing a special language +character, excluding \fBASCII\fR characters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBiswalnum(\fR\fIwc\fR\fB)\fR\fR +.ad +.RS 19n +.rt +Tests whether \fIwc\fR is a wide-character code representing a character of +class "alpha" or "digit" in the program's current locale. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBiswascii(\fR\fIwc\fR\fB)\fR\fR +.ad +.RS 19n +.rt +Tests whether \fIwc\fR is a wide-character code representing an \fBASCII\fR +character. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBiswblank(\fR\fIwc\fR\fB)\fR\fR +.ad +.RS 19n +.rt +Tests whether \fIwc\fR is a wide-character code representing a character of +class "blank" in the program's current locale. This function is not available +to applications conforming to standards prior to SUSv3. See \fBstandards\fR(5). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBiswlower(\fR\fIwc\fR\fB)\fR\fR +.ad +.RS 19n +.rt +Tests whether \fIwc\fR is a wide-character code representing a character of +class "lower" in the program's current locale. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBiswcntrl(\fR\fIwc\fR\fB)\fR\fR +.ad +.RS 19n +.rt +Tests whether \fIwc\fR is a wide-character code representing a character of +class "cntrl" in the program's current locale. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBiswdigit(\fR\fIwc\fR\fB)\fR\fR +.ad +.RS 19n +.rt +Tests whether \fIwc\fR is a wide-character code representing a character of +class "digit" in the program's current locale. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBiswgraph(\fR\fIwc\fR\fB)\fR\fR +.ad +.RS 19n +.rt +Tests whether \fIwc\fR is a wide-character code representing a character of +class "graph" in the program's current locale. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBiswprint(\fR\fIwc\fR\fB)\fR\fR +.ad +.RS 19n +.rt +Tests whether \fIwc\fR is a wide-character code representing a character of +class "print" in the program's current locale. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBiswpunct(\fR\fIwc\fR\fB)\fR\fR +.ad +.RS 19n +.rt +Tests whether \fIwc\fR is a wide-character code representing a character of +class "punct" in the program's current locale. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBiswspace(\fR\fIwc\fR\fB)\fR\fR +.ad +.RS 19n +.rt +Tests whether \fIwc\fR is a wide-character code representing a character of +class "space" in the program's current locale. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBiswupper(\fR\fIwc\fR\fB)\fR\fR +.ad +.RS 19n +.rt +Tests whether \fIwc\fR is a wide-character code representing a character of +class "upper" in the program's current locale. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBiswxdigit(\fR\fIwc\fR\fB)\fR\fR +.ad +.RS 19n +.rt +Tests whether \fIwc\fR is a wide-character code representing a character of +class "xdigit" in the program's current locale. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +CSIEnabled +_ +Interface StabilitySee below. +_ +MT-LevelMT-Safe with exceptions +.TE + +.sp +.LP +The \fBiswalpha()\fR, \fBiswalnum()\fR, \fBiswblank()\fR, \fBiswcntrl()\fR, +\fBiswdigit()\fR, \fBiswgraph()\fR, \fBiswlower()\fR, \fBiswprint()\fR, +\fBiswpunct()\fR, \fBiswspace()\fR, \fBiswupper()\fR, and \fBiswxdigit()\fR +functions are Standard. +.SH SEE ALSO +.sp +.LP +\fBlocaledef\fR(1), \fBsetlocale\fR(3C), \fBstdio\fR(3C), \fBascii\fR(5), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/iswctype.3c b/usr/src/man/man3c/iswctype.3c new file mode 100644 index 0000000000..9796ecd43a --- /dev/null +++ b/usr/src/man/man3c/iswctype.3c @@ -0,0 +1,118 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH iswctype 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +iswctype \- test character for specified class +.SH SYNOPSIS +.LP +.nf +#include <wchar.h> + +\fBint\fR \fBiswctype\fR(\fBwint_t\fR \fIwc\fR, \fBwctype_t\fR \fIcharclass\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBiswctype()\fR function determines whether the wide-character code +\fIwc\fR has the character class \fIcharclass\fR, returning \fBTRUE\fR or +\fBFALSE\fR. The \fBiswctype()\fR function is defined on \fBWEOF\fR and +wide-character codes corresponding to the valid character encodings in the +current locale. If the \fIwc\fR argument is not in the domain of the function, +the result is undefined. If the value of \fIcharclass\fR is invalid (that is, +not obtained by a call to \fBwctype\fR(3C) or \fIcharclass \fR is invalidated +by a subsequent call to \fBsetlocale\fR(3C) that has affected category +\fBLC_CTYPE\fR), the result is indeterminate. +.SH RETURN VALUES +.sp +.LP +The \fBiswctype()\fR function returns \fB0\fR for \fBFALSE\fR and non-zero for +\fBTRUE\fR. +.SH USAGE +.sp +.LP +There are twelve strings that are reserved for the standard character classes: +.sp + +.sp +.TS +tab(); +lw(1.83i) |lw(1.83i) |lw(1.83i) +lw(1.83i) |lw(1.83i) |lw(1.83i) +. +"alnum""alpha""blank" +_ +"cntrl""digit""graph" +_ +"lower""print""punct" +_ +"space""upper""xdigit" +.TE + +.sp +.LP +In the table below, the functions in the left column are equivalent to the +functions in the right column. +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fBiswalnum(\fR\fIwc\fR\fB)\fRiswctype(\fIwc,\fR\fB wctype(\fR"alnum"\fB))\fR +iswalpha(\fIwc\fR\fB)\fRiswctype(\fIwc,\fR\fB wctype(\fR"alpha"\fB))\fR +iswcntrl(\fIwc\fR\fB)\fRiswctype(\fIwc,\fR\fB wctype(\fR"cntrl"\fB))\fR +iswdigit(\fI wc\fR\fB)\fRiswctype(\fIwc,\fR\fB wctype(\fR"digit"\fB))\fR +iswgraph(\fIwc\fR\fB)\fRiswctype(\fIwc,\fR\fB wctype(\fR"graph"\fB))\fR +iswlower(\fIwc\fR\fB)\fRiswctype(\fIwc,\fR\fB wctype(\fR"lower"\fB))\fR +iswprint(\fIwc\fR\fB)\fRiswctype(\fIwc,\fR\fB wctype(\fR"print"\fB))\fR +iswpunct(\fIwc\fR\fB)\fRiswctype(\fI wc,\fR\fB wctype(\fR"punct"\fB))\fR +iswspace(\fIwc\fR\fB)\fRiswctype(\fIwc,\fR\fB wctype(\fR"space"\fB))\fR +iswupper(\fIwc\fR\fB)\fRiswctype(\fIwc,\fR\fB wctype(\fR"upper"\fB))\fR +iswxdigit(\fIwc\fR\fB)\fRiswctype(\fIwc,\fR\fB wctype(\fR"xdigit"\fB))\fR +.TE + +.sp +.LP +The call +.sp +.LP +\fBiswctype(\fR\fIwc,\fR\fB wctype(\fR"blank"\fB))\fR +.sp +.LP +does not have an equivalent \fBisw*(\|)\fR function. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +CSIEnabled +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBiswalpha\fR(3C), \fBsetlocale\fR(3C), \fBwctype\fR(3C), \fBattributes\fR(5), +\fBenviron\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/killpg.3c b/usr/src/man/man3c/killpg.3c new file mode 100644 index 0000000000..24d4422d04 --- /dev/null +++ b/usr/src/man/man3c/killpg.3c @@ -0,0 +1,96 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH killpg 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +killpg \- send signal to a process group +.SH SYNOPSIS +.LP +.nf +#include <signal.h> + +\fBint\fR \fBkillpg\fR(\fBpid_t\fR \fIpgrp\fR, \fBint\fR \fIsig\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBkillpg()\fR function sends the signal \fIsig\fR to the process group +\fIpgrp\fR. See \fBsignal.h\fR(3HEAD) for a list of signals. +.sp +.LP +The real or effective user \fBID\fR of the sending process must match the real +or saved set-user \fBID\fR of the receiving process, unless the effective user +\fBID\fR of the sending process is the privileged user. A single exception is +the signal \fBSIGCONT\fR, which may always be sent to any descendant of the +current process. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBkillpg()\fR function will fail and no signal will be sent if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIsig\fR argument is not a valid signal number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 10n +.rt +The effective user \fBID\fR of the sending process is not privileged user, and +neither its real nor effective user \fBID\fR matches the real or saved set-user +\fBID\fR of one or more of the target processes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBESRCH\fR\fR +.ad +.RS 10n +.rt +No processes were found in the specified process group. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBkill\fR(2), \fBsetpgrp\fR(2), \fBsigaction\fR(2), \fBsignal.h\fR(3HEAD), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/lckpwdf.3c b/usr/src/man/man3c/lckpwdf.3c new file mode 100644 index 0000000000..2835433de1 --- /dev/null +++ b/usr/src/man/man3c/lckpwdf.3c @@ -0,0 +1,104 @@ +'\" te +.\" Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH lckpwdf 3C "29 Dec 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +lckpwdf, ulckpwdf \- manipulate shadow password database lock file +.SH SYNOPSIS +.LP +.nf +#include <shadow.h> + +\fBint\fR \fBlckpwdf\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBint\fR \fBulckpwdf\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBlckpwdf()\fR and \fBulckpwdf()\fR functions enable modification access +to the password databases through the lock file. A process first uses +\fBlckpwdf()\fR to lock the lock file, thereby gaining exclusive rights to +modify the \fB/etc/passwd\fR or \fB/etc/shadow\fR password database. See +\fBpasswd\fR(4) and \fBshadow\fR(4). Upon completing modifications, a process +should release the lock on the lock file using \fBulckpwdf()\fR. This mechanism +prevents simultaneous modification of the password databases. The lock file, +\fB/etc/.pwd.lock\fR, is used to coordinate modification access to the password +databases \fB/etc/passwd\fR and \fB/etc/shadow\fR. +.SH RETURN VALUES +.sp +.LP +If \fBlckpwdf()\fR is successful in locking the file within 15 seconds, it +returns \fB0\fR. If unsuccessful (for example, \fB/etc/.pwd.lock\fR is already +locked), it returns \fB\(mi1\fR\&. +.sp +.LP +If \fBulckpwdf()\fR is successful in unlocking the file \fB/etc/.pwd.lock\fR, +it returns \fB0\fR. If unsuccessful (for example, \fB/etc/.pwd.lock\fR is +already unlocked), it returns \fB\(mi1\fR\&. +.SH USAGE +.sp +.LP +These routines are for internal use only; compatibility is not guaranteed. +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/etc/passwd\fR\fR +.ad +.RS 18n +.rt +password database +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/shadow\fR\fR +.ad +.RS 18n +.rt +shadow password database +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/.pwd.lock\fR\fR +.ad +.RS 18n +.rt +lock file +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgetpwnam\fR(3C), \fBgetspnam\fR(3C), \fBpasswd\fR(4), \fBshadow\fR(4), +\fBattributes\fR(5) diff --git a/usr/src/man/man3c/lfmt.3c b/usr/src/man/man3c/lfmt.3c new file mode 100644 index 0000000000..9048500c3e --- /dev/null +++ b/usr/src/man/man3c/lfmt.3c @@ -0,0 +1,451 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH lfmt 3C "29 Dec 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +lfmt \- display error message in standard format and pass to logging and +monitoring services +.SH SYNOPSIS +.LP +.nf +#include <pfmt.h> + +\fBint\fR \fBlfmt\fR(\fBFILE *\fR\fIstream\fR, \fBlong\fR \fIflags\fR, \fBchar *\fR\fIformat\fR, \fB\&... /*\fR \fIarg\fR*/); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBlfmt()\fR function retrieves a format string from a locale-specific +message database (unless \fBMM_NOGET\fR is specified) and uses it for +\fBprintf\fR(3C) style formatting of \fIargs\fR. The output is displayed on +\fIstream\fR. If \fIstream\fR is \fINULL\fR no output is displayed. +.sp +.LP +The \fBlfmt()\fR function encapsulates the output in the standard error message +format (unless \fBMM_NOSTD\fR is specified, in which case the output is like +that of \fBprintf()\fR. It forwards its output to the logging and monitoring +facility, even if \fIstream\fR is \fINULL\fR. Optionally, \fBlfmt()\fR +displays the output on the console with a date and time stamp. +.sp +.LP +If the \fBprintf()\fR format string is to be retrieved from a message database, +the \fBformat\fR argument must have the following structure: +.sp +.LP +\fI<catalog>\fR\fB:\fR\fI<msgnum>\fR\fB:\fR\fI<defmsg>\fR\&. +.sp +.LP +If \fBMM_NOGET\fR is specified, only the \fI<defmsg>\fR field must be +specified. +.sp +.LP +The \fI<catalog>\fR field indicates the message database that contains the +localized version of the format string. This field is limited to 14 characters +selected from a set of all characters values, excluding the null character +(\fB\e0\fR) and the ASCII codes for slash (\fB/\fR) and colon (\fB:\fR). +.sp +.LP +The \fI<msgnum>\fR field is a positive number that indicates the index of the +string into the message database. +.sp +.LP +If the catalog does not exist in the locale (specified by the last call to +\fBsetlocale\fR(3C) using the \fBLC_ALL\fR or \fBLC_MESSAGES\fR categories), +or if the message number is out of bound, \fBlfmt()\fR will attempt to retrieve +the message from the C locale. If this second retrieval fails, \fBlfmt()\fR +uses the \fI<defmsg>\fR field of the \fBformat\fR argument. +.sp +.LP +If \fI<catalog>\fR is omitted, \fBlfmt()\fR will attempt to retrieve the string +from the default catalog specified by the last call to \fBsetcat\fR(3C). In +this case, the \fBformat\fR argument has the following structure: +.sp +.LP +\fB:\fR\fI<msgnum>\fR\fB:\fR\fI<defmsg>\fR\&. +.sp +.LP +The \fBlfmt()\fR function will output the message +.sp +.LP +\fBMessage not found!!\en\fR +.sp +.LP +as the format string if \fI<catalog>\fR is not a valid catalog name, if no +catalog is specified (either explicitly or with \fBsetcat()\fR), if +\fI<msgnum>\fR is not a valid number, or if no message could be retrieved from +the message databases and \fI<defmsg>\fR was omitted. +.sp +.LP +The \fIflags\fR argument determines the type of output (whether the +\fBformat\fR should be interpreted as it is or be encapsulated in the standard +message format) and the access to message catalogs to retrieve a localized +version of \fBformat\fR. +.sp +.LP +The \fIflags\fR argument is composed of several groups, and can take the +following values (one from each group): +.sp +.ne 2 +.mk +.na +\fB\fIOutput format control\fR\fR +.ad +.sp .6 +.RS 4n +.sp +.ne 2 +.mk +.na +\fB\fBMM_NOSTD\fR\fR +.ad +.RS 12n +.rt +Do not use the standard message format but interpret \fBformat\fR as a +\fBprintf()\fR \fBformat\fR. Only \fIcatalog access control flags\fR, +\fIconsole display control\fR and \fIlogging information\fR should be specified +if \fBMM_NOSTD\fR is used; all other flags will be ignored. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMM_STD\fR\fR +.ad +.RS 12n +.rt +Output using the standard message format (default value is 0). +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fICatalog access control\fR\fR +.ad +.sp .6 +.RS 4n +.sp +.ne 2 +.mk +.na +\fB\fBMM_NOGET\fR\fR +.ad +.RS 12n +.rt +Do not retrieve a localized version of \fBformat\fR. In this case, only the +\fI<defmsg>\fR field of \fBformat\fR is specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMM_GET\fR\fR +.ad +.RS 12n +.rt +Retrieve a localized version of \fBformat\fR from \fI<catalog>\fR, using +\fI<msgid>\fR as the index and \fI<defmsg>\fR as the default message (default +value is 0). +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fISeverity (standard message format only)\fR\fR +.ad +.sp .6 +.RS 4n +.sp +.ne 2 +.mk +.na +\fB\fBMM_HALT\fR\fR +.ad +.RS 14n +.rt +Generate a localized version of \fBHALT,\fR but donot halt the machine. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMM_ERROR\fR\fR +.ad +.RS 14n +.rt +Generate a localized version of \fBERROR\fR (default value is 0). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMM_WARNING\fR\fR +.ad +.RS 14n +.rt +Generate a localized version of \fBWARNING\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMM_INFO\fR\fR +.ad +.RS 14n +.rt +Generate a localized version of \fBINFO\fR. +.RE + +Additional severities can be defined with the \fBaddsev\fR(3C) function, using +number-string pairs with numeric values in the range [5-255]. The specified +severity is formed by the bitwise \fBOR\fR operation of the numeric value and +other \fIflags\fR arguments. +.sp +If the severity is not defined, \fBlfmt()\fR uses the string \fBSEV=\fR\fIN\fR +where \fIN\fR is the integer severity value passed in \fIflags\fR. +.sp +Multiple severities passed in \fIflags\fR will not be detected as an error. Any +combination of severities will be summed and the numeric value will cause the +display of either a severity string (if defined) or the string +\fBSEV=\fR\fIN\fR (if undefined). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIAction\fR\fR +.ad +.sp .6 +.RS 4n +.sp +.ne 2 +.mk +.na +\fB\fBMM_ACTION\fR\fR +.ad +.RS 13n +.rt +Specify an action message. Any severity value is superseded and replaced by a +localized version of \fBTO FIX\fR. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIConsole display control\fR\fR +.ad +.sp .6 +.RS 4n +.sp +.ne 2 +.mk +.na +\fB\fBMM_CONSOLE\fR\fR +.ad +.RS 16n +.rt +Display the message to the console in addition to the specified \fIstream\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMM_NOCONSOLE\fR\fR +.ad +.RS 16n +.rt +Do not display the message to the console in addition to the specified +\fIstream\fR (default value is 0). +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fILogging information\fR\fR +.ad +.sp .6 +.RS 4n +.sp +.ne 2 +.mk +.na +\fB\fIMajor classification\fR\fR +.ad +.sp .6 +.RS 4n +Identify the source of the condition. Identifiers are: \fBMM_HARD\fR +(hardware), \fBMM_SOFT\fR (software), and \fBMM_FIRM\fR (firmware). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIMessage source subclassification\fR\fR +.ad +.sp .6 +.RS 4n +Identify the type of software in which the problem is spotted. Identifiers are: +\fBMM_APPL\fR (application), \fBMM_UTIL\fR (utility), and \fBMM_OPSYS\fR +(operating system). +.RE + +.RE + +.SH STANDARD ERROR MESSAGE FORMAT +.sp +.LP +The \fBlfmt()\fR function displays error messages in the following format: +.sp +.in +2 +.nf +\fIlabel\fR\fB:\fR \fIseverity\fR\fB:\fR \fItext\fR +.fi +.in -2 + +.sp +.LP +If no \fIlabel\fR was defined by a call to \fBsetlabel\fR(3C), the message is +displayed in the format: +.sp +.in +2 +.nf +\fIseverity\fR\fB:\fR \fItext\fR +.fi +.in -2 + +.sp +.LP +If \fBlfmt()\fR is called twice to display an error message and a helpful +\fIaction\fR or recovery message, the output may appear as follows: +.sp +.in +2 +.nf +\fIlabel\fR\fB: \fR\fIseverity\fR\fB: \fR\fItext\fR +\fIlabel\fR\fB: \fR \fBTO FIX:\fR \fItext\fR +.fi +.in -2 + +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBlfmt()\fR returns the number of bytes +transmitted. Otherwise, it returns a negative value: +.sp +.ne 2 +.mk +.na +\fB\fB\(mi1\fR\fR +.ad +.RS 9n +.rt +Write the error to \fIstream\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\(mi2\fR\fR +.ad +.RS 9n +.rt +Cannot log and/or display at console. +.RE + +.SH USAGE +.sp +.LP +Since \fBlfmt()\fR uses \fBgettxt\fR(3C), it is recommended that \fBlfmt()\fR +not be used. +.SH EXAMPLES +.LP +\fBExample 1 \fRThe following example +.sp +.in +2 +.nf +setlabel("UX:test"); +lfmt(stderr, MM_ERROR|MM_CONSOLE|MM_SOFT|MM_UTIL, + "test:2:Cannot open file: %s\en", strerror(errno)); +.fi +.in -2 + +.sp +.LP +displays the message to \fBstderr\fR and to the console and makes it available +for logging: + +.sp +.in +2 +.nf +UX:test: ERROR: Cannot open file: No such file or directory +.fi +.in -2 + +.LP +\fBExample 2 \fRThe following example +.sp +.in +2 +.nf +setlabel("UX:test"); +lfmt(stderr, MM_INFO|MM_SOFT|MM_UTIL, + "test:23:test facility is enabled\en"); +.fi +.in -2 + +.sp +.LP +displays the message to \fBstderr\fR and makes it available for logging: + +.sp +.in +2 +.nf +UX:test: INFO: test facility enabled +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBaddsev\fR(3C), \fBgettxt\fR(3C), \fBpfmt\fR(3C), \fBprintf\fR(3C), +\fBsetcat\fR(3C), \fBsetlabel\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5), +\fBenviron\fR(5) diff --git a/usr/src/man/man3c/lio_listio.3c b/usr/src/man/man3c/lio_listio.3c new file mode 100644 index 0000000000..a9ba424a25 --- /dev/null +++ b/usr/src/man/man3c/lio_listio.3c @@ -0,0 +1,303 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH lio_listio 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +lio_listio \- list directed I/O +.SH SYNOPSIS +.LP +.nf +#include <aio.h> + +\fBint\fR \fBlio_listio\fR(\fBint\fR \fImode\fR, \fBstruct aiocb *restrict const\fR \fIlist\fR[], + \fBint\fR \fInent\fR, \fBstruct sigevent *restrict\fR \fIsig\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBlio_listio()\fR function allows the calling process, LWP, or thread, to +initiate a list of I/O requests within a single function call. +.sp +.LP +The \fImode\fR argument takes one of the values \fBLIO_WAIT\fR or +\fBLIO_NOWAIT\fR declared in <\fBaio.h\fR> 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 \fImode\fR argument is \fBLIO_WAIT\fR, the +function waits until all I/O is complete and the \fIsig\fR argument is ignored. +.sp +.LP +If the \fImode\fR argument is \fBLIO_NOWAIT\fR, the function returns +immediately, and asynchronous notification occurs, according to the \fIsig\fR +argument, when all the I/O operations complete. If \fIsig\fR is \fINULL\fR, no +asynchronous notification occurs. If \fIsig\fR is not \fINULL\fR, asynchronous +notification occurs as specified in \fBsignal.h\fR(3HEAD) when all the requests +in \fIlist\fR have completed. +.sp +.LP +The I/O requests enumerated by \fIlist\fR are submitted in an unspecified +order. +.sp +.LP +The \fIlist\fR argument is an array of pointers to \fBaiocb\fR structures. The +array contains \fInent\fR elements. The array may contain null elements, which +are ignored. +.sp +.LP +The \fIaio_lio_opcode\fR field of each \fBaiocb\fR structure specifies the +operation to be performed. The supported operations are \fBLIO_READ\fR, +\fBLIO_WRITE\fR, and \fBLIO_NOP\fR; these symbols are defined in <\fBaio.h\fR>. +The \fBLIO_NOP\fR operation causes the list entry to be ignored. If the +\fIaio_lio_opcode\fR element is equal to \fBLIO_READ,\fR then an I/O operation +is submitted as if by a call to \fBaio_read\fR(3C) with the \fIaiocbp\fR equal +to the address of the \fBaiocb\fR structure. If the \fIaio_lio_opcode\fR +element is equal to \fBLIO_WRITE\fR, then an I/O operation is submitted as if +by a call to \fBaio_write\fR(3C) with the \fIaiocbp\fR equal to the address of +the \fBaiocb\fR structure. +.sp +.LP +The \fIaio_fildes\fR member specifies the file descriptor on which the +operation is to be performed. +.sp +.LP +The \fIaio_buf\fR member specifies the address of the buffer to or from which +the data is to be transferred. +.sp +.LP +The \fIaio_nbytes\fR member specifies the number of bytes of data to be +transferred. +.sp +.LP +The members of the \fIaiocb\fR structure further describe the I/O operation to +be performed, in a manner identical to that of the corresponding \fBaiocb\fR +structure when used by the \fBaio_read\fR(3C) and \fBaio_write\fR(3C) +functions. +.sp +.LP +The \fInent\fR argument specifies how many elements are members of the list, +that is, the length of the array. +.sp +.LP +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 +\fBaio_fildes\fR. See \fBfcntl.h\fR(3HEAD) definitions of \fBO_DSYNC\fR and +\fBO_SYNC\fR. +.sp +.LP +For regular files, no data transfer will occur past the offset maximum +established in the open file description associated with +\fIaiocbp\fR\(->\fBaio_fildes\fR. +.SH RETURN VALUES +.sp +.LP +If the \fImode\fR argument has the value \fBLIO_NOWAIT\fR, and the I/O +operations are successfully queued, \fBlio_listio()\fR returns \fB0\fR; +otherwise, it returns \fB\(mi1\fR, and sets \fBerrno\fR to indicate the error. +.sp +.LP +If the \fImode\fR argument has the value \fBLIO_WAIT\fR, and all the +indicated I/O has completed successfully, \fBlio_listio()\fR returns \fB0\fR; +otherwise, it returns \fB\(mi1\fR, and sets \fBerrno\fR to indicate the error. +.sp +.LP +In either case, the return value only indicates the success or failure of the +\fBlio_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 must examine the error status associated with each \fIaiocb\fR +control block. Each error status so returned is identical to that returned as +a result of an \fBaio_read\fR(3C) or \fBaio_write\fR(3C) function. +.SH ERRORS +.sp +.LP +The \fBlio_listio()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +The resources necessary to queue all the I/O requests were not available. The +error status for each request is recorded in the \fBaio_error\fR member of the +corresponding \fBaiocb\fR structure, and can be retrieved using +\fBaio_error\fR(3C). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +The number of entries indicated by \fInent\fR would cause the system-wide limit +\fBAIO_MAX\fR to be exceeded. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fImode\fR argument is an improper value, or the value of \fInent\fR is +greater than \fBAIO_LISTIO_MAX\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 10n +.rt +A signal was delivered while waiting for all I/O requests to complete during an +\fBLIO_WAIT\fR operation. Note that, since each I/O operation invoked by +\fBlio_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 can use \fBaio_fsync\fR(3C) to determine if any request was +initiated; \fBaio_return\fR(3C) to determine if any request has completed; or +\fBaio_error\fR(3C) to determine if any request was canceled. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 10n +.rt +One or more of the individual I/O operations failed. The application can use +\fBaio_error\fR(3C) to check the error status for each \fBaiocb\fR structure to +determine the individual request(s) that failed. +.RE + +.sp +.LP +In addition to the errors returned by the \fBlio_listio()\fR function, if the +\fBlio_listio()\fR function succeeds or fails with errors of \fBEAGAIN\fR, +\fBEINTR\fR, or \fBEIO\fR, then some of the I/O specified by the list may have +been initiated. If the \fBlio_listio()\fR function fails with an error code +other than \fBEAGAIN\fR, \fBEINTR\fR, or \fBEIO\fR, no operations from the list +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 \fBaiocb\fR control block +contains the associated error code. The error codes that can be set are the +same as would be set by a \fBread\fR(2) or \fBwrite\fR(2) function, with the +following additional error codes possible: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 15n +.rt +The requested I/O operation was not queued due to resource limitations. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBECANCELED\fR\fR +.ad +.RS 15n +.rt +The requested I/O was canceled before the I/O completed due to an explicit +\fBaio_cancel\fR(3C) request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFBIG\fR\fR +.ad +.RS 15n +.rt +The \fIaiocbp\fR\(->\fBaio_lio_opcode\fR is \fBLIO_WRITE\fR, the file is a +regular file, \fIaiocbp\fR\(->\fBaio_nbytes\fR is greater than 0, and the +\fIaiocbp\fR\(->\fBaio_offset\fR is greater than or equal to the offset maximum +in the open file description associated with \fIaiocbp\fR\(->\fBaio_fildes.\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINPROGRESS\fR\fR +.ad +.RS 15n +.rt +The requested I/O is in progress. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOVERFLOW\fR\fR +.ad +.RS 15n +.rt +The \fIaiocbp\fR\(->\fBaio_lio_opcode\fR is \fBLIO_READ\fR, the file is a +regular file, \fIaiocbp\fR\(->\fBaio_nbytes\fR is greater than 0, and the +\fIaiocbp\fR\(->\fBaio_offset\fR is before the end-of-file and is greater than +or equal to the offset maximum in the open file description associated with +\fIaiocbp\fR\(->\fBaio_fildes.\fR +.RE + +.SH USAGE +.sp +.LP +The \fBlio_listio()\fR function has a transitional interface for 64-bit file +offsets. See \fBlf64\fR(5). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBclose\fR(2), \fBexec\fR(2), \fBexit\fR(2), \fBfork\fR(2), \fBlseek\fR(2), +\fBread\fR(2), \fBwrite\fR(2), \fBaio_cancel\fR(3C), \fBaio_error\fR(3C), +\fBaio_fsync\fR(3C), \fBaio_read\fR(3C), \fBaio_return\fR(3C), +\fBaio_write\fR(3C), \fBaio.h\fR(3HEAD), \fBfcntl.h\fR(3HEAD), +\fBsiginfo.h\fR(3HEAD), \fBsignal.h\fR(3HEAD), \fBattributes\fR(5), +\fBlf64\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/localeconv.3c b/usr/src/man/man3c/localeconv.3c new file mode 100644 index 0000000000..1a0d5074f2 --- /dev/null +++ b/usr/src/man/man3c/localeconv.3c @@ -0,0 +1,620 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH localeconv 3C "12 Dec 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +localeconv \- get numeric formatting information +.SH SYNOPSIS +.LP +.nf +#include <locale.h> + +\fBstruct lconv *\fR\fBlocaleconv\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBlocaleconv()\fR function sets the components of an object with type +\fBstruct lconv\fR (defined in \fB<locale.h>\fR) with the values appropriate +for the formatting of numeric quantities (monetary and otherwise) according to +the rules of the current locale (see \fBsetlocale\fR(3C)). The definition of +\fBstruct lconv\fR is given below (the values for the fields in the "C" locale +are given in comments). +.sp +.in +2 +.nf +char *decimal_point; /* "." */ +char *thousands_sep; /* "" (zero length string) */ +char *grouping; /* "" */ +char *int_curr_symbol; /* "" */ +char *currency_symbol; /* "" */ +char *mon_decimal_point; /* "" */ +char *mon_thousands_sep; /* "" */ +char *mon_grouping; /* "" */ +char *positive_sign; /* "" */ +char *negative_sign; /* "" */ +char int_frac_digits; /* CHAR_MAX */ +char frac_digits; /* CHAR_MAX */ +char p_cs_precedes; /* CHAR_MAX */ +char p_sep_by_space; /* CHAR_MAX */ +char n_cs_precedes; /* CHAR_MAX */ +char n_sep_by_space; /* CHAR_MAX */ +char p_sign_posn; /* CHAR_MAX*/ +char n_sign_posn; /* CHAR_MAX */ +.fi +.in -2 + +.sp +.LP +The following members are also available to SUSv3-conforming applications. See +\fBstandards\fR(5) +.sp +.in +2 +.nf +char int_p_cs_precedes; /* CHAR_MAX */ +char int_p_sep_by_space; /* CHAR_MAX */ +char int_n_cs_precedes; /* CHAR_MAX */ +char int_n_sep_by_space; /* CHAR_MAX */ +char int_p_sign_posn; /* CHAR_MAX */ +char int_n_sign_posn; /* CHAR_MAX */ +.fi +.in -2 + +.sp +.LP +The members of the structure with type \fBchar *\fR are strings, any of which +(except \fBdecimal_point\fR) can point to a null string (""), to indicate that +the value is not available in the current locale or is of zero length. The +members with type \fBchar\fR are non-negative numbers, any of which can be +\fBCHAR_MAX\fR (defined in the \fB<limits.h>\fR header) to indicate that the +value is not available in the current locale. The members are the following: +.sp +.ne 2 +.mk +.na +\fB\fBchar *decimal_point\fR\fR +.ad +.RS 27n +.rt +The decimal-point character used to format non-monetary quantities. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBchar *thousands_sep\fR\fR +.ad +.RS 27n +.rt +The character used to separate groups of digits to the left of the +decimal-point character in formatted non-monetary quantities. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBchar *grouping\fR\fR +.ad +.RS 27n +.rt +A string whose elements taken as one-byte integer values indicate the size of +each group of digits in formatted non-monetary quantities. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBchar *int_curr_symbol\fR\fR +.ad +.RS 27n +.rt +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: 1995 standard. The fourth +character (immediately preceding the null byte) is the character used to +separate the international currency symbol from the monetary quantity. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBchar *currency_symbol\fR\fR +.ad +.RS 27n +.rt +The local currency symbol applicable to the current locale. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBchar *mon_decimal_point\fR\fR +.ad +.RS 27n +.rt +The decimal point used to format monetary quantities. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBchar *mon_thousands_sep\fR\fR +.ad +.RS 27n +.rt +The separator for groups of digits to the left of the decimal point in +formatted monetary quantities. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBchar *mon_grouping\fR\fR +.ad +.RS 27n +.rt +A string whose elements taken as one-byte integer values indicate the size of +each group of digits in formatted monetary quantities. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBchar *positive_sign\fR\fR +.ad +.RS 27n +.rt +The string used to indicate a non-negative-valued formatted monetary quantity. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBchar *negative_sign\fR\fR +.ad +.RS 27n +.rt +The string used to indicate a negative-valued formatted monetary quantity. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBchar int_frac_digits\fR\fR +.ad +.RS 27n +.rt +The number of fractional digits (those to the right of the decimal point) to be +displayed in an internationally formatted monetary quantity. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBchar frac_digits\fR\fR +.ad +.RS 27n +.rt +The number of fractional digits (those to the right of the decimal point) to be +displayed in a formatted monetary quantity. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBchar p_cs_precedes\fR\fR +.ad +.RS 27n +.rt +Set to 1 or 0 if the \fBcurrency_symbol\fR respectively precedes or succeeds +the value for a non-negative formatted monetary quantity. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBchar p_sep_by_space\fR\fR +.ad +.RS 27n +.rt +Set to 0 if no space separates the \fBcurrency_symbol\fR or +\fBint_curr_symbol\fR from the value for a non-negative formatted monetary +quantity. Set to 1 if a space separates the symbol from the value; and set to 2 +if a space separates the symbol and the sign string, if adjacent. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBchar n_cs_precedes\fR\fR +.ad +.RS 27n +.rt +Set to 1 or 0 if the \fBcurrency_symbol\fR respectively precedes or succeeds +the value for a negative formatted monetary quantity. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBchar n_sep_by_space\fR\fR +.ad +.RS 27n +.rt +Set to 0 if no space separates the \fBcurrency_symbol\fR or +\fBint_curr_symbol\fR from the value for a negative formatted monetary +quantity. Set to 1 if a space separates the symbol from the value; and set to 2 +if a space separates the symbol and the sign string, if adjacent. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBchar p_sign_posn\fR\fR +.ad +.RS 27n +.rt +Set to a value indicating the positioning of the \fBpositive_sign\fR for a +non-negative formatted monetary quantity. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBchar n_sign_posn\fR\fR +.ad +.RS 27n +.rt +Set to a value indicating the positioning of the \fBnegative_sign\fR for a +negative formatted monetary quantity. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBchar int_p_cs_precedes\fR\fR +.ad +.RS 27n +.rt +Set to 1 or 0 if the \fBint_curr_symbol\fR respectively precedes or succeeds +the value for a non-negative internationally formatted monetary quantity. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBchar int_n_cs_precedes\fR\fR +.ad +.RS 27n +.rt +Set to 1 or 0 if the \fBint_curr_symbol\fR respectively precedes or succeeds +the value for a negative internationally formatted monetary quantity. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBchar int_p_sep_by_space\fR\fR +.ad +.RS 27n +.rt +Set to a value indicating the separation of the \fBint_curr_symbol\fR, the sign +string, and the value for a non-negative internationally formatted monetary +quantity. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBchar int_n_sep_by_space\fR\fR +.ad +.RS 27n +.rt +Set to a value indicating the separation of the \fBint_curr_symbol\fR, the sign +string, and the value for a negative internationally formatted monetary +quantity. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBchar int_p_sign_posn\fR\fR +.ad +.RS 27n +.rt +Set to a value indicating the positioning of the \fBpositive_sign\fR for a +non-negative internationally formatted monetary quantity. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBchar int_n_sign_posn\fR\fR +.ad +.RS 27n +.rt +Set to a value indicating the positioning of the \fBnegative_sign\fR for a +negative internationally formatted monetary quantity. +.RE + +.sp +.LP +The elements of \fBgrouping\fR and \fBmon_grouping\fR are interpreted according +to the following: +.sp +.ne 2 +.mk +.na +\fB{\fBCHAR_MAX\fR}\fR +.ad +.RS 14n +.rt +No further grouping is to be performed. +.RE + +.sp +.ne 2 +.mk +.na +\fB0\fR +.ad +.RS 14n +.rt +The previous element is to be repeatedly used for the remainder of the digits. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIother\fR\fR +.ad +.RS 14n +.rt +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. +.RE + +.sp +.LP +The values of \fBp_sep_by_space\fR, \fBn_sep_by_space\fR, +\fBint_p_sep_by_space\fR, and \fBint_n_sep_by_space\fR are interpreted +according to the following: +.sp +.ne 2 +.mk +.na +\fB0\fR +.ad +.RS 5n +.rt +No space separates the currency symbol and value. +.RE + +.sp +.ne 2 +.mk +.na +\fB1\fR +.ad +.RS 5n +.rt +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. +.RE + +.sp +.ne 2 +.mk +.na +\fB2\fR +.ad +.RS 5n +.rt +If the currency symbol and sign string are adjacent, a space separates them; +otherwise, a space separates the sign string from the value. +.RE + +.sp +.LP +In an SUSv3-conforming application, for \fBint_p_sep_by_space\fR and +\fBint_n_sep_by_space\fR, the fourth character of \fBint_curr_symbol\fR is used +instead of a space. +.sp +.LP +The values of \fBp_sign_posn\fR, \fBn_sign_posn\fR, \fBint_p_sign_posn\fR, and +\fBint_n_sign_posn\fR are interpreted according to the following: +.sp +.ne 2 +.mk +.na +\fB0\fR +.ad +.RS 5n +.rt +Parentheses surround the quantity and \fBcurrency_symbol\fR or +\fBint_curr_symbol\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB1\fR +.ad +.RS 5n +.rt +The sign string precedes the quantity and \fBcurrency_symbol\fR or +\fBint_curr_symbol\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB2\fR +.ad +.RS 5n +.rt +The sign string succeeds the quantity and \fBcurrency_symbol\fR or +\fBint_curr_symbol\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB3\fR +.ad +.RS 5n +.rt +The sign string immediately precedes the \fBcurrency_symbol\fR or +\fBint_curr_symbol\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB4\fR +.ad +.RS 5n +.rt +The sign string immediately succeeds the \fBcurrency_symbol\fR or +\fBint_curr_symbol\fR. +.RE + +.SH RETURN VALUES +.sp +.LP +The \fBlocaleconv()\fR function returns a pointer to the filled-in object. The +structure pointed to by the return value may be overwritten by a subsequent +call to \fBlocaleconv()\fR. +.SH EXAMPLES +.LP +\fBExample 1 \fRRules used by four countries to format monetary quantities. +.sp +.LP +The following table illustrates the rules used by four countries to format +monetary quantities. + +.sp + +.sp +.TS +tab(); +lw(1.38i) |lw(1.38i) |lw(1.38i) |lw(1.38i) +lw(1.38i) |lw(1.38i) |lw(1.38i) |lw(1.38i) +. +\fBCountry\fR\fBPositive\fR\fBNegative\fR\fBInternational\fR +_ +Italy (IT)L.1.234\(miL.1.234ITL.1.234 +_ +Netherlands (NE)F 1.234,56F \(mi1.234,56NLG 1.234,56 +_ +Norway (NO)kr1.234,56kr1.234,56\(miNOK 1.234,56 +_ +Switzerland (SW)SFrs.1,234.56SFrs.1,234.56CCHF 1,234.56 +.TE + +.sp +.LP +For these four countries, the respective values for the monetary members of the +structure returned by \fBlocaleconv()\fR are as follows: + +.sp + +.sp +.TS +tab(); +lw(5.5i) lw(0i) lw(0i) lw(0i) lw(0i) +lw(5.5i) lw(0i) lw(0i) lw(0i) lw(0i) +. +\fBIT\fR\fBNE\fR\fBNO\fR\fBSW\fR +\fBint_curr_symbol\fR"ITL.""NLG ""NOK ""CHF " +\fBcurrency_symbol\fR"L.""F""kr""SFrs." +\fBmon_decimal_point\fR""","",""." +\fBmon_thousands_sep\fR".""."".""," +\fBmon_grouping\fR"\e3""\e3""\e3""\e3" +\fBpositive_sign\fR"""""""" +\fBnegative_sign\fR"-""-""-""C" +\fBint_frac_digits\fR0222 +\fBfrac_digits\fR0222 +\fBp_cs_precedes\fR1111 +\fBp_sep_by_space\fR0100 +\fBn_cs_precedes\fR1111 +\fBn_sep_by_space\fR0100 +\fBp_sign_posn\fR1111 +\fBn_sign_posn\fR1422 +\fBint_p_cs_precedes\fR1111 +\fBint_n_cs_precedes\fR1111 +\fBint_p_sep_by_space\fR0000 +\fBint_n_sep_by_space\fR0000 +\fBint_p_sign_posn\fR1111 +\fBint_n_sign_posn\fR1442 +.TE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +CSIEnabled +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe with exceptions +.TE + +.sp +.LP +The \fBlocaleconv()\fR function can be used safely in multithreaded +applications, as long as \fBsetlocale\fR(3C) is not being called to change the +locale. +.SH SEE ALSO +.sp +.LP +\fBsetlocale\fR(3C), \fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/lockf.3c b/usr/src/man/man3c/lockf.3c new file mode 100644 index 0000000000..94c5460407 --- /dev/null +++ b/usr/src/man/man3c/lockf.3c @@ -0,0 +1,296 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH lockf 3C "10 Apr 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +lockf \- record locking on files +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> + +\fBint\fR \fBlockf\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIfunction\fR, \fBoff_t\fR \fIsize\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBlockf()\fR function allows sections of a file to be locked; advisory or +mandatory write locks depending on the mode bits of the file (see +\fBchmod\fR(2)). Calls to \fBlockf()\fR from other threads that attempt to lock +the locked file section will either return an error value or be put to sleep +until the resource becomes unlocked. All the locks for a process are removed +when the process terminates. See \fBfcntl\fR(2) for more information about +record locking. +.sp +.LP +The \fIfildes\fR argument is an open file descriptor. The file descriptor must +have \fBO_WRONLY\fR or \fBO_RDWR\fR permission in order to establish locks with +this function call. +.sp +.LP +The \fBfunction\fR argument is a control value that specifies the action to be +taken. The permissible values for \fBfunction\fR are defined in +<\fBunistd.h\fR> as follows: +.sp +.in +2 +.nf +#define F_ULOCK 0 /* unlock previously locked section */ +#define F_LOCK 1 /* lock section for exclusive use */ +#define F_TLOCK 2 /* test & lock section for exclusive use */ +#define F_TEST 3 /* test section for other locks */ +.fi +.in -2 + +.sp +.LP +All other values of \fBfunction\fR are reserved for future extensions and will +result in an error if not implemented. +.sp +.LP +\fBF_TEST\fR is used to detect if a lock by another process is present on the +specified section. \fBF_LOCK\fR and \fBF_TLOCK\fR both lock a section of a file +if the section is available. \fBF_ULOCK\fR removes locks from a section of the +file. +.sp +.LP +The \fBsize\fR argument is the number of contiguous bytes to be locked or +unlocked. The resource to be locked or unlocked starts at the current offset in +the file and extends forward for a positive size and backward for a negative +size (the preceding bytes up to but not including the current offset). If +\fBsize\fR is zero, the section from the current offset through the largest +file offset is 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 in order to +be locked as such locks may exist past the end-of-file. +.sp +.LP +The sections locked with \fBF_LOCK\fR or \fBF_TLOCK\fR may, in whole or in +part, contain or be contained by a previously locked section for the same +process. Locked sections will be unlocked starting at the point of the offset +through \fBsize\fR bytes or to the end of file if \fBsize\fR is (\fBoff_t\fR) +0. When this situation occurs, or if this situation occurs in adjacent +sections, the sections are combined into a single section. If the request +requires that a new element be added to the table of active locks and this +table is already full, an error is returned, and the new section is not locked. +.sp +.LP +\fBF_LOCK\fR and \fBF_TLOCK\fR requests differ only by the action taken if the +resource is not available. \fBF_LOCK\fR blocks the calling thread until the +resource is available. \fBF_TLOCK\fR causes the function to return \(mi1 and +set \fBerrno\fR to \fBEAGAIN\fR if the section is already locked by another +process. +.sp +.LP +File locks are released on first close by the locking process of any file +descriptor for the file. +.sp +.LP +\fBF_ULOCK\fR requests may, in whole or in part, release one or more locked +sections controlled by the process. When sections are not fully released, the +remaining sections are still locked by the process. Releasing the center +section of a locked section requires an additional element in the table of +active locks. If this table is full, an \fBerrno\fR is set to \fBEDEADLK\fR and +the requested section is not released. +.sp +.LP +An \fBF_ULOCK\fR request in which \fBsize\fR is non-zero and the offset of the +last byte of the requested section is the maximum value for an object of type +\fBoff_t\fR, when the process has an existing lock in which \fBsize\fR is 0 and +which includes the last byte of the requested section, will be treated as a +request to unlock from the start of the requested section with a size equal to +0. Otherwise, an \fBF_ULOCK\fR request will attempt to unlock only the +requested section. +.sp +.LP +A potential for deadlock occurs if the threads of a process controlling a +locked resource is put to sleep by requesting another process's locked +resource. Thus calls to \fBlockf()\fR or \fBfcntl\fR(2) scan for a deadlock +prior to sleeping on a locked resource. An error return is made if sleeping on +the locked resource would cause a deadlock. +.sp +.LP +Sleeping on a resource is interrupted with any signal. The \fBalarm\fR(2) +function may be used to provide a timeout facility in applications that require +this facility. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBlockf()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 20n +.rt +The \fIfildes\fR argument is not a valid open file descriptor; or +\fBfunction\fR is \fBF_LOCK\fR or \fBF_TLOCK\fR and \fIfildes\fR is not a valid +file descriptor open for writing. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR or \fBEAGAIN\fR\fR +.ad +.RS 20n +.rt +The \fBfunction\fR argument is \fBF_TLOCK\fR or \fBF_TEST\fR and the section is +already locked by another process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEDEADLK\fR\fR +.ad +.RS 20n +.rt +The \fBfunction\fR argument is \fBF_LOCK\fR and a deadlock is detected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 20n +.rt +A signal was caught during execution of the function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBECOMM\fR\fR +.ad +.RS 20n +.rt +The \fIfildes\fR argument is on a remote machine and the link to that machine +is no longer active. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 20n +.rt +The \fBfunction\fR argument is not one of \fBF_LOCK\fR, \fBF_TLOCK\fR, +\fBF_TEST\fR, or \fBF_ULOCK\fR; or \fBsize\fR plus the current file offset is +less than 0. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOVERFLOW\fR\fR +.ad +.RS 20n +.rt +The offset of the first, or if \fBsize\fR is not 0 then the last, byte in the +requested section cannot be represented correctly in an object of type +\fBoff_t\fR. +.RE + +.sp +.LP +The \fBlockf()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 24n +.rt +The \fBfunction\fR argument is \fBF_LOCK\fR or \fBF_TLOCK\fR and the file is +mapped with \fBmmap\fR(2). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEDEADLK\fR or \fBENOLCK\fR\fR +.ad +.RS 24n +.rt +The \fBfunction\fR argument is \fBF_LOCK\fR, \fBF_TLOCK\fR, or \fBF_ULOCK\fR +and the request would cause the number of locks to exceed a system-imposed +limit. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOPNOTSUPP\fR or \fBEINVAL\fR\fR +.ad +.RS 24n +.rt +The locking of files of the type indicated by the \fIfildes\fR argument is not +supported. +.RE + +.SH USAGE +.sp +.LP +Record-locking should not be used in combination with the \fBfopen\fR(3C), +\fBfread\fR(3C), \fBfwrite\fR(3C) and other \fBstdio\fR functions. Instead, +the more primitive, non-buffered functions (such as \fBopen\fR(2)) 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 +\fBstdio\fR functions are the most common source of unexpected buffering. +.sp +.LP +The \fBalarm\fR(2) function may be used to provide a timeout facility in +applications requiring it. +.sp +.LP +The \fBlockf()\fR function has a transitional interface for 64-bit file +offsets. See \fBlf64\fR(5). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(2), \fBalarm\fR(2), \fBchmod\fR(2), \fBclose\fR(2), \fBcreat\fR(2), +\fBfcntl\fR(2), \fBmmap\fR(2), \fBopen\fR(2), \fBread\fR(2), \fBwrite\fR(2), +\fBattributes\fR(5), \fBlf64\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/lsearch.3c b/usr/src/man/man3c/lsearch.3c new file mode 100644 index 0000000000..0613b3a2e9 --- /dev/null +++ b/usr/src/man/man3c/lsearch.3c @@ -0,0 +1,147 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH lsearch 3C "6 Dec 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +lsearch, lfind \- linear search and update +.SH SYNOPSIS +.LP +.nf +#include <search.h> + +\fBvoid *\fR\fBlsearch\fR(\fBconst void *\fR\fIkey\fR, \fBvoid *\fR\fIbase\fR, \fBsize_t *\fR\fInelp\fR, + \fBsize_t\fR \fIwidth\fR, \fBint\fR (*\fIcompar\fR)(\fBconst void *\fR, \fBconst void *\fR)); +.fi + +.LP +.nf +\fBvoid *\fR\fBlfind\fR(\fBconst void *\fR\fIkey\fR, \fBconst void *\fR\fIbase\fR, \fBsize_t *\fR\fInelp\fR, + \fBsize_t\fR \fIwidth\fR, \fBint (*\fR\fIcompar\fR)(const void *, \fBconst void *));\fR +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBlsearch()\fR function is a linear search routine generalized from Knuth +(6.1) Algorithm S. (see \fIThe Art of Computer Programming, Volume 3, Section +6.1, by Donald E. Knuth.\fR). It returns a pointer to a table indicating where +a datum can be found. If the datum does not occur, it is added at the end of +the table. The \fIkey\fR argument points to the datum to be sought in the +table. The \fIbase\fR argument points to the first element in the table. The +\fInelp\fR argument points to an integer containing the current number of +elements in the table. The integer is incremented if the datum is added to the +table. The \fIwidth\fR argument is the size of an element in bytes. The +\fIcompar\fR argument is a pointer to the comparison function that the user +must supply (\fBstrcmp\fR(3C) for example). It is called with two arguments +that point to the elements being compared. The function must return zero if the +elements are equal and non-zero otherwise. +.sp +.LP +The \fBlfind()\fR function is the same as \fBlsearch()\fR except that if the +datum is not found, it is not added to the table. Instead, a null pointer is +returned. +.sp +.LP +It is important to note the following: +.RS +4 +.TP +.ie t \(bu +.el o +The pointers to the key and the element at the base of the table can be +pointers to any type. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The comparison function need not compare every byte, so arbitrary data can be +contained in the elements in addition to the values being compared. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The value returned should be cast into type pointer-to-element. +.RE +.SH RETURN VALUES +.sp +.LP +If the searched-for datum is found, both \fBlsearch()\fR and \fBlfind()\fR +return a pointer to it. Otherwise, \fBlfind()\fR returns \fINULL\fR and +\fBlsearch()\fR returns a pointer to the newly added element. +.SH USAGE +.sp +.LP +Undefined results can occur if there is not enough room in the table to add a +new item. +.sp +.LP +The \fBlsearch()\fR and \fBlfind()\fR functions safely allows concurrent access +by multiple threads to disjoint data, such as overlapping subtrees or tables. +.SH EXAMPLES +.LP +\fBExample 1 \fRA sample code using the \fBlsearch()\fR function. +.sp +.LP +This program will read in less than \fBTABSIZE\fR strings of length less than +\fBELSIZE\fR and store them in a table, eliminating duplicates, and then will +print each entry. + +.sp +.in +2 +.nf +#include <search.h> +#include <string.h> +#include <stdlib.h> +#include <stdio.h> + +#define TABSIZE 50 +#define ELSIZE 120 + +main() +{ + char line[ELSIZE]; /* buffer to hold input string */ + char tab[TABSIZE][ELSIZE]; /* table of strings */ + size_t nel = 0; /* number of entries in tab */ + int i; + + while (fgets(line, ELSIZE, stdin) != NULL && + nel < TABSIZE) + (void) lsearch(line, tab, &nel, ELSIZE, mycmp); + for( i = 0; i < nel; i++ ) + (void)fputs(tab[i], stdout); + return 0; +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBbsearch\fR(3C), \fBhsearch\fR(3C), \fBstring\fR(3C), \fBtsearch\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) +.sp +.LP +\fIThe Art of Computer Programming, Volume 3, Sorting and Searching by Donald +E. Knuth, published by Addison-Wesley Publishing Company, 1973.\fR diff --git a/usr/src/man/man3c/madvise.3c b/usr/src/man/man3c/madvise.3c new file mode 100644 index 0000000000..56ed4ccea9 --- /dev/null +++ b/usr/src/man/man3c/madvise.3c @@ -0,0 +1,291 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Right Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH madvise 3C "23 Feb 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +madvise \- provide advice to VM system +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/mman.h> + +\fBint\fR \fBmadvise\fR(\fBcaddr_t\fR \fIaddr\fR, \fBsize_t\fR \fIlen\fR, \fBint\fR \fIadvice\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBmadvise()\fR function advises the kernel that a region of user mapped +memory in the range [\fIaddr\fR, \fIaddr\fR + \fIlen\fR) will be accessed +following a type of pattern. The kernel uses this information to optimize the +procedure for manipulating and maintaining the resources associated with the +specified mapping range. +.sp +.LP +Values for \fIadvice\fR are defined in <\fBsys/mman.h\fR> as: +.sp +.in +2 +.nf +#define MADV_NORMAL 0x0 /* No further special treatment */ +#define MADV_RANDOM 0x1 /* Expect random page references */ +#define MADV_SEQUENTIAL 0x2 /* Expect sequential page references */ +#define MADV_WILLNEED 0x3 /* Will need these pages */ +#define MADV_DONTNEED 0x4 /* Don't need these pages */ +#define MADV_FREE 0x5 /* Contents can be freed */ +#define MADV_ACCESS_DEFAULT 0x6 /* default access */ +#define MADV_ACCESS_LWP 0x7 /* next LWP to access heavily */ +#define MADV_ACCESS_MANY 0x8 /* many processes to access heavily */ +.fi +.in -2 + +.sp +.ne 2 +.mk +.na +\fB\fBMADV_NORMAL\fR\fR +.ad +.RS 23n +.rt +This is the default system characteristic where accessing memory within the +address range causes the system to read data from the mapped file. The kernel +reads all data from files into pages which are retained for a period of time as +a "cache." System pages can be a scarce resource, so the kernel steals pages +from other mappings when needed. This is a likely occurrence, but adversely +affects system performance only if a large amount of memory is accessed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMADV_RANDOM\fR\fR +.ad +.RS 23n +.rt +Tell the kernel to read in a minimum amount of data from a mapped file on any +single particular access. If \fBMADV_NORMAL\fR is in effect when an address of +a mapped file is accessed, the system tries to read in as much data from the +file as reasonable, in anticipation of other accesses within a certain +locality. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMADV_SEQUENTIAL\fR\fR +.ad +.RS 23n +.rt +Tell the system that addresses in this range are likely to be accessed only +once, so the system will free the resources mapping the address range as +quickly as possible. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMADV_WILLNEED\fR\fR +.ad +.RS 23n +.rt +Tell the system that a certain address range is definitely needed so the kernel +will start reading the specified range into memory. This can benefit programs +wanting to minimize the time needed to access memory the first time, as the +kernel would need to read in from the file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMADV_DONTNEED\fR\fR +.ad +.RS 23n +.rt +Tell the kernel that the specified address range is no longer needed, so the +system starts to free the resources associated with the address range. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMADV_FREE\fR\fR +.ad +.RS 23n +.rt +Tell the kernel that contents in the specified address range are no longer +important and the range will be overwritten. When there is demand for memory, +the system will free pages associated with the specified address range. In this +instance, the next time a page in the address range is referenced, it will +contain all zeroes. Otherwise, it will contain the data that was there prior +to the \fBMADV_FREE\fR call. References made to the address range will not make +the system read from backing store (swap space) until the page is modified +again. +.sp +This value cannot be used on mappings that have underlying file objects. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMADV_ACCESS_LWP\fR\fR +.ad +.RS 23n +.rt +Tell the kernel that the next LWP to touch the specified address range will +access it most heavily, so the kernel should try to allocate the memory and +other resources for this range and the LWP accordingly. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMADV_ACCESS_MANY\fR\fR +.ad +.RS 23n +.rt +Tell the kernel that many processes and/or LWPs will access the specified +address range randomly across the machine, so the kernel should try to allocate +the memory and other resources for this range accordingly. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMADV_ACCESS_DEFAULT\fR\fR +.ad +.RS 23n +.rt +Reset the kernel's expectation for how the specified range will be accessed to +the default. +.RE + +.sp +.LP +The \fBmadvise()\fR function should be used by applications with specific +knowledge of their access patterns over a memory object, such as a mapped file, +to increase system performance. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBmadvise()\fR returns \fB0\fR; otherwise, it +returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +Some or all mappings in the address range [\fIaddr\fR, \fIaddr\fR + +\fIlen\fR) are locked for I/O. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBUSY\fR\fR +.ad +.RS 10n +.rt +Some or all of the addresses in the range [\fIaddr\fR, \fIaddr\fR + \fIlen\fR) +are locked and \fBMS_SYNC\fR with the \fBMS_INVALIDATE\fR option is specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +.rt +Some or all of the addresses in the specified range could not be read into +memory from the underlying object when performing \fBMADV_WILLNEED\fR. The +\fBmadvise()\fR function could return prior to this condition being detected, +in which case \fBerrno\fR will not be set to \fBEFAULT\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIaddr\fR argument is not a multiple of the page size as returned by +\fBsysconf\fR(3C), the length of the specified address range is equal to 0, or +the \fIadvice\fR argument was invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 10n +.rt +An I/O error occurred while reading from or writing to the file system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Addresses in the range [\fIaddr\fR, \fIaddr\fR + \fIlen\fR) are outside the +valid range for the address space of a process, or specify one or more pages +that are not mapped. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBESTALE\fR\fR +.ad +.RS 10n +.rt +Stale \fBNFS\fR file handle. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStable +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBmeminfo\fR(2), \fBmmap\fR(2), \fBsysconf\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/makecontext.3c b/usr/src/man/man3c/makecontext.3c new file mode 100644 index 0000000000..304ecb0658 --- /dev/null +++ b/usr/src/man/man3c/makecontext.3c @@ -0,0 +1,208 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH makecontext 3C "8 Mar 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +makecontext, swapcontext \- manipulate user contexts +.SH SYNOPSIS +.LP +.nf +#include <ucontext.h> + +\fBvoid\fR \fBmakecontext\fR(\fBucontext_t *\fR\fIucp\fR, \fBvoid (*\fR\fIfunc\fR)(), \fBint\fR \fIargc\fR...); +.fi + +.LP +.nf +\fBint\fR \fBswapcontext\fR(\fBucontext_t *restrict\fR \fIoucp\fR, + \fBconst ucontext_t *restrict\fR \fIucp\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBmakecontext()\fR function modifies the context specified by \fIucp\fR, +which has been initialized using \fBgetcontext\fR(2). When this context is +resumed using \fBswapcontext()\fR or \fBsetcontext\fR(2), execution continues +by calling the function \fIfunc\fR, passing it the arguments that follow +\fIargc\fR in the \fBmakecontext()\fR call. The value of \fIargc\fR must match +the number of pointer-sized integer arguments passed to \fIfunc\fR, otherwise +the behavior is undefined. +.sp +.LP +Before a call is made to \fBmakecontext()\fR, the context being modified should +have a stack allocated for it. The stack is assigned to the context by +initializing the \fBuc_stack\fR member. +.sp +.LP +The \fBuc_link\fR member is used to determine the context that will be resumed +when the context being modified by \fBmakecontext()\fR returns. The +\fBuc_link\fR member should be initialized prior to the call to +\fBmakecontext()\fR. If the \fBuc_link\fR member is initialized to \fINULL\fR, +the thread executing \fIfunc\fR will exit when \fIfunc\fR returns. See +\fBpthread_exit\fR(3C). +.sp +.LP +The \fBswapcontext()\fR function saves the current context in the context +structure pointed to by \fIoucp\fR and sets the context to the context +structure pointed to by \fIucp\fR. +.sp +.LP +If the \fIucp\fR or \fIoucp\fR argument points to an invalid address, the +behavior is undefined and \fBerrno\fR may be set to \fBEFAULT\fR. +.SH RETURN VALUES +.sp +.LP +On successful completion, \fBswapcontext()\fR returns \fB0\fR. Otherwise, +\fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBswapcontext()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +The \fIucp\fR argument does not have enough stack left to complete the +operation. +.RE + +.sp +.LP +The \fBswapcontext()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +.rt +The \fIucp\fR or \fIoucp\fR argument points to an invalid address. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRAlternate execution context on a stack whose memory was +allocated using \fBmmap()\fR. +.sp +.in +2 +.nf +#include <stdio.h> +#include <ucontext.h> +#include <sys/mman.h> + +void +assign(long a, int *b) +{ + *b = (int)a; +} + +int +main(int argc, char **argv) +{ + ucontext_t uc, back; + size_t sz = 0x10000; + int value = 0; + + getcontext(&uc); + + uc.uc_stack.ss_sp = mmap(0, sz, + PROT_READ | PROT_WRITE | PROT_EXEC, + MAP_PRIVATE | MAP_ANON, -1, 0); + uc.uc_stack.ss_size = sz; + uc.uc_stack.ss_flags = 0; + + uc.uc_link = &back; + + makecontext(&uc, assign, 2, 100L, &value); + swapcontext(&back, &uc); + + printf("done %d\en", value); + + return (0); +} +.fi +.in -2 + +.SH USAGE +.sp +.LP +These functions are useful for implementing user-level context switching +between multiple threads of control within a process (co-processing). More +effective multiple threads of control can be obtained by using native support +for multithreading. See \fBthreads\fR(5). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBmmap\fR(2), \fBgetcontext\fR(2), \fBsigaction\fR(2), \fBsigprocmask\fR(2), +\fBpthread_exit\fR(3C), \fBucontext.h\fR(3HEAD), \fBattributes\fR(5), +\fBstandards\fR(5), \fBthreads\fR(5) +.SH NOTES +.sp +.LP +The semantics of the \fBuc_stack\fR member of the \fBucontext_t\fR structure +have changed as they apply to inputs to \fBmakecontext()\fR. Prior to Solaris +10, the \fBss_sp\fR member of the \fBuc_stack\fR structure represented the high +memory address of the area reserved for the stack. The \fBss_sp\fR member now +represents the base (low memory address), in keeping with other uses of +\fBss_sp\fR. +.sp +.LP +This change in the meaning of \fBss_sp\fR is now the default behavior. The +\fB-D__MAKECONTEXT_V2_SOURCE\fR compilation flag used in Solaris 9 update +releases to access this behavior is obsolete. +.sp +.LP +Binary compatibility has been preserved with releases prior to Solaris 10. +Before recompiling, applications that use \fBmakecontext()\fR must be updated +to reflect this behavior change. The example below demonstates a typical change +that must be applied: +.sp +.in +2 +.nf +--- example1_s9.c Thu Oct 3 11:58:17 2002 ++++ example1.c Thu Jun 27 13:28:16 2002 +@@ -27,12 +27,9 @@ + uc.uc_stack.ss_sp = mmap(0, sz, + PROT_READ | PROT_WRITE | PROT_EXEC, + MAP_PRIVATE | MAP_ANON, -1, 0); +- uc.uc_stack.ss_sp = (char *)uc.uc_stack.ss_sp + sz - 8; + uc.uc_stack.ss_size = sz; + uc.uc_stack.ss_flags = 0; + + uc.uc_link = &back + + makecontext(&uc, assign, 2, 100L, &value); +.fi +.in -2 + diff --git a/usr/src/man/man3c/makedev.3c b/usr/src/man/man3c/makedev.3c new file mode 100644 index 0000000000..cb31b290f6 --- /dev/null +++ b/usr/src/man/man3c/makedev.3c @@ -0,0 +1,114 @@ +'\" te +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH makedev 3C "29 Dec 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +makedev, major, minor \- manage a device number +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/mkdev.h> + +\fBdev_t\fR \fBmakedev\fR(\fBmajor_t\fR \fImaj\fR, \fBminor_t\fR \fImin\fR); +.fi + +.LP +.nf +\fBmajor_t\fR \fBmajor\fR(\fBdev_t\fR \fIdevice\fR); +.fi + +.LP +.nf +\fBminor_t\fR \fBminor\fR(\fBdev_t\fR \fIdevice\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBmakedev()\fR function returns a formatted device number on success and +\fBNODEV\fR on failure. The \fImaj\fR argument is the major number. The +\fImin\fR argument is the minor number. The \fBmakedev()\fR function can be +used to create a device number for input to \fBmknod\fR(2). +.sp +.LP +The \fBmajor()\fR function returns the major number component from +\fIdevice\fR. +.sp +.LP +The \fBminor()\fR function returns the minor number component from +\fIdevice\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBmakedev()\fR returns a formatted device number. +Otherwise, \fBNODEV\fR is returned and \fBerrno\fR is set to indicate the +error. +.SH ERRORS +.sp +.LP +The \fBmakedev()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +One or both of the arguments \fImaj\fR and \fImin\fR is too large, or the +\fIdevice\fR number created from \fImaj\fR and \fImin\fR is \fBNODEV\fR. +.RE + +.sp +.LP +The \fBmajor()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIdevice\fR argument is \fBNODEV\fR, or the major number component of +\fIdevice\fR is too large. +.RE + +.sp +.LP +The \fBminor()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIdevice\fR argument is \fBNODEV\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBmknod\fR(2), \fBstat\fR(2), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/malloc.3c b/usr/src/man/man3c/malloc.3c new file mode 100644 index 0000000000..d1549885d4 --- /dev/null +++ b/usr/src/man/man3c/malloc.3c @@ -0,0 +1,208 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH malloc 3C "21 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +malloc, calloc, free, memalign, realloc, valloc, alloca \- memory allocator +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBvoid *\fR\fBmalloc\fR(\fBsize_t\fR \fIsize\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBcalloc\fR(\fBsize_t\fR \fInelem\fR, \fBsize_t\fR \fIelsize\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBfree\fR(\fBvoid *\fR\fIptr\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBmemalign\fR(\fBsize_t\fR \fIalignment\fR, \fBsize_t\fR \fIsize\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBrealloc\fR(\fBvoid *\fR\fIptr\fR, \fBsize_t\fR \fIsize\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBvalloc\fR(\fBsize_t\fR \fIsize\fR); +.fi + +.LP +.nf +#include <alloca.h> + +\fBvoid *\fR\fBalloca\fR(\fBsize_t\fR \fIsize\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBmalloc()\fR and \fBfree()\fR functions provide a simple, general-purpose +memory allocation package. The \fBmalloc()\fR function returns a pointer to a +block of at least \fIsize\fR bytes suitably aligned for any use. If the space +assigned by \fBmalloc()\fR is overrun, the results are undefined. +.sp +.LP +The argument to \fBfree()\fR is a pointer to a block previously allocated by +\fBmalloc()\fR, \fBcalloc()\fR, or \fBrealloc()\fR. After \fBfree()\fR is +executed, this space is made available for further allocation by the +application, though not returned to the system. Memory is returned to the +system only upon termination of the application. If \fIptr\fR is a null +pointer, no action occurs. If a random number is passed to \fBfree()\fR, the +results are undefined. +.sp +.LP +The \fBcalloc()\fR function allocates space for an array of \fInelem\fR +elements of size \fIelsize\fR. The space is initialized to zeros. +.sp +.LP +The \fBmemalign()\fR function allocates \fIsize\fR bytes on a specified +alignment boundary and returns a pointer to the allocated block. The value of +the returned address is guaranteed to be an even multiple of \fIalignment\fR. +The value of \fIalignment\fR must be a power of two and must be greater than or +equal to the size of a word. +.sp +.LP +The \fBrealloc()\fR function changes the size of the block pointed to by +\fIptr\fR to \fIsize\fR bytes and returns a pointer to the (possibly moved) +block. The contents will be unchanged up to the lesser of the new and old +sizes. If the new size of the block requires movement of the block, the space +for the previous instantiation of the block is freed. If the new size is +larger, the contents of the newly allocated portion of the block are +unspecified. If \fIptr\fR is \fINULL\fR, \fBrealloc()\fR behaves like +\fBmalloc()\fR for the specified size. If \fIsize\fR is 0 and \fIptr\fR is not +a null pointer, the space pointed to is freed. +.sp +.LP +The \fBvalloc()\fR function has the same effect as \fBmalloc()\fR, except that +the allocated memory will be aligned to a multiple of the value returned by +\fBsysconf\fR(\fB_SC_PAGESIZE\fR). +.sp +.LP +The \fBalloca()\fR function allocates \fIsize\fR bytes of space in the stack +frame of the caller, and returns a pointer to the allocated block. This +temporary space is automatically freed when the caller returns. If the +allocated block is beyond the current stack limit, the resulting behavior is +undefined. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, each of the allocation functions returns a pointer +to space suitably aligned (after possible pointer coercion) for storage of any +type of object. +.sp +.LP +If there is no available memory, \fBmalloc()\fR, \fBrealloc()\fR, +\fBmemalign()\fR, \fBvalloc()\fR, and \fBcalloc()\fR return a null pointer. +When \fBrealloc()\fR is called with \fIsize\fR > 0 and returns \fINULL\fR, the +block pointed to by \fIptr\fR is left intact. If \fIsize\fR, \fInelem\fR, or +\fIelsize\fR is 0, either a null pointer or a unique pointer that can be passed +to \fBfree()\fR is returned. +.sp +.LP +If \fBmalloc()\fR, \fBcalloc()\fR, or \fBrealloc()\fR returns unsuccessfully, +\fBerrno\fR will be set to indicate the error. The \fBfree()\fR function does +not set \fBerrno\fR. +.SH ERRORS +.sp +.LP +The \fBmalloc()\fR, \fBcalloc()\fR, and \fBrealloc()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +The physical limits of the system are exceeded by \fIsize\fR bytes of memory +which cannot be allocated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +There is not enough memory available to allocate \fIsize\fR bytes of memory; +but the application could try again later. +.RE + +.SH USAGE +.sp +.LP +Portable applications should avoid using \fBvalloc()\fR but should instead use +\fBmalloc()\fR or \fBmmap\fR(2). On systems with a large page size, the number +of successful \fBvalloc()\fR operations might be 0. +.sp +.LP +These default memory allocation routines are safe for use in multithreaded +applications but are not scalable. Concurrent accesses by multiple threads are +single-threaded through the use of a single lock. Multithreaded applications +that make heavy use of dynamic memory allocation should be linked with +allocation libraries designed for concurrent access, such as +\fBlibumem\fR(3LIB) or \fBlibmtmalloc\fR(3LIB). Applications that want to avoid +using heap allocations (with \fBbrk\fR(2)) can do so by using either +\fBlibumem\fR or \fBlibmapmalloc\fR(3LIB). The allocation libraries +\fBlibmalloc\fR(3LIB) and \fBlibbsdmalloc\fR(3LIB) are available for special +needs. +.sp +.LP +Comparative features of the various allocation libraries can be found in the +\fBumem_alloc\fR(3MALLOC) manual page. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilitySee below. +_ +MT-LevelSafe +.TE + +.sp +.LP +The \fBmalloc()\fR, \fBcalloc()\fR, \fBfree()\fR, \fBrealloc()\fR, +\fBvalloc()\fR functions are Standard. The \fBmemalign()\fR and \fBalloca()\fR +functions are Stable. +.SH SEE ALSO +.sp +.LP +\fBbrk\fR(2), \fBgetrlimit\fR(2), \fBlibbsdmalloc\fR(3LIB), +\fBlibmalloc\fR(3LIB), \fBlibmapmalloc\fR(3LIB), \fBlibmtmalloc\fR(3LIB), +\fBlibumem\fR(3LIB), \fBumem_alloc\fR(3MALLOC), \fBwatchmalloc\fR(3MALLOC), +\fBattributes\fR(5) +.SH WARNINGS +.sp +.LP +Undefined results will occur if the size requested for a block of memory +exceeds the maximum size of a process's heap, which can be obtained with +\fBgetrlimit\fR(2) +.sp +.LP +The \fBalloca()\fR function is machine-, compiler-, and most of all, +system-dependent. Its use is strongly discouraged. diff --git a/usr/src/man/man3c/mblen.3c b/usr/src/man/man3c/mblen.3c new file mode 100644 index 0000000000..8c028f1c17 --- /dev/null +++ b/usr/src/man/man3c/mblen.3c @@ -0,0 +1,89 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH mblen 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +mblen \- get number of bytes in a character +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBint\fR \fBmblen\fR(\fBconst char *\fR\fIs\fR, \fBsize_t\fR \fIn\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +If \fIs\fR is not a null pointer, \fBmblen()\fR determines the number of bytes +constituting the character pointed to by \fIs\fR. It is equivalent to: +.sp +.LP +\fBmbtowc((wchar_t *)0, \fR\fIs\fR, \fIn\fR); +.sp +.LP +A call with \fIs\fR as a null pointer causes this function to return \fB0\fR. +The behavior of this function is affected by the \fBLC_CTYPE\fR category of the +current locale. +.SH RETURN VALUES +.sp +.LP +If \fIs\fR is a null pointer, \fBmblen()\fR returns \fB0\fR. It \fIs\fR is not +a null pointer, \fBmblen()\fR returns \fB0\fR (if \fIs\fR points to the null +byte), the number of bytes that constitute the character (if the next \fIn\fR +or fewer bytes form a valid character), or \fB\(mi1\fR (if they do not form a +valid character) and may set \fBerrno\fR to indicate the error. In no case will +the value returned be greater than \fIn\fR or the value of the \fBMB_CUR_MAX\fR +macro. +.SH ERRORS +.sp +.LP +The \fBmblen()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEILSEQ\fR\fR +.ad +.RS 10n +.rt +Invalid character sequence is detected. +.RE + +.SH USAGE +.sp +.LP +The \fBmblen()\fR function can be used safely in multithreaded applications, as +long as \fBsetlocale\fR(3C) is not being called to change the locale. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +CSIEnabled +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBmbstowcs\fR(3C), \fBmbtowc\fR(3C), \fBsetlocale\fR(3C), \fBwcstombs\fR(3C), +\fBwctomb\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/mbrlen.3c b/usr/src/man/man3c/mbrlen.3c new file mode 100644 index 0000000000..429c39bda9 --- /dev/null +++ b/usr/src/man/man3c/mbrlen.3c @@ -0,0 +1,161 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH mbrlen 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +mbrlen \- get number of bytes in a character (restartable) +.SH SYNOPSIS +.LP +.nf +#include <wchar.h> + +\fBsize_t\fR \fBmbrlen\fR(\fBconst char *restrict\fR \fIs\fR, \fBsize_t\fR \fIn\fR, \fBmbstate_t *restrict\fR \fIps\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +If \fIs\fR is not a null pointer, \fBmbrlen()\fR determines the number of +bytes constituting the character pointed to by \fIs\fR. It is equivalent to: +.sp +.in +2 +.nf +mbstate_t internal; +mbrtowc(NULL, s, n, ps != NULL ? ps : &internal); +.fi +.in -2 + +.sp +.LP +If \fIps\fR is a null pointer, the \fBmbrlen()\fR function uses its own +internal \fBmbstate_t\fR object, which is initialized at program startup to the +initial conversion state. Otherwise, the \fBmbstate_t\fR object pointed to +by \fIps\fR is used to completely describe the current conversion state of the +associated character sequence. Solaris will behave as if no function defined in +the Solaris Reference Manual calls \fBmbrlen()\fR. +.sp +.LP +The behavior of this function is affected by the \fBLC_CTYPE\fR category of the +current locale. See \fBenviron\fR(5). +.SH RETURN VALUES +.sp +.LP +The \fBmbrlen()\fR function returns the first of the following that applies: +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 17n +.rt +If the next \fIn\fR or fewer bytes complete the character that corresponds to +the null wide-character. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpositive\fR\fR +.ad +.RS 17n +.rt +If the next \fIn\fR or fewer bytes complete a valid character; the value +returned is the number of bytes that complete the character. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB(size_t)\(mi2\fR\fR +.ad +.RS 17n +.rt +If the next \fIn\fR bytes contribute to an incomplete but potentially valid +character, and all \fIn\fR bytes have been processed. When \fIn\fR has at least +the value of the \fBMB_CUR_MAX\fR macro, this case can only occur if \fIs\fR +points at a sequence of redundant shift sequences (for implementations with +state-dependent encodings). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB(size_t)\(mi1\fR\fR +.ad +.RS 17n +.rt +If an encoding error occurs, in which case the next \fIn\fR or fewer bytes do +not contribute to a complete and valid character. In this case, \fBEILSEQ\fR +is stored in \fBerrno\fR and the conversion state is undefined. +.RE + +.SH ERRORS +.sp +.LP +The \fBmbrlen()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIps\fR argument points to an object that contains an invalid conversion +state. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEILSEQ\fR\fR +.ad +.RS 10n +.rt +Invalid character sequence is detected. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSee NOTES below +.TE + +.SH SEE ALSO +.sp +.LP +\fBmbrtowc\fR(3C), \fBmbsinit\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5), +\fBenviron\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +If \fIps\fR is not a null pointer, \fBmbrlen()\fR uses the \fBmbstate_t\fR +object pointed to by \fIps\fR and the function can be used safely in +multithreaded applications, as long as \fBsetlocale\fR(3C) is not being called +to change the locale. If \fIps\fR is a null pointer, \fBmbrlen()\fR uses its +internal \fBmbstate_t\fR object and the function is Unsafe in multithreaded +applications. diff --git a/usr/src/man/man3c/mbrtowc.3c b/usr/src/man/man3c/mbrtowc.3c new file mode 100644 index 0000000000..de00b5f5f4 --- /dev/null +++ b/usr/src/man/man3c/mbrtowc.3c @@ -0,0 +1,176 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH mbrtowc 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +mbrtowc \- convert a character to a wide-character code (restartable) +.SH SYNOPSIS +.LP +.nf +#include <wchar.h> + +\fBsize_t\fR \fBmbrtowc\fR(\fBwchar_t *restrict\fR \fIpwc\fR, \fBconst char *restrict\fR \fIs\fR, \fBsize_t\fR \fIn\fR, + \fBmbstate_t *restrict\fR \fIps\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +If \fIs\fR is a null pointer, the \fBmbrtowc()\fR function is equivalent to the +call: +.sp +.in +2 +.nf +mbrtowc(NULL, ``'', 1, ps) +.fi +.in -2 + +.sp +.LP +In this case, the values of the arguments \fIpwc\fR and \fIn\fR are ignored. +.sp +.LP +If \fIs\fR is not a null pointer, the \fBmbrtowc()\fR function inspects at most +\fIn\fR bytes beginning at the byte pointed to by \fIs\fR 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 determines the value of the corresponding wide-character and then, if +\fIpwc\fR is not a null pointer, stores that value in the object pointed to by +\fIpwc\fR. If the corresponding wide-character is the null wide-character, the +resulting state described is the initial conversion state. +.sp +.LP +If \fIps\fR is a null pointer, the \fBmbrtowc()\fR function uses its own +internal \fBmbstate_t\fR object, which is initialized at program startup to the +initial conversion state. Otherwise, the \fBmbstate_t\fR object pointed to +by \fIps\fR is used to completely describe the current conversion state of the +associated character sequence. Solaris will behave as if no function defined in +the Solaris Reference Manual calls \fBmbrtowc()\fR. +.sp +.LP +The behavior of this function is affected by the \fBLC_CTYPE\fR category of the +current locale. See \fBenviron\fR(5). +.SH RETURN VALUES +.sp +.LP +The \fBmbrtowc()\fR function returns the first of the following that applies: +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 17n +.rt +If the next \fIn\fR or fewer bytes complete the character that corresponds to +the null wide-character (which is the value stored). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpositive\fR\fR +.ad +.RS 17n +.rt +If the next \fIn\fR or fewer bytes complete a valid character (which is the +value stored); the value returned is the number of bytes that complete the +character. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB(size_t)\(mi2\fR\fR +.ad +.RS 17n +.rt +If the next \fIn\fR bytes contribute to an incomplete but potentially valid +character, and all \fIn\fR bytes have been processed (no value is stored). +When \fIn\fR has at least the value of the \fBMB_CUR_MAX\fR macro, this case +can only occur if \fIs\fR points at a sequence of redundant shift sequences +(for implementations with state-dependent encodings). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB(size_t)\(mi1\fR\fR +.ad +.RS 17n +.rt +If an encoding error occurs, in which case the next \fIn\fR or fewer bytes do +not contribute to a complete and valid character (no value is stored). In +this case, \fBEILSEQ\fR is stored in \fBerrno\fR and the conversion state is +undefined. +.RE + +.SH ERRORS +.sp +.LP +The \fBmbrtowc()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIps\fR argument points to an object that contains an invalid conversion +state. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEILSEQ\fR\fR +.ad +.RS 10n +.rt +Invalid character sequence is detected. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSee NOTES below +.TE + +.SH SEE ALSO +.sp +.LP +\fBmbsinit\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5), \fBenviron\fR(5), +\fBstandards\fR(5) +.SH NOTES +.sp +.LP +If \fIps\fR is not a null pointer, \fBmbrtowc()\fR uses the \fBmbstate_t\fR +object pointed to by \fIps\fR and the function can be used safely in +multithreaded applications, as long as \fBsetlocale\fR(3C) is not being called +to change the locale. If \fIps\fR is a null pointer, \fBmbrtowc()\fR uses its +internal \fBmbstate_t\fR object and the function is Unsafe in multithreaded +applications. diff --git a/usr/src/man/man3c/mbsinit.3c b/usr/src/man/man3c/mbsinit.3c new file mode 100644 index 0000000000..0823687253 --- /dev/null +++ b/usr/src/man/man3c/mbsinit.3c @@ -0,0 +1,88 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH mbsinit 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +mbsinit \- determine conversion object status +.SH SYNOPSIS +.LP +.nf +#include <wchar.h> + +\fBint\fR \fBmbsinit\fR(\fBconst mbstate_t *\fR\fIps\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +If \fBps\fR is not a null pointer, the \fBmbsinit()\fR function determines +whether the object pointed to by \fBps\fR describes an initial conversion +state. +.SH RETURN VALUES +.sp +.LP +The \fBmbsinit()\fR function returns non-zero if \fBps\fR is a null pointer, +or if the pointed-to object describes an initial conversion state; otherwise, +it returns \fB0\fR. +.sp +.LP +If an \fBmbstate_t\fR 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 \fBLC_CTYPE\fR category setting +than on earlier function calls, the behavior is undefined. See +\fBenviron\fR(5). +.SH ERRORS +.sp +.LP +No errors are defined. +.SH USAGE +.sp +.LP +The \fBmbstate_t\fR object is used to describe the current conversion state +from a particular character sequence to a wide-character sequence (or vice +versa) under the rules of a particular setting of the \fBLC_CTYPE\fR category +of the current locale. +.sp +.LP +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 \fBmbstate_t\fR object is at least one way to describe an initial +conversion state. A zero-valued \fBmbstate_t\fR object can be used to initiate +conversion involving any character sequence, in any \fBLC_CTYPE\fR category +setting. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBmbrlen\fR(3C), \fBmbrtowc\fR(3C), \fBmbsrtowcs\fR(3C), \fBsetlocale\fR(3C), +\fBwcrtomb\fR(3C), \fBwcsrtombs\fR(3C), \fBattributes\fR(5), \fBenviron\fR(5), +\fBstandards\fR(5) +.SH NOTES +.sp +.LP +The \fBmbsinit()\fR function can be used safely in multithreaded applications, +as long as \fBsetlocale\fR(3C) is not being called to change the locale. diff --git a/usr/src/man/man3c/mbsrtowcs.3c b/usr/src/man/man3c/mbsrtowcs.3c new file mode 100644 index 0000000000..bb1d369412 --- /dev/null +++ b/usr/src/man/man3c/mbsrtowcs.3c @@ -0,0 +1,137 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH mbsrtowcs 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +mbsrtowcs \- convert a character string to a wide-character string +(restartable) +.SH SYNOPSIS +.LP +.nf +#include <wchar.h> + +\fBsize_t\fR \fBmbsrtowcs\fR(\fBwchar_t *restrict\fR \fIdst\fR, \fBconst char **restrict\fR \fIsrc\fR, + \fBsize_t\fR \fIlen\fR, \fBmbstate_t *restrict\fR \fIps\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBmbsrtowcs()\fR function converts a sequence of characters, beginning in +the conversion state described by the object pointed to by \fIps\fR, from the +array indirectly pointed to by \fIsrc\fR into a sequence of corresponding +wide-characters. If \fIdst\fR is not a null pointer, the converted characters +are stored into the array pointed to by \fIdst\fR. Conversion continues up to +and including a terminating null character, which is also stored. Conversion +stops early in either of the following cases: +.RS +4 +.TP +.ie t \(bu +.el o +When a sequence of bytes is encountered that does not form a valid character. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +When \fIlen\fR codes have been stored into the array pointed to by \fIdst\fR +(and \fIdst\fR is not a null pointer). +.RE +.sp +.LP +Each conversion takes place as if by a call to the \fBmbrtowc()\fR function. +.sp +.LP +If \fIdst\fR is not a null pointer, the pointer object pointed to by \fIsrc\fR +is 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 \fIdst\fR is not a null pointer, the resulting state +described is the initial conversion state. +.sp +.LP +If \fIps\fR is a null pointer, the \fBmbsrtowcs()\fR function uses its own +internal \fBmbstate_t\fR object, which is initialized at program startup to the +initial conversion state. Otherwise, the \fBmbstate_t\fR object pointed to by +\fIps\fR is used to completely describe the current conversion state of the +associated character sequence. Solaris will behave as if no function defined in +the Solaris Reference Manual calls \fBmbsrtowcs()\fR. +.sp +.LP +The behavior of this function is affected by the \fBLC_CTYPE\fR category of the +current locale. See \fBenviron\fR(5). +.SH RETURN VALUES +.sp +.LP +If the input conversion encounters a sequence of bytes that do not form a valid +character, an encoding error occurs. In this case, the \fBmbsrtowcs()\fR +function stores the value of the macro \fBEILSEQ\fR in \fBerrno\fR and returns +\fB(size_t)\(mi1\fR; the conversion state is undefined. Otherwise, it returns +the number of characters successfully converted, not including the terminating +null (if any). +.SH ERRORS +.sp +.LP +The \fBmbsrtowcs()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIps\fR argument points to an object that contains an invalid conversion +state. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEILSEQ\fR\fR +.ad +.RS 10n +.rt +Invalid character sequence is detected. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSee NOTES below +.TE + +.SH SEE ALSO +.sp +.LP +\fBmbrtowc\fR(3C), \fBmbsinit\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5), +\fBenviron\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +If \fIps\fR is not a null pointer, \fBmbsrtowcs()\fR uses the \fBmbstate_t\fR +object pointed to by \fIps\fR and the function can be used safely in +multithreaded applications, as long as \fBsetlocale\fR(3C) is not being called +to change the locale. If \fIps\fR is a null pointer, \fBmbsrtowcs()\fR uses its +internal \fBmbstate_t\fR object and the function is Unsafe in multithreaded +applications. diff --git a/usr/src/man/man3c/mbtowc.3c b/usr/src/man/man3c/mbtowc.3c new file mode 100644 index 0000000000..5a0ff0e4e8 --- /dev/null +++ b/usr/src/man/man3c/mbtowc.3c @@ -0,0 +1,94 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH mbtowc 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +mbtowc \- convert a character to a wide-character code +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBint\fR \fBmbtowc\fR(\fBwchar_t *restrict\fR \fIpwc\fR, \fBconst char *restrict\fR \fIs\fR, \fBsize_t\fR \fIn\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +If \fIs\fR is not a null pointer, \fBmbtowc()\fR determines the number of the +bytes that constitute the character pointed to by \fIs\fR. It then determines +the wide-character code for the value of type \fBwchar_t\fR 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 \fIpwc\fR is not a null pointer, +\fBmbtowc()\fR stores the wide-character code in the object pointed to by +\fIpwc\fR. +.sp +.LP +A call with \fIs\fR as a null pointer causes this function to return \fB0\fR. +The behavior of this function is affected by the \fBLC_CTYPE\fR category of the +current locale. At most \fIn\fR bytes of the array pointed to by \fIs\fR will +be examined. +.SH RETURN VALUES +.sp +.LP +If \fIs\fR is a null pointer, \fBmbtowc()\fR returns \fB0\fR. If \fIs\fR is not +a null pointer, \fBmbtowc()\fR returns \fB0\fR (if \fIs\fR points to the null +byte), the number of bytes that constitute the converted character (if the next +\fIn\fR or fewer bytes form a valid character), or \fB\(mi1\fR and may set +\fBerrno\fR to indicate the error (if they do not form a valid character). +.sp +.LP +In no case will the value returned be greater than \fIn\fR or the value of the +\fBMB_CUR_MAX\fR macro. +.SH ERRORS +.sp +.LP +The \fBmbtowc()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEILSEQ\fR\fR +.ad +.RS 10n +.rt +Invalid character sequence is detected. +.RE + +.SH USAGE +.sp +.LP +The \fBmbtowc()\fR function can be used safely in multithreaded applications, +as long as \fBsetlocale\fR(3C) is not being called to change the locale. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +CSIEnabled +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBmblen\fR(3C), \fBmbstowcs\fR(3C), \fBsetlocale\fR(3C), \fBwcstombs\fR(3C), +\fBwctomb\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/membar_ops.3c b/usr/src/man/man3c/membar_ops.3c new file mode 100644 index 0000000000..1595012ad8 --- /dev/null +++ b/usr/src/man/man3c/membar_ops.3c @@ -0,0 +1,109 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH membar_ops 3C "14 Feb 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +membar_ops, membar_enter, membar_exit, membar_producer, membar_consumer \- +memory access synchronization barrier operations +.SH SYNOPSIS +.LP +.nf +#include <atomic.h> + +\fBvoid\fR \fBmembar_enter\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBmembar_exit\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBmembar_producer\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBmembar_consumer\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBmembar_enter()\fR function is a generic memory barrier used during lock +entry. It is placed after the memory operation that acquires the lock to +guarantee that the lock protects its data. No stores from after the memory +barrier will reach visibility and no loads from after the barrier will be +resolved before the lock acquisition reaches global visibility. +.sp +.LP +The \fBmembar_exit()\fR function is a generic memory barrier used during lock +exit. It is placed before the memory operation that releases the lock to +guarantee that the lock protects its data. All loads and stores issued before +the barrier will be resolved before the subsequent lock update reaches +visibility. +.sp +.LP +The \fBmembar_enter()\fR and \fBmembar_exit()\fR functions are used together to +allow regions of code to be in relaxed store order and then ensure that the +load or store order is maintained at a higher level. They are useful in the +implementation of mutex exclusion locks. +.sp +.LP +The \fBmembar_producer()\fR function arranges for all stores issued before this +point in the code to reach global visibility before any stores that follow. +This is useful in producer modules that update a data item, then set a flag +that it is available. The memory barrier guarantees that the available flag is +not visible earlier than the updated data, thereby imposing store ordering. +.sp +.LP +The \fBmembar_consumer()\fR function arranges for all loads issued before this +point in the code to be completed before any subsequent loads. This is useful +in consumer modules that check if data is available and read the data. The +memory barrier guarantees that the data is not sampled until after the +available flag has been seen, thereby imposing load ordering. +.SH RETURN VALUES +.sp +.LP +No values are returned. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStable +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBatomic_add\fR(3C), \fBatomic_and\fR(3C), \fBatomic_bits\fR(3C), +\fBatomic_cas\fR(3C), \fBatomic_dec\fR(3C), \fBatomic_inc\fR(3C), +\fBatomic_ops\fR(3C), \fBatomic_or\fR(3C), \fBatomic_swap\fR(3C), +\fBattributes\fR(5), \fBatomic_ops\fR(9F) +.SH NOTES +.sp +.LP +Atomic instructions (see \fBatomic_ops\fR(3C)) ensure global visibility of +atomically-modified variables on completion. In a relaxed store order system, +this does not guarantee that the visibility of other variables will be +synchronized with the completion of the atomic instruction. If such +synchronization is required, memory barrier instructions must be used. diff --git a/usr/src/man/man3c/memory.3c b/usr/src/man/man3c/memory.3c new file mode 100644 index 0000000000..c8edfd8e71 --- /dev/null +++ b/usr/src/man/man3c/memory.3c @@ -0,0 +1,137 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH memory 3C "4 Feb 2009" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +memory, memccpy, memchr, memcmp, memcpy, memmove, memset \- memory operations +.SH SYNOPSIS +.LP +.nf +#include <string.h> + +\fBvoid *\fR\fBmemccpy\fR(\fBvoid *restrict\fR \fIs1\fR, \fBconst void *restrict\fR \fIs2\fR, + \fBint\fR \fIc\fR, \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBmemchr\fR(\fBconst void *\fR\fIs\fR, \fBint\fR \fIc\fR, \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +\fBint\fR \fBmemcmp\fR(\fBconst void *\fR\fIs1\fR, \fBconst void *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBmemcpy\fR(\fBvoid *restrict\fR \fIs1\fR, \fBconst void *restrict\fR \fIs2\fR, \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBmemmove\fR(\fBvoid *\fR\fIs1\fR, \fBconst void *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBmemset\fR(\fBvoid *\fR\fIs\fR, \fBint\fR \fIc\fR, \fBsize_t\fR \fIn\fR); +.fi + +.SS "ISO C++" +.LP +.nf +#include <string.h> + +\fBconst void *\fR\fBmemchr\fR(\fBconst void *\fR\fIs\fR, \fBint\fR \fIc\fR, \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +#include <cstring> + +\fBvoid *std::\fR\fBmemchr\fR(\fBvoid *\fR\fIs\fR, \fBint\fR \fIc\fR, \fBsize_t\fR \fIn\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions operate as efficiently as possible on memory areas (arrays of +bytes bounded by a count, not terminated by a null character). They do not +check for the overflow of any receiving memory area. +.sp +.LP +The \fBmemccpy()\fR function copies bytes from memory area \fIs2\fR into +\fIs1\fR, stopping after the first occurrence of \fIc\fR (converted to an +\fBunsigned char\fR) has been copied, or after \fIn\fR bytes have been copied, +whichever comes first. It returns a pointer to the byte after the copy of +\fIc\fR in \fIs1\fR, or a null pointer if \fIc\fR was not found in the first +\fIn\fR bytes of \fIs2\fR. +.sp +.LP +The \fBmemchr()\fR function returns a pointer to the first occurrence of +\fIc\fR (converted to an \fBunsigned char\fR) in the first \fIn\fR bytes (each +interpreted as an \fBunsigned char\fR) of memory area \fIs\fR, or a null +pointer if \fIc\fR does not occur. +.sp +.LP +The \fBmemcmp()\fR function compares its arguments, looking at the first +\fIn\fR bytes (each interpreted as an \fBunsigned char\fR), and returns an +integer less than, equal to, or greater than 0, according as \fIs1\fR is +lexicographically less than, equal to, or greater than \fIs2\fR when taken to +be unsigned characters. +.sp +.LP +The \fBmemcpy()\fR function copies \fIn\fR bytes from memory area \fIs2\fR to +\fIs1\fR. It returns \fIs1\fR. If copying takes place between objects that +overlap, the behavior is undefined. +.sp +.LP +The \fBmemmove()\fR function copies \fIn\fR bytes from memory area \fIs2\fR to +memory area \fIs1\fR. Copying between objects that overlap will take place +correctly. It returns \fIs1\fR. +.sp +.LP +The \fBmemset()\fR function sets the first \fIn\fR bytes in memory area \fIs\fR +to the value of \fIc\fR (converted to an \fBunsigned char\fR). It returns +\fIs\fR. +.SH USAGE +.sp +.LP +Using \fBmemcpy()\fR might be faster than using \fBmemmove()\fR if the +application knows that the objects being copied do not overlap. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStable +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBstring\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +Overlap between objects being copied can arise even when their (virtual) +address ranges appear to be disjoint; for example, as a result of +memory-mapping overlapping portions of the same underlying file, or of +attaching the same shared memory segment more than once. diff --git a/usr/src/man/man3c/mkfifo.3c b/usr/src/man/man3c/mkfifo.3c new file mode 100644 index 0000000000..c6ba7950b0 --- /dev/null +++ b/usr/src/man/man3c/mkfifo.3c @@ -0,0 +1,222 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH mkfifo 3C "24 Apr 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +mkfifo \- make a FIFO special file +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/stat.h> + +\fBint\fR \fBmkfifo\fR(\fBconst char *\fR\fIpath\fR, \fBmode_t\fR \fImode\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBmkfifo()\fR function creates a new FIFO special file named by the +pathname pointed to by \fIpath\fR. The file permission bits of the new FIFO +are initialized from \fImode\fR. The file permission bits of the \fImode\fR +argument are modified by the process's file creation mask (see \fBumask\fR(2)). +Bits other than the file permission bits in \fImode\fR are ignored. +.sp +.LP +If \fIpath\fR names a symbolic link, \fBmkfifo()\fR fails and sets \fBerrno\fR +to \fBEEXIST\fR. +.sp +.LP +The FIFO's user ID is set to the process's effective user ID. The FIFO's group +ID is set to the group ID of the parent directory or to the effective group ID +of the process. +.sp +.LP +The \fBmkfifo()\fR function calls \fBmknod\fR(2) to create the file. +.sp +.LP +Upon successful completion, \fBmkfifo()\fR marks for update the \fBst_atime\fR, +\fBst_ctime\fR, and \fBst_mtime\fR fields of the file. Also, the \fBst_ctime\fR +and \fBst_mtime\fR fields of the directory that contains the new entry are +marked for update. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBmkfifo()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 16n +.rt +A component of the path prefix denies search permission, or write permission is +denied on the parent directory of the FIFO to be created. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEEXIST\fR\fR +.ad +.RS 16n +.rt +The named file already exists. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBELOOP\fR\fR +.ad +.RS 16n +.rt +A loop exists in symbolic links encountered during resolution of the \fIpath\fR +argument. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +The length of the \fIpath\fR argument exceeds {\fBPATH_MAX\fR} or a pathname +component is longer than {\fBNAME_MAX\fR}. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 16n +.rt +A component of the path prefix specified by \fIpath\fR does not name an +existing directory or \fIpath\fR is an empty string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSPC\fR\fR +.ad +.RS 16n +.rt +The directory that would contain the new file cannot be extended or the file +system is out of file-allocation resources. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTDIR\fR\fR +.ad +.RS 16n +.rt +A component of the path prefix is not a directory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEROFS\fR\fR +.ad +.RS 16n +.rt +The named file resides on a read-only file system. +.RE + +.sp +.LP +The \fBmkfifo()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBELOOP\fR\fR +.ad +.RS 16n +.rt +Too many symbolic links were encountered in resolving \fIpath\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +The length of the \fIpath\fR argument exceeds {\fBPATH_MAX\fR} or a pathname +component is longer than {\fBNAME_MAX\fR}. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRCreate a FIFO File +.sp +.LP +The following example demonstrates how to create a FIFO file named +\fB/home/cnd/mod_done\fR with read and write permissions for the owner and read +permissions for the group and others. + +.sp +.in +2 +.nf +#include sys/types.h> +#include sys/stat.h> +int status; +\&... +status = mkfifo("/home/cnd/mod_done", S_IWUSR | S_IRUSR | + S_IRGRP | S_IROTH); +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBmkdir\fR(1), \fBchmod\fR(2), \fBexec\fR(2), \fBmknod\fR(2), \fBumask\fR(2), +\fBstat.h\fR(3HEAD), \fBufs\fR(7FS), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/mkstemp.3c b/usr/src/man/man3c/mkstemp.3c new file mode 100644 index 0000000000..33d1bf693c --- /dev/null +++ b/usr/src/man/man3c/mkstemp.3c @@ -0,0 +1,117 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH mkstemp 3C "22 Feb 2006" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +mkstemp, mkstemps, mkdtemp \- make a unique file name from a template and open +the file +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBint\fR \fBmkstemp\fR(\fBchar *\fR\fItemplate\fR); +.fi + +.LP +.nf +\fBint\fR \fBmkstemps\fR(\fBchar *\fR\fItemplate\fR, \fBint\fR \fIslen\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBmkdtemp\fR(\fBchar *\fR\fItemplate\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBmkstemp()\fR function replaces the contents of the string pointed to by +\fItemplate\fR by a unique file name, and returns a file descriptor for the +file open for reading and writing. The function thus prevents any possible race +condition between testing whether the file exists and opening it for use. The +string in \fItemplate\fR should look like a file name with six trailing 'X's; +\fBmkstemp()\fR replaces each 'X' with a character from the portable file name +character set. The characters are chosen such that the resulting name does not +duplicate the name of an existing file. +.sp +.LP +The \fBmkstemps()\fR function behaves the same as \fBmkstemp()\fR, except it +permits a suffix to exist in the template. The template should be of the form +/\fBtmp\fR/\fBtmp\fR\fIXXXXXX\fR\fIsuffix\fR. The \fIslen\fR parameter +specifies the length of the suffix string. +.sp +.LP +The \fBmkdtemp()\fR function makes the same replacement to the template as in +\fBmktemp\fR(3C) and creates the template directory using \fBmkdir\fR(2), +passing a \fImode\fR argument of 0700. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBmkstemp()\fR returns an open file descriptor. +Otherwise \(mi1 is returned if no suitable file could be created. +.SH ERRORS +.sp +.LP +The \fBmkstemp()\fR, \fBmkstemps()\fR, and \fBmkdtemp()\fR functions can set +\fBerrno\fR to the same values as \fBlstat\fR(2). +.sp +.LP +The \fBmkstemp()\fR and \fBmkstemps()\fR functions can set \fBerrno\fR to the +same values as \fBopen\fR(2). +.sp +.LP +The \fBmkdtemp()\fR function can set \fBerrno\fR to the same values as +\fBmkdir\fR(2). +.SH USAGE +.sp +.LP +It is possible to run out of letters. +.sp +.LP +The \fBmkstemp()\fR function does not check to determine whether the file name +part of \fItemplate\fR exceeds the maximum allowable file name length. +.sp +.LP +The \fBtmpfile\fR(3C) function is preferred over this function. +.sp +.LP +The \fBmkstemp()\fR function is frequently used to create a temporary file that +will be removed by the application before the application terminates. +.sp +.LP +The \fBmkstemp()\fR function has a transitional interface for 64-bit file +offsets. See \fBlf64\fR(5). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilitySee below. +.TE + +.sp +.LP +The \fBmkstemp()\fR function is Standard. The \fBmkstemps()\fR and +\fBmkdtemp()\fR functions are Stable. +.SH SEE ALSO +.sp +.LP +\fBgetpid\fR(2), \fBlstat\fR(2), \fBmkdir\fR(2), \fBopen\fR(2), +\fBtmpfile\fR(3C), \fBmktemp\fR(3C), \fBattributes\fR(5), \fBlf64\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/mktemp.3c b/usr/src/man/man3c/mktemp.3c new file mode 100644 index 0000000000..e81ee5f33f --- /dev/null +++ b/usr/src/man/man3c/mktemp.3c @@ -0,0 +1,90 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH mktemp 3C "15 Sep 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +mktemp \- make a unique file name from a template +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBchar *\fR\fBmktemp\fR(\fBchar *\fR\fItemplate\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBmktemp()\fR function replaces the contents of the string pointed to by +\fItemplate\fR with a unique file name, and returns \fItemplate\fR. The string +in \fItemplate\fR should look like a file name with six trailing 'X's; +\fBmktemp()\fR will replace the 'X's with a character string that can be used +to create a unique file name. Only 26 unique file names per thread can be +created for each unique \fItemplate\fR. +.SH RETURN VALUES +.sp +.LP +The \fBmktemp()\fR function returns the pointer \fItemplate\fR. If a unique +name cannot be created, \fItemplate\fR points to a null string. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH EXAMPLES +.LP +\fBExample 1 \fRGenerate a filename. +.sp +.LP +The following example replaces the contents of the "template" string with a +10-character filename beginning with the characters "file" and returns a +pointer to the "template" string that contains the new filename. + +.sp +.in +2 +.nf +#include <stdlib.h> +\&... +char *template = "/tmp/fileXXXXXX"; +char *ptr; +ptr = mktemp(template); +.fi +.in -2 + +.SH USAGE +.sp +.LP +Between the time a pathname is created and the file opened, it is possible for +some other process to create a file with the same name. The \fBmkstemp\fR(3C) +function avoids this problem and is preferred over this function. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBmkstemp\fR(3C), \fBtmpfile\fR(3C), \fBtmpnam\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/mktime.3c b/usr/src/man/man3c/mktime.3c new file mode 100644 index 0000000000..f03d243f09 --- /dev/null +++ b/usr/src/man/man3c/mktime.3c @@ -0,0 +1,187 @@ +'\" te +.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH mktime 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +mktime \- converts a tm structure to a calendar time +.SH SYNOPSIS +.LP +.nf +#include <time.h> + +\fBtime_t\fR \fBmktime\fR(\fBstruct tm *\fR\fItimeptr\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBmktime()\fR function converts the time represented by the \fBtm\fR +structure pointed to by \fItimeptr\fR into a calendar time (the number of +seconds since 00:00:00 UTC, January 1, 1970). +.sp +.LP +The \fBtm\fR structure contains the following members: +.sp +.in +2 +.nf +int tm_sec; /* seconds after the minute [0, 60] */ +int tm_min; /* minutes after the hour [0, 59] */ +int tm_hour; /* hour since midnight [0, 23] */ +int tm_mday; /* day of the month [1, 31] */ +int tm_mon; /* months since January [0, 11] */ +int tm_year; /* years since 1900 */ +int tm_wday; /* days since Sunday [0, 6] */ +int tm_yday; /* days since January 1 [0, 365] */ +int tm_isdst; /* flag for daylight savings time */ +.fi +.in -2 + +.sp +.LP +In addition to computing the calendar time, \fBmktime()\fR normalizes the +supplied \fBtm\fR structure. The original values of the \fBtm_wday\fR and +\fBtm_yday\fR components of the structure are ignored, and the original values +of the other components are not restricted to the ranges indicated in the +definition of the structure. On successful completion, the values of the +\fBtm_wday\fR and \fBtm_yday\fR components are set appropriately, and the other +components are set to represent the specified calendar time, but with their +values forced to be within the appropriate ranges. The final value of +\fBtm_mday\fR is not set until \fBtm_mon\fR and \fBtm_year\fR are determined. +.sp +.LP +The \fBtm_year\fR member must be for year 1901 or later. Calendar times before +20:45:52 UTC, December 13, 1901 or after 03:14:07 UTC, January 19, 2038 cannot +be represented. Portable applications should not try to create dates before +00:00:00 UTC, January 1, 1970 or after 00:00:00 UTC, January 1, 2038. +.sp +.LP +The original values of the components may be either greater than or less than +the specified range. For example, a \fBtm_hour\fR of \(mi1 means 1 hour before +midnight, \fBtm_mday\fR of 0 means the day preceding the current month, and +\fBtm_mon\fR of \(mi2 means 2 months before January of \fBtm_year\fR. +.sp +.LP +If \fBtm_isdst\fR is positive, the original values are assumed to be in the +alternate timezone. If it turns out that the alternate timezone is not valid +for the computed calendar time, then the components are adjusted to the main +timezone. Likewise, if \fBtm_isdst\fR is zero, the original values are assumed +to be in the main timezone and are converted to the alternate timezone if the +main timezone is not valid. If \fBtm_isdst\fR is negative, \fBmktime()\fR +attempts to determine whether the alternate timezone is in effect for the +specified time. +.sp +.LP +Local timezone information is used as if \fBmktime()\fR had called +\fBtzset()\fR. See \fBctime\fR(3C). +.SH RETURN VALUES +.sp +.LP +If the calendar time can be represented in an object of type \fBtime_t\fR, +\fBmktime()\fR returns the specified calendar time without changing +\fBerrno\fR. If the calendar time cannot be represented, the function returns +the value (\fBtime_t\fR)\(mi1 and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBmktime()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEOVERFLOW\fR\fR +.ad +.RS 13n +.rt +The date represented by the input \fBtm\fR struct cannot be represented in a +\fBtime_t\fR. Note that the \fBerrno\fR setting may change if future revisions +to the standards specify a different value. +.RE + +.SH USAGE +.sp +.LP +The \fBmktime()\fR function is MT-Safe in multithreaded applications, as long +as no user-defined function directly modifies one of the following variables: +\fBtimezone\fR, \fBaltzone\fR, \fBdaylight\fR, and \fBtzname\fR. See +\fBctime\fR(3C). +.sp +.LP +Note that \(mi1 can be a valid return value for the time that is one second +before the Epoch. The user should clear \fBerrno\fR before calling +\fBmktime()\fR. If \fBmktime()\fR then returns \(mi1, the user should check +\fBerrno\fR to determine whether or not an error actually occurred. +.sp +.LP +The \fBmktime()\fR function assumes Gregorian dates. Times before the adoption +of the Gregorian calendar will not match historial records. +.SH EXAMPLES +.LP +\fBExample 1 \fRSample code using \fBmktime()\fR. +.sp +.LP +What day of the week is July 4, 2001? + +.sp +.in +2 +.nf +#include <stdio.h> +#include <time.h> +static char *const wday[\|] = { + "Sunday", "Monday", "Tuesday", "Wednesday", + "Thursday", "Friday", "Saturday", "-unknown-" +}; +struct tm time_str; +/*\|.\|.\|.*/ +time_str.tm_year = 2001 - 1900; +time_str.tm_mon = 7 - 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)== \(mi1) + time_str.tm_wday=7; +printf("%s\en", wday[time_str.tm_wday]); +.fi +.in -2 + +.SH BUGS +.sp +.LP +The \fBzoneinfo\fR timezone data files do not transition past Tue Jan 19 +03:14:07 2038 UTC. Therefore for 64-bit applications using \fBzoneinfo\fR +timezones, calculations beyond this date may not use the correct offset from +standard time, and could return incorrect values. This affects the 64-bit +version of \fBmktime()\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBctime\fR(3C), \fBgetenv\fR(3C), \fBTIMEZONE\fR(4), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/mlock.3c b/usr/src/man/man3c/mlock.3c new file mode 100644 index 0000000000..3677e4928e --- /dev/null +++ b/usr/src/man/man3c/mlock.3c @@ -0,0 +1,180 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH mlock 3C "10 Apr 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +mlock, munlock \- lock or unlock pages in memory +.SH SYNOPSIS +.LP +.nf +#include <sys/mman.h> + +\fBint\fR \fBmlock\fR(\fBcaddr_t\fR \fIaddr\fR, \fBsize_t\fR \fIlen\fR); +.fi + +.LP +.nf +\fBint\fR \fBmunlock\fR(\fBcaddr_t\fR \fIaddr\fR, \fBsize_t\fR \fIlen\fR); +.fi + +.SS "Standard conforming" +.LP +.nf +#include <sys/mman.h> + +\fBint\fR \fBmlock\fR(\fBconst void *\fR \fIaddr\fR, \fBsize_t\fR \fIlen\fR); +.fi + +.LP +.nf +\fBint\fR \fBmunlock\fR(\fBconst void *\fR \fIaddr\fR, \fBsize_t\fR \fIlen\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBmlock()\fR function uses the mappings established for the address range +[\fIaddr, addr + len\fR) to identify pages to be locked in memory. If the page +identified by a mapping changes, such as occurs when a copy of a writable +\fBMAP_PRIVATE\fR page is made upon the first store, the lock will be +transferred to the newly copied private page. +.sp +.LP +The \fBmunlock()\fR function removes locks established with \fBmlock()\fR. +.sp +.LP +A given page may be locked multiple times by executing an \fBmlock()\fR through +different mappings. That is, if two different processes lock the same page, +then the page will remain locked until both processes remove their locks. +However, within a given mapping, page locks do not nest \(mi multiple +\fBmlock()\fR operations on the same address in the same process will all be +removed with a single \fBmunlock()\fR. Of course, a page locked in one process +and mapped in another (or visible through a different mapping in the locking +process) is still locked in memory. This fact can be used to create +applications that do nothing other than lock important data in memory, thereby +avoiding page I/O faults on references from other processes in the system. +.sp +.LP +The contents of the locked pages will not be transferred to or from disk except +when explicitly requested by one of the locking processes. This guarantee +applies only to the mapped data, and not to any associated data structures +(file descriptors and on-disk metadata, among others). +.sp +.LP +If the mapping through which an \fBmlock()\fR has been performed is removed, an +\fBmunlock()\fR is implicitly performed. An \fBmunlock()\fR is also performed +implicitly when a page is deleted through file removal or truncation. +.sp +.LP +Locks established with \fBmlock()\fR are not inherited by a child process after +a \fBfork()\fR and are not nested. +.sp +.LP +Attempts to \fBmlock()\fR more memory than a system-specific limit will fail. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBmlock()\fR and \fBmunlock()\fR functions +return \fB0\fR. Otherwise, no changes are made to any locks in the address +space of the process, the functions return \fB\(mi1\fR and set \fBerrno\fR to +indicate the error. +.SH ERRORS +.sp +.LP +The \fBmlock()\fR and \fBmunlock()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIaddr\fR argument is not a multiple of the page size as returned by +\fBsysconf\fR(3C). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Addresses in the range [\fIaddr, addr + len\fR) are invalid for the address +space of a process, or specify one or more pages which are not mapped. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR\fR +.ad +.RS 10n +.rt +The system does not support this memory locking interface. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 10n +.rt +The {\fBPRIV_PROC_LOCK_MEMORY\fR} privilege is not asserted in the effective +set of the calling process. +.RE + +.sp +.LP +The \fBmlock()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +Some or all of the memory identified by the range [\fIaddr, addr + len\fR) +could not be locked because of insufficient system resources or because of a +limit or resource control on locked memory. +.RE + +.SH USAGE +.sp +.LP +Because of the impact on system resources, the use of \fBmlock()\fR and +\fBmunlock()\fR is restricted to users with the {\fBPRIV_PROC_LOCK_MEMORY\fR} +privilege. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfork\fR(2), \fBmemcntl\fR(2), \fBmmap\fR(2), \fBplock\fR(3C), +\fBmlockall\fR(3C), \fBsysconf\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/mlockall.3c b/usr/src/man/man3c/mlockall.3c new file mode 100644 index 0000000000..6b7e33eece --- /dev/null +++ b/usr/src/man/man3c/mlockall.3c @@ -0,0 +1,131 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH mlockall 3C "22 Mar 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +mlockall, munlockall \- lock or unlock address space +.SH SYNOPSIS +.LP +.nf +#include <sys/mman.h> + +\fBint\fR \fBmlockall\fR(\fBint\fR \fIflags\fR); +.fi + +.LP +.nf +\fBint\fR \fBmunlockall\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBmlockall()\fR function locks in memory all pages mapped by an address +space. +.sp +.LP +The value of \fIflags\fR determines whether the pages to be locked are those +currently mapped by the address space, those that will be mapped in the future, +or both: +.sp +.in +2 +.nf + \fBMCL_CURRENT\fR Lock current mappings + \fBMCL_FUTURE\fR Lock future mappings +.fi +.in -2 + +.sp +.LP +If \fBMCL_FUTURE\fR is specified for \fBmlockall()\fR, mappings are locked as +they are added to the address space (or replace existing mappings), provided +sufficient memory is available. Locking in this manner is not persistent across +the \fBexec\fR family of functions (see \fBexec\fR(2)). +.sp +.LP +Mappings locked using \fBmlockall()\fR with any option may be explicitly +unlocked with a \fBmunlock()\fR call (see \fBmlock\fR(3C)). +.sp +.LP +The \fBmunlockall()\fR function removes address space locks and locks on +mappings in the address space. +.sp +.LP +All conditions and constraints on the use of locked memory that apply to +\fBmlock\fR(3C) also apply to \fBmlockall()\fR. +.sp +.LP +Locks established with \fBmlockall()\fR are not inherited by a child process +after a \fBfork\fR(2) call, and are not nested. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBmlockall()\fR and \fBmunlockall()\fR +functions return \fB0\fR. Otherwise, they return \fB\(mi1\fR and set +\fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBmlockall()\fR and \fBmunlockall()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +Some or all of the memory in the address space could not be locked due to +sufficient resources. This error condition applies to \fBmlockall()\fR only. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIflags\fR argument contains values other than \fBMCL_CURRENT\fR and +\fBMCL_FUTURE\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 10n +.rt +The {\fBPRIV_PROC_LOCK_MEMORY\fR} privilege is not asserted in the effective +set of the calling process. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBexec\fR(2), \fBfork\fR(2), \fBmemcntl\fR(2), \fBmmap\fR(2), \fBplock\fR(3C), +\fBmlock\fR(3C), \fBsysconf\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/monitor.3c b/usr/src/man/man3c/monitor.3c new file mode 100644 index 0000000000..8b012d683a --- /dev/null +++ b/usr/src/man/man3c/monitor.3c @@ -0,0 +1,205 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH monitor 3C "29 Dec 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +monitor \- prepare process execution profile +.SH SYNOPSIS +.LP +.nf +#include <mon.h> + +\fBvoid\fR \fBmonitor\fR(\fBint (*\fR\fIlowpc\fR(), \fBint (*\fR\fIhighpc\fR)(), \fBWORD *\fR\fIbuffer\fR, \fBsize_t\fR \fIbufsize\fR, + \fBsize_t\fR \fInfunc\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBmonitor()\fR function is an interface to the \fBprofil\fR(2) function +and is called automatically with default parameters by any program created by +the \fBcc\fR utility with the \fB-p\fR option specified. Except to establish +further control over profiling activity, it is not necessary to explicitly call +\fBmonitor()\fR. +.sp +.LP +When used, \fBmonitor()\fR is called at least at the beginning and the end of a +program. The first call to \fBmonitor()\fR initiates the recording of two +different kinds of execution-profile information: execution-time distribution +and function call count. Execution-time distribution data is generated by +\fBprofil()\fR and the function call counts are generated by code supplied to +the object file (or files) by \fBcc\fR \fB-p.\fR Both types of information are +collected as a program executes. The last call to \fBmonitor()\fR writes this +collected data to the output file \fBmon.out\fR. +.sp +.LP +The name of the file written by \fBmonitor()\fR is controlled by the +environment variable \fBPROFDIR\fR. If \fBPROFDIR\fR does not exist, the file +\fBmon.out\fR is created in the current directory. If \fBPROFDIR\fR exists but +has no value, \fBmonitor()\fR does no profiling and creates no output file. If +\fBPROFDIR\fR is \fBdirname\fR, and \fBmonitor()\fR is called automatically by +compilation with \fBcc \fR\fB-p\fR, the file created is +\fBdirname\fR\fB/\fR\fIpid.progname\fR where \fIprogname\fR is the name of the +program. +.sp +.LP +The \fIlowpc\fR and \fIhighpc\fR arguments are the beginning and ending +addresses of the region to be profiled. +.sp +.LP +The \fIbuffer\fR argument is the address of a user-supplied array of \fBWORD\fR +(defined in the header \fB<mon.h>\fR). The \fIbuffer\fR argument is used by +\fBmonitor()\fR to store the histogram generated by \fBprofil()\fR and the call +counts. +.sp +.LP +The \fIbufsize\fR argument identifies the number of array elements in +\fIbuffer\fR. +.sp +.LP +The \fInfunc\fR argument is the number of call count cells that have been +reserved in \fIbuffer\fR. Additional call count cells will be allocated +automatically as they are needed. +.sp +.LP +The \fIbufsize\fR argument should be computed using the following formula: +.sp +.in +2 +.nf +size_of_buffer = + sizeof(struct hdr) + + \fInfunc\fR * sizeof(struct cnt) + + ((\fIhighpc\fR-\fIlowpc\fR)/\fIBARSIZE\fR) * sizeof(WORD) + + sizeof(WORD) \(mi 1 ; +bufsize = (size_of_buffer / sizeof(WORD)); +.fi +.in -2 + +.sp +.LP +where: +.RS +4 +.TP +.ie t \(bu +.el o +\fIlowpc\fR, \fIhighpc\fR, \fInfunc\fR are the same as the arguments to +\fBmonitor()\fR; +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fIBARSIZE\fR is the number of program bytes that correspond to each histogram +bar, or cell, of the \fBprofil()\fR buffer; +.RE +.RS +4 +.TP +.ie t \(bu +.el o +the \fBhdr\fR and \fBcnt\fR structures and the type \fBWORD\fR are defined in +the header \fB<mon.h>\fR\&. +.RE +.sp +.LP +The default call to \fBmonitor()\fR is as follows: +.sp +.in +2 +.nf +monitor (&eprol, &etext, wbuf, wbufsz, 600); +.fi +.in -2 + +.sp +.LP +where: +.RS +4 +.TP +.ie t \(bu +.el o +\fBeprol\fR is the beginning of the user's program when linked with \fBcc +\fR\fB-p\fR (see \fBend\fR(3C)); +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBetext\fR is the end of the user's program (see \fBend\fR(3C)); +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBwbuf\fR is an array of \fBWORD\fR with \fIwbufsz\fR elements; +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBwbufsz\fR is computed using the \fIbufsize\fR formula shown above with +\fIBARSIZE\fR of 8; +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fB600\fR is the number of call count cells that have been reserved in +\fIbuffer\fR. +.RE +.sp +.LP +These parameter settings establish the computation of an execution-time +distribution histogram that uses \fBprofil()\fR for the entire program, +initially reserves room for 600 call count cells in \fIbuffer\fR, and provides +for enough histogram cells to generate significant distribution-measurement +results. For more information on the effects of \fIbufsize\fR on +execution-distribution measurements, see \fBprofil\fR(2). +.SH EXAMPLES +.LP +\fBExample 1 \fRExample to stop execution monitoring and write the results to a +file. +.sp +.LP +To stop execution monitoring and write the results to a file, use the +following: + +.sp +.in +2 +.nf +monitor(\|(int (*)(\|)\|)0, (int (*)(\|)\|)0, (WORD *)0, 0, 0); +.fi +.in -2 + +.sp +.LP +Use \fBprof\fR to examine the results. + +.SH USAGE +.sp +.LP +Additional calls to \fBmonitor()\fR after \fBmain()\fR has been called and +before \fBexit()\fR has been called will add to the function-call count +capacity, but such calls will also replace and restart the \fBprofil()\fR +histogram computation. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBprofil\fR(2), \fBend\fR(3C), \fBattributes\fR(5), \fBprof\fR(5) diff --git a/usr/src/man/man3c/mq_close.3c b/usr/src/man/man3c/mq_close.3c new file mode 100644 index 0000000000..07c9c3c88b --- /dev/null +++ b/usr/src/man/man3c/mq_close.3c @@ -0,0 +1,99 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH mq_close 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +mq_close \- close a message queue +.SH SYNOPSIS +.LP +.nf +#include <mqueue.h> + +\fBint\fR \fBmq_close\fR(\fBmqd_t\fR \fImqdes\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBmq_close()\fR function removes the association between the message queue +descriptor, \fImqdes\fR, and its message queue. The results of using this +message queue descriptor after successful return from this \fBmq_close()\fR, +and until the return of this message queue descriptor from a subsequent +\fBmq_open\fR(3C), are undefined. +.sp +.LP +If the process (or thread) has successfully attached a notification request to +the message queue via this \fImqdes\fR, this attachment is removed and the +message queue is available for another process to attach for notification. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBmq_close()\fR returns \fB0\fR; otherwise, the +function returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the error +condition. +.SH ERRORS +.sp +.LP +The \fBmq_close()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR \fR +.ad +.RS 11n +.rt +The \fImqdes\fR argument is an invalid message queue descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR \fR +.ad +.RS 11n +.rt +The \fBmq_open()\fR function is not supported by the system. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBmqueue.h\fR(3HEAD), \fBmq_notify\fR(3C), \fBmq_open\fR(3C), +\fBmq_unlink\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +Solaris 2.6 was the first release to support the Asynchronous Input and Output +option. Prior to this release, this function always returned \fB\(mi1\fR and +set \fBerrno\fR to \fBENOSYS\fR. diff --git a/usr/src/man/man3c/mq_getattr.3c b/usr/src/man/man3c/mq_getattr.3c new file mode 100644 index 0000000000..c38489881e --- /dev/null +++ b/usr/src/man/man3c/mq_getattr.3c @@ -0,0 +1,147 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH mq_getattr 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +mq_getattr \- get message queue attributes +.SH SYNOPSIS +.LP +.nf +#include <mqueue.h> + +\fBint\fR \fBmq_getattr\fR(\fBmqd_t\fR \fImqdes\fR, \fBstruct mq_attr *\fR\fImqstat\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fImqdes\fR argument specifies a message queue descriptor. The +\fBmq_getattr()\fR function is used to get status information and attributes of +the message queue and the open message queue description associated with the +message queue descriptor. The results are returned in the \fImq_attr\fR +structure referenced by the \fImqstat\fR argument. +.sp +.LP +Upon return, the following members will have the values associated with the +open message queue description as set when the message queue was opened and as +modified by subsequent \fBmq_setattr\fR(3C) calls: +.sp +.ne 2 +.mk +.na +\fB\fBmq_flags\fR\fR +.ad +.RS 12n +.rt +message queue flags +.RE + +.sp +.LP +The following attributes of the message queue are returned as set at message +queue creation: +.sp +.ne 2 +.mk +.na +\fB\fBmq_maxmsg\fR\fR +.ad +.RS 14n +.rt +maximum number of messages +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBmq_msgsize\fR\fR +.ad +.RS 14n +.rt +maximum message size +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBmq_curmsgs\fR\fR +.ad +.RS 14n +.rt +number of messages currently on the queue. +.RE + +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBmq_getattr()\fR function returns \fB0\fR. +Otherwise, the function returns \fB\(mi1\fR and sets \fBerrno\fR to indicate +the error. +.SH ERRORS +.sp +.LP +The \fBmq_getattr()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fImqdes\fR argument is not a valid message queue descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR\fR +.ad +.RS 10n +.rt +The \fBmq_getattr()\fR function is not supported by the system. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBmsgctl\fR(2), \fBmsgget\fR(2), \fBmsgrcv\fR(2), \fBmsgsnd\fR(2), +\fBmqueue.h\fR(3HEAD), \fBmq_open\fR(3C), \fBmq_send\fR(3C), +\fBmq_setattr\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +Solaris 2.6 was the first release to support the Asynchronous Input and Output +option. Prior to this release, this function always returned \fB\(mi1\fR and +set \fBerrno\fR to \fBENOSYS\fR. diff --git a/usr/src/man/man3c/mq_notify.3c b/usr/src/man/man3c/mq_notify.3c new file mode 100644 index 0000000000..76690e4e02 --- /dev/null +++ b/usr/src/man/man3c/mq_notify.3c @@ -0,0 +1,119 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH mq_notify 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +mq_notify \- notify process (or thread) that a message is available on a queue +.SH SYNOPSIS +.LP +.nf +#include <mqueue.h> + +\fBint\fR \fBmq_notify\fR(\fBmqd_t\fR \fImqdes\fR, \fBconst struct sigevent *\fR\fInotification\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBmq_notify()\fR function provides an asynchronous mechanism for processes +to receive notice that messages are available in a message queue, rather than +synchronously blocking (waiting) in \fBmq_receive\fR(3C). +.sp +.LP +If \fInotification\fR is not \fINULL\fR, this function registers the calling +process to be notified of message arrival at an empty message queue associated +with the message queue descriptor, \fImqdes\fR. The notification specified by +\fInotification\fR will be sent to the process when the message queue +transitions from empty to non-empty. See \fBsignal.h\fR(3HEAD). At any time, +only one process may be registered for notification by a specific message +queue. If the calling process or any other process has already registered for +notification of message arrival at the specified message queue, subsequent +attempts to register for that message queue will fail. +.sp +.LP +If \fInotification\fR is \fINULL\fR and the process is currently registered for +notification by the specified message queue, the existing registration is +removed. The message queue is then available for future registration. +.sp +.LP +When the notification is sent to the registered process, its registration is +removed. The message queue is then available for registration. +.sp +.LP +If a process has registered for notification of message arrival at a message +queue and some processes is blocked in \fBmq_receive\fR(3C) waiting to receive +a message when a message arrives at the queue, the arriving message will be +received by the appropriate \fBmq_receive\fR(3C), and no notification will be +sent to the registered process. The resulting behavior is as if the message +queue remains empty, and this notification will not be sent until the next +arrival of a message at this queue. +.sp +.LP +Any notification registration is removed if the calling process either closes +the message queue or exits. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBmq_notify()\fR returns \fB0\fR; otherwise, it +returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBmq_notify()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 9n +.rt +The \fImqdes\fR argument is not a valid message queue descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBUSY\fR\fR +.ad +.RS 9n +.rt +A process is already registered for notification by the message queue. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBmq_close\fR(3C), \fBmq_open\fR(3C), \fBmq_receive\fR(3C), \fBmq_send\fR(3C), +\fBmqueue.h\fR(3HEAD), \fBsiginfo.h\fR(3HEAD), \fBsignal.h\fR(3HEAD), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/mq_open.3c b/usr/src/man/man3c/mq_open.3c new file mode 100644 index 0000000000..e86ee7a898 --- /dev/null +++ b/usr/src/man/man3c/mq_open.3c @@ -0,0 +1,327 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH mq_open 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +mq_open \- open a message queue +.SH SYNOPSIS +.LP +.nf +#include <mqueue.h> + +\fBmqd_t\fR \fBmq_open\fR(\fBconst char *\fR\fIname\fR, \fBint\fR \fIoflag\fR, + \fB/* unsigned long\fR \fImode\fR, \fBmq_attr\fR \fIattr\fR */ ...); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBmq_open()\fR function establishes the connection between a process and a +message queue with a message queue descriptor. It creates a 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. +.sp +.LP +The \fIname\fR argument points to a string naming a message queue. The +\fIname\fR argument must conform to the construction rules for a path-name. If +\fIname\fR is not the name of an existing message queue and its creation is not +requested, \fBmq_open()\fR fails and returns an error. The first character of +\fIname\fR must be a slash (\fB/\fR) character and the remaining characters of +\fIname\fR cannot include any slash characters. For maximum portability, +\fIname\fR should include no more than 14 characters, but this limit is not +enforced. +.sp +.LP +The \fIoflag\fR argument requests the desired receive and/or send access to the +message queue. The requested access permission to receive messages or send +messages is granted if the calling process would be granted read or write +access, respectively, to a file with the equivalent permissions. +.sp +.LP +The value of \fIoflag\fR is the bitwise inclusive \fBOR\fR of values from the +following list. Applications must specify exactly one of the first three values +(access modes) below in the value of \fIoflag\fR: +.sp +.ne 2 +.mk +.na +\fB\fBO_RDONLY\fR \fR +.ad +.RS 13n +.rt +Open the message queue for receiving messages. The process can use the returned +message queue descriptor with \fBmq_receive\fR(3C), but not \fBmq_send\fR(3C). +A message queue may be open multiple times in the same or different processes +for receiving messages. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBO_WRONLY\fR \fR +.ad +.RS 13n +.rt +Open the queue for sending messages. The process can use the returned message +queue descriptor with \fBmq_send\fR(3C) but not \fBmq_receive\fR(3C). A message +queue may be open multiple times in the same or different processes for sending +messages. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBO_RDWR\fR \fR +.ad +.RS 13n +.rt +Open the queue for both receiving and sending messages. The process can use any +of the functions allowed for \fBO_RDONLY\fR and \fBO_WRONLY\fR. A message queue +may be open multiple times in the same or different processes for sending +messages. +.RE + +.sp +.LP +Any combination of the remaining flags may additionally be specified in the +value of \fIoflag\fR: +.sp +.ne 2 +.mk +.na +\fB\fBO_CREAT\fR \fR +.ad +.RS 15n +.rt +This option is used to create a message queue, and it requires two additional +arguments: \fImode\fR, which is of type \fBmode_t\fR, and \fIattr\fR, which is +pointer to a \fBmq_attr\fR structure. If the pathname, \fIname\fR, has already +been used to create a message queue that still exists, then this flag has no +effect, except as noted under \fBO_EXCL\fR (see below). Otherwise, a message +queue is created without any messages in it. +.sp +The user ID of the message queue is set to the effective user ID of process, +and the group ID of the message queue is set to the effective group ID of the +process. The file permission bits are set to the value of \fImode\fR, and +modified by clearing all bits set in the file mode creation mask of the process +(see \fBumask\fR(2)). +.sp +If \fIattr\fR is non-\fINULL\fR and the calling process has the appropriate +privilege on \fIname\fR, the message queue \fImq_maxmsg\fR and \fImq_msgsize\fR +attributes are set to the values of the corresponding members in the +\fBmq_attr\fR structure referred to by \fIattr\fR. If \fIattr\fR is +non-\fINULL\fR, but the calling process does not have the appropriate privilege +on \fIname\fR, the \fBmq_open()\fR function fails and returns an error without +creating the message queue. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBO_EXCL\fR \fR +.ad +.RS 15n +.rt +If both \fBO_EXCL\fR and \fBO_CREAT\fR are set, \fBmq_open()\fR will fail if +the message queue \fIname\fR exists. The check for the existence of the message +queue and the creation of the message queue if it does not exist are atomic +with respect to other processes executing \fBmq_open()\fR naming the same +\fIname\fR with both \fBO_EXCL\fR and \fBO_CREAT\fR set. If \fBO_EXCL\fR and +\fBO_CREAT\fR are not set, the result is undefined. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBO_NONBLOCK\fR \fR +.ad +.RS 15n +.rt +The setting of this flag is associated with the open message queue description +and determines whether a \fBmq_send\fR(3C) or \fBmq_receive\fR(3C) waits for +resources or messages that are not currently available, or fails with +\fBerrno\fR set to \fBEAGAIN\fR. See \fBmq_send\fR(3C) and \fBmq_receive\fR(3C) +for details. +.RE + +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBmq_open()\fR returns a message queue descriptor; +otherwise the function returns \fB(mqd_t)\(mi1\fR and sets \fBerrno\fR to +indicate the error condition. +.SH ERRORS +.sp +.LP +The \fBmq_open()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR \fR +.ad +.RS 17n +.rt +The message queue exists and the permissions specified by \fIoflag\fR are +denied, or the message queue does not exist and permission to create the +message queue is denied. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEEXIST\fR \fR +.ad +.RS 17n +.rt +\fBO_CREAT\fR and \fBO_EXCL\fR are set and the named message queue already +exists. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR \fR +.ad +.RS 17n +.rt +The \fBmq_open()\fR operation was interrupted by a signal. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR \fR +.ad +.RS 17n +.rt +The \fBmq_open()\fR operation is not supported for the given name, or +\fBO_CREAT\fR was specified in \fIoflag\fR, the value of \fIattr\fR is not +\fINULL,\fR and either \fBmq_maxmsg\fR or \fBmq_msgsize\fR was less than or +equal to zero. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR \fR +.ad +.RS 17n +.rt +The number of open message queue descriptors in this process exceeds +\fBMQ_OPEN_MAX,\fR of the number of open file descriptors in this process +exceeds \fBOPEN_MAX.\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR \fR +.ad +.RS 17n +.rt +The length of the \fIname\fR string exceeds \fBPATH_MAX,\fR or a pathname +component is longer than \fINAME_MAX\fR while \fB_POSIX_NO_TRUNC\fR is in +effect. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENFILE\fR \fR +.ad +.RS 17n +.rt +Too many message queues are currently open in the system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR \fR +.ad +.RS 17n +.rt +\fBO_CREAT\fR is not set and the named message queue does not exist. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSPC\fR \fR +.ad +.RS 17n +.rt +There is insufficient space for the creation of the new message queue. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR \fR +.ad +.RS 17n +.rt +The \fBmq_open()\fR function is not supported by the system. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBexec\fR(2), \fBexit\fR(2), \fBumask\fR(2), \fBsysconf\fR(3C), +\fBmqueue.h\fR(3HEAD), \fBmq_close\fR(3C), \fBmq_receive\fR(3C), +\fBmq_send\fR(3C), \fBmq_setattr\fR(3C), \fBmq_unlink\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +Due to the manner in which message queues are implemented, they should not be +considered secure and should not be used in security-sensitive applications. +.sp +.LP +Solaris 2.6 was the first release to support the Asynchronous Input and Output +option. Prior to this release, this function always returned \fB\(mi1\fR and +set \fBerrno\fR to \fBENOSYS\fR. diff --git a/usr/src/man/man3c/mq_receive.3c b/usr/src/man/man3c/mq_receive.3c new file mode 100644 index 0000000000..3d244806ea --- /dev/null +++ b/usr/src/man/man3c/mq_receive.3c @@ -0,0 +1,237 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH mq_receive 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +mq_receive, mq_timedreceive, mq_reltimedreceive_np \- receive a message from a +message queue +.SH SYNOPSIS +.LP +.nf +#include <mqueue.h> + +\fBssize_t\fR \fBmq_receive\fR(\fBmqd_t\fR \fImqdes\fR, \fBchar *\fR\fImsg_ptr\fR, \fBsize_t\fR \fImsg_len\fR, + \fBunsigned *\fR\fImsg_prio\fR); +.fi + +.LP +.nf +#include <mqueue.h> +#include <time.h> + +\fBssize_t\fR \fBmq_timedreceive\fR(\fBmqd_t\fR \fImqdes\fR, \fBchar *restrict\fR \fImsg_ptr\fR, + \fBsize_t\fR \fImsg_len\fR, \fBunsigned *restrict\fR \fImsg_prio\fR, + \fBconst struct timespec *restrict\fR \fIabs_timeout\fR); +.fi + +.LP +.nf +\fBssize_t\fR \fBmq_reltimedreceive_np\fR(\fBmqd_t\fR \fImqdes\fR, + \fBchar *restrict\fR \fImsg_ptr\fR, \fBsize_t\fR \fImsg_len\fR, + \fBunsigned *restrict\fR \fImsg_prio\fR, + \fBconst struct timespec *restrict\fR \fIrel_timeout\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBmq_receive()\fR function receives the oldest of the highest priority +message(s) from the message queue specified by \fImqdes\fR. If the size of the +buffer in bytes, specified by \fImsg_len\fR, is less than the \fBmq_msgsize\fR +member of the message queue, the function fails and returns an error. +Otherwise, the selected message is removed from the queue and copied to the +buffer pointed to by \fImsg_ptr\fR. +.sp +.LP +If the value of \fImsg_len\fR is greater than {\fBSSIZE_MAX\fR}, the result is +implementation-defined. +.sp +.LP +If \fImsg_prio\fR is not \fINULL\fR, the priority of the selected message is +stored in the location referenced by \fImsg_prio\fR. +.sp +.LP +If the specified message queue is empty and \fBO_NONBLOCK\fR is not set in the +message queue description associated with \fImqdes\fR, (see \fBmq_open\fR(3C) +and \fBmq_setattr\fR(3C)), \fBmq_receive()\fR blocks, waiting until a message +is enqueued on the message queue, or until \fBmq_receive()\fR is interrupted by +a signal. If more than one process (or thread) is waiting to receive a message +when a message arrives at an empty queue, then the process of highest priority +that has been waiting the longest is selected to receive the message. If the +specified message queue is empty and \fBO_NONBLOCK\fR is set in the message +queue description associated with \fImqdes\fR, no message is removed from the +queue, and \fBmq_receive()\fR returns an error. +.sp +.LP +The \fBmq_timedreceive()\fR function receives the oldest of the highest +priority messages from the message queue specified by \fImqdes\fR as described +for the \fBmq_receive()\fR function. However, if \fBO_NONBLOCK\fR was not +specified when the message queue was opened with the \fBmq_open\fR(3C) +function, and no message exists on the queue to satisfy the receive, the wait +for such a message is terminated when the specified timeout expires. If +\fBO_NONBLOCK\fR is set, this function is equivalent to \fBmq_receive()\fR. +.sp +.LP +The \fBmq_reltimedreceive_np()\fR function is identical to the +\fBmq_timedreceive()\fR function, except that the timeout is specified as a +relative time interval. +.sp +.LP +For \fBmq_timedreceive()\fR, the timeout expires when the absolute time +specified by \fIabs_timeout\fR passes, as measured by the \fBCLOCK_REALTIME\fR +clock (that is, when the value of that clock equals or exceeds +\fIabs_timeout\fR), or if the absolute time specified by \fIabs_timeout\fR has +already been passed at the time of the call. +.sp +.LP +For \fBmq_reltimedreceive_np()\fR, the timeout expires when the time interval +specified by \fIrel_timeout\fR passes, as measured by the \fBCLOCK_REALTIME\fR +clock, or if the time interval specified by \fIrel_timeout\fR is negative at +the time of the call. +.sp +.LP +The resolution of the timeout is the resolution of the \fBCLOCK_REALTIME\fR +clock. The \fBtimespec\fR argument is defined in the <\fBtime.h\fR> header. +.sp +.LP +Under no circumstance does the operation fail with a timeout if a message can +be removed from the message queue immediately. The validity of the timeout +parameter need not be checked if a message can be removed from the message +queue immediately. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBmq_receive()\fR, \fBmq_timedreceive()\fR, and +\fBmq_reltimedreceive_np()\fR return the length of the selected message in +bytes and the message is removed from the queue. Otherwise, no message is +removed from the queue, the functions return a value of \fB\(mi1\fR, and sets +\fBerrno\fR to indicate the error condition. +.SH ERRORS +.sp +.LP +The \fBmq_receive()\fR, \fBmq_timedreceive()\fR, and +\fBmq_reltimedreceive_np()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR \fR +.ad +.RS 13n +.rt +\fBO_NONBLOCK\fR was set in the message description associated with +\fImqdes\fR, and the specified message queue is empty. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR \fR +.ad +.RS 13n +.rt +The \fImqdes\fR argument is not a valid message queue descriptor open for +reading. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR \fR +.ad +.RS 13n +.rt +The function was interrupted by a signal. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 13n +.rt +The process or thread would have blocked, and the timeout parameter specified a +nanoseconds field value less than zero or greater than or equal to 1,000 +million. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMSGSIZE\fR \fR +.ad +.RS 13n +.rt +The specified message buffer size, \fImsg_len\fR, is less than the message size +member of the message queue. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBETIMEDOUT\fR\fR +.ad +.RS 13n +.rt +The \fBO_NONBLOCK\fR flag was not set when the message queue was opened, but no +message arrived on the queue before the specified timeout expired. +.RE + +.sp +.LP +The \fBmq_receive()\fR, \fBmq_timedreceive()\fR, and +\fBmq_reltimedreceive_np()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADMSG\fR \fR +.ad +.RS 12n +.rt +A data corruption problem with the message has been detected. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee below. +.TE + +.sp +.LP +For \fBmq_receive()\fR and \fBmq_timedreceive()\fR. see \fBstandards\fR(5). +.SH SEE ALSO +.sp +.LP +\fBmqueue.h\fR(3HEAD), \fBmq_open\fR(3C), \fBmq_send\fR(3C), +\fBmq_setattr\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/mq_send.3c b/usr/src/man/man3c/mq_send.3c new file mode 100644 index 0000000000..6ffddea5ab --- /dev/null +++ b/usr/src/man/man3c/mq_send.3c @@ -0,0 +1,230 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH mq_send 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +mq_send, mq_timedsend, mq_reltimedsend_np \- send a message to a message queue +.SH SYNOPSIS +.LP +.nf +#include <mqueue.h> + +\fBint\fR \fBmq_send\fR(\fBmqd_t\fR \fImqdes\fR, \fBconst char *\fR\fImsg_ptr\fR, \fBsize_t\fR \fImsg_len\fR, + \fBunsigned\fR \fImsg_prio\fR); +.fi + +.LP +.nf +#include <mqueue.h> +#include <time.h> + +\fBint\fR \fBmq_timedsend\fR(\fBmqd_t\fR \fImqdes\fR, \fBconst char *\fR\fImsg_ptr\fR, + \fBsize_t\fR \fImsg_len\fR, \fBunsigned\fR \fImsg_prio\fR, + \fBconst struct timespec *restrict\fR \fIabs_timeout\fR); +.fi + +.LP +.nf +\fBint\fR \fBmq_reltimedsend_np\fR(\fBmqd_t\fR \fImqdes\fR, \fBconst char *\fR\fImsg_ptr\fR, + \fBsize_t\fR \fImsg_len\fR, \fBunsigned\fR \fImsg_prio\fR, + \fBconst struct timespec *restrict\fR \fIrel_timeout\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBmq_send()\fR function adds the message pointed to by the argument +\fImsg_ptr\fR to the message queue specified by \fImqdes\fR. The \fImsg_len\fR +argument specifies the length of the message in bytes pointed to by +\fImsg_ptr\fR. The value of \fImsg_len\fR is less than or equal to the +\fImq_msgsize\fR attribute of the message queue, or \fBmq_send()\fR fails. +.sp +.LP +If the specified message queue is not full, \fBmq_send()\fR behaves as if the +message is inserted into the message queue at the position indicated by the +\fImsg_prio\fR argument. A message with a larger numeric value of +\fImsg_prio\fR is inserted before messages with lower values of \fImsg_prio\fR. +A message will be inserted after other messages in the queue, if any, with +equal \fImsg_prio\fR. The value of \fImsg_prio\fR must be greater than zero and +less than or equal to \fBMQ_PRIO_MAX\fR. +.sp +.LP +If the specified message queue is full and \fBO_NONBLOCK\fR is not set in the +message queue description associated with \fImqdes\fR (see \fBmq_open\fR(3C) +and \fBmq_setattr\fR(3C)), \fBmq_send()\fR blocks until space becomes available +to enqueue the message, or until \fBmq_send()\fR is interrupted by a signal. If +more than one thread is waiting to send when space becomes available in the +message queue, then the thread of the highest priority which has been waiting +the longest is unblocked to send its message. Otherwise, it is unspecified +which waiting thread is unblocked. If the specified message queue is full and +\fBO_NONBLOCK\fR is set in the message queue description associated with +\fImqdes\fR, the message is not queued and \fBmq_send()\fR returns an error. +.sp +.LP +The \fBmq_timedsend()\fR function adds a message to the message queue specified +by \fImqdes\fR in the manner defined for the \fBmq_send()\fR function. However, +if the specified message queue is full and \fBO_NONBLOCK\fR is not set in the +message queue description associated with \fImqdes\fR, the wait for sufficient +room in the queue is terminated when the specified timeout expires. If +\fBO_NONBLOCK\fR is set in the message queue description, this function is +equivalent to \fBmq_send()\fR. +.sp +.LP +The \fBmq_reltimedsend_np()\fR function is identical to the +\fBmq_timedsend()\fR function, except that the timeout is specified as a +relative time interval. +.sp +.LP +For \fBmq_timedsend()\fR, the timeout expires when the absolute time specified +by \fIabs_timeout\fR passes, as measured by the \fBCLOCK_REALTIME\fR clock +(that is, when the value of that clock equals or exceeds \fIabs_timeout\fR), or +if the absolute time specified by \fIabs_timeout\fR has already been passed at +the time of the call. +.sp +.LP +For \fBmq_reltimedsend_np()\fR, the timeout expires when the time interval +specified by \fIrel_timeout\fR passes, as measured by the \fBCLOCK_REALTIME\fR +clock, or if the time interval specified by \fIrel_timeout\fR is negative at +the time of the call. +.sp +.LP +The resolution of the timeout is the resolution of the \fBCLOCK_REALTIME\fR +clock. The \fBtimespec\fR argument is defined in the <\fBtime.h\fR> header. +.sp +.LP +Under no circumstance does the operation fail with a timeout if there is +sufficient room in the queue to add the message immediately. The validity of +the timeout parameter need not be checked when there is sufficient room in the +queue. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBmq_send()\fR, \fBmq_timedsend()\fR, and +\fBmq_reltimedsend_np()\fR return \fB0\fR. Otherwise, no message is enqueued, +the functions return \fB\(mi1\fR, and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBmq_send()\fR, \fBmq_timedsend()\fR, and \fBmq_reltimedsend_np()\fR +functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR \fR +.ad +.RS 13n +.rt +The \fBO_NONBLOCK\fR flag is set in the message queue description associated +with \fImqdes\fR, and the specified message queue is full. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR \fR +.ad +.RS 13n +.rt +The \fImqdes\fR argument is not a valid message queue descriptor open for +writing. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR \fR +.ad +.RS 13n +.rt +A signal interrupted the function call. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 13n +.rt +The value of \fImsg_prio\fR was outside the valid range. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 13n +.rt +The process or thread would have blocked, and the timeout parameter specified a +nanoseconds field value less than zero or greater than or equal to 1,000 +million. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMSGSIZE\fR \fR +.ad +.RS 13n +.rt +The specified message length, \fImsg_len\fR, exceeds the message size attribute +of the message queue. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBETIMEDOUT\fR\fR +.ad +.RS 13n +.rt +The \fBO_NONBLOCK\fR flag was not set when the message queue was opened, but +the timeout expired before the message could be added to the queue. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee below. +.TE + +.sp +.LP +For \fBmq_send()\fR and \fBmq_timedsend()\fR, see \fBstandards\fR(5). +.SH SEE ALSO +.sp +.LP +\fBsysconf\fR(3C), \fBmqueue.h\fR(3HEAD), \fBmq_open\fR(3C), +\fBmq_receive\fR(3C), \fBmq_setattr\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/mq_setattr.3c b/usr/src/man/man3c/mq_setattr.3c new file mode 100644 index 0000000000..d5f4acc0ae --- /dev/null +++ b/usr/src/man/man3c/mq_setattr.3c @@ -0,0 +1,122 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH mq_setattr 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +mq_setattr \- set/get message queue attributes +.SH SYNOPSIS +.LP +.nf +#include <mqueue.h> + +\fBint\fR \fBmq_setattr\fR(\fBmqd_t\fR \fImqdes\fR, \fBconst struct mq_attr *\fR\fImqstat\fR, + \fBstruct mq_attr *\fR\fIomqstat\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBmq_setattr()\fR function is used to set attributes associated with the +open message queue description referenced by the message queue descriptor +specified by \fImqdes\fR. +.sp +.LP +The message queue attributes corresponding to the following members defined in +the \fBmq_attr\fR structure are set to the specified values upon successful +completion of \fBmq_setattr()\fR: +.sp +.ne 2 +.mk +.na +\fB\fBmq_flags\fR \fR +.ad +.RS 13n +.rt +The value of this member is either \fB0\fR or \fBO_NONBLOCK.\fR +.RE + +.sp +.LP +The values of \fBmq_maxmsg\fR, \fBmq_msgsize\fR, and \fBmq_curmsgs\fR are +ignored by \fBmq_setattr()\fR. +.sp +.LP +If \fIomqstat\fR is non-\fINULL\fR, \fBmq_setattr()\fR stores, in the location +referenced by \fIomqstat\fR, the previous message queue attributes and the +current queue status. These values are the same as would be returned by a call +to \fBmq_getattr()\fR at that point. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBmq_setattr()\fR returns \fB0\fR and the +attributes of the message queue will have been changed as specified. Otherwise, +the message queue attributes are unchanged, and the function returns +\fB\(mi1\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBmq_setattr()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR \fR +.ad +.RS 11n +.rt +The \fImqdes\fR argument is not a valid message queue descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR \fR +.ad +.RS 11n +.rt +The \fBmq_setattr()\fR function is not supported by the system. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBmsgctl\fR(2), \fBmsgget\fR(2), \fBmsgrcv\fR(2), \fBmsgsnd\fR(2), +\fBmq_getattr\fR(3C), \fBmq_open\fR(3C), \fBmq_receive\fR(3C), +\fBmq_send\fR(3C), \fBmqueue.h\fR(3HEAD), \fBattributes\fR(5), +\fBstandards\fR(5) +.SH NOTES +.sp +.LP +Solaris 2.6 was the first release to support the Asynchronous Input and Output +option. Prior to this release, this function always returned \fB\(mi1\fR and +set \fBerrno\fR to \fBENOSYS\fR. diff --git a/usr/src/man/man3c/mq_unlink.3c b/usr/src/man/man3c/mq_unlink.3c new file mode 100644 index 0000000000..41b8a46b7f --- /dev/null +++ b/usr/src/man/man3c/mq_unlink.3c @@ -0,0 +1,122 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH mq_unlink 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +mq_unlink \- remove a message queue +.SH SYNOPSIS +.LP +.nf +#include <mqueue.h> + +\fBint\fR \fBmq_unlink\fR(\fBconst char *\fR\fIname\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBmq_unlink()\fR function removes the message queue named by the pathname +\fIname\fR. After a successful call to \fBmq_unlink()\fR with \fIname\fR, a +call to \fBmq_open\fR(3C) with \fIname\fR fails if the flag \fBO_CREAT\fR is +not set in \fIflags\fR. If one or more processes have the message queue open +when \fBmq_unlink()\fR is called, destruction of the message queue is postponed +until all references to the message queue have been closed. Calls to +\fBmq_open\fR(3C) to re-create the message queue may fail until the message +queue is actually removed. However, the \fBmq_unlink()\fR call need not block +until all references have been closed; it may return immediately. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBmq_unlink()\fR returns \fB0\fR; otherwise, the +named message queue is not changed by this function call, the function returns +\fB\(mi1\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBmq_unlink()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR \fR +.ad +.RS 17n +.rt +Permission is denied to unlink the named message queue. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR \fR +.ad +.RS 17n +.rt +The length of the \fIname\fR string exceeds \fBPATH_MAX\fR, or a pathname +component is longer than \fINAME_MAX\fR while \fB_POSIX_NO_TRUNC\fR is in +effect. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR \fR +.ad +.RS 17n +.rt +The named message queue, \fIname\fR, does not exist. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR \fR +.ad +.RS 17n +.rt +\fBmq_unlink()\fR is not supported by the system. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBmqueue.h\fR(3HEAD), \fBmq_close\fR(3C), \fBmq_open\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +Solaris 2.6 was the first release to support the Asynchronous Input and Output +option. Prior to this release, this function always returned \fB\(mi1\fR and +set \fBerrno\fR to \fBENOSYS\fR. diff --git a/usr/src/man/man3c/msync.3c b/usr/src/man/man3c/msync.3c new file mode 100644 index 0000000000..92bdf1683c --- /dev/null +++ b/usr/src/man/man3c/msync.3c @@ -0,0 +1,236 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH msync 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +msync \- synchronize memory with physical storage +.SH SYNOPSIS +.LP +.nf +#include <sys/mman.h> + +\fBint\fR \fBmsync\fR(\fBvoid *\fR\fIaddr\fR, \fBsize_t\fR \fIlen\fR, \fBint\fR \fIflags\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBmsync()\fR function writes all modified copies of pages over the range +[\fIaddr, addr + len\fR) to the underlying hardware, or invalidates any copies +so that further references to the pages will be obtained by the system from +their permanent storage locations. The permanent storage for a modified +\fBMAP_SHARED\fR mapping is the file the page is mapped to; the permanent +storage for a modified \fBMAP_PRIVATE\fR mapping is its swap area. +.sp +.LP +The \fIflags\fR argument is a bit pattern built from the following values: +.sp +.ne 2 +.mk +.na +\fBMS_ASYNC\fR +.ad +.RS 17n +.rt +perform asynchronous writes +.RE + +.sp +.ne 2 +.mk +.na +\fBMS_SYNC\fR +.ad +.RS 17n +.rt +perform synchronous writes +.RE + +.sp +.ne 2 +.mk +.na +\fBMS_INVALIDATE\fR +.ad +.RS 17n +.rt +invalidate mappings +.RE + +.sp +.LP +If \fIflags\fR is \fBMS_ASYNC\fR or \fBMS_SYNC\fR, the function synchronizes +the file contents to match the current contents of the memory region. +.RS +4 +.TP +.ie t \(bu +.el o +All write references to the memory region made prior to the call are visible by +subsequent read operations on the file. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +All writes to the same portion of the file prior to the call may or may not be +visible by read references to the memory region. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Unmodified pages in the specified range are not written to the underlying +hardware. +.RE +.sp +.LP +If \fIflags\fR is \fBMS_ASYNC\fR, the function may return immediately once all +write operations are scheduled; if \fIflags\fR is \fBMS_SYNC\fR, the function +does not return until all write operations are completed. +.sp +.LP +If \fIflags\fR is \fBMS_INVALIDATE\fR, the function synchronizes the contents +of the memory region to match the current file contents. +.RS +4 +.TP +.ie t \(bu +.el o +All writes to the mapped portion of the file made prior to the call are visible +by subsequent read references to the mapped memory region. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +All write references prior to the call, by any process, to memory regions +mapped to the same portion of the file using \fBMAP_SHARED\fR, are visible by +read references to the region. +.RE +.sp +.LP +If \fBmsync()\fR causes any write to the file, then the file's \fBst_ctime\fR +and \fBst_mtime\fR fields are marked for update. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBmsync()\fR returns \fB0\fR; otherwise, it +returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBmsync()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBUSY\fR\fR +.ad +.RS 10n +.rt +Some or all of the addresses in the range [\fIaddr\fR, \fIaddr\fR + \fIlen\fR) +are locked and \fBMS_SYNC\fR with the \fBMS_INVALIDATE\fR option is specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +Some or all pages in the range [\fIaddr\fR, \fIaddr\fR + \fIlen\fR) are +locked for I/O. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIaddr\fR argument is not a multiple of the page size as returned by +\fBsysconf\fR(3C). +.sp +The \fIflags\fR argument is not some combination of \fBMS_ASYNC\fR and +\fBMS_INVALIDATE\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 10n +.rt +An I/O error occurred while reading from or writing to the file system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Addresses in the range [\fIaddr, addr + len\fR) are outside the valid range for +the address space of a process, or specify one or more pages that are not +mapped. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 10n +.rt +\fBMS_INVALIDATE\fR was specified and one or more of the pages is locked in +memory. +.RE + +.SH USAGE +.sp +.LP +The \fBmsync()\fR function should be used by programs that require a memory +object to be in a known state, for example in building transaction facilities. +.sp +.LP +Normal system activity can cause pages to be written to disk. Therefore, there +are no guarantees that \fBmsync()\fR is the only control over when pages are or +are not written to disk. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBmemcntl\fR(2), \fBmmap\fR(2), \fBsysconf\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/mutex_init.3c b/usr/src/man/man3c/mutex_init.3c new file mode 100644 index 0000000000..0f98058c8a --- /dev/null +++ b/usr/src/man/man3c/mutex_init.3c @@ -0,0 +1,1009 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 1995 IEEE All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH mutex_init 3C "5 Jun 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +mutex_init, mutex_lock, mutex_trylock, mutex_unlock, mutex_consistent, +mutex_destroy \- mutual exclusion locks +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <thread.h> +#include <synch.h> + +\fBint\fR \fBmutex_init\fR(\fBmutex_t *\fR\fImp\fR, \fBint\fR \fItype\fR, \fBvoid *\fR \fIarg\fR); +.fi + +.LP +.nf +\fBint\fR \fBmutex_lock\fR(\fBmutex_t *\fR\fImp\fR); +.fi + +.LP +.nf +\fBint\fR \fBmutex_trylock\fR(\fBmutex_t *\fR\fImp\fR); +.fi + +.LP +.nf +\fBint\fR \fBmutex_unlock\fR(\fBmutex_t *\fR\fImp\fR); +.fi + +.LP +.nf +\fBint\fR \fBmutex_consistent\fR(\fBmutex_t *\fR\fImp\fR); +.fi + +.LP +.nf +\fBint\fR \fBmutex_destroy\fR(\fBmutex_t *\fR\fImp\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +Mutual exclusion locks (mutexes) prevent multiple threads from simultaneously +executing critical sections of code that access shared data (that is, mutexes +are used to serialize the execution of threads). All mutexes must be global. A +successful call for a mutex lock by way of \fBmutex_lock()\fR will cause +another thread that is also trying to lock the same mutex to block until the +owner thread unlocks it by way of \fBmutex_unlock()\fR. Threads within the +same process or within other processes can share mutexes. +.sp +.LP +Mutexes can synchronize threads within the same process or in other processes. +Mutexes can be used to synchronize threads between processes if the mutexes are +allocated in writable memory and shared among the cooperating processes (see +\fBmmap\fR(2)), and have been initialized for this task. +.SS "Initialize" +.sp +.LP +Mutexes are either intra-process or inter-process, depending upon the argument +passed implicitly or explicitly to the initialization of that mutex. A +statically allocated mutex does not need to be explicitly initialized; by +default, a statically allocated mutex is initialized with all zeros and its +scope is set to be within the calling process. +.sp +.LP +For inter-process synchronization, a mutex needs to be allocated in memory +shared between these processes. Since the memory for such a mutex must be +allocated dynamically, the mutex needs to be explicitly initialized using +\fBmutex_init()\fR. +.sp +.LP +The \fBmutex_init()\fR function initializes the mutex referenced by \fImp\fR +with the type specified by \fItype\fR. Upon successful initialization the +state of the mutex becomes initialized and unlocked. Only the attribute type +\fBLOCK_PRIO_PROTECT\fR uses \fIarg\fR. The \fItype\fR argument must be one of +the following: +.sp +.ne 2 +.mk +.na +\fB\fBUSYNC_THREAD\fR\fR +.ad +.sp .6 +.RS 4n +The mutex can synchronize threads only in this process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUSYNC_PROCESS\fR\fR +.ad +.sp .6 +.RS 4n +The mutex can synchronize threads in this process and other processes. The +object initialized with this attribute must be allocated in memory shared +between processes, either in System V shared memory (see \fBshmop\fR(2)) or in +memory mapped to a file (see \fBmmap\fR(2)). If the object is not allocated in +such shared memory, it will not be shared between processes. +.RE + +.sp +.LP +The \fItype\fR argument can be augmented by the bitwise-inclusive-\fBOR\fR of +zero or more of the following flags: +.sp +.ne 2 +.mk +.na +\fB\fBLOCK_ROBUST\fR\fR +.ad +.sp .6 +.RS 4n +The mutex can synchronize threads robustly. At the time of thread or process +death, either by calling \fBthr_exit()\fR or \fBexit()\fR or due to process +abnormal termination, the lock is unlocked if is held by the thread or process. +The next owner of the mutex will acquire it with an error return of +\fBEOWNERDEAD\fR. The application must always check the return value from +\fBmutex_lock()\fR for a mutex of this type. The new owner of this mutex should +then attempt to make the state protected by the mutex consistent, since this +state could have been left inconsistent when the last owner died. If the new +owner is able to make the state consistent, it should call +\fBmutex_consistent()\fR to restore the state of the mutex and then unlock the +mutex. All subsequent calls to \fBmutex_lock()\fRwill then behave normally. +Only the new owner can make the mutex consistent. If for any reason the new +owner is not able to make the state consistent, it should not call +\fBmutex_consistent()\fR but should simply unlock the mutex. All waiting +processes will be awakened and all subsequent calls to \fBmutex_lock()\fR will +fail in acquiring the mutex with an error value of \fBENOTRECOVERABLE\fR. If +the thread or process that acquired the lock with \fBEOWNERDEAD\fR terminates +without unlocking the mutex, the next owner will acquire the lock with an error +value of \fBEOWNERDEAD\fR. +.sp +The memory for the object to be initialized with this attribute must be zeroed +before initialization. Any thread or process interested in the robust lock can +call \fBmutex_init()\fR to potentially initialize it, provided that all such +callers of \fBmutex_init()\fR specify the same set of attribute flags. In this +situation, if \fBmutex_init()\fR is called on a previously initialized robust +mutex, \fBmutex_init()\fR will not reinitialize the mutex and will return the +error value \fBEBUSY\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOCK_RECURSIVE\fR\fR +.ad +.sp .6 +.RS 4n +A thread attempting to relock this mutex without first unlocking it will +succeed in locking the mutex. The mutex must be unlocked as many times as it is +locked. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOCK_ERRORCHECK\fR\fR +.ad +.sp .6 +.RS 4n +Unless \fBLOCK_RECURSIVE\fR is also set, a thread attempting to relock this +mutex without first unlocking it will return with an error rather than +deadlocking itself. A thread attempting to unlock this mutex without first +owning it will return with an error. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOCK_PRIO_INHERIT\fR\fR +.ad +.sp .6 +.RS 4n +When a thread is blocking higher priority threads because of owning one or more +mutexes with the \fBLOCK_PRIO_INHERIT\fR attribute, it executes at the higher +of its priority or the priority of the highest priority thread waiting on any +of the mutexes owned by this thread and initialized with this attribute. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOCK_PRIO_PROTECT\fR\fR +.ad +.sp .6 +.RS 4n +When a thread owns one or more mutexes initialized with the +\fBLOCK_PRIO_PROTECT\fR attribute, it executes at the higher of its priority or +the highest of the priority ceilings of all the mutexes owned by this thread +and initialized with this attribute, regardless of whether other threads are +blocked on any of these mutexes. When this attribute is specified, \fIarg\fR +must point to an \fBint\fR containing the priority ceiling. +.RE + +.sp +.LP +See \fBpthread_mutexattr_getrobust\fR(3C) for more information about robust +mutexes. The \fBLOCK_ROBUST\fR attribute is the same as the POSIX +\fBPTHREAD_MUTEX_ROBUST\fR attribute. +.sp +.LP +See \fBpthread_mutexattr_settype\fR(3C) for more information on recursive and +error checking mutex types. The combination (\fBLOCK_RECURSIVE\fR | +\fBLOCK_ERRORCHECK\fR) is the same as the POSIX \fBPTHREAD_MUTEX_RECURSIVE\fR +type. By itself, \fBLOCK_ERRORCHECK\fR is the same as the \fBPOSIX +PTHREAD_MUTEX_ERRORCHECK\fR type. +.sp +.LP +The \fBLOCK_PRIO_INHERIT\fR attribute is the same as the POSIX +\fBPTHREAD_PRIO_INHERIT\fR attribute. The \fBLOCK_PRIO_PROTECT\fR attribute is +the same as the POSIX \fBPTHREAD_PRIO_PROTECT\fR attribute. See +\fBpthread_mutexattr_getprotocol\fR(3C), +\fBpthread_mutexattr_getprioceiling\fR(3C), and +\fBpthread_mutex_getprioceiling\fR(3C) for a full discussion. The +\fBLOCK_PRIO_INHERIT\fR and \fBLOCK_PRIO_PROTECT\fR attributes are mutually +exclusive. Specifying both of these attributes causes \fBmutex_init()\fR to +fail with \fBEINVAL\fR. +.sp +.LP +Initializing mutexes can also be accomplished by allocating in zeroed memory +(default), in which case a \fItype\fR of \fBUSYNC_THREAD\fR is assumed. In +general, the following rules apply to mutex initialization: +.RS +4 +.TP +.ie t \(bu +.el o +The same mutex must not be simultaneously initialized by multiple threads. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +A mutex lock must not be reinitialized while in use by other threads. +.RE +.sp +.LP +These rules do not apply to \fBLOCK_ROBUST\fR mutexes. See the description for +\fBLOCK_ROBUST\fRabove. If default mutex attributes are used, the macro +\fBDEFAULTMUTEX\fR can be used to initialize mutexes that are statically +allocated. +.sp +.LP +Default mutex initialization (intra-process): +.sp +.in +2 +.nf +mutex_t mp; +mutex_init(&mp, USYNC_THREAD, NULL); +.fi +.in -2 + +.sp +.LP +or +.sp +.in +2 +.nf +mutex_t mp = DEFAULTMUTEX; +.fi +.in -2 + +.sp +.LP +Customized mutex initialization (inter-process): +.sp +.in +2 +.nf +mutex_init(&mp, USYNC_PROCESS, NULL); +.fi +.in -2 + +.sp +.LP +Customized mutex initialization (inter-process robust): +.sp +.in +2 +.nf +mutex_init(&mp, USYNC_PROCESS | LOCK_ROBUST, NULL); +.fi +.in -2 + +.sp +.LP +Statically allocated mutexes can also be initialized with macros specifying +\fBLOCK_RECURSIVE\fR and/or \fBLOCK_ERRORCHECK\fR: +.sp +.ne 2 +.mk +.na +\fB\fBmutex_t mp = RECURSIVEMUTEX;\fR\fR +.ad +.sp .6 +.RS 4n +Same as (\fBUSYNC_THREAD\fR | \fBLOCK_RECURSIVE\fR) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBmutex_t mp = ERRORCHECKMUTEX;\fR\fR +.ad +.sp .6 +.RS 4n +Same as (\fBUSYNC_THREAD\fR | \fBLOCK_ERRORCHECK\fR) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBmutex_t mp = RECURSIVE_ERRORCHECKMUTEX;\fR\fR +.ad +.sp .6 +.RS 4n +Same as (\fBUSYNC_THREAD\fR | \fBLOCK_RECURSIVE\fR | \fBLOCK_ERRORCHECK\fR) +.RE + +.SS "Lock and Unlock" +.sp +.LP +A critical section of code is enclosed by a the call to lock the mutex and the +call to unlock the mutex to protect it from simultaneous access by multiple +threads. Only one thread at a time may possess mutually exclusive access to +the critical section of code that is enclosed by the mutex-locking call and the +mutex-unlocking call, whether the mutex's scope is intra-process or +inter-process. A thread calling to lock the mutex either gets exclusive access +to the code starting from the successful locking until its call to unlock the +mutex, or it waits until the mutex is unlocked by the thread that locked it. +.sp +.LP +Mutexes have ownership, unlike semaphores. Although any thread, within the +scope of a mutex, can get an unlocked mutex and lock access to the same +critical section of code, only the thread that locked a mutex should unlock it. +.sp +.LP +If a thread waiting for a mutex receives a signal, upon return from the signal +handler, the thread resumes waiting for the mutex as if there was no interrupt. +A mutex protects code, not data; therefore, strongly bind a mutex with the +data by putting both within the same structure, or at least within the same +procedure. +.sp +.LP +A call to \fBmutex_lock()\fR locks the mutex object referenced by \fImp\fR. If +the mutex is already locked, the calling thread blocks until the mutex is +freed; this will return with the mutex object referenced by \fImp\fR in the +locked state with the calling thread as its owner. If the current owner of a +mutex tries to relock the mutex, it will result in deadlock. +.sp +.LP +The \fBmutex_trylock()\fR function is the same as \fBmutex_lock()\fR, +respectively, except that if the mutex object referenced by \fImp\fR is locked +(by any thread, including the current thread), the call returns immediately +with an error. +.sp +.LP +The \fBmutex_unlock()\fR function are called by the owner of the mutex object +referenced by \fImp\fR to release it. The mutex must be locked and the calling +thread must be the one that last locked the mutex (the owner). If there are +threads blocked on the mutex object referenced by \fImp\fR when +\fBmutex_unlock()\fR is called, the \fImp\fR is freed, and the scheduling +policy will determine which thread gets the mutex. If the calling thread is not +the owner of the lock, no error status is returned, and the behavior of the +program is undefined. +.SS "Destroy" +.sp +.LP +The \fBmutex_destroy()\fR function destroys the mutex object referenced by +\fImp\fR. The mutex object becomes uninitialized. The space used by the +destroyed mutex variable is not freed. It needs to be explicitly reclaimed. +.SH RETURN VALUES +.sp +.LP +If successful, these functions return \fB0\fR. Otherwise, an error number is +returned. +.SH ERRORS +.sp +.LP +The \fBmutex_init()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fItype\fR is invalid, or the \fBLOCK_PRIO_INHERIT\fR +and \fBLOCK_PRIO_PROTECT\fR attributes are both specified. +.RE + +.sp +.LP +The \fBmutex_init()\fR function will fail for \fBLOCK_ROBUST\fR type mutex if: +.sp +.ne 2 +.mk +.na +\fB\fBEBUSY\fR\fR +.ad +.RS 10n +.rt +The mutex pointed to by \fImp\fR was previously initialized and has not yet +been destroyed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The mutex pointed to by \fImp\fR was previously initialized with a different +set of attribute flags. +.RE + +.sp +.LP +The \fBmutex_trylock()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBUSY\fR\fR +.ad +.RS 9n +.rt +The mutex pointed to by \fImp\fR is already locked. +.RE + +.sp +.LP +The \fBmutex_lock()\fR and \fBmutex_trylock()\fR functions will fail for a +\fBLOCK_RECURSIVE\fR mutex if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +The mutex could not be acquired because the maximum number of recursive locks +for the mutex has been reached. +.RE + +.sp +.LP +The \fBmutex_lock()\fR function will fail for a \fBLOCK_ERRORCHECK\fR and +non-\fBLOCK_RECURSIVE\fR mutex if: +.sp +.ne 2 +.mk +.na +\fB\fBEDEADLK\fR\fR +.ad +.RS 11n +.rt +The caller already owns the mutex. +.RE + +.sp +.LP +The \fBmutex_lock()\fR function may fail for a non-\fBLOCK_ERRORCHECK\fR and +non-\fBLOCK_RECURSIVE\fR mutex if: +.sp +.ne 2 +.mk +.na +\fB\fBEDEADLK\fR\fR +.ad +.RS 11n +.rt +The caller already owns the mutex. +.RE + +.sp +.LP +The \fBmutex_unlock()\fR function will fail for a \fBLOCK_ERRORCHECK\fR mutex +if: +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 9n +.rt +The caller does not own the mutex. +.RE + +.sp +.LP +The \fBmutex_lock()\fR or \fBmutex_trylock()\fR functions will fail for +\fBLOCK_ROBUST\fR type mutex if: +.sp +.ne 2 +.mk +.na +\fB\fBEOWNERDEAD\fR\fR +.ad +.RS 19n +.rt +The last owner of this mutex died while holding the mutex. This mutex is now +owned by the caller. The caller must now attempt to make the state protected by +the mutex consistent. If it is able to clean up the state, then it should +restore the state of the mutex by calling \fBmutex_consistent()\fR and unlock +the mutex. Subsequent calls to \fBmutex_lock()\fR will behave normally, as +before. If the caller is not able to clean up the state, +\fBmutex_consistent()\fR should not be called but the mutex should be unlocked. +Subsequent calls to \fBmutex_lock()\fR will fail to acquire the mutex, +returning with the error value \fBENOTRECOVERABLE\fR. If the owner who acquired +the lock with \fBEOWNERDEAD\fR dies, the next owner will acquire the lock with +\fBEOWNERDEAD\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTRECOVERABLE\fR\fR +.ad +.RS 19n +.rt +The mutex trying to be acquired was protecting the state that has been left +unrecoverable when the mutex's last owner could not make the state protected by +the mutex consistent. The mutex has not been acquired. This condition occurs +when the lock was previously acquired with \fBEOWNERDEAD\fR and the owner was +not able to clean up the state and unlocked the mutex without calling +\fBmutex_consistent()\fR. +.RE + +.sp +.LP +The \fBmutex_consistent()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The caller does not own the mutex or the mutex is not a \fBLOCK_ROBUST\fR mutex +having an inconsistent state (\fBEOWNERDEAD\fR). +.RE + +.SH EXAMPLES +.SS "Single Gate" +.sp +.LP +The following example uses one global mutex as a gate-keeper to permit each +thread exclusive sequential access to the code within the user-defined +function "change_global_data." This type of synchronization will protect the +state of shared data, but it also prohibits parallelism. +.sp +.in +2 +.nf +/* cc thisfile.c -lthread */ +#define _REENTRANT +#include <stdio.h> +#include <thread.h> +#define NUM_THREADS 12 +void *change_global_data(void *); /* for thr_create() */ +main(int argc,char * argv[]) { + int i=0; + for (i=0; i< NUM_THREADS; i++) { + thr_create(NULL, 0, change_global_data, NULL, 0, NULL); + } + while ((thr_join(NULL, NULL, NULL) == 0)); +} + +void * change_global_data(void *null){ + static mutex_t Global_mutex; + static int Global_data = 0; + mutex_lock(&Global_mutex); + Global_data++; + sleep(1); + printf("%d is global data\en",Global_data); + mutex_unlock(&Global_mutex); + return NULL; +} +.fi +.in -2 + +.SS "Multiple Instruction Single Data" +.sp +.LP +The previous example, the mutex, the code it owns, and the data it protects was +enclosed in one function. The next example uses C++ features to accommodate +many functions that use just one mutex to protect one data: +.sp +.in +2 +.nf +/* CC thisfile.c -lthread use C++ to compile*/ + +#define _REENTRANT +#include <stdlib.h> +#include <stdio.h> +#include <thread.h> +#include <errno.h> +#include <iostream.h> +#define NUM_THREADS 16 +void *change_global_data(void *); /* for thr_create() */ + +class Mutected { + private: + static mutex_t Global_mutex; + static int Global_data; + public: + static int add_to_global_data(void); + static int subtract_from_global_data(void); +}; + +int Mutected::Global_data = 0; +mutex_t Mutected::Global_mutex; + +int Mutected::add_to_global_data() { + mutex_lock(&Global_mutex); + Global_data++; + mutex_unlock(&Global_mutex); + return Global_data; +} + +int Mutected::subtract_from_global_data() { + mutex_lock(&Global_mutex); + Global_data--; + mutex_unlock(&Global_mutex); + return Global_data; +} + +void +main(int argc,char * argv[]) { + int i=0; + for (i=0;i< NUM_THREADS;i++) { + thr_create(NULL,0,change_global_data,NULL,0,NULL); + } + while ((thr_join(NULL,NULL,NULL) == 0)); +} + +void * change_global_data(void *) { + static int switcher = 0; + if ((switcher++ % 3) == 0) /* one-in-three threads subtracts */ + cout << Mutected::subtract_from_global_data() << endl; + else + cout << Mutected::add_to_global_data() << endl; + return NULL; +} +.fi +.in -2 + +.SS "Interprocess Locking" +.sp +.LP +A mutex can protect data that is shared among processes. The mutex would need +to be initialized as \fBUSYNC_PROCESS\fR. One process initializes the +process-shared mutex and writes it to a file to be mapped into memory by all +cooperating processes (see \fBmmap\fR(2)). Afterwards, other independent +processes can run the same program (whether concurrently or not) and share +mutex-protected data. +.sp +.in +2 +.nf +/* cc thisfile.c -lthread */ +/* To execute, run the command line "a.out 0 &; a.out 1" */ + +#define _REENTRANT +#include <sys/types.h> +#include <sys/mman.h> +#include <sys/stat.h> +#include <fcntl.h> +#include <stdio.h> +#include <thread.h> +#define INTERPROCESS_FILE "ipc-sharedfile" +#define NUM_ADDTHREADS 12 +#define NUM_SUBTRACTTHREADS 10 +#define INCREMENT '0' +#define DECREMENT '1' +typedef struct { + mutex_t Interprocess_mutex; + int Interprocess_data; +} buffer_t; +buffer_t *buffer; + +void *add_interprocess_data(), *subtract_interprocess_data(); +void create_shared_memory(), test_argv(); +int zeroed[sizeof(buffer_t)]; +int ipc_fd, i=0; + +void +main(int argc,char * argv[]){ + test_argv(argv[1]); + + switch (*argv[1]) { + case INCREMENT: + /* Initializes the process-shared mutex */ + /* Should be run prior to running a DECREMENT process */ + create_shared_memory(); + ipc_fd = open(INTERPROCESS_FILE, O_RDWR); + buffer = (buffer_t *)mmap(NULL, sizeof(buffer_t), + PROT_READ | PROT_WRITE, MAP_SHARED, ipc_fd, 0); + buffer->Interprocess_data = 0; + mutex_init(&buffer->Interprocess_mutex, USYNC_PROCESS,0); + for (i=0; i< NUM_ADDTHREADS; i++) + thr_create(NULL, 0, add_interprocess_data, argv[1], + 0, NULL); + break; + + case DECREMENT: + /* Should be run after the INCREMENT process has run. */ + while(ipc_fd = open(INTERPROCESS_FILE, O_RDWR)) == -1) + sleep(1); + buffer = (buffer_t *)mmap(NULL, sizeof(buffer_t), + PROT_READ | PROT_WRITE, MAP_SHARED, ipc_fd, 0); + for (i=0; i< NUM_SUBTRACTTHREADS; i++) + thr_create(NULL, 0, subtract_interprocess_data, argv[1], + 0, NULL); + break; + } /* end switch */ + + while ((thr_join(NULL,NULL,NULL) == 0)); +} /* end main */ + +void *add_interprocess_data(char argv_1[]){ + mutex_lock(&buffer->Interprocess_mutex); + buffer->Interprocess_data++; + sleep(2); + printf("%d is add-interprocess data, and %c is argv1\en", + buffer->Interprocess_data, argv_1[0]); + mutex_unlock(&buffer->Interprocess_mutex); + return NULL; +} + +void *subtract_interprocess_data(char argv_1[]) { + mutex_lock(&buffer->Interprocess_mutex); + buffer->Interprocess_data--; + sleep(2); + printf("%d is subtract-interprocess data, and %c is argv1\en", + buffer->Interprocess_data, argv_1[0]); + mutex_unlock(&buffer->Interprocess_mutex); + return NULL; +} + +void create_shared_memory(){ + int i; + ipc_fd = creat(INTERPROCESS_FILE, O_CREAT | O_RDWR ); + for (i=0; i<sizeof(buffer_t); i++){ + zeroed[i] = 0; + write(ipc_fd, &zeroed[i],2); + } + close(ipc_fd); + chmod(INTERPROCESS_FILE, S_IRWXU | S_IRWXG | S_IRWXO); +} + +void test_argv(char argv1[]) { + if (argv1 == NULL) { + printf("use 0 as arg1 for initial process\en \e + or use 1 as arg1 for the second process\en"); + exit(NULL); + } +} +.fi +.in -2 + +.SS "Solaris Interprocess Robust Locking" +.sp +.LP +A mutex can protect data that is shared among processes robustly. The mutex +would need to be initialized as \fBUSYNC_PROCESS\fR | \fBLOCK_ROBUST\fR. One +process initializes the robust process-shared mutex and writes it to a file to +be mapped into memory by all cooperating processes (see \fBmmap\fR(2)). +Afterwards, other independent processes can run the same program (whether +concurrently or not) and share mutex-protected data. +.sp +.LP +The following example shows how to use a \fBUSYNC_PROCESS\fR | +\fBLOCK_ROBUST\fR type mutex. +.sp +.in +2 +.nf +/* cc thisfile.c -lthread */ + /* To execute, run the command line "a.out & a.out 1" */ + #include <sys/types.h> + #include <sys/mman.h> + #include <fcntl.h> + #include <stdio.h> + #include <thread.h> + #define INTERPROCESS_FILE "ipc-sharedfile" + typedef struct { + mutex_t Interprocess_mutex; + int Interprocess_data; + } buffer_t; + buffer_t *buffer; + int make_date_consistent(); + void create_shared_memory(); + int zeroed[sizeof(buffer_t)]; + int ipc_fd, i=0; + main(int argc,char * argv[]) { + int rc; + if (argc > 1) { + while((ipc_fd = open(INTERPROCESS_FILE, O_RDWR)) == -1) + sleep(1); + buffer = (buffer_t *)mmap(NULL, sizeof(buffer_t), + PROT_READ | PROT_WRITE, MAP_SHARED, ipc_fd, 0); + mutex_init(&buffer->Interprocess_mutex, + USYNC_PROCESS | LOCK_ROBUST,0); + } else { + create_shared_memory(); + ipc_fd = open(INTERPROCESS_FILE, O_RDWR); + buffer = (buffer_t *)mmap(NULL, sizeof(buffer_t), + PROT_READ | PROT_WRITE, MAP_SHARED, ipc_fd, 0); + buffer->Interprocess_data = 0; + mutex_init(&buffer->Interprocess_mutex, + USYNC_PROCESS | LOCK_ROBUST,0); + } + for(;;) { + rc = mutex_lock(&buffer->Interprocess_mutex); + switch (rc) { + case EOWNERDEAD: + /* + * The lock is acquired. + * The last owner died holding the lock. + * Try to make the state associated with + * the mutex consistent. + * If successful, make the robust lock consistent. + */ + if (make_data_consistent()) + mutex_consistent(&buffer->Interprocess_mutex); + mutex_unlock(&buffer->Interprocess_mutex); + break; + case ENOTRECOVERABLE: + /* + * The lock is not acquired. + * The last owner got the mutex with EOWNERDEAD + * and failed to make the data consistent. + * There is no way to recover, so just exit. + */ + exit(1); + case 0: + /* + * There is no error - data is consistent. + * Do something with data. + */ + mutex_unlock(&buffer->Interprocess_mutex); + break; + } + } +} /* end main */ +void create_shared_memory() { + int i; + ipc_fd = creat(INTERPROCESS_FILE, O_CREAT | O_RDWR ); + for (i=0; i<sizeof(buffer_t); i++) { + zeroed[i] = 0; + write(ipc_fd, &zeroed[i],2); + } + close(ipc_fd); + chmod(INTERPROCESS_FILE, S_IRWXU | S_IRWXG | S_IRWXO); + } + + /* return 1 if able to make data consistent, otherwise 0. */ + int make_data_consistent () { + buffer->Interprocess_data = 0; + return (1); + } +.fi +.in -2 + +.SS "Dynamically Allocated Mutexes" +.sp +.LP +The following example allocates and frees memory in which a mutex is embedded. +.sp +.in +2 +.nf +struct record { + int field1; + int field2; + mutex_t m; +} *r; +r = malloc(sizeof(struct record)); +mutex_init(&r->m, USYNC_THREAD, NULL); +/* + * The fields in this record are accessed concurrently + * by acquiring the embedded lock. + */ +.fi +.in -2 + +.sp +.LP +The thread execution in this example is as follows: +.sp +.in +2 +.nf +\fIThread 1 executes:\fR \fIThread 2 executes:\fR + +\&... ... +mutex_lock(&r->m); mutex_lock(&r->m); +r->field1++; localvar = r->field1; +mutex_unlock(&r->m); mutex_unlock(&r->m); +\&... ... +.fi +.in -2 + +.sp +.LP +Later, when a thread decides to free the memory pointed to by \fIr\fR, the +thread should call \fBmutex_destroy\fR(\|) on the mutexes in this memory. +.sp +.LP +In the following example, the main thread can do a \fBthr_join\fR(\|) on both +of the above threads. If there are no other threads using the memory in +\fIr\fR, the main thread can now safely free \fIr\fR: +.sp +.in +2 +.nf +for (i = 0; i < 2; i++) + thr_join(0, 0, 0); +mutex_destroy(&r->m); /* first destroy mutex */ +free(r); /* then free memory */ +.fi +.in -2 + +.sp +.LP +If the mutex is not destroyed, the program could have memory leaks. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStable +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBmmap\fR(2), \fBshmop\fR(2), \fBpthread_mutexattr_getprioceiling\fR(3C), +\fBpthread_mutexattr_getprotocol\fR(3C), \fBpthread_mutexattr_getrobust\fR(3C), +\fBpthread_mutexattr_gettype\fR(3C), \fBpthread_mutex_getprioceiling\fR(3C), +\fBpthread_mutex_init\fR(3C), \fBattributes\fR(5), \fBmutex\fR(5), +\fBstandards\fR(5) +.SH NOTES +.sp +.LP +Previous releases of Solaris provided the \fBUSYNC_PROCESS_ROBUST\fR mutex +type. This type is now deprecated but is still supported for source and binary +compatibility. When passed to \fBmutex_init()\fR, it is transformed into +(\fBUSYNC_PROCESS\fR | \fBLOCK_ROBUST\fR). The former method for restoring a +\fBUSYNC_PROCESS_ROBUST\fR mutex to a consistent state was to reinitialize it +by calling \fBmutex_init()\fR. This method is still supported for source and +binary compatibility, but the proper method is to call +\fBmutex_consistent()\fR. +.sp +.LP +The \fBUSYNC_PROCESS_ROBUST\fR type permitted an alternate error value, +\fBELOCKUNMAPPED\fR, to be returned by \fBmutex_lock()\fR if the process +containing a locked robust mutex unmapped the memory containing the mutex or +performed one of the \fBexec\fR(2) functions. The \fBELOCKUNMAPPED\fR error +value implies all of the consequences of the \fBEOWNERDEAD\fR error value and +as such is just a synonym for \fBEOWNERDEAD\fR. For full source and binary +compatibility, the \fBELOCKUNMAPPED\fR error value is still returned from +\fBmutex_lock()\fR in these circumstances, but only if the mutex was +initialized with the \fBUSYNC_PROCESS_ROBUST\fR type. Otherwise, +\fBEOWNERDEAD\fR is returned in these circumstances. +.sp +.LP +The \fBmutex_lock()\fR, \fBmutex_unlock()\fR, and \fBmutex_trylock()\fR +functions do not validate the mutex type. An uninitialized mutex or a mutex +with an invalid type does not return \fBEINVAL\fR. Interfaces for mutexes with +an invalid type have unspecified behavior. +.sp +.LP +Uninitialized mutexes that are allocated locally could contain junk data. Such +mutexes need to be initialized using \fBmutex_init()\fR. +.sp +.LP +By default, if multiple threads are waiting for a mutex, the order of +acquisition is undefined. diff --git a/usr/src/man/man3c/nanosleep.3c b/usr/src/man/man3c/nanosleep.3c new file mode 100644 index 0000000000..d8dcbfd55f --- /dev/null +++ b/usr/src/man/man3c/nanosleep.3c @@ -0,0 +1,120 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH nanosleep 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +nanosleep \- high resolution sleep +.SH SYNOPSIS +.LP +.nf +#include <time.h> + +\fBint\fR \fBnanosleep\fR(\fBconst struct timespec *\fR\fIrqtp\fR, + \fBstruct timespec *\fR\fIrmtp\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBnanosleep()\fR function causes the current thread to be suspended from +execution until either the time interval specified by the \fIrqtp\fR 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 will not be less than the time specified by +\fIrqtp\fR, as measured by the system clock, \fBCLOCK_REALTIME\fR. +.sp +.LP +The use of the \fBnanosleep()\fR function has no effect on the action or +blockage of any signal. +.SH RETURN VALUES +.sp +.LP +If the \fBnanosleep()\fR function returns because the requested time has +elapsed, its return value is \fB0\fR. +.sp +.LP +If the \fBnanosleep()\fR function returns because it has been interrupted by a +signal, the function returns a value of \(mi1 and sets \fBerrno\fR to indicate +the interruption. If the \fIrmtp\fR argument is non-\fINULL\fR, the +\fBtimespec\fR structure referenced by it is updated to contain the amount of +time remaining in the interval (the requested time minus the time actually +slept). If the \fIrmtp\fR argument is \fINULL\fR, the remaining time is not +returned. +.sp +.LP +If \fBnanosleep()\fR fails, it returns \fB\(mi1\fR and sets \fBerrno\fR to +indicate the error. +.SH ERRORS +.sp +.LP +The \fBnanosleep()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 10n +.rt +The \fBnanosleep()\fR function was interrupted by a signal. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIrqtp\fR argument specified a nanosecond value less than zero or greater +than or equal to 1000 million. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR\fR +.ad +.RS 10n +.rt +The \fBnanosleep()\fR function is not supported by this implementation. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBsleep\fR(3C), \fBtime.h\fR(3HEAD), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/ndbm.3c b/usr/src/man/man3c/ndbm.3c new file mode 100644 index 0000000000..75b2fc20a6 --- /dev/null +++ b/usr/src/man/man3c/ndbm.3c @@ -0,0 +1,317 @@ +'\" te +.\" Copyright (c) 1985 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, +.\" X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.TH ndbm 3C "17 Sep 2001" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +ndbm, dbm_clearerr, dbm_close, dbm_delete, dbm_error, dbm_fetch, dbm_firstkey, +dbm_nextkey, dbm_open, dbm_store \- database functions +.SH SYNOPSIS +.LP +.nf +#include <ndbm.h> + +\fBint\fR \fBdbm_clearerr\fR(\fBDBM *\fR\fIdb\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBdbm_close\fR(\fBDBM *\fR\fIdb\fR); +.fi + +.LP +.nf +\fBint\fR \fBdbm_delete\fR(\fBDBM *\fR\fIdb\fR, \fBdatum\fR \fIkey\fR); +.fi + +.LP +.nf +\fBint\fR \fBdbm_error\fR(\fBDBM *\fR\fIdb\fR); +.fi + +.LP +.nf +\fBdatum\fR \fBdbm_fetch\fR(\fBDBM *\fR\fIdb\fR, \fBdatum\fR \fIkey\fR); +.fi + +.LP +.nf +\fBdatum\fR \fBdbm_firstkey\fR(\fBDBM *\fR\fIdb\fR); +.fi + +.LP +.nf +\fBdatum\fR \fBdbm_nextkey\fR(\fBDBM *\fR\fIdb\fR); +.fi + +.LP +.nf +\fBDBM *\fR\fBdbm_open\fR(\fBconst char *\fR\fIfile\fR, \fBint\fR \fIopen_flags\fR, \fBmode_t\fR \fIfile_mode\fR); +.fi + +.LP +.nf +\fBint\fR \fBdbm_store\fR(\fBDBM *\fR\fIdb\fR, \fBdatum\fR \fIkey\fR, \fBdatum\fR \fIcontent\fR, \fBint\fR \fIstore_mode\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions create, access and modify a database. They maintain +\fIkey\fR/\fIcontent\fR pairs in a database. The functions will handle large +databases (up to a billion blocks) and will access a keyed item in one or two +file system accesses. This package replaces the earlier \fBdbm\fR(3UCB) +library, which managed only a single database. +.sp +.LP +\fIkey\fRs and \fIcontent\fRs are described by the \fBdatum\fR typedef. A +\fBdatum\fR consists of at least two members, \fBdptr\fR and \fBdsize\fR. The +\fBdptr\fR member points to an object that is \fBdsize\fR bytes in length. +Arbitrary binary data, as well as ASCII character strings, may be stored in the +object pointed to by \fBdptr\fR. +.sp +.LP +The database is stored in two files. One file is a directory containing a bit +map of keys and has \fB\&.dir\fR as its suffix. The second file contains all +data and has \fB\&.pag\fR as its suffix. +.sp +.LP +The \fBdbm_open()\fR function opens a database. The \fBfile\fR argument to the +function is the pathname of the database. The function opens two files named +\fBfile\fR\fB\&.dir\fR and \fBfile\fR\fB\&.pag.\fR The \fIopen_flags\fR +argument has the same meaning as the \fIflags\fR argument of \fBopen\fR(2) +except that a database opened for write-only access opens the files for read +and write access. The \fIfile_mode\fR argument has the same meaning as the +third argument of \fBopen\fR(2). +.sp +.LP +The \fBdbm_close()\fR function closes a database. The argument \fIdb\fR must +be a pointer to a \fBdbm\fR structure that has been returned from a call to +\fBdbm_open()\fR. +.sp +.LP +The \fBdbm_fetch()\fR function reads a record from a database. The argument +\fIdb\fR is a pointer to a database structure that has been returned from a +call to \fBdbm_open()\fR. The argument \fIkey\fR is a \fBdatum\fR that has been +initialized by the application program to the value of the key that matches the +key of the record the program is fetching. +.sp +.LP +The \fBdbm_store()\fR function writes a record to a database. The argument +\fIdb\fR is a pointer to a database structure that has been returned from a +call to \fBdbm_open()\fR. The argument \fIkey\fR is a \fBdatum\fR that has been +initialized by the application program to the value of the key that identifies +(for subsequent reading, writing or deleting) the record the program is +writing. The argument \fIcontent\fR is a \fBdatum\fR that has been initialized +by the application program to the value of the record the program is writing. +The argument \fIstore_mode\fR controls whether \fBdbm_store()\fR replaces any +pre-existing record that has the same key that is specified by the \fIkey\fR +argument. The application program must set \fIstore_mode\fR to either +\fBDBM_INSERT\fR or \fBDBM_REPLACE\fR. If the database contains a record that +matches the \fIkey\fR argument and \fIstore_mode\fR is \fBDBM_REPLACE\fR, the +existing record is replaced with the new record. If the database contains a +record that matches the \fIkey\fR argument and \fIstore_mode\fR is +\fBDBM_INSERT\fR, the existing record is not replaced with the new record. If +the database does not contain a record that matches the \fIkey\fR argument and +\fIstore_mode\fR is either \fBDBM_INSERT\fR or \fBDBM_REPLACE\fR, the new +record is inserted in the database. +.sp +.LP +The \fBdbm_delete()\fR function deletes a record and its key from the database. +The argument \fIdb\fR is a pointer to a database structure that has been +returned from a call to \fBdbm_open()\fR. The argument \fIkey\fR is a +\fBdatum\fR that has been initialized by the application program to the value +of the key that identifies the record the program is deleting. +.sp +.LP +The \fBdbm_firstkey()\fR function returns the first key in the database. The +argument \fIdb\fR is a pointer to a database structure that has been returned +from a call to \fBdbm_open()\fR. +.sp +.LP +The \fBdbm_nextkey()\fR function returns the next key in the database. The +argument \fIdb\fR is a pointer to a database structure that has been returned +from a call to \fBdbm_open()\fR. The \fBdbm_firstkey()\fR function must be +called before calling \fBdbm_nextkey()\fR. Subsequent calls to +\fBdbm_nextkey()\fR return the next key until all of the keys in the database +have been returned. +.sp +.LP +The \fBdbm_error()\fR function returns the error condition of the database. +The argument \fIdb\fR is a pointer to a database structure that has been +returned from a call to \fBdbm_open()\fR. +.sp +.LP +The \fBdbm_clearerr()\fR function clears the error condition of the database. +The argument \fIdb\fR is a pointer to a database structure that has been +returned from a call to \fBdbm_open()\fR. +.sp +.LP +These database functions support key/content pairs of at least 1024 bytes. +.SH RETURN VALUES +.sp +.LP +The \fBdbm_store()\fR and \fBdbm_delete()\fR functions return \fB0\fR when they +succeed and a negative value when they fail. +.sp +.LP +The \fBdbm_store()\fR function returns \fB1\fR if it is called with a +\fIflags\fR value of \fBDBM_INSERT\fR and the function finds an existing record +with the same key. +.sp +.LP +The \fBdbm_error()\fR function returns \fB0\fR if the error condition is not +set and returns a non-zero value if the error condition is set. +.sp +.LP +The return value of \fBdbm_clearerr()\fR is unspecified . +.sp +.LP +The \fBdbm_firstkey()\fR and \fBdbm_nextkey()\fR functions return a key +\fBdatum\fR. When the end of the database is reached, the \fBdptr\fR member of +the key is a null pointer. If an error is detected, the \fBdptr\fR member of +the key is a null pointer and the error condition of the database is set. +.sp +.LP +The \fBdbm_fetch()\fR function returns a content \fBdatum\fR. If no record in +the database matches the key or if an error condition has been detected in the +database, the \fBdptr\fR member of the content is a null pointer. +.sp +.LP +The \fBdbm_open()\fR function returns a pointer to a database structure. If an +error is detected during the operation, \fBdbm_open()\fR returns a (\fBDBM +*\fR)0. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH USAGE +.sp +.LP +The following code can be used to traverse the database: +.sp +.in +2 +.nf +for(key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db)) +.fi +.in -2 + +.sp +.LP +The \fBdbm_\fR 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. +.sp +.LP +The \fBdptr\fR pointers returned by these functions may point into static +storage that may be changed by subsequent calls. +.sp +.LP +The \fBdbm_delete()\fR function does not physically reclaim file space, +although it does make it available for reuse. +.sp +.LP +After calling \fBdbm_store()\fR or \fBdbm_delete()\fR during a pass through the +keys by \fBdbm_firstkey()\fR and \fBdbm_nextkey()\fR, the application should +reset the database by calling \fBdbm_firstkey()\fR before again calling +\fBdbm_nextkey()\fR. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing the Database Functions +.sp +.LP +The following example stores and retrieves a phone number, using the name as +the key. Note that this example does not include error checking. + +.sp +.in +2 +.nf +#include <ndbm.h> +#include <stdio.h> +#include <fcntl.h> +#define NAME "Bill" +#define PHONE_NO "123-4567" +#define DB_NAME "phones" +main() +{ + DBM *db; + datum name = {NAME, sizeof (NAME)}; + datum put_phone_no = {PHONE_NO, sizeof (PHONE_NO)}; + datum get_phone_no; + /* Open the database and store the record */ + db = dbm_open(DB_NAME, O_RDWR | O_CREAT, 0660); + (void) dbm_store(db, name, put_phone_no, DBM_INSERT); + /* Retrieve the record */ + get_phone_no = dbm_fetch(db, name); + (void) printf("Name: %s, Phone Number: %s\en", name.dptr, + get_phone_no.dptr); + /* Close the database */ + dbm_close(db); + return (0); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBar\fR(1), \fBcat\fR(1), \fBcp\fR(1), \fBtar\fR(1), \fBopen\fR(2), +\fBdbm\fR(3UCB), \fBnetconfig\fR(4), \fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +The \fB\&.pag\fR file will contain holes so that its apparent size may be +larger than its actual content. Older versions of the UNIX operating system may +create real file blocks for these holes when touched. These files cannot be +copied by normal means ( \fBcp\fR(1), \fBcat\fR(1), \fBtar\fR(1), \fBar\fR(1)) +without filling in the holes. +.sp +.LP +The sum of the sizes of a \fIkey\fR/\fIcontent\fR pair must not exceed the +internal block size (currently 1024 bytes). Moreover all +\fIkey\fR/\fIcontent\fR pairs that hash together must fit on a single block. +\fBdbm_store()\fR will return an error in the event that a disk block fills +with inseparable data. +.sp +.LP +The order of keys presented by \fBdbm_firstkey()\fR and \fBdbm_nextkey()\fR +depends on a hashing function. +.sp +.LP +There are no interlocks and no reliable cache flushing; thus concurrent +updating and reading is risky. +.sp +.LP +The database files (\fBfile\fR\fB\&.dir\fR and \fBfile\fR\fB\&.pag\fR) are +binary and are architecture-specific (for example, they depend on the +architecture's byte order.) These files are not guaranteed to be portable +across architectures. diff --git a/usr/src/man/man3c/nl_langinfo.3c b/usr/src/man/man3c/nl_langinfo.3c new file mode 100644 index 0000000000..cd4e2aaa46 --- /dev/null +++ b/usr/src/man/man3c/nl_langinfo.3c @@ -0,0 +1,80 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH nl_langinfo 3C "24 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +nl_langinfo \- language information +.SH SYNOPSIS +.LP +.nf +#include <langinfo.h> + +\fBchar *\fR\fBnl_langinfo\fR(\fBnl_item\fR \fIitem\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBnl_langinfo()\fR function returns a pointer to a null-terminated string +containing information relevant to a particular language or cultural area +defined in the programs locale. The manifest constant names and values of +\fIitem\fR are defined by <\fBlanginfo.h\fR>. For example: +.sp +.LP +\fBnl_langinfo (ABDAY_1);\fR +.sp +.LP +would return a pointer to the string "\fBDim\fR" if the identified language was +French and a French locale was correctly installed; or "\fBSun\fR" if the +identified language was English. +.SH RETURN VALUES +.sp +.LP +If \fBsetlocale\fR(3C) has not been called successfully, or if data for a +supported language is either not available, or if \fIitem\fR is not defined +therein, then \fBnl_langinfo()\fR returns a pointer to the corresponding string +in the C locale. In all locales, \fBnl_langinfo()\fR returns a pointer to an +empty string if \fIitem\fR contains an invalid setting. +.SH USAGE +.sp +.LP +The \fBnl_langinfo()\fR function can be used safely in multithreaded +applications, as long as \fBsetlocale\fR(3C) is not being called to change the +locale. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +CSIEnabled +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBsetlocale\fR(3C), \fBlanginfo.h\fR(3HEAD), \fBnl_types.h\fR(3HEAD), +\fBattributes\fR(5), \fBstandards\fR(5) +.SH WARNINGS +.sp +.LP +The array pointed to by the return value should not be modified by the program. +Subsequent calls to \fBnl_langinfo()\fR may overwrite the array. diff --git a/usr/src/man/man3c/offsetof.3c b/usr/src/man/man3c/offsetof.3c new file mode 100644 index 0000000000..2a3f7ac669 --- /dev/null +++ b/usr/src/man/man3c/offsetof.3c @@ -0,0 +1,45 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH offsetof 3C "29 Dec 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +offsetof \- offset of structure member +.SH SYNOPSIS +.LP +.nf +#include <stddef.h> + +\fBsize_t\fR \fBoffsetof\fR(\fB\fR\fItype\fR, \fB\fR\fImember-designator\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBoffsetof()\fR macro defined in <\fBstddef.h\fR> expands to an integral +constant expression that has type \fBsize_t\fR. The value of this expression is +the offset in bytes to the structure member (designated by +\fImember-designator\fR) from the beginning of its structure (designated by +\fItype\fR). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5) diff --git a/usr/src/man/man3c/opendir.3c b/usr/src/man/man3c/opendir.3c new file mode 100644 index 0000000000..dd9fc685e2 --- /dev/null +++ b/usr/src/man/man3c/opendir.3c @@ -0,0 +1,200 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH opendir 3C "26 Jun 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +opendir, fdopendir \- open directory +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <dirent.h> + +\fBDIR *\fR\fBopendir\fR(\fBconst char *\fR\fIdirname\fR); +.fi + +.LP +.nf +\fBDIR *\fR\fBfdopendir\fR(\fBint\fR \fIfildes\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBopendir()\fR function opens a directory stream corresponding to the +directory named by the \fIdirname\fR argument. +.sp +.LP +The \fBfdopendir()\fR function opens a directory stream for the directory file +descriptor \fIfildes\fR. The directory file descriptor should not be used or +closed following a successful function call, as this might cause undefined +results from future operations on the directory stream obtained from the call. +Use \fBclosedir\fR(3C) to close a directory stream. +.sp +.LP +The directory stream is positioned at the first entry. If the type \fBDIR\fR is +implemented using a file descriptor, applications will only be able to open up +to a total of {\fBOPEN_MAX\fR} files and directories. A successful call to any +of the \fBexec\fR functions will close any directory streams that are open in +the calling process. See \fBexec\fR(2). +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBopendir()\fR and \fBfdopendir()\fR return a +pointer to an object of type \fBDIR\fR. Otherwise, a null pointer is returned +and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBopendir()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 16n +.rt +Search permission is denied for the component of the path prefix of +\fIdirname\fR or read permission is denied for \fIdirname\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBELOOP\fR\fR +.ad +.RS 16n +.rt +Too many symbolic links were encountered in resolving \fIpath\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +The length of the \fIdirname\fR argument exceeds {\fBPATH_MAX\fR}, or a path +name component is longer than {\fBNAME_MAX\fR} while {\fB_POSIX_NO_TRUNC\fR} is +in effect. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 16n +.rt +A component of \fIdirname\fR does not name an existing directory or +\fIdirname\fR is an empty string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTDIR\fR\fR +.ad +.RS 16n +.rt +A component of \fIdirname\fR is not a directory. +.RE + +.sp +.LP +The \fBfdopendir()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOTDIR\fR\fR +.ad +.RS 11n +.rt +The file descriptor \fIfildes\fR does not reference a directory. +.RE + +.sp +.LP +The \fBopendir()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 16n +.rt +There are {\fBOPEN_MAX\fR} file descriptors currently open in the calling +process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +Pathname resolution of a symbolic link produced an intermediate result whose +length exceeds \fBPATH_MAX\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENFILE\fR\fR +.ad +.RS 16n +.rt +Too many files are currently open on the system. +.RE + +.SH USAGE +.sp +.LP +The \fBopendir()\fR and \fBfdopendir()\fR functions should be used in +conjunction with \fBreaddir\fR(3C), \fBclosedir\fR(3C) and \fBrewinddir\fR(3C) +to examine the contents of the directory (see the \fBEXAMPLES\fR section in +\fBreaddir\fR(3C)). This method is recommended for portability. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityT{ +\fBopendir()\fR is Standard; \fBfdopendir()\fR is Evolving +T} +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlstat\fR(2), \fBsymlink\fR(2), \fBclosedir\fR(3C), \fBreaddir\fR(3C), +\fBrewinddir\fR(3C), \fBscandir\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/perror.3c b/usr/src/man/man3c/perror.3c new file mode 100644 index 0000000000..93df640ca4 --- /dev/null +++ b/usr/src/man/man3c/perror.3c @@ -0,0 +1,72 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH perror 3C "12 Jul 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +perror, errno \- print system error messages +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBvoid\fR \fBperror\fR(\fBconst char *\fR\fIs\fR) +.fi + +.LP +.nf +#include <errno.h> + +int errno; +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBperror()\fR function produces a message on the standard error output +(file descriptor 2) describing the last error encountered during a call to a +system or library function. The argument string \fIs\fR is printed, followed by +a colon and a blank, followed by the message and a \fBNEWLINE\fR character. If +\fIs\fR is a null pointer or points to a null string, the colon is not printed. +The argument string should include the name of the program that incurred the +error. The error number is taken from the external variable \fBerrno\fR, which +is set when errors occur but not cleared when non-erroneous calls are made. See +\fBIntro\fR(2). +.sp +.LP +In the case of multithreaded applications, the \fB-mt\fR option must be +specified on the command line at compilation time (see \fBthreads\fR(5)). When +the \fB-mt\fR option is specified, \fBerrno\fR becomes a macro that enables +each thread to have its own \fBerrno\fR. This \fBerrno\fR macro can be used on +either side of the assignment as though it were a variable. +.SH USAGE +.sp +.LP +Messages printed from this function are in the native language specified by the +\fBLC_MESSAGES\fR locale category. See \fBsetlocale\fR(3C). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(2), \fBfmtmsg\fR(3C), \fBgettext\fR(3C), \fBsetlocale\fR(3C), +\fBstrerror\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5), \fBthreads\fR(5) diff --git a/usr/src/man/man3c/pfmt.3c b/usr/src/man/man3c/pfmt.3c new file mode 100644 index 0000000000..077331e6d2 --- /dev/null +++ b/usr/src/man/man3c/pfmt.3c @@ -0,0 +1,340 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pfmt 3C "29 Dec 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pfmt \- display error message in standard format +.SH SYNOPSIS +.LP +.nf +#include <pfmt.h> + +\fBint\fR \fBpfmt\fR(\fBFILE *\fR\fIstream\fR, \fBlong\fR \fIflags\fR, \fBchar *\fR\fIformat\fR, \fB\&... /*\fR \fIarg */\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpfmt()\fR retrieves a format string from a locale-specific message +database (unless \fBMM_NOGET\fR is specified) and uses it for \fBprintf\fR(3C) +style formatting of \fIargs\fR. The output is displayed on \fIstream\fR. +.sp +.LP +The \fBpfmt()\fR function encapsulates the output in the standard error message +format (unless \fBMM_NOSTD\fR is specified, in which case the output is similar +to \fBprintf()\fR). +.sp +.LP +If the \fBprintf()\fR format string is to be retrieved from a message database, +the \fBformat\fR argument must have the following structure: +.sp +.LP +\fI<catalog>\fR\fB:\fR\fI<msgnum>\fR\fB:\fR\fI<defmsg>\fR\&. +.sp +.LP +If \fBMM_NOGET\fR is specified, only the \fIdefmsg\fR field must be specified. +.sp +.LP +The \fIcatalog\fR field is used to indicate the message database that contains +the localized version of the format string. This field must be limited to 14 +characters selected from the set of all characters values, excluding \fB\e0\fR +(null) and the ASCII codes for \fB/\fR (slash) and \fB:\fR (colon). +.sp +.LP +The \fImsgnum\fR field is a positive number that indicates the index of the +string into the message database. +.sp +.LP +If the catalog does not exist in the locale (specified by the last call to +\fBsetlocale\fR(3C) using the \fBLC_ALL\fR or \fBLC_MESSAGES\fR categories), or +if the message number is out of bound, \fBpfmt()\fR will attempt to retrieve +the message from the C locale. If this second retrieval fails, \fBpfmt()\fR +uses the \fIdefmsg\fR field of the \fBformat\fR argument. +.sp +.LP +If \fIcatalog\fR is omitted, \fBpfmt()\fR will attempt to retrieve the string +from the default catalog specified by the last call to \fBsetcat\fR(3C). In +this case, the \fBformat\fR argument has the following structure: +.sp +.LP +\fB:\fR\fI<msgnum>\fR\fB:\fR\fI<defmsg>\fR\&. +.sp +.LP +The \fBpfmt()\fR will output \fBMessage not found!!\en\fR as format string if +\fIcatalog\fR is not a valid catalog name, if no catalog is specified (either +explicitely or with \fBsetcat()\fR), if \fImsgnum\fR is not a valid number, or +if no message could be retrieved from the message databases and \fIdefmsg\fR +was omitted. +.sp +.LP +The \fIflags\fR argument determine the type of output (such as whether the +\fBformat\fR should be interpreted as is or encapsulated in the standard +message format), and the access to message catalogs to retrieve a localized +version of \fBformat\fR. +.sp +.LP +The \fIflags\fR argument is composed of several groups, and can take the +following values (one from each group): +.sp +.LP +\fIOutput format control\fR +.sp +.ne 2 +.mk +.na +\fB\fBMM_NOSTD\fR\fR +.ad +.RS 12n +.rt +Do not use the standard message format, interpret \fBformat\fR as +\fBprintf()\fR \fBformat\fR. Only \fIcatalog access control flags\fR should be +specified if \fBMM_NOSTD\fR is used; all other flags will be ignored. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMM_STD\fR\fR +.ad +.RS 12n +.rt +Output using the standard message format (default value 0). +.RE + +.sp +.LP +\fICatalog access control\fR +.sp +.ne 2 +.mk +.na +\fB\fBMM_NOGET\fR\fR +.ad +.RS 12n +.rt +Do not retrieve a localized version of \fBformat\fR. In this case, only the +\fIdefmsg\fR field of the \fBformat\fR is specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMM_GET\fR\fR +.ad +.RS 12n +.rt +Retrieve a localized version of \fBformat\fR from the \fIcatalog\fR, using +\fImsgid\fR as the index and \fIdefmsg\fR as the default message (default value +0). +.RE + +.sp +.LP +\fISeverity (standard message format only)\fR +.sp +.ne 2 +.mk +.na +\fB\fBMM_HALT\fR\fR +.ad +.RS 14n +.rt +Generate a localized version of \fBHALT,\fR but do not halt the machine. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMM_ERROR\fR\fR +.ad +.RS 14n +.rt +Generate a localized version of \fBERROR\fR (default value 0). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMM_WARNING\fR\fR +.ad +.RS 14n +.rt +Generate a localized version of \fBWARNING.\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMM_INFO\fR\fR +.ad +.RS 14n +.rt +Generate a localized version of \fBINFO.\fR +.RE + +.sp +.LP +Additional severities can be defined. Add-on severities can be defined with +number-string pairs with numeric values from the range [5-255], using +\fBaddsev\fR(3C). The specified severity will be generated from the bitwise +\fBOR\fR operation of the numeric value and other \fIflags\fR If the severity +is not defined, \fBpfmt()\fR uses the string \fBSEV=\fR\fIN\fR, where \fIN\fR +is replaced by the integer severity value passed in \fIflags\fR. +.sp +.LP +Multiple severities passed in \fIflags\fR will not be detected as an error. Any +combination of severities will be summed and the numeric value will cause the +display of either a severity string (if defined) or the string +\fBSEV=\fR\fIN\fR (if undefined). +.sp +.LP +\fIAction\fR +.sp +.ne 2 +.mk +.na +\fB\fBMM_ACTION\fR\fR +.ad +.RS 13n +.rt +Specify an action message. Any severity value is superseded and replaced by a +localized version of \fBTO FIX\fR. +.RE + +.SH STANDARD ERROR MESSAGE FORMAT +.sp +.LP +The \fBpfmt()\fR function displays error messages in the following format: +.sp +.in +2 +.nf +\fIlabel\fR: \fIseverity\fR: \fItext\fR +.fi +.in -2 + +.sp +.LP +If no \fIlabel\fR was defined by a call to \fBsetlabel\fR(3C), the message is +displayed in the format: +.sp +.in +2 +.nf +\fIseverity\fR: \fItext\fR +.fi +.in -2 + +.sp +.LP +If \fBpfmt()\fR is called twice to display an error message and a helpful +\fIaction\fR or recovery message, the output can look like: +.sp +.in +2 +.nf +\fIlabel\fR: \fIseverity\fR: \fItext\fR\fIlabel\fR: TO FIX: \fItext\fR +.fi +.in -2 + +.br +.in +2 + +.in -2 +.br +.in +2 + +.in -2 +.SH RETURN VALUES +.sp +.LP +Upon success, \fBpfmt()\fR returns the number of bytes transmitted. Upon +failure, it returns a negative value: +.sp +.ne 2 +.mk +.na +\fB\fB\(mi1\fR\fR +.ad +.RS 9n +.rt +Write error to \fIstream\fR. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRExample of \fBpfmt()\fR function. +.sp +.LP +Example 1: + +.sp +.in +2 +.nf +setlabel("UX:test"); +pfmt(stderr, MM_ERROR, "test:2:Cannot open file: %s\en", + strerror(errno)); + +displays the message: + +UX:test: ERROR: Cannot open file: No such file or directory +.fi +.in -2 + +.sp +.LP +Example 2: + +.sp +.in +2 +.nf +setlabel("UX:test"); +setcat("test"); +pfmt(stderr, MM_ERROR, ":10:Syntax error\en"); +pfmt(stderr, MM_ACTION, "55:Usage ...\en"); +.fi +.in -2 + +.sp +.LP +displays the message + +.sp +.in +2 +.nf +UX:test: ERROR: Syntax error +UX:test: TO FIX: Usage ... +.fi +.in -2 + +.SH USAGE +.sp +.LP +Since it uses \fBgettxt\fR(3C), \fBpfmt()\fR should not be used. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBaddsev\fR(3C), \fBgettxt\fR(3C), \fBlfmt\fR(3C), \fBprintf\fR(3C), +\fBsetcat\fR(3C), \fBsetlabel\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5), +\fBenviron\fR(5) diff --git a/usr/src/man/man3c/plock.3c b/usr/src/man/man3c/plock.3c new file mode 100644 index 0000000000..6e75b4d1b4 --- /dev/null +++ b/usr/src/man/man3c/plock.3c @@ -0,0 +1,148 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH plock 3C "22 Mar 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +plock \- lock or unlock into memory process, text, or data +.SH SYNOPSIS +.LP +.nf +#include <sys/lock.h> + +\fBint\fR \fBplock\fR(\fBint\fR \fIop\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBplock()\fR function allows the calling process to lock or unlock into +memory its text segment (text lock), its data segment (data lock), or both its +text and data segments (process lock). Locked segments are immune to all +routine swapping. The effective user ID of the calling process must be +super-user to use this call. +.sp +.LP +The \fBplock()\fR function performs the function specified by \fIop\fR: +.sp +.ne 2 +.mk +.na +\fB\fBPROCLOCK\fR\fR +.ad +.RS 12n +.rt +Lock text and data segments into memory (process lock). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTXTLOCK\fR\fR +.ad +.RS 12n +.rt +Lock text segment into memory (text lock). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDATLOCK\fR\fR +.ad +.RS 12n +.rt +Lock data segment into memory (data lock). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUNLOCK\fR\fR +.ad +.RS 12n +.rt +Remove locks. +.RE + +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBplock()\fR function fails and does not perform the requested operation +if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +Not enough memory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIop\fR argument is equal to \fBPROCLOCK\fR and a process lock, a text +lock, or a data lock already exists on the calling process; the \fIop\fR +argument is equal to \fBTXTLOCK\fR and a text lock or a process lock already +exists on the calling process; the \fIop\fR argument is equal to \fBDATLOCK\fR +and a data lock or a process lock already exists on the calling process; or the +\fIop\fR argument is equal to \fBUNLOCK\fR and no lock exists on the calling +process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 10n +.rt +The {\fBPRIV_PROC_LOCK_MEMORY\fR} privilege is not asserted in the effective +set of the calling process. +.RE + +.SH USAGE +.sp +.LP +The \fBmlock\fR(3C) and \fBmlockall\fR(3C) functions are the preferred +interfaces for process locking. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBexec\fR(2), \fBexit\fR(2), \fBfork\fR(2), \fBmemcntl\fR(2), \fBmlock\fR(3C), +\fBmlockall\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/popen.3c b/usr/src/man/man3c/popen.3c new file mode 100644 index 0000000000..ade577bfce --- /dev/null +++ b/usr/src/man/man3c/popen.3c @@ -0,0 +1,223 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T. +.\" Portions Copyright (c) 1997, The Open Group. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH popen 3C "14 Dec 2006" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +popen, pclose \- initiate a pipe to or from a process +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBFILE *\fR\fBpopen\fR(\fBconst char *\fR\fIcommand\fR, \fBconst char *\fR\fImode\fR); +.fi + +.LP +.nf +\fBint\fR \fBpclose\fR(\fBFILE *\fR\fIstream\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpopen()\fR function creates a pipe between the calling program and the +command to be executed. The arguments to \fBpopen()\fR are pointers to +null-terminated strings. The \fIcommand\fR argument consists of a shell +command line. The \fImode\fR argument is an I/O mode, either \fBr\fR for +reading or \fIw\fR for writing. The value returned is a stream pointer such +that one can write to the standard input of the command, if the I/O mode is +\fIw\fR, by writing to the file \fIstream\fR (see \fBIntro\fR(3)); and one can +read from the standard output of the command, if the I/O mode is \fBr\fR, by +reading from the file \fIstream\fR. Because open files are shared, a type +\fBr\fR command may be used as an input filter and a type \fIw\fR as an output +filter. A trailing \fBF\fR character can also be included in the \fImode\fR +argument as described in \fBfopen\fR(3C) to enable extended FILE facility. +.sp +.LP +The environment of the executed command will be as if a child process were +created within the \fBpopen()\fR call using \fBfork\fR(2). If the application +is standard-conforming (see \fBstandards\fR(5)), the child is created as if +invoked with the call: +.sp +.LP +\fBexecl("/usr/xpg4/bin/sh", "sh", "\fR\fB-c\fR\fB",\fR\fIcommand\fR, \fB(char +*)0);\fR +.sp +.LP +otherwise, the child is created as if invoked with the call: +.sp +.LP +\fBexecl("/usr/bin/sh", "sh", "\fR\fB-c\fR\fB",\fR\fIcommand\fR, \fB(char +*)0);\fR +.sp +.LP +The \fBpclose()\fR function closes a stream opened by \fBpopen()\fR by closing +the pipe. It waits for the associated process to terminate and returns the +termination status of the process running the command language interpreter. +This is the value returned by \fBwaitpid\fR(3C). See \fBwait.h\fR(3HEAD) for +more information on termination status. If, however, a call to \fBwaitpid()\fR +with a \fIpid\fR argument equal to the process ID of the command line +interpreter causes the termination status to be unavailable to \fBpclose()\fR, +then \fBpclose()\fR returns \(mi1 with \fBerrno\fR set to \fBECHILD\fR to +report this condition. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBpopen()\fR returns a pointer to an open stream +that can be used to read or write to the pipe. Otherwise, it returns a null +pointer and may set \fBerrno\fR to indicate the error. +.sp +.LP +Upon successful completion, \fBpclose()\fR returns the termination status of +the command language interpreter as returned by \fBwaitpid()\fR. Otherwise, it +returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpclose()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBECHILD\fR\fR +.ad +.RS 10n +.rt +The status of the child process could not be obtained, as described in the +DESCRIPTION. +.RE + +.sp +.LP +The \fBpopen()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 10n +.rt +There are currently \fBFOPEN_MAX\fR or \fBSTREAM_MAX\fR streams open in the +calling process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fImode\fR argument is invalid. +.RE + +.sp +.LP +The \fBpopen()\fR function may also set \fBerrno\fR values as described by +\fBfork\fR(2) or \fBpipe\fR(2). +.SH USAGE +.sp +.LP +If the original and \fBpopen()\fR processes concurrently read or write a common +file, neither should use buffered I/O. Problems with an output filter may be +forestalled by careful buffer flushing, for example, with \fBfflush()\fR (see +\fBfclose\fR(3C)). A security hole exists through the \fBIFS\fR and \fBPATH\fR +environment variables. Full pathnames should be used (or \fBPATH\fR reset) and +\fBIFS\fR should be set to space and tab (\fB" \et"\fR). +.sp +.LP +Even if the process has established a signal handler for \fBSIGCHLD\fR, it will +be called when the command terminates. Even if another thread in the same +process issues a \fBwait\fR(3C) call, it will interfere with the return value +of \fBpclose()\fR. Even if the process's signal handler for \fBSIGCHLD\fR has +been set to ignore the signal, there will be no effect on \fBpclose()\fR. +.SH EXAMPLES +.LP +\fBExample 1 \fR\fBpopen()\fR example +.sp +.LP +The following program will print on the standard output (see \fBstdio\fR(3C)) +the names of files in the current directory with a \fB\&.c\fR suffix. + +.sp +.in +2 +.nf +#include <stdio.h> +#include <stdlib.h> +main(\|) +{ + char *cmd = "/usr/bin/ls *.c"; + char buf[BUFSIZ]; + FILE *ptr; + + if ((ptr = popen(cmd, "r")) != NULL) { + while (fgets(buf, BUFSIZ, ptr) != NULL) + (void) printf("%s", buf); + (void) pclose(ptr); + } + return 0; +} +.fi +.in -2 + +.LP +\fBExample 2 \fR\fBsystem()\fR replacement +.sp +.LP +The following function can be used in a multithreaded process in place of the +most common usage of the Unsafe \fBsystem\fR(3C) function: + +.sp +.in +2 +.nf +int my_system(const char *cmd) +{ + FILE *p; + + if ((p = popen(cmd, "w")) == NULL) + return (-1); + return (pclose(p)); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilitySee below. +_ +MT-LevelSafe +.TE + +.sp +.LP +The \fBF\fR character in the \fImode\fR argument of \fBpopen()\fR is Evolving. +In all other respects this function is Standard. The \fBpclose()\fR function is +Standard. +.SH SEE ALSO +.sp +.LP +\fBksh\fR(1), \fBpipe\fR(2), \fBfclose\fR(3C), \fBfopen\fR(3C), +\fBposix_spawn\fR(3C), \fBstdio\fR(3C), \fBsystem\fR(3C), \fBwait\fR(3C), +\fBwaitpid\fR(3C), \fBwait.h\fR(3HEAD), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/port_alert.3c b/usr/src/man/man3c/port_alert.3c new file mode 100644 index 0000000000..e3e2a01a4f --- /dev/null +++ b/usr/src/man/man3c/port_alert.3c @@ -0,0 +1,147 @@ +'\" te +.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH port_alert 3C "1 Oct 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +port_alert \- set a port in alert mode +.SH SYNOPSIS +.LP +.nf +#include <port.h> + +\fBint\fR \fBport_alert\fR(\fBint\fR \fIport\fR, \fBint\fR \fIflags\fR, \fBint\fR \fIevents\fR, \fBvoid *\fR\fIuser\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBport_alert()\fR function transitions a port into or out of alert mode. +A port in alert mode immediately awakens all threads blocked in +\fBport_get\fR(3C) or \fBport_getn\fR(3C). These threads return with an alert +notification that consists of a single \fBport_event_t\fR structure with the +source \fBPORT_SOURCE_ALERT\fR. Subsequent threads trying to retrieve events +from a port that is in alert mode will return immediately with the alert +notification. +.sp +.LP +A port is transitioned into alert mode by calling the \fBport_alert()\fR +function with a non-zero \fIevents\fR parameter. The specified \fIevents\fR +and \fIuser\fR parameters will be made available in the \fBportev_events\fR and +the \fBportev_user\fR members of the alert notification, respectively. The +\fIflags\fR argument determines the mode of operation of the alert mode: +.RS +4 +.TP +.ie t \(bu +.el o +If \fIflags\fR is set to \fBPORT_ALERT_SET\fR, \fBport_alert()\fR sets the port +in alert mode independent of the current state of the port. The +\fBportev_events\fR and \fBportev_user\fR members are set or updated +accordingly. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If \fIflags\fR is set to \fBPORT_ALERT_UPDATE\fR and the port is not in alert +mode, \fBport_alert()\fR transitions the port into alert mode. The +\fBportev_events\fR and \fBportev_user\fR members are set accordingly. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If \fIflags\fR is set to \fBPORT_ALERT_UPDATE\fR and the port is already in +alert mode, \fBport_alert()\fR returns with an error value of \fBEBUSY\fR. +.RE +.sp +.LP +\fBPORT_ALERT_SET\fR and \fBPORT_ALERT_UPDATE\fR are mutually exclusive. +.sp +.LP +A port is transitioned out of alert mode by calling the \fBport_alert()\fR +function with a zero \fIevents\fR parameter. +.sp +.LP +Events can be queued to a port that is in alert mode, but they will not be +retrievable until the port is transitioned out of alert mode. +.SH RETURN VALUES +.sp +.LP +Upon succesful completion, 0 is returned. Otherwise, -1 is returned and +\fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBport_alert()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The port identifier is not valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADFD\fR\fR +.ad +.RS 10n +.rt +The \fIport\fR argument is not an event port file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBUSY\fR\fR +.ad +.RS 10n +.rt +The port is already in alert mode. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +Mutually exclusive \fIflags\fR are set. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Architectureall +_ +Interface StabilityEvolving +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBport_associate\fR(3C), \fBport_create\fR(3C), \fBport_get\fR(3C), +\fBport_send\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/port_associate.3c b/usr/src/man/man3c/port_associate.3c new file mode 100644 index 0000000000..c19189e670 --- /dev/null +++ b/usr/src/man/man3c/port_associate.3c @@ -0,0 +1,452 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH port_associate 3C "9 Nov 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +port_associate, port_dissociate \- associate or dissociate the object with the +port +.SH SYNOPSIS +.LP +.nf +#include <port.h> + +\fBint\fR \fBport_associate\fR(\fBint\fR \fIport\fR, \fBint\fR \fIsource\fR, \fBuintptr_t\fR \fIobject\fR, + \fBint\fR \fIevents\fR, \fBvoid *\fR\fIuser\fR); +.fi + +.LP +.nf +\fBint\fR \fBport_dissociate\fR(\fBint\fR \fIport\fR, \fBint\fR \fIsource\fR, \fBuintptr_t\fR \fIobject\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBport_associate()\fR function associates specific \fIevents\fR of a given +\fIobject\fR with a \fIport\fR. Only objects associated with a particular port +are able to generate events that can be retrieved using \fBport_get\fR(3C) or +\fBport_getn\fR(3C). The delivery event has its \fBportev_user\fR member set to +the value specified in the \fIuser\fR parameter. If the specified object is +already associated with the specified port, the \fBport_associate()\fR function +serves to update the \fIevents\fR and \fIuser\fR arguments of the association. +The \fBport_dissociate()\fR function removes the association of an object with +a port. +.sp +.LP +The objects that can be associated with a port by way of the +\fBport_associate()\fR function are objects of type \fBPORT_SOURCE_FD\fR and +\fBPORT_SOURCE_FILE\fR. Objects of other types have type-specific association +mechanisms. A \fBport_notify_t\fR structure, defined in \fB<port.h>\fR, is used +to specify the event port and an application-defined cookie to associate with +these event sources. See \fBport_create\fR(3C) and \fBsignal.h\fR(3HEAD). +.sp +.LP +The \fBport_notify_t\fR structure contains the following members: +.sp +.in +2 +.nf +int portntfy_port; /* bind request(s) to port */ +void *portntfy_user; /* user defined cookie */ +.fi +.in -2 + +.sp +.LP +Objects of type \fBPORT_SOURCE_FD\fR are file descriptors. The event types for +\fBPORT_SOURCE_FD\fR objects are described in \fBpoll\fR(2). At most one event +notification will be generated per associated file descriptor. For example, if +a file descriptor is associated with a port for the \fBPOLLRDNORM\fR event and +data is available on the file descriptor at the time the \fBport_associate()\fR +function is called, an event is immediately sent to the port. If data is not +yet available, one event is sent to the port when data first becomes available. +.sp +.LP +When an event for a \fBPORT_SOURCE_FD\fR object is retrieved, the object no +longer has an association with the port. The event can be processed without +the possibility that another thread can retrieve a subsequent event for the +same object. After processing of the file descriptor is completed, the +\fBport_associate()\fR function can be called to reassociate the object with +the port. +.sp +.LP +Objects of type \fBPORT_SOURCE_FILE\fR are pointer to the structure +\fBfile_obj\fR defined in \fB<sys/port.h>\fR. This event source provides event +notification when the specified file/directory is accessed or modified or when +its status changes. The path name of the file/directory to be watched is passed +in the \fBstruct file_obj\fR along with the \fBaccess\fR, \fBmodification\fR, +and \fBchange\fR time stamps acquired from a \fBstat\fR(2) call. If the file +name is a symbolic links, it is followed by default. The \fBFILE_NOFOLLOW\fR +needs to be passed in along with the specified events if the symbolic link +itself needs to be watched and \fBlstat()\fR needs to be used to get the file +status of the symbolic link file. +.sp +.LP +The \fBstruct file_obj\fR contains the following elements: +.sp +.in +2 +.nf +timestruc_t fo_atime; /* Access time got from stat() */ +timestruc_t fo_mtime; /* Modification time from stat() */ +timestruc_t fo_ctime; /* Change time from stat() */ +char *fo_name; /* Pointer to a null terminated path name */ +.fi +.in -2 + +.sp +.LP +At the time the \fBport_associate()\fR function is called, the time stamps +passed in the structure \fBfile_obj\fR are compared with the file or +directory's current time stamps and, if there has been a change, an event is +immediately sent to the port. If not, an event will be sent when such a change +occurs. +.sp +.LP +The event types that can be specified at \fBport_associate()\fR time for +\fBPORT_SOURCE_FILE\fR are \fBFILE_ACCESS\fR, \fBFILE_MODIFIED\fR, and +\fBFILE_ATTRIB\fR, corresponding to the three time stamps. An \fBfo_atime\fR +change results in the \fBFILE_ACCESS\fR event, an \fBfo_mtime\fR change results +in the \fBFILE_MODIFIED\fR event, and an \fBfo_time\fR change results in the +\fBFILE_ATTRIB\fR event. +.sp +.LP +The following exception events are delivered when they occur. These event types +cannot be filtered. +.sp +.in +2 +.nf +FILE_DELETE /* Monitored file/directory was deleted */ +FILE_RENAME_TO /* Monitored file/directory was renamed */ +FILE_RENAME_FROM /* Monitored file/directory was renamed */ +UNMOUNTED /* Monitored file system got unmounted */ +MOUNTEDOVER /* Monitored file/directory was mounted over */ +.fi +.in -2 + +.sp +.LP +At most one event notification will be generated per associated \fBfile_obj\fR. +When the event for the associated \fBfile_obj\fR is retrieved, the object is no +longer associated with the port. The event can be processed without the +possibility that another thread can retrieve a subsequent event for the same +object. The \fBport_associate()\fR can be called to reassociate the +\fBfile_obj\fR object with the port. +.sp +.LP +The association is also removed if the port gets closed or when +\fBport_dissociate()\fR is called. +.sp +.LP +The parent and child processes are allowed to retrieve events from file +descriptors shared after a call to \fBfork\fR(2). The process performing the +first association with a port (parent or child process) is designated as the +owner of the association. Only the owner of an association is allowed to +dissociate the file descriptor from a port. The association is removed if the +owner of the association closes the port . +.sp +.LP +On NFS file systems, events from only the client side (local) +access/modifications to files or directories will be delivered. +.SH RETURN VALUES +.sp +.LP +Upon succesful completion, 0 is returned. Otherwise, \(mi1 is returned and +\fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBport_associate()\fR and \fBport_dissociate()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIport\fR identifier is not valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADFD\fR\fR +.ad +.RS 10n +.rt +The \fIsource\fR argument is of type \fBPORT_SOURCE_FD\fR and the object +argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIsource\fR argument is not valid. +.RE + +.sp +.LP +The \fBport_associate()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 11n +.rt +The source argument is \fBPORT_SOURCE_FILE\fR and, Search permission is denied +on a component of path prefix or the file exists and the permissions, +corresponding to the events argument, are denied. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 11n +.rt +The maximum number of objects associated with the port was exceeded. The +maximum allowable number of events or association of objects per port is the +minimum value of the \fBprocess.max-port-events\fR resource control at the time +\fBport_create\fR(3C) was used to create the port. See \fBsetrctl\fR(2) and +\fBrctladm\fR(1M) for information on using resource controls. +.sp +The number of objects associated with a port is composed of all supported +resource types. Some of the source types do not explicitly use the +\fBport_associate()\fR function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 11n +.rt +The source argument is \fBPORT_SOURCE_FILE\fR and the file does not exist or +the path prefix does not exist or the path points to an empty string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 11n +.rt +The physical memory limits of the system have been exceeded. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSUP\fR\fR +.ad +.RS 11n +.rt +The source argument is \fBPORT_SOURCE_FILE\fR and the file system on which the +specified file resides, does not support watching for file events +notifications. +.RE + +.sp +.LP +The \fBport_dissociate()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 10n +.rt +The process is not the owner of the association. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 10n +.rt +The specified object is not associated with the port. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRRetrieve data from a pipe file descriptor. +.sp +.LP +The following example retrieves data from a pipe file descriptor. + +.sp +.in +2 +.nf +#include <port.h> + +int port; +int fd; +int error; +int index; +void *mypointer; +port_event_t pev; +struct timespec_t timeout; +char rbuf[STRSIZE]; +int fds[MAXINDEX]; + +/* create a port */ +port = port_create(); + +for (index = 0; index < MAXINDEX; index++) { + error = mkfifo(name[index], S_IRWXU | S_IRWXG | S_IRWXO); + if (error) + /* handle error code */ + fds[index] = open(name[index], O_RDWR); + + /* associate pipe file descriptor with the port */ + error = port_associate(port, PORT_SOURCE_FD, fds[index], + POLLIN, mypointer); +} +\&... +timeout.tv_sec = 1; /* user defined */ +timeout.tv_nsec = 0; + +/* loop to retrieve data from the list of pipe file descriptors */ +for (...) { + /* retrieve a single event */ + error = port_get(port, &pev, &timeout); + if (error) { + /* handle error code */ + } + fd = pev.portev_object; + if (read(fd, rbuf, STRSIZE)) { + /* handle error code */ + } + if (fd-still-accepting-data) { + /* + * re-associate the file descriptor with the port. + * The re-association is required for the + * re-activation of the data detection. + * Internals events and user arguments are set to the + * new (or the same) values delivered here. + */ + error = port_associate(port, PORT_SOURCE_FD, fd, POLLIN, + pev.portev_user); + } else { + /* + * If file descriptor is no longer required, + * - it can remain disabled but still associated with + * the port, or + * - it can be dissociated from the port. + */ + } +.fi +.in -2 + +.LP +\fBExample 2 \fRBind AIO transaction to a specific port. +.sp +.LP +The following example binds the AIO transaction to a specific port. + +.sp +.in +2 +.nf +#include <port.h> + +int port; +port_notify_t pn; +aiocb_t aiocb; +aiocb_t *aiocbp; +void *mypointer; +int error; +int my_errno; +int my_status; +struct timespec_t timeout; +port_event_t pev; + +port = port_create(); +\&... +/* fill AIO specific part */ +aiocb.aio_fildes = fd; +aiocb.aio_nbytes = BUFSIZE; +aiocb.aio_buf = bufp; +aiocb.aio_offset = 0; + +/* port specific part */ +pn.portnfy_port = port; +pn.portnfy_user = mypointer; +aiocb.aio_sigevent.sigev_notify = SIGEV_PORT; +aiocb.aio_sigevent.sigev_value.sival_ptr = &pn + +/* + * The aio_read() function binds internally the asynchronous I/O + * transaction with the port delivered in port_notify_t. + */ +error = aio_read(&aiocb); + +timeout.tv_sec = 1; /* user defined */ +timeout.tv_nsec = 0; + +/* retrieve a single event */ +error = port_get(port, &pev, &timeout); +if (error) { + /* handle error code */ +} + +/* + * pev.portev_object contains a pointer to the aiocb structure + * delivered in port_notify_t (see aio_read()). + */ +aiocbp = pev.portev_object; + +/* check error code and return value in +my_errno = aio_error(aiocbp); +\&... +my_status = aio_return(aiocbp); +\&... +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Architectureall +_ +Interface StabilityCommitted +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBrctladm\fR(1M), \fBpoll\fR(2), \fBsetrctl\fR(2), \fBport_alert\fR(3C), +\fBport_create\fR(3C), \fBport_get\fR(3C), \fBport_send\fR(3C), +\fBsignal.h\fR(3HEAD), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/port_create.3c b/usr/src/man/man3c/port_create.3c new file mode 100644 index 0000000000..54a6cc9a49 --- /dev/null +++ b/usr/src/man/man3c/port_create.3c @@ -0,0 +1,169 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH port_create 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +port_create \- create a port +.SH SYNOPSIS +.LP +.nf +#include <port.h> + +\fBint\fR \fBport_create\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBport_create()\fR function establishes a queue that multiplexes events +from disjoint sources. Each source has a corresponding object type and +source-specific mechanism for associating an object with a port. +.sp + +.sp +.TS +tab(); +cw(1.83i) cw(1.83i) cw(1.83i) +lw(1.83i) lw(1.83i) lw(1.83i) +. +sourceobject typeassociation mechanism +_ +\fBPORT_SOURCE_AIO\fR\fBstruct aiocb\fRT{ +\fBaio_read\fR(3C), \fBaio_write\fR(3C), \fBlio_listio\fR(3C) +T} +\fBPORT_SOURCE_FD\fRfile descriptor\fBport_associate\fR(3C) +\fBPORT_SOURCE_MQ\fR\fBmqd_t\fR\fBmq_notify\fR(3C) +\fBPORT_SOURCE_TIMER\fR\fBtimer_t\fR\fBtimer_create\fR(3C) +\fBPORT_SOURCE_USER\fR\fBuintptr_t\fR\fBport_send\fR(3C) +\fBPORT_SOURCE_ALERT\fR\fBuintptr_t\fR\fBport_alert\fR(3C) +\fBPORT_SOURCE_FILE\fR\fBfile_obj_t\fR\fBport_associate\fR(3C) +.TE + +.sp +.LP +\fBPORT_SOURCE_AIO\fR events represent the completion of an asynchronous I/O +transaction. An asynchronous I/O transaction is associated with a port by +specifying \fBSIGEV_PORT\fR as its notification mechanism. See +\fBaio_read\fR(3C), \fBaio_write\fR(3C), \fBlio_listio\fR(3C), and +\fBaio.h\fR(3HEAD) for details. +.sp +.LP +\fBPORT_SOURCE_FD\fR events represent a transition in the \fBpoll\fR(2) status +of a given file descriptor. Once an event is delivered, the file descriptor is +no longer associated with the port. A file descriptor is associated (or +re-associated) with a port using the \fBport_associate\fR(3C) function. +.sp +.LP +\fBPORT_SOURCE_MQ\fR events represent a message queue transition from empty to +non-empty. A message queue is associated with a port by specifying +\fBSIGEV_PORT\fR as its notification mechanism. See \fBmq_notify\fR(3C) for +more information. +.sp +.LP +\fBPORT_SOURCE_TIMER\fR events represent one or more timer expirations for a +given timer. A timer is associated with a port by specifying \fBSIGEV_PORT\fR +as its notification mechanism. See \fBtimer_create\fR(3C) for more information. +.sp +.LP +\fBPORT_SOURCE_USER\fR events represent user-defined events. These events are +generated by \fBport_send\fR(3C) or \fBport_sendn\fR(3C). +.sp +.LP +\fBPORT_SOURCE_ALERT\fR events indicate that the port itself is in alert mode. +The mode of the port is changed with \fBport_alert\fR(3C).The +\fBport_create()\fR function returns a file descriptor that represents a newly +created port. The \fBclose\fR(2) function destroys the port and frees all +allocated resources. +.sp +.LP +\fBPORT_SOURCE_FILE\fR events represent file/directory status change. Once an +event is delivered, the file object associated with the port is no longer +active. It has to be reassociated to activate. A file object is associated or +reassociated with a port using the \fBport_associate\fR(3C). +.sp +.LP +The \fBport_get\fR(3C) and \fBport_getn\fR(3C) functions retrieve events from a +port. They ignore non retrievable events (non-own or non-shareable events). +.sp +.LP +As a port is represented by a file descriptor, ports are shared between child +and parent processes after \fBfork()\fR. Both can continue to associate +sources with the port, both can receive events from the port, and events +associated with and/or generated by either process are retrievable in the +other. Since some events might not have meaning in both parent and child, care +must be taken when using ports after \fBfork()\fR. +.sp +.LP +If a port is exported to other processes, the port is destroyed on last close. +.sp +.LP +\fBPORT_SOURCE_USER\fR and \fBPORT_SOURCE_ALERT\fR events can be distributed +across processes. \fBPORT_SOURCE_FD\fR events can only be shared between +processes when child processes inherit opened file decriptors from the parent +process. See \fBfork\fR(2). \fBPORT_SOURCE_TIMER\fR and \fBPORT_SOURCE_AIO\fR +cannot be shared between processes. +.SH RETURN VALUES +.sp +.LP +Upon succesful completion, the \fBport_create()\fR function returns a +non-negative value, the port identifier. Otherwise, \(mi1 is returned and errno +is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBport_create()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +The maximum allowable number of ports is currently open in the system. The +maximum allowable number of ports is the minimum value of the +\fBproject.max-port-ids\fR resource control. See \fBsetrctl\fR(2) and +\fBrctladm\fR(1M) for information on using resource controls. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 10n +.rt +The process has too many open descriptors. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Architectureall +_ +Interface StabilityCommitted +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBrctladm\fR(1M), \fBclose\fR(2), \fBexit\fR(2), \fBfork\fR(2), \fBpoll\fR(2), +\fBsetrctl\fR(2), \fBaio_read\fR(3C), \fBaio_write\fR(3C), \fBaio.h\fR(3HEAD), +\fBlio_listio\fR(3C), \fBmq_notify\fR(3C), \fBport_associate\fR(3C), +\fBport_get\fR(3C), \fBtimer_create\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/port_get.3c b/usr/src/man/man3c/port_get.3c new file mode 100644 index 0000000000..54575a1e71 --- /dev/null +++ b/usr/src/man/man3c/port_get.3c @@ -0,0 +1,307 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH port_get 3C "31 Jan 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +port_get, port_getn \- retrieve event information from a port +.SH SYNOPSIS +.LP +.nf +#include <port.h> + +\fBint\fR \fBport_get\fR(\fBint\fR \fIport\fR, \fBport_event_t *\fR\fIpe\fR, + \fBconst timespec_t *\fR\fItimeout\fR); +.fi + +.LP +.nf +\fBint\fR \fBport_getn\fR(\fBint\fR \fIport\fR, \fBport_event_t\fR \fIlist\fR[], \fBuint_t\fR \fImax\fR, + \fBuint_t *\fR\fInget\fR, \fBconst timespec_t *\fR\fItimeout\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBport_get()\fR and \fBport_getn()\fR functions retrieve events from a +port. The \fBport_get()\fR function retrieves at most a single event. The +\fBport_getn()\fR function can retrieve multiple events. +.sp +.LP +The \fIpe\fR argument points to an uninitialized \fBport_event_t\fR structure +that is filled in by the system when the \fBport_get()\fR function returns +successfully. +.sp +.LP +The \fBport_event_t\fR structure contains the following members: +.sp +.in +2 +.nf +int portev_events; /* detected events */ +ushort_t portev_source; /* event source */ +uintptr_t portev_object; /* specific to event source */ +void *portev_user; /* user defined cookie */ +.fi +.in -2 + +.sp +.LP +The \fBportev_events\fR and \fBportev_object\fR members are specific to the +event source. The \fBportev_events\fR denotes the delivered events. The +\fBportev_object\fR refers to the associated object (see +\fBport_create\fR(3C)). The \fBportev_source\fR member specifies the source of +the event. The \fBportev_user\fR member is a user-specified value. +.sp +.LP +If the \fItimeout\fR pointer is \fINULL\fR, the \fBport_get()\fR function +blocks until an event is available. To poll for an event without waiting, +\fItimeout\fR should point to a zeroed \fBtimespec\fR. A non-zeroed +\fBtimespec\fR specifies the desired time to wait for events. The +\fBport_get()\fR function returns before the timeout elapses if an event is +available, a signal occurs, a port is closed by another thread, or the port is +in or enters alert mode. See \fBport_alert\fR(3C) for details on alert mode. +.sp +.LP +The \fBport_getn()\fR function can retrieve multiple events from a port. The +\fIlist\fR argument is an array of uninitialized \fBport_event_t\fR structures +that is filled in by the system when the \fBport_getn()\fR function returns +succesfully. The \fInget\fR argument points to the desired number of events to +be retrieved. The \fImax\fR parameter specifies the maximum number of events +that can be returned in \fIlist\fR[]. If \fImax\fR is 0, the value pointed to +by \fInget\fR is set to the number of events available on the port. The +\fBport_getn()\fR function returns immediately but no events are retrieved. +.sp +.LP +The \fBport_getn()\fR function block until the desired number of events are +available, the timeout elapses, a signal occurs, a port is closed by another +thread, or the port is in or enters alert mode. +.sp +.LP +On return, the value pointed to by \fInget\fR is updated to the actual number +of events retrieved in list. +.sp +.LP +Threads calling the \fBport_get()\fR function might starve threads waiting in +the \fBport_getn()\fR function for more than one event. Similarly, threads +calling the \fBport_getn()\fR function for \fIn\fR events might starve threads +waiting in the \fBport_getn()\fR function for more than \fIn\fR events. +.sp +.LP +The \fBport_get()\fR and the \fBport_getn()\fR functions ignore non-shareable +events (see \fBport_create\fR(3C)) generated by other processes. +.SH RETURN VALUES +.sp +.LP +Upon succesful completion, 0 is returned. Otherwise, -1 is returned and errno +is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBport_get()\fR and \fBport_getn()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIport\fR identifier is not valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADFD\fR\fR +.ad +.RS 10n +.rt +The \fIport\fR argument is not an event port file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +.rt +Event or event list can not be delivered (\fIlist\fR[] pointer and/or user +space reserved to accomodate the list of events is not reasonable), or the +\fItimeout\fR argument is not reasonable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 10n +.rt +A signal was caught during the execution of the function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fItimeout\fR element \fBtv_sec\fR is < 0 or the \fItimeout\fR element +\fBtv_nsec\fR is < 0 or > 1000000000. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBETIME\fR\fR +.ad +.RS 10n +.rt +The time interval expired before the expected number of events have been posted +to the port. +.RE + +.sp +.LP +The \fBport_getn()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIlist\fR[] argument is \fINULL\fR, the \fInget\fR argument is \fINULL\fR, +or the content of \fInget\fR is > \fImax\fR and \fImax\fR is > 0. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +.rt +The \fItimeout\fR argument is not reasonable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBETIME\fR\fR +.ad +.RS 10n +.rt +The time interval expired before the expected number of events have been posted +to the port (original value in \fInget\fR), or \fInget\fR is updated with the +number of returned \fBport_event_t\fR structures in \fIlist\fR[]. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRSend a user event (PORT_SOURCE_USER) to a port and retrieve it +with \fBport_get()\fR. +.sp +.LP +The following example sends a user event (\fBPORT_SOURCE_USER\fR) to a port and +retrieves it with \fBport_get()\fR. The \fBportev_user\fR and +\fBportev_events\fR members of the \fBport_event_t\fR structure are the same as +the corresponding user and events arguments of the \fBport_send\fR(3C) +function. + +.sp +.in +2 +.nf +#include <port.h> + +int myport; +port_event_t pe; +struct timespec timeout; +int ret; +void *user; +uintptr_t object; + +myport = port_create(); +if (myport < 0) { + /* port creation failed ... */ + ... + return(...); +} +\&... +events = 0x01; /* own event definition(s) */ +object = <myobject>; +user = <my_own_value>; +ret = port_send(myport, events, user); +if (ret == -1) { + /* error detected ... */ + ... + close(myport); + return (...); +} + +/* + * The following code could also be executed in another thread or + * process. + */ +timeout.tv_sec = 1; /* user defined */ +timeout.tv_nsec = 0; +ret = port_get(myport, &pe, &timeout); +if (ret == -1) { + /* + * error detected : + * - EINTR or ETIME : log error code and try again ... + * - Other kind of errors : may have to close the port ... + */ + return(...); +} + +/* + * After port_get() returns successfully, the port_event_t + * structure will be filled with: + * pe.portev_source = PORT_SOURCE_USER + * pe.portev_events = 0x01 + * pe.portev_object = <myobject> + * pe.portev_user = <my_own_value> + */ +\&... +close(myport); +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Architectureall +_ +Interface StabilityEvolving +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBport_alert\fR(3C), \fBport_associate\fR(3C), \fBport_create\fR(3C), +\fBport_send\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/port_send.3c b/usr/src/man/man3c/port_send.3c new file mode 100644 index 0000000000..841b6dfb29 --- /dev/null +++ b/usr/src/man/man3c/port_send.3c @@ -0,0 +1,238 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH port_send 3C "24 Oct 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +port_send, port_sendn \- send a user-defined event to a port or list of ports +.SH SYNOPSIS +.LP +.nf +#include <port.h> + +\fBint\fR \fBport_send\fR(\fBint\fR \fIport\fR, \fBint\fR \fIevents\fR, \fBvoid *\fR\fIuser\fR); +.fi + +.LP +.nf +\fBint\fR \fBport_sendn\fR(\fBint\fR \fIports\fR[], \fBint\fR \fIerrors\fR[], \fBuint_t\fR \fInent\fR, + \fBint\fR \fIevents\fR, \fBvoid *\fR\fIuser\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBport_send()\fR function submits a user-defined event to a specified +port. The \fIport\fR argument is a file descriptor that represents a port. The +sent event has its \fBportev_events\fR member set to the value specified in the +\fIevents\fR parameter and its \fBportev_user\fR member set to the value +specified in the \fIuser\fR parameter. The \fBportev_object\fR member of an +event sent with \fBport_send()\fR is unspecified. +.sp +.LP +The \fBport_sendn()\fR function submits a user-defined event to multiple ports. +The \fIports\fR argument is an array of file descriptors that represents ports +(see \fBport_create\fR(3C)). The \fInent\fR argument specifies the number of +file descriptors in the \fIports\fR[] array. An event is submitted to each +specified port. Each event has its \fBportev_events\fR member set to the value +specified in the \fIevents\fR parameter and its \fBportev_user\fR member set to +the value specified in the \fIuser\fR parameter. The \fBportev_object\fR +member of \fIevents\fR sent with \fBport_sendn()\fR is unspecified. +.sp +.LP +A port that is in alert mode can be sent an event, but that event will not be +retrievable until the port has resumed normal operation. See +\fBport_alert\fR(3C). +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBport_send()\fR function returns 0. +Otherwise, it returns \(mi1 and sets \fBerrno\fR to indicate the error. +.sp +.LP +The \fBport_sendn()\fR function returns the number of successfully submitted +events. A non-negative return value less than the \fInent\fR argument +indicates that at least one error occurred. In this case, each element of the +\fIerrors\fR[] array is filled in. An element of the \fIerrors\fR[] array is +set to 0 if the event was successfully sent to the corresponding port in the +\fIports\fR[] array, or is set to indicate the error if the event was not +successfully sent. If an error occurs, the \fBport_sendn()\fR function returns +\(mi1 and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBport_send()\fR and \fBport_sendn()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +The maximum number of events per port is exceeded. The maximum allowable +number of events per port is the minimum value of the +\fBprocess.max-port-events\fR resource control at the time +\fBport_create\fR(3C) was used to create the port. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The port file descriptor is not valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADFD\fR\fR +.ad +.RS 10n +.rt +The \fIport\fR argument is not an event port file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +There is not enough memory available to satisfy the request. +.RE + +.sp +.LP +The \fBport_sendn()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +.rt +The \fIports\fR[] pointer or \fIerrors\fR[] pointer is not reasonable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of the \fInent\fR argument is 0. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRUse \fBport_send()\fR to send a user event (PORT_SOURCE_USER) +to a port. +.sp +.LP +The following example uses \fBport_send()\fR to send a user event +(\fBPORT_SOURCE_USER\fR) to a port and \fBport_get()\fR to retrieve it. The +\fBportev_user\fR and \fBportev_events\fR members of the \fBport_event_t\fR +structure are the same as the corresponding user and events arguments of the +\fBport_send()\fR function. + +.sp +.in +2 +.nf +#include <port.h> + +int myport; +port_event_t pe; +struct timespec timeout; +int ret; +void *user; + +myport = port_create(); +if (myport) { + /* port creation failed ... */ + ... + return(...); +} +\&... +events = 0x01; /* own event definition(s) */ +user = <my_own_value>; +ret = port_send(myport, events, user); +if (ret == -1) { + /* error detected ... */ + ... + close(myport); + return (...); +} + +/* + * The following code could also be executed from another thread or + * process. + */ +timeout.tv_sec = 1; /* user defined */ +timeout.tv_nsec = 0; +ret = port_get(myport, &pe, &timeout); +if (ret == -1) { + /* + * error detected : + * - EINTR or ETIME : log error code and try again ... + * - Other kind of errors : may have to close the port ... + */ + return(...); +} + +/* + * After port_get() returns successfully, the port_event_t + * structure will be filled with: + * pe.portev_source = PORT_SOURCE_USER + * pe.portev_events = 0x01 + * pe.portev_object = unspecified + * pe.portev_user = <my_own_value> + */ +\&... +close(myport); +.fi +.in -2 + +.SH USAGE +.sp +.LP +See \fBsetrctl\fR(2) and \fBrctladm\fR(1M) for information on using resource +controls. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Architectureall +_ +Interface StabilityCommitted +_ +MT-LevelAsync-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBrctladm\fR(1M), \fBsetrctl\fR(2), \fBport_alert\fR(3C), +\fBport_associate\fR(3C), \fBport_create\fR(3C), \fBport_get\fR(3C), +\fBattributes\fR(5) diff --git a/usr/src/man/man3c/posix_fadvise.3c b/usr/src/man/man3c/posix_fadvise.3c new file mode 100644 index 0000000000..1d28ec3952 --- /dev/null +++ b/usr/src/man/man3c/posix_fadvise.3c @@ -0,0 +1,186 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH posix_fadvise 3C "14 Jul 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +posix_fadvise \- file advisory information +.SH SYNOPSIS +.LP +.nf +#include <fcntl.h> + +\fBint\fR \fBposix_fadvise\fR(\fBint\fR \fIfd\fR, \fBoff_t\fR \fIoffset\fR, \fBoff_t\fR \fIlen\fR, \fBint\fR \fIadvice\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBposix_fadvise()\fR function advises the system on the expected behavior +of the application with respect to the data in the file associated with the +open file descriptor, \fIfd\fR, starting at \fIoffset\fR and continuing for +\fIlen\fR bytes. The specified range need not currently exist in the file. If +\fIlen\fR is zero, all data following offset is specified. The system may use +this information to optimize handling of the specified data. The +\fBposix_fadvise()\fR function has no effect on the semantics of other +operations on the specified data, although it may affect the performance of +other operations. +.sp +.LP +The advice to be applied to the data is specified by the \fIadvice\fR parameter +and may be one of the following values: +.sp +.ne 2 +.mk +.na +\fB\fBPOSIX_FADV_NORMAL\fR\fR +.ad +.RS 25n +.rt +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. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPOSIX_FADV_SEQUENTIAL\fR\fR +.ad +.RS 25n +.rt +Specifies that the application expects to access the specified data +sequentially from lower offsets to higher offsets. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPOSIX_FADV_RANDOM\fR\fR +.ad +.RS 25n +.rt +Specifies that the application expects to access the specified data in a random +order. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPOSIX_FADV_WILLNEED\fR\fR +.ad +.RS 25n +.rt +Specifies that the application expects to access the specified data in the near +future. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPOSIX_FADV_DONTNEED\fR\fR +.ad +.RS 25n +.rt +Specifies that the application expects that it will not access the specified +data in the near future. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPOSIX_FADV_NOREUSE\fR\fR +.ad +.RS 25n +.rt +Specifies that the application expects to access the specified data once and +then not reuse it thereafter. +.RE + +.sp +.LP +These values are defined in \fB<fcntl.h>\fR +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBposix_fadvise()\fR returns zero. Otherwise, an +error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBposix_fadvise()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIfd\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of \fIadvice\fR is invalid, or the value of \fIlen\fR is less than +zero. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBESPIPE\fR\fR +.ad +.RS 10n +.rt +The \fIfd\fR argument is associated with a pipe or FIFO. +.RE + +.SH USAGE +.sp +.LP +The \fBposix_fadvise()\fR function has a transitional interface for 64-bit file +offsets. See \fBlf64\fR(5). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBposix_madvise\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/posix_fallocate.3c b/usr/src/man/man3c/posix_fallocate.3c new file mode 100644 index 0000000000..819b0f37ce --- /dev/null +++ b/usr/src/man/man3c/posix_fallocate.3c @@ -0,0 +1,172 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH posix_fallocate 3C "14 Jul 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +posix_fallocate \- file space control +.SH SYNOPSIS +.LP +.nf +#include <fcntl.h> + +\fBint\fR \fBposix_fallocate\fR(\fBint\fR \fIfd\fR, \fBoff_t\fR \fIoffset\fR, \fBoff_t\fR \fIlen\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBposix_fallocate()\fR function ensures that any required storage for +regular file data starting at \fIoffset\fR and continuing for \fIlen\fR bytes +is allocated on the file system storage media. If \fBposix_fallocate()\fR +returns successfully, subsequent writes to the specified file data will not +fail due to the lack of free space on the file system storage media. +.sp +.LP +If the \fIoffset\fR+\fIlen\fR is beyond the current file size, then +\fBposix_fallocate()\fR adjusts the file size to \fIoffset\fR+\fIlen\fR. +Otherwise, the file size is not changed. +.sp +.LP +Space allocated with \fBposix_fallocate()\fR is freed by a successful call to +\fBcreat\fR(2) or \fBopen\fR(2) that truncates the size of the file. Space +allocated with \fBposix_fallocate()\fR may be freed by a successful call to +\fBftruncate\fR(3C) that reduces the file size to a size smaller than +\fIoffset\fR+\fIlen\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBposix_fallocate()\fR returns zero. Otherwise, an +error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBposix_fallocate()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIfd\fR argument is not a valid file descriptor or references a file that +was opened without write permission. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFBIG\fR\fR +.ad +.RS 10n +.rt +The value of \fIoffset\fR+\fIlen\fR is greater than the maximum file size. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 10n +.rt +A signal was caught during execution. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIlen\fR argument is less than or equal to zero, or the \fIoffset\fR +argument is less than zero, or the underlying file system does not support this +operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 10n +.rt +An I/O error occurred while reading from or writing to a file system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENODEV\fR\fR +.ad +.RS 10n +.rt +The \fIfd\fR argument does not refer to a regular file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSPC\fR\fR +.ad +.RS 10n +.rt +There is insufficient free space remaining on the file system storage media. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBESPIPE\fR\fR +.ad +.RS 10n +.rt +The \fIfd\fR argument is associated with a pipe or FIFO. +.RE + +.SH USAGE +.sp +.LP +The \fBposix_fallocate()\fR function has a transitional interface for 64-bit +file offsets. See \fBlf64\fR(5). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBcreat\fR(2), \fBopen\fR(2), \fBunlink\fR(2), \fBftruncate\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/posix_madvise.3c b/usr/src/man/man3c/posix_madvise.3c new file mode 100644 index 0000000000..aee2ae39e3 --- /dev/null +++ b/usr/src/man/man3c/posix_madvise.3c @@ -0,0 +1,172 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH posix_madvise 3C "14 Jul 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +posix_madvise \- memory advisory information +.SH SYNOPSIS +.LP +.nf +#include <sys/mman.h> + +\fBint\fR \fBposix_madvise\fR(\fBvoid *\fR\fIaddr\fR, \fBsize_t\fR \fIlen\fR, \fBint\fR \fIadvice\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBposix_madvise()\fR function advises the system on the expected behavior +of the application with respect to the data in the memory starting at address +\fIaddr\fR, and continuing for \fIlen\fR bytes. The system may use this +information to optimize handling of the specified data. The +\fBposix_madvise()\fR function has no effect on the semantics of access to +memory in the specified range, although it may affect the performance of +access. +.sp +.LP +The advice to be applied to the memory range is specified by the \fIadvice\fR +parameter and may be one of the following values: +.sp +.ne 2 +.mk +.na +\fB\fBPOSIX_MADV_NORMAL\fR\fR +.ad +.RS 25n +.rt +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. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPOSIX_MADV_SEQUENTIAL\fR\fR +.ad +.RS 25n +.rt +Specifies that the application expects to access the specified range +sequentially from lower addresses to higher addresses. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPOSIX_MADV_RANDOM\fR\fR +.ad +.RS 25n +.rt +Specifies that the application expects to access the specified range in a +random order. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPOSIX_MADV_WILLNEED\fR\fR +.ad +.RS 25n +.rt +Specifies that the application expects to access the specified range in the +near future. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPOSIX_MADV_DONTNEED\fR\fR +.ad +.RS 25n +.rt +Specifies that the application expects that it will not access the specified +range in the near future. +.RE + +.sp +.LP +These values are defined in \fB<sys/mman.h>\fR +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBposix_madvise()\fR returns zero. Otherwise, an +error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBposix_madvise()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of \fIadvice\fR is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Addresses in the range starting at \fIaddr\fR and continuing for \fIlen\fR +bytes are partly or completely outside the range allowed for the address space +of the calling process. +.RE + +.sp +.LP +The \fBposix_madvise()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of \fIlen\fR is zero. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBmmap\fR(2), \fBmadvise\fR(3C), posix_madvise(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/posix_memalign.3c b/usr/src/man/man3c/posix_memalign.3c new file mode 100644 index 0000000000..79cd1faa6f --- /dev/null +++ b/usr/src/man/man3c/posix_memalign.3c @@ -0,0 +1,98 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH posix_memalign 3C "14 Jul 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +posix_memalign \- aligned memory allocation +.SH SYNOPSIS +.LP +.nf +#include <sys/mman.h> + +\fBint\fR \fBposix_memalign\fR(\fBvoid **\fR\fImemptr\fR, \fBsize_t\fR \fIalignment\fR, \fBsize_t\fR \fIsize\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBposix_memalign()\fR function allocates size bytes aligned on a boundary +specified by alignment, and returns a pointer to the allocated memory in +\fImemptr\fR. The value of alignment must be a power of two multiple of +\fBsizeof\fR(\fBvoid *\fR). +.sp +.LP +Upon successful completion, the value pointed to by \fImemptr\fR will be a +multiple of alignment. +.sp +.LP +If the size of the space requested is 0, the value returned in \fImemptr\fR +will be a null pointer. +.sp +.LP +The \fBfree\fR(3C) function will deallocate memory that has previously been +allocated by \fBposix_memalign()\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBposix_memalign()\fR returns zero. Otherwise, an +error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBposix_memalign()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of the alignment parameter is not a power of two multiple of +\fBsizeof\fR(\fBvoid *\fR). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +There is insufficient memory available with the requested alignment. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBfree\fR(3C), \fBmalloc\fR(3C), \fBmemalign\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/posix_openpt.3c b/usr/src/man/man3c/posix_openpt.3c new file mode 100644 index 0000000000..ec0b5f157c --- /dev/null +++ b/usr/src/man/man3c/posix_openpt.3c @@ -0,0 +1,195 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH posix_openpt 3C "1 Dec 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +posix_openpt \- open a pseudo terminal device +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> +#include <fcntl.h> + +\fBint\fR \fBposix_openpt\fR(\fBint\fR \fIoflag\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBposix_openpt()\fR function establishes 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. +.sp +.LP +The file status flags and file access modes of the open file description are +set according to the value of \fIoflag\fR. +.sp +.LP +Values for \fIoflag\fR are constructed by a bitwise-inclusive OR of flags from +the following list, defined in <\fBfcntl.h\fR>. +.sp +.ne 2 +.mk +.na +\fB\fBO_RDWR\fR\fR +.ad +.RS 12n +.rt +Open for reading and writing. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBO_NOCTTY\fR\fR +.ad +.RS 12n +.rt +If set, \fBposix_openpt()\fR does not cause the terminal device to become the +controlling terminal for the process. +.RE + +.sp +.LP +The behavior of other values for the \fIoflag\fR argument is unspecified. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBposix_openpt()\fR function opens a master +pseudo-terminal device and returns a non-negative integer representing the +lowest numbered unused file descriptor. Otherwise, -1 is returned and +\fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBposix_openpt()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 10n +.rt +{\fBOPEN_MAX\fR} file descriptors are currently open in the calling process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENFILE\fR\fR +.ad +.RS 10n +.rt +The maximum allowable number of files is currently open in the system. +.RE + +.sp +.LP +The \fBposix_openpt()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of \fIoflag\fR is not valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +Out of pseudo-terminal resources. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 10n +.rt +Out of STREAMS resources. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fROpen a pseudo-terminal. +.sp +.LP +The following example opens a pseudo-terminal and returns the name of the slave +device and a file descriptor. + +.sp +.in +2 +.nf +#include fcntl.h> +#include stdio.h> + +int masterfd, slavefd; +char *slavedevice; + +masterfd = posix_openpt(O_RDWR|O_NOCTTY); + +if (masterfd == -1 + || grantpt (masterfd) == -1 + || unlockpt (masterfd) == -1 + || (slavedevice = ptsname (masterfd)) == NULL) + return -1; + +printf("slave device is: %s\en", slavedevice); + +slavefd = open(slave, O_RDWR|O_NOCTTY); +if (slavefd < 0) + return -1; +.fi +.in -2 + +.SH USAGE +.sp +.LP +This function provides a method for portably obtaining a file descriptor of a +master terminal device for a pseudo-terminal. The \fBgrantpt\fR(3C) and +\fBptsname\fR(3C) functions can be used to manipulate mode and ownership +permissions and to obtain the name of the slave device, respectively. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBopen\fR(2), \fBgrantpt\fR(3C), \fBptsname\fR(3C), \fBunlockpt\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/posix_spawn.3c b/usr/src/man/man3c/posix_spawn.3c new file mode 100644 index 0000000000..4814560f47 --- /dev/null +++ b/usr/src/man/man3c/posix_spawn.3c @@ -0,0 +1,439 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical +.\" and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH posix_spawn 3C "20 Feb 2009" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +posix_spawn, posix_spawnp \- spawn a process +.SH SYNOPSIS +.LP +.nf +#include <spawn.h> + +\fBint\fR \fBposix_spawn\fR(\fBpid_t *restrict\fR \fIpid\fR, \fBconst char *restrict\fR \fIpath\fR, + \fBconst posix_spawn_file_actions_t *\fR\fIfile_actions\fR, + \fBconst posix_spawnattr_t *restrict\fR \fIattrp\fR, + \fBchar *const\fR \fIargv\fR[restrict], \fBchar *const\fR \fIenvp\fR[restrict]); +.fi + +.LP +.nf +\fBint\fR \fBposix_spawnp\fR(\fBpid_t *restrict\fR \fIpid\fR, \fBconst char *restrict\fR \fIfile\fR, + \fBconst posix_spawn_file_actions_t *\fR\fIfile_actions\fR, + \fBconst posix_spawnattr_t *restrict\fR \fIattrp\fR, + \fBchar *const\fR \fIargv\fR[restrict], \fBchar *const\fR \fIenvp\fR[restrict]); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBposix_spawn()\fR and \fBposix_spawnp()\fR functions create a new process +(child process) from the specified process image. The new process image is +constructed from a regular executable file called the new process image file. +.sp +.LP +When a C program is executed as the result of this call, it is entered as a C +language function call as follows: +.sp +.in +2 +.nf +int main(int \fIargc\fR, char *\fIargv\fR[]); +.fi +.in -2 + +.sp +.LP +where \fIargc\fR is the argument count and \fIargv\fR is an array of character +pointers to the arguments themselves. In addition, the following variable +.sp +.in +2 +.nf +extern char **environ; +.fi +.in -2 + +.sp +.LP +is initialized as a pointer to an array of character pointers to the +environment strings. +.sp +.LP +The argument \fIargv\fR is an array of character pointers to null-terminated +strings. The last member of this array is a null pointer and is not counted in +\fIargc\fR. These strings constitute the argument list available to the new +process image. The value in \fIargv\fR[0] should point to a filename that is +associated with the process image being started by the \fBposix_spawn()\fR or +\fBposix_spawnp()\fR function. +.sp +.LP +The argument \fIenvp\fR 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. +.sp +.LP +The number of bytes available for the child process's combined argument and +environment lists is {\fBARG_MAX\fR}, counting all character pointers, the +strings they point to, the trailing null bytes in the strings, and the +list-terminating null pointers. There is no additional system overhead included +in this total. +.sp +.LP +The \fIpath\fR argument to \fBposix_spawn()\fR is a pathname that identifies +the new process image file to execute. +.sp +.LP +The \fIfile\fR parameter to \fBposix_spawnp()\fR is used to construct a +pathname that identifies the new process image file. If the file parameter +contains a slash character, the file parameter is used as the pathname for the +new process image file. Otherwise, the path prefix for this file is obtained by +a search of the directories passed as the environment variable \fBPATH\fR. If +this environment variable is not defined, the results of the search are +implementation-defined. +.sp +.LP +If \fIfile_actions\fR is a null pointer, then file descriptors open in the +calling process remain open in the child process, except for those whose +close-on-exec flag \fBFD_CLOEXEC\fR is set (see \fBfcntl\fR(2)). For those +file descriptors that remain open, all attributes of the corresponding open +file descriptions, including file locks (see \fBfcntl\fR(2)), remain unchanged. +.sp +.LP +If \fIfile_actions\fR is not \fINULL\fR, then the file descriptors open in the +child process are those open in the calling process as modified by the spawn +file actions object pointed to by \fIfile_actions\fR and the \fBFD_CLOEXEC\fR +flag of each remaining open file descriptor after the spawn file actions have +been processed. The effective order of processing the spawn file actions are: +.RS +4 +.TP +1. +The set of open file descriptors for the child process are initially the +same set as is open for the calling process. All attributes of the +corresponding open file descriptions, including file locks (see +\fBfcntl\fR(2)), remain unchanged. +.RE +.RS +4 +.TP +2. +The signal mask, signal default or ignore actions, and the effective user +and group IDs for the child process are changed as specified in the attributes +object referenced by \fIattrp\fR. +.RE +.RS +4 +.TP +3. +The file actions specified by the spawn file actions object are performed in +the order in which they were added to the spawn file actions object. +.RE +.RS +4 +.TP +4. +Any file descriptor that has its \fBFD_CLOEXEC\fR flag set (see +\fBfcntl\fR(2)) is closed. +.RE +.sp +.LP +The \fBposix_spawnattr_t\fR spawn attributes object type is defined in +<\fBspawn.h\fR>. It contains at least the attributes defined below. +.sp +.LP +If the \fBPOSIX_SPAWN_SETPGROUP\fR flag is set in the \fIspawn-flags\fR +attribute of the object referenced by \fIattrp\fR, and the \fIspawn-pgroup\fR +attribute of the same object is non-zero, then the child's process group is as +specified in the \fIspawn-pgroup\fR attribute of the object referenced by +\fIattrp\fR. +.sp +.LP +As a special case, if the \fBPOSIX_SPAWN_SETPGROUP\fR flag is set in the +\fIspawn-flags\fR attribute of the object referenced by \fIattrp\fR, and the +\fIspawn-pgroup\fR attribute of the same object is set to zero, then the child +will be in a new process group with a process group ID equal to its process ID. +.sp +.LP +If the \fBPOSIX_SPAWN_SETPGROUP\fR flag is not set in the \fIspawn-flags\fR +attribute of the object referenced by \fIattrp\fR, the new child process +inherits the parent's process group. +.sp +.LP +If the \fBPOSIX_SPAWN_SETSCHEDPARAM\fR flag is set in the \fIspawn-flags\fR +attribute of the object referenced by \fIattrp\fR, but +\fBPOSIX_SPAWN_SETSCHEDULER\fR is not set, the new process image initially has +the scheduling policy of the calling process with the scheduling parameters +specified in the \fIspawn-schedparam\fR attribute of the object referenced by +\fIattrp\fR. +.sp +.LP +If the \fBPOSIX_SPAWN_SETSCHEDULER\fR flag is set in \fIspawn-flags\fR +attribute of the object referenced by \fIattrp\fR (regardless of the setting of +the \fBPOSIX_SPAWN_SETSCHEDPARAM\fR flag), the new process image initially has +the scheduling policy specified in the \fIspawn-schedpolicy\fR attribute of the +object referenced by \fIattrp\fR and the scheduling parameters specified in the +\fIspawn-schedparam\fR attribute of the same object. +.sp +.LP +The \fBPOSIX_SPAWN_RESETIDS\fR flag in the \fIspawn-flags\fR attribute of the +object referenced by \fIattrp\fR governs the effective user ID of the child +process. If this flag is not set, the child process inherits the parent +process's effective user ID. If this flag is set, the child process's effective +user ID is 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 becomes that file's owner ID before the new process +image begins execution. If this flag is set, the child process's effective user +ID is 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 becomes that file's owner ID before the new process image begins +execution. +.sp +.LP +The \fBPOSIX_SPAWN_RESETIDS\fR flag in the \fIspawn-flags\fR attribute of the +object referenced by \fIattrp\fR also governs the effective group ID of the +child process. If this flag is not set, the child process inherits the parent +process's effective group ID. If this flag is set, the child process's +effective group ID is 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 becomes that file's group ID before the new +process image begins execution. +.sp +.LP +If the \fBPOSIX_SPAWN_SETSIGMASK\fR flag is set in the \fIspawn-flags\fR +attribute of the object referenced by \fIattrp\fR, the child process initially +has the signal mask specified in the \fIspawn-sigmask\fR attribute of the +object referenced by \fIattrp\fR. +.sp +.LP +If the \fBPOSIX_SPAWN_SETSIGDEF\fR flag is set in the \fIspawn-flags\fR +attribute of the object referenced by \fIattrp\fR, the signals specified in the +\fIspawn-sigdefault\fR attribute of the same object is set to their default +actions in the child process. +.sp +.LP +If the \fBPOSIX_SPAWN_SETSIGIGN_NP\fR flag is set in the spawn-flags attribute +of the object referenced by \fIattrp\fR, the signals specified in the +\fIspawn-sigignore\fR attribute of the same object are set to be ignored in the +child process. +.sp +.LP +If both \fBPOSIX_SPAWN_SETSIGDEF\fR and \fBPOSIX_SPAWN_SETSIGIGN_NP\fR flags +are set in the spawn-flags attribute of the object referenced by \fIattrp\fR, +the actions for \fBPOSIX_SPAWN_SETSIGDEF\fR take precedence over the actions +for \fBPOSIX_SPAWN_SETSIGIGN_NP\fR. +.sp +.LP +If the \fBPOSIX_SPAWN_NOSIGCHLD_NP\fR flag is set in the \fIspawn-flags\fR +attribute of the object referenced by \fIattrp\fR, no \fBSIGCHLD\fR signal will +be posted to the parent process when the child process terminates, regardless +of the disposition of the \fBSIGCHLD\fR signal in the parent. \fBSIGCHLD\fR +signals are still possible for job control stop and continue actions if the +parent has requested them. +.sp +.LP +If the \fBPOSIX_SPAWN_WAITPID_NP\fR flag is set in the \fIspawn-flags\fR +attribute of the object referenced by \fIattrp\fR, no wait-for-multiple-pids +operation by the parent, as in \fBwait()\fR, \fBwaitid\fR(\fBP_ALL\fR), or +\fBwaitid\fR(\fBP_PGID\fR), will succeed in reaping the child, and the child +will not be reaped automatically due the disposition of the \fBSIGCHLD\fR +signal being set to be ignored in the parent. Only a specific wait for the +child, as in \fBwaitid\fR(\fBP_PID\fR, \fBpid\fR), is allowed and it is +required, else when the child exits it will remain a zombie until the parent +exits. +.sp +.LP +If the \fBPOSIX_SPAWN_NOEXECERR_NP\fR flag is set in the spawn-flags attribute +of the object referenced by \fIattrp\fR, and if the specified process image +file cannot be executed, then the \fBposix_spawn()\fR and \fBposix_spawnp()\fR +functions do not fail with one of the \fBexec\fR(2) error codes, as is normal, +but rather return successfully having created a child process that exits +immediately with exit status 127. This flag permits \fBsystem\fR(3C) and +\fBpopen\fR(3C) to be implemented with \fBposix_spawn()\fR and still conform +strictly to their POSIX specifications. +.sp +.LP +Signals set to be caught or set to the default action in the calling process +are set to the default action in the child process, unless the +\fBPOSIX_SPAWN_SETSIGIGN_NP\fR flag is set in the spawn-flags attribute of the +object referenced by \fIattrp\fR and the signals are specified in the +\fIspawn-sigignore\fR attribute of the same object. +.sp +.LP +Except for \fBSIGCHLD\fR, signals set to be ignored by the calling process +image are set to be ignored by the child process, unless otherwise specified by +the \fBPOSIX_SPAWN_SETSIGDEF\fR flag being set in the \fIspawn-flags\fR +attribute of the object referenced by \fIattrp\fR and the signals being +indicated in the \fIspawn-sigdefault\fR attribute of the object referenced by +\fIattrp\fR. +.sp +.LP +If the \fBSIGCHLD\fR signal is set to be ignored by the calling process, it is +unspecified whether the \fBSIGCHLD\fR signal is set to be ignored or to the +default action in the child process, unless otherwise specified by the +\fBPOSIX_SPAWN_SETSIGDEF\fR flag being set in the \fIspawn-flags\fR attribute +of the object referenced by \fIattrp\fR and the \fBSIGCHLD\fR signal being +indicated in the \fIspawn-sigdefault\fR attribute of the object referenced by +\fIattrp\fR. +.sp +.LP +If the value of the \fIattrp\fR pointer is \fINULL\fR, then the default values +are used. +.sp +.LP +All process attributes, other than those influenced by the attributes set in +the object referenced by \fIattrp\fR as specified above or by the file +descriptor manipulations specified in \fIfile_actions\fR appear in the new +process image as though \fBfork()\fR had been called to create a child process +and then a member of the \fBexec\fR family of functions had been called by the +child process to execute the new process image. +.sp +.LP +The fork handlers are not run when \fBposix_spawn()\fR or \fBposix_spawnp()\fR +is called. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBposix_spawn()\fR and \fBposix_spawnp()\fR return +the process ID of the child process to the parent process in the variable +pointed to by a non-null \fIpid\fR argument, and return zero as the function +return value. Otherwise, no child process is created, the value stored into the +variable pointed to by a non-null \fIpid\fR is unspecified, and an error number +is returned as the function return value to indicate the error. If the +\fIpid\fR argument is a null pointer, the process ID of the child is not +returned to the caller. +.SH ERRORS +.sp +.LP +The \fBposix_spawn()\fR and \fBposix_spawnp()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIfile_actions\fR or \fIattrp\fR is invalid. +.RE + +.sp +.LP +If \fBposix_spawn()\fR or \fBposix_spawnp()\fR fails for any of the reasons +that would cause \fBfork()\fR or one of the \fBexec\fR family of functions to +fail, an error value is returned as described by \fBfork\fR(2) and +\fBexec\fR(2), respectively +.sp +.LP +If \fBPOSIX_SPAWN_SETPGROUP\fR is set in the \fIspawn-flags\fR attribute of the +object referenced by \fIattrp\fR, and \fBposix_spawn()\fR or +\fBposix_spawnp()\fR fails while changing the child's process group, an error +value is returned as described by \fBsetpgid\fR(2). +.sp +.LP +If \fBPOSIX_SPAWN_SETSCHEDPARAM\fR is set and \fBPOSIX_SPAWN_SETSCHEDULER\fR is +not set in the \fIspawn-flags\fR attribute of the object referenced by +\fIattrp\fR, then if \fBposix_spawn()\fR or \fBposix_spawnp()\fR fails for any +of the reasons that would cause \fBsched_setparam()\fR to fail, an error value +is returned as described by \fBsched_setparam\fR(3C). +.sp +.LP +If \fBPOSIX_SPAWN_SETSCHEDULER\fR is set in the \fIspawn-flags\fR attribute of +the object referenced by \fIattrp\fR, and if \fBposix_spawn()\fR or +\fBposix_spawnp()\fR fails for any of the reasons that would cause +\fBsched_setscheduler()\fR to fail, an error value is returned as described by +\fBsched_setscheduler\fR(3C). +.sp +.LP +If the \fIfile_actions\fR argument is not \fINULL\fR and specifies any +\fBclose()\fR, \fBdup2()\fR, or \fBopen()\fR actions to be performed, and if +\fBposix_spawn()\fR or \fBposix_spawnp()\fR fails for any of the reasons that +would cause \fBclose()\fR, \fBdup2()\fR, or \fBopen()\fR to fail, an error +value is returned as described by \fBclose\fR(2), \fBdup2\fR(3C), or +\fBopen\fR(2), respectively. An open file action might, by itself, result in +any of the errors described by \fBclose()\fR or \fBdup2()\fR, in addition to +those described by \fBopen()\fR. +.sp +.LP +If a \fBclose\fR(2) operation is specified to be performed for a file +descriptor that is not open at the time of the call to \fBposix_spawn()\fR or +\fBposix_spawnp()\fR, the action does not cause \fBposix_spawn()\fR or +\fBposix_spawnp()\fR to fail. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBalarm\fR(2), \fBchmod\fR(2), \fBclose\fR(2), \fBdup\fR(2), \fBexec\fR(2), +\fBexit\fR(2), \fBfcntl\fR(2), \fBfork\fR(2), \fBkill\fR(2), \fBopen\fR(2), +\fBsetpgid\fR(2), \fBsetuid\fR(2), \fBstat\fR(2), \fBtimes\fR(2), +\fBdup2\fR(3C), \fBpopen\fR(3C), \fBposix_spawn_file_actions_addclose\fR(3C), +\fBposix_spawn_file_actions_adddup2\fR(3C), +\fBposix_spawn_file_actions_addopen\fR(3C), +\fBposix_spawn_file_actions_destroy\fR(3C), +\fBposix_spawn_file_actions_init\fR(3C), \fBposix_spawnattr_destroy\fR(3C), +\fBposix_spawnattr_getflags\fR(3C), \fBposix_spawnattr_getpgroup\fR(3C), +\fBposix_spawnattr_getschedparam\fR(3C), +\fBposix_spawnattr_getschedpolicy\fR(3C), +\fBposix_spawnattr_getsigdefault\fR(3C), +\fBposix_spawnattr_getsigignore_np\fR(3C), +\fBposix_spawnattr_getsigmask\fR(3C), \fBposix_spawnattr_init\fR(3C), +\fBposix_spawnattr_setflags\fR(3C), \fBposix_spawnattr_setpgroup\fR(3C), +\fBposix_spawnattr_setschedparam\fR(3C), +\fBposix_spawnattr_setschedpolicy\fR(3C), +\fBposix_spawnattr_setsigdefault\fR(3C), +\fBposix_spawnattr_setsigignore_np\fR(3C), +\fBposix_spawnattr_setsigmask\fR(3C), \fBsched_setparam\fR(3C), +\fBsched_setscheduler\fR(3C), \fBsystem\fR(3C), \fBwait\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +The SUSv3 POSIX standard (The Open Group Base Specifications Issue 6, IEEE Std +1003.1-2001) permits the \fBposix_spawn()\fR and \fBposix_spawnp()\fR functions +to return successfully before some of the above-described errors are detected, +allowing the child process to fail instead: +.sp +.in +2 +.nf +\&... if the error occurs after the calling process +successfully returns, the child process exits with +exit status 127. +.fi +.in -2 + +.sp +.LP +With the one exception of when the \fBPOSIX_SPAWN_NOEXECERR_NP\fR flag is +passed in the attributes structure, this behavior is not present in the Solaris +implementation. Any error that occurs before the new process image is +successfully constructed causes the \fBposix_spawn()\fR and +\fBposix_spawnp()\fR functions to return the corresponding non-zero error value +without creating a child process. +.sp +.LP +The \fBPOSIX_SPAWN_NOSIGCHLD_NP\fR, \fBPOSIX_SPAWN_WAITPID_NP\fR, +\fBPOSIX_SPAWN_NOEXECERR_NP\fR, and \fBPOSIX_SPAWN_SETSIGIGN_NP\fR flags and +the \fBposix_spawnattr_getsigignore_np()\fR and +\fBposix_spawnattr_setsigignore_np()\fR functions are non-portable Solaris +extensions to the \fBposix_spawn()\fR and \fBposix_spawnp()\fR interfaces. diff --git a/usr/src/man/man3c/posix_spawn_file_actions_addclose.3c b/usr/src/man/man3c/posix_spawn_file_actions_addclose.3c new file mode 100644 index 0000000000..07cea3429e --- /dev/null +++ b/usr/src/man/man3c/posix_spawn_file_actions_addclose.3c @@ -0,0 +1,160 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical +.\" and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH posix_spawn_file_actions_addclose 3C "20 Feb 2009" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +posix_spawn_file_actions_addclose, posix_spawn_file_actions_addopen \- add +close or open action to spawn file actions object +.SH SYNOPSIS +.LP +.nf +#include <spawn.h> + +\fBint\fR \fBposix_spawn_file_actions_addclose\fR( + \fBposix_spawn_file_actions_t *\fR\fIfile_actions\fR, \fBint\fR \fIfildes\fR); +.fi + +.LP +.nf +\fBint\fR \fBposix_spawn_file_actions_addopen\fR( + \fBposix_spawn_file_actions_t *restrict\fR \fIfile_actions\fR, \fBint\fR \fIfildes\fR, + \fBconst char *restrict\fR \fIpath\fR, \fBint\fR \fIoflag\fR, \fBmode_t\fR \fImode\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions add or delete a close or open action to a spawn file actions +object. +.sp +.LP +A spawn file actions object is of type \fBposix_spawn_file_actions_t\fR +(defined in <\fBspawn.h\fR>) and is used to specify a series of actions to be +performed by a \fBposix_spawn\fR(3C) or \fBposix_spawn\fR(3C) operation to +arrive at the set of open file descriptors for the child process given the set +of open file descriptors of the parent. +.sp +.LP +A spawn file actions object, when passed to \fBposix_spawn()\fR or +\fBposix_spawnp()\fR, specifies 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 occurs as though 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 +\fBFD_CLOEXEC\fR flag set is closed (see \fBposix_spawn\fR(3C)). +.sp +.LP +The \fBposix_spawn_file_actions_addclose()\fR function adds a close action to +the object referenced by \fIfile_actions\fR that causes the file descriptor +fildes to be closed (as if \fBclose\fR(\fIfildes\fR) had been called) when a +new process is spawned using this file actions object. +.sp +.LP +The \fBposix_spawn_file_actions_addopen()\fR function adds an open action to +the object referenced by \fIfile_actions\fR that causes the file named by path +to be opened (as if \fBopen\fR(\fIpath\fR, \fIoflag\fR, \fImode\fR) had been +called, and the returned file descriptor, if not \fIfildes\fR, had been changed +to \fIfildes\fR) when a new process is spawned using this file actions object. +If \fIfildes\fR was already an open file descriptor, it is closed before the +new file is opened. +.sp +.LP +The string described by \fIpath\fR is copied by the +\fBposix_spawn_file_actions_addopen()\fR function. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, these functions return 0. Otherwise, an error +number is returned to indicate the error. +.SH ERRORS +.sp +.LP +These functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 9n +.rt +The value specified by \fIfildes\fR is negative or greater than or equal to +{\fBOPEN_MAX\fR}. +.RE + +.sp +.LP +These functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIfile_actions\fR is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient memory exists to add to the spawn file actions object. +.RE + +.sp +.LP +It is not considered an error for the \fIfildes\fR 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 \fBposix_spawn()\fR +or \fBposix_spawnp()\fR operation. +.sp +.LP +If a \fBclose\fR(2) operation is specified for a file descriptor that is not +open at the time of the call to \fBposix_spawn()\fR or \fBposix_spawnp()\fR, +the close operation will not cause the \fBposix_spawn()\fR or +\fBposix_spawnp()\fR operation to fail. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBclose\fR(2), \fBdup\fR(2), \fBopen\fR(2), \fBposix_spawn\fR(3C), +\fBposix_spawn_file_actions_adddup2\fR(3C), +\fBposix_spawn_file_actions_destroy\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/posix_spawn_file_actions_addclosefrom_np.3c b/usr/src/man/man3c/posix_spawn_file_actions_addclosefrom_np.3c new file mode 100644 index 0000000000..af6499207e --- /dev/null +++ b/usr/src/man/man3c/posix_spawn_file_actions_addclosefrom_np.3c @@ -0,0 +1,105 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical +.\" and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH posix_spawn_file_actions_addclosefrom_np 3C "20 Feb 2009" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +posix_spawn_file_actions_addclosefrom_np \- add closefrom action to spawn file +actions object +.SH SYNOPSIS +.LP +.nf +#include <spawn.h> + +\fBint\fR \fBposix_spawn_file_actions_addclosefrom_np\fR( + \fBposix_spawn_file_actions_t *\fR\fIfile_actions\fR, \fBint\fR \fIlowfildes\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBposix_spawn_file_actions_addclosefrom_np()\fR function adds a closefrom +action to the object referenced by \fIfile_actions\fR that causes all open file +descriptors greater than or equal to \fIlowfildes\fR to be closed when a new +process is spawned using this file actions object (see \fBclosefrom\fR(3C)). +.sp +.LP +A spawn file actions object is as defined in +\fBposix_spawn_file_actions_addclose\fR(3C). +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the +\fBposix_spawn_file_actions_addclosefrom_np()\fR function returns 0. Otherwise, +an error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBposix_spawn_file_actions_addclosefrom_np()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 9n +.rt +The value specified by \fIlowfildes\fR is negative. +.RE + +.sp +.LP +The \fBposix_spawn_file_actions_addclosefrom_np()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIfile_actions\fR is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient memory exists to add to the spawn file actions object. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBclose\fR(2), \fBclosefrom\fR(3C), \fBposix_spawn\fR(3C), +\fBposix_spawn_file_actions_addclose\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/posix_spawn_file_actions_adddup2.3c b/usr/src/man/man3c/posix_spawn_file_actions_adddup2.3c new file mode 100644 index 0000000000..8695cb0cb8 --- /dev/null +++ b/usr/src/man/man3c/posix_spawn_file_actions_adddup2.3c @@ -0,0 +1,116 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH posix_spawn_file_actions_adddup2 3C "30 Jan 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +posix_spawn_file_actions_adddup2 \- add dup2 action to spawn file actions +object +.SH SYNOPSIS +.LP +.nf +#include <spawn.h> + +\fBint\fR \fBposix_spawn_file_actions_adddup2\fR( + \fBposix_spawn_file_actions_t *\fR\fIfile_actions\fR, \fBint\fR \fIfildes\fR, + \fBint\fR \fInewfildes\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBposix_spawn_file_actions_adddup2()\fR function adds a \fBdup2\fR(3C) +action to the object referenced by \fIfile_actions\fR that causes the file +descriptor \fIfildes\fR to be duplicated as \fInewfildes\fR (as if +\fBdup2\fR(\fIfildes\fR, \fInewfildes\fR) had been called) when a new process +is spawned using this file actions object. +.sp +.LP +A spawn file actions object is as defined in +\fBposix_spawn_file_actions_addclose\fR(3C). +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBposix_spawn_file_actions_adddup2()\fR +function returns 0. Otherwise, an error number is be returned to indicate the +error. +.SH ERRORS +.sp +.LP +The \fBposix_spawn_file_actions_adddup2()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIfildes\fR or \fInewfildes\fR is negative or greater +than or equal to {\fBOPEN_MAX\fR}. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient memory exists to add to the spawn file actions object. +.RE + +.sp +.LP +The \fBposix_spawn_file_actions_adddup2()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIfile_actions\fR is invalid. +.RE + +.sp +.LP +It is not considered an error for the \fIfildes\fR argument passed to +\fBposix_spawn_file_actions_adddup2()\fR 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 \fBposix_spawn\fR(3C) or \fBposix_spawnp\fR(3C) operation. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdup2\fR(3C), \fBposix_spawn\fR(3C), +\fBposix_spawn_file_actions_addclose\fR(3C), +\fBposix_spawn_file_actions_destroy\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/posix_spawn_file_actions_destroy.3c b/usr/src/man/man3c/posix_spawn_file_actions_destroy.3c new file mode 100644 index 0000000000..ef6dd4417f --- /dev/null +++ b/usr/src/man/man3c/posix_spawn_file_actions_destroy.3c @@ -0,0 +1,110 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH posix_spawn_file_actions_destroy 3C "30 Jan 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +posix_spawn_file_actions_destroy, posix_spawn_file_actions_init \- destroy and +initialize spawn file actions object +.SH SYNOPSIS +.LP +.nf +#include <spawn.h> + +\fBint\fR \fBposix_spawn_file_actions_destroy\fR( + \fBposix_spawn_file_actions_t *\fR\fIfile_actions\fR); +.fi + +.LP +.nf +\fBint\fR \fBposix_spawn_file_actions_init\fR( + \fBposix_spawn_file_actions_t *\fR\fIfile_actions\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBposix_spawn_file_actions_destroy()\fR function destroys the object +referenced by \fIfile_actions\fR. The object becomes, in effect, uninitialized. +An implementation can cause \fBposix_spawn_file_actions_destroy()\fR to set the +object referenced by file_actions to an invalid value. A destroyed spawn file +actions object can be reinitialized using +\fBposix_spawn_file_actions_init()\fR. The results of otherwise referencing the +object after it has been destroyed are undefined. +.sp +.LP +The \fBposix_spawn_file_actions_init()\fR function initializes the object +referenced by \fIfile_actions\fR to contain no file actions for +\fBposix_spawn\fR(3C) or \fBposix_spawnp\fR(3C) to perform. +.sp +.LP +A spawn file actions object is as defined in +\fBposix_spawn_file_actions_addclose\fR(3C). +.sp +.LP +The effect of initializing an already initialized spawn file actions object is +undefined. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, these functions return 0. Otherwise, an error +number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBposix_spawn_file_actions_init()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient memory exists to initialize the spawn file actions object. +.RE + +.sp +.LP +The \fBposix_spawn_file_actions_destroy()\fR function will may if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIfile_actions\fR is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBposix_spawn\fR(3C), \fBposix_spawn_file_actions_addclose\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/posix_spawnattr_destroy.3c b/usr/src/man/man3c/posix_spawnattr_destroy.3c new file mode 100644 index 0000000000..a7753cf54a --- /dev/null +++ b/usr/src/man/man3c/posix_spawnattr_destroy.3c @@ -0,0 +1,124 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH posix_spawnattr_destroy 3C "30 Jan 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +posix_spawnattr_destroy, posix_spawnattr_init \- destroy and initialize spawn +attributes object +.SH SYNOPSIS +.LP +.nf +#include <spawn.h> + +\fBint\fR \fBposix_spawnattr_destroy\fR(\fBposix_spawnattr_t *\fR\fIattr\fR); +.fi + +.LP +.nf +\fBint\fR \fBposix_spawnattr_init\fR(\fBposix_spawnattr_t *\fR\fIattr\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBposix_spawnattr_destroy()\fR function destroys a spawn attributes +object. A destroyed \fIattr\fR attributes object can be reinitialized using +\fBposix_spawnattr_init()\fR. The results of otherwise referencing the object +after it has been destroyed are undefined. An implementation can cause +\fBposix_spawnattr_destroy()\fR to set the object referenced by \fIattr\fR to +an invalid value. +.sp +.LP +The \fBposix_spawnattr_init()\fR function initializes a spawn attributes object +\fIattr\fR with the default value for all of the individual attributes used by +the implementation. Results are undefined if \fBposix_spawnattr_init()\fR is +called specifying an already initialized \fIattr\fR attributes object. +.sp +.LP +A spawn attributes object is of type \fBposix_spawnattr_t\fR (defined in +<\fBspawn.h\fR>) and is used to specify the inheritance of process attributes +across a spawn operation. +.sp +.LP +No attributes other than those defined by IEEE Std 1003.1-200x are provided. +.sp +.LP +The resulting spawn attributes object (possibly modified by setting individual +attribute values), is used to modify the behavior of \fBposix_spawn\fR(3C) or +\fBposix_spawnp\fR(3C). After a spawn attributes object has been used to spawn +a process by a call to \fBposix_spawn()\fR or \fBposix_spawnp()\fR, any +function affecting the attributes object (including destruction) will not +affect any process that has been spawned in this way. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBposix_spawnattr_destroy()\fR and +\fBposix_spawnattr_init()\fR return 0. Otherwise, an error number is returned +to indicate the error. +.SH ERRORS +.sp +.LP +The \fBposix_spawnattr_init()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient memory exists to initialize the spawn attributes object. +.RE + +.sp +.LP +The \fBposix_spawnattr_destroy()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIattr\fR is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBposix_spawn\fR(3C), \fBposix_spawnattr_getflags\fR(3C), +\fBposix_spawnattr_getpgroup\fR(3C), \fBposix_spawnattr_getschedparam\fR(3C), +\fBposix_spawnattr_getschedpolicy\fR(3C), +\fBposix_spawnattr_getsigdefault\fR(3C), \fBposix_spawnattr_getsigmask\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/posix_spawnattr_getflags.3c b/usr/src/man/man3c/posix_spawnattr_getflags.3c new file mode 100644 index 0000000000..0952275b5e --- /dev/null +++ b/usr/src/man/man3c/posix_spawnattr_getflags.3c @@ -0,0 +1,153 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH posix_spawnattr_getflags 3C "25 Sep 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +posix_spawnattr_getflags, posix_spawnattr_setflags \- get and set spawn-flags +attribute of spawn attributes object +.SH SYNOPSIS +.LP +.nf +#include <spawn.h> + +\fBint\fR \fBposix_spawnattr_getflags\fR(\fBconst posix_spawnattr_t *restrict\fR \fIattr\fR, + \fBshort *restrict\fR \fIflags\fR); +.fi + +.LP +.nf +\fBint\fR \fBposix_spawnattr_setflags\fR(\fBposix_spawnattr_t *\fR \fIattr\fR, \fBshort\fR \fIflags\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBposix_spawnattr_getflags()\fR function obtains the value of the +\fIspawn-flags\fR attribute from the attributes object referenced by +\fIattr\fR. +.sp +.LP +The \fBposix_spawnattr_setflags()\fR function sets the \fIspawn-flags\fR +attribute in an initialized attributes object referenced by \fIattr\fR. +.sp +.LP +The \fIspawn-flags\fR attribute is used to indicate which process attributes +are to be changed in the new process image when invoking \fBposix_spawn\fR(3C) +or \fBposix_spawnp\fR(3C). It is the bitwise inclusive-OR of zero or more of +the following flags: +.br +.in +2 +\fBPOSIX_SPAWN_RESETIDS\fR +.in -2 +.br +.in +2 +\fBPOSIX_SPAWN_SETPGROUP\fR +.in -2 +.br +.in +2 +\fBPOSIX_SPAWN_SETSIGDEF\fR +.in -2 +.br +.in +2 +\fBPOSIX_SPAWN_SETSIGMASK\fR +.in -2 +.br +.in +2 +\fBPOSIX_SPAWN_SETSCHEDPARAM\fR +.in -2 +.br +.in +2 +\fBPOSIX_SPAWN_SETSCHEDULER\fR +.in -2 +.br +.in +2 +\fBPOSIX_SPAWN_NOSIGCHLD_NP\fR +.in -2 +.br +.in +2 +\fBPOSIX_SPAWN_WAITPID_NP\fR +.in -2 +.br +.in +2 +\fBPOSIX_SPAWN_NOEXECERR_NP\fR +.in -2 +.sp +.LP +These flags are defined in \fB<spawn.h>\fR. The default value of this attribute +is as if no flags were set. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBposix_spawnattr_getflags()\fR returns 0 and +stores the value of the spawn-flags attribute of attr into the object +referenced by the flags parameter. Otherwise, an error number is returned to +indicate the error. +.sp +.LP +Upon successful completion, \fBposix_spawnattr_setflags()\fR returns 0. +Otherwise, an error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +These functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIattr\fR is invalid. +.RE + +.sp +.LP +The \fBposix_spawnattr_setflags()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of the attribute being set is not valid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBposix_spawn\fR(3C), \fBposix_spawnattr_destroy\fR(3C), +\fBposix_spawnattr_getpgroup\fR(3C), \fBposix_spawnattr_getschedparam\fR(3C), +\fBposix_spawnattr_getschedpolicy\fR(3C), +\fBposix_spawnattr_getsigdefault\fR(3C), \fBposix_spawnattr_getsigmask\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/posix_spawnattr_getpgroup.3c b/usr/src/man/man3c/posix_spawnattr_getpgroup.3c new file mode 100644 index 0000000000..ff845dc16b --- /dev/null +++ b/usr/src/man/man3c/posix_spawnattr_getpgroup.3c @@ -0,0 +1,111 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH posix_spawnattr_getpgroup 3C "30 Jan 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +posix_spawnattr_getpgroup, posix_spawnattr_setpgroup \- get and set +spawn-pgroup attribute of spawn attributes object +.SH SYNOPSIS +.LP +.nf +#include <spawn.h> + +\fBint\fR \fBposix_spawnattr_getpgroup\fR(\fBconst posix_spawnattr_t *restrict\fR \fIattr\fR, + \fBpid_t *restrict\fR \fIpgroup\fR); +.fi + +.LP +.nf +\fBint\fR \fBposix_spawnattr_setpgroup\fR(\fBposix_spawnattr_t *\fR\fIattr\fR, \fBpid_t\fR \fIpgroup\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBposix_spawnattr_getpgroup()\fR function obtains the value of the +\fIspawn-pgroup\fR attribute from the attributes object referenced by +\fIattr\fR. +.sp +.LP +The \fBposix_spawnattr_setpgroup()\fR function sets the \fIspawn-pgroup\fR +attribute in an initialized attributes object referenced by \fIattr\fR. +.sp +.LP +The \fIspawn-pgroup\fR attribute represents the process group to be joined by +the new process image in a spawn operation (if \fBPOSIX_SPAWN_SETPGROUP\fR is +set in the \fIspawn-flags\fR attribute). The default value of this attribute is +zero. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBposix_spawnattr_getpgroup()\fR returns 0 and +stores the value of the \fIspawn-pgroup\fR attribute of \fIattr\fR into the +object referenced by the \fIpgroup\fR parameter. Otherwise, an error number is +returned to indicate the error. +.sp +.LP +Upon successful completion, \fBposix_spawnattr_setpgroup()\fR returns 0. +Otherwise, an error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +These functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIattr\fR is invalid. +.RE + +.sp +.LP +The \fBposix_spawnattr_setpgroup()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of the attribute being set is not valid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBposix_spawn\fR(3C), posix_spawnattr_getpgroup(3C), +posix_spawnattr_getpgroup(3C), \fBposix_spawnattr_getschedparam\fR(3C), +\fBposix_spawnattr_getschedpolicy\fR(3C), +\fBposix_spawnattr_getsigdefault\fR(3C), \fBposix_spawnattr_getsigmask\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/posix_spawnattr_getschedparam.3c b/usr/src/man/man3c/posix_spawnattr_getschedparam.3c new file mode 100644 index 0000000000..483182fe80 --- /dev/null +++ b/usr/src/man/man3c/posix_spawnattr_getschedparam.3c @@ -0,0 +1,115 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH posix_spawnattr_getschedparam 3C "30 Jan 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +posix_spawnattr_getschedparam, posix_spawnattr_setschedparam \- get and set +spawn-schedparam attribute of spawn attributes object +.SH SYNOPSIS +.LP +.nf +#include <spawn.h> +#include <sched.h> + +\fBint\fR \fBposix_spawnattr_getschedparam\fR(\fBconst posix_spawnattr_t *restrict\fR \fIattr\fR, + \fBstruct sched_param *restrict\fR \fIschedparam\fR); +.fi + +.LP +.nf +\fBint\fR \fBposix_spawnattr_setschedparam\fR(\fBposix_spawnattr_t *restrict\fR \fIattr\fR, + \fBconst struct sched_param *restrict\fR \fIschedparam\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBposix_spawnattr_getschedparam()\fR function obtains the value of the +\fIspawn-schedparam\fR attribute from the attributes object referenced by +\fIattr\fR. +.sp +.LP +The \fBposix_spawnattr_setschedparam()\fR function sets the +\fIspawn-schedparam\fR attribute in an initialized attributes object referenced +by \fIattr\fR. +.sp +.LP +The \fIspawn-schedparam\fR attribute represents the scheduling parameters to be +assigned to the new process image in a spawn operation (if +\fBPOSIX_SPAWN_SETSCHEDULER\fR or \fBPOSIX_SPAWN_SETSCHEDPARAM\fR is set in the +\fIspawn-flags\fR attribute). The default value of this attribute is +unspecified. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBposix_spawnattr_getschedparam()\fR returns 0 and +stores the value of the \fIspawn-schedparam\fR attribute of \fIattr\fR into the +object referenced by the \fIschedparam\fR parameter. Otherwise, an error number +is returned to indicate the error. +.sp +.LP +Upon successful completion, \fBposix_spawnattr_setschedparam()\fR returns 0. +Otherwise, an error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +These functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIattr\fR is invalid. +.RE + +.sp +.LP +The \fBposix_spawnattr_setschedparam()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of the attribute being set is not valid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBposix_spawn\fR(3C), \fBposix_spawnattr_destroy\fR(3C), +\fBposix_spawnattr_getflags\fR(3C), \fBposix_spawnattr_getpgroup\fR(3C), +\fBposix_spawnattr_getschedpolicy\fR(3C), +\fBposix_spawnattr_getsigdefault\fR(3C), \fBposix_spawnattr_getsigmask\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/posix_spawnattr_getschedpolicy.3c b/usr/src/man/man3c/posix_spawnattr_getschedpolicy.3c new file mode 100644 index 0000000000..cdbd436495 --- /dev/null +++ b/usr/src/man/man3c/posix_spawnattr_getschedpolicy.3c @@ -0,0 +1,115 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH posix_spawnattr_getschedpolicy 3C "30 Jan 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +posix_spawnattr_getschedpolicy, posix_spawnattr_setschedpolicy \- get and set +spawn-schedpolicy attribute of spawn attributes object +.SH SYNOPSIS +.LP +.nf +#include <spawn.h> +#include <sched.h> + +\fBint\fR \fBposix_spawnattr_getschedpolicy\fR( + \fBconst posix_spawnattr_t *restrict\fR \fIattr\fR, + \fBint *restrict\fR \fIschedpolicy\fR); +.fi + +.LP +.nf +\fBint\fR \fBposix_spawnattr_setschedpolicy\fR(\fBposix_spawnattr_t *\fR\fIattr\fR, + \fBint\fR \fIschedpolicy\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBposix_spawnattr_getschedpolicy()\fR function obtains the value of the +\fIspawn-schedpolicy\fR attribute from the attributes object referenced by +\fIattr\fR. +.sp +.LP +The \fBposix_spawnattr_setschedpolicy()\fR function sets the +\fIspawn-schedpolicy\fR attribute in an initialized attributes object +referenced by \fIattr\fR. +.sp +.LP +The \fIspawn-schedpolicy\fR attribute represents the scheduling policy to be +assigned to the new process image in a spawn operation (if +\fBPOSIX_SPAWN_SETSCHEDULER\fR is set in the \fIspawn-flags\fR attribute). The +default value of this attribute is unspecified. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBposix_spawnattr_getschedpolicy()\fR returns 0 +and stores the value of the \fIspawn-schedpolicy\fR attribute of \fIattr\fR +into the object referenced by the \fIschedpolicy\fR parameter. Otherwise, an +error number is returned to indicate the error. +.sp +.LP +Upon successful completion, \fBposix_spawnattr_setschedpolicy()\fR returns 0. +Otherwise, an error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +These functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIattr\fR is invalid. +.RE + +.sp +.LP +The \fBposix_spawnattr_setschedpolicy()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of the attribute being set is not valid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBposix_spawn\fR(3C), \fBposix_spawnattr_destroy\fR(3C), +\fBposix_spawnattr_getflags\fR(3C), \fBposix_spawnattr_getpgroup\fR(3C), +\fBposix_spawnattr_getschedparam\fR(3C), +\fBposix_spawnattr_getsigdefault\fR(3C), \fBposix_spawnattr_getsigmask\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/posix_spawnattr_getsigdefault.3c b/usr/src/man/man3c/posix_spawnattr_getsigdefault.3c new file mode 100644 index 0000000000..8697f3b950 --- /dev/null +++ b/usr/src/man/man3c/posix_spawnattr_getsigdefault.3c @@ -0,0 +1,114 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH posix_spawnattr_getsigdefault 3C "30 Jan 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +posix_spawnattr_getsigdefault, posix_spawnattr_setsigdefault \- get and set +spawn-sigdefault attribute of spawn attributes object +.SH SYNOPSIS +.LP +.nf +#include <signal.h> +#include <spawn.h> + +\fBint\fR \fBposix_spawnattr_getsigdefault\fR(\fBconst posix_spawnattr_t *restrict\fR \fIattr\fR, + \fBsigset_t *restrict\fR \fIsigdefault\fR); +.fi + +.LP +.nf +\fBint\fR \fBposix_spawnattr_setsigdefault\fR(\fBposix_spawnattr_t *restrict\fR \fIattr\fR, + \fBconst sigset_t *restrict\fR \fIsigdefault\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBposix_spawnattr_getsigdefault()\fR function obtains the value of the +\fIspawn-sigdefault\fR attribute from the attributes object referenced by +\fIattr\fR. +.sp +.LP +The \fBposix_spawnattr_setsigdefault()\fR function sets the +\fIspawn-sigdefault\fR attribute in an initialized attributes object referenced +by \fIattr\fR. +.sp +.LP +The \fIspawn-sigdefault\fR attribute represents the set of signals to be forced +to default signal handling in the new process image (if +\fBPOSIX_SPAWN_SETSIGDEF\fR is set in the \fIspawn-flags\fR attribute) by a +spawn operation. The default value of this attribute is an empty signal set. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBposix_spawnattr_getsigdefault()\fR returns 0 and +stores the value of the \fIspawn-sigdefault\fR attribute of \fIattr\fR into the +object referenced by the \fIsigdefault\fR parameter. Otherwise, an error +number is returned to indicate the error. +.sp +.LP +Upon successful completion, \fBposix_spawnattr_setsigdefault()\fR returns 0. +Otherwise, an error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +These functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIattr\fR is invalid. +.RE + +.sp +.LP +The \fBposix_spawnattr_setsigdefault()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of the attribute being set is not valid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBposix_spawn\fR(3C), \fBposix_spawnattr_destroy\fR(3C), +\fBposix_spawnattr_getflags\fR(3C), \fBposix_spawnattr_getpgroup\fR(3C), +\fBposix_spawnattr_getschedparam\fR(3C), +\fBposix_spawnattr_getschedpolicy\fR(3C), \fBposix_spawnattr_getsigmask\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/posix_spawnattr_getsigignore_np.3c b/usr/src/man/man3c/posix_spawnattr_getsigignore_np.3c new file mode 100644 index 0000000000..4aaaaada3d --- /dev/null +++ b/usr/src/man/man3c/posix_spawnattr_getsigignore_np.3c @@ -0,0 +1,119 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH posix_spawnattr_getsigignore_np 3C "28 Oct 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +posix_spawnattr_getsigignore_np, posix_spawnattr_setsigignore_np \- get and set +spawn-sigignore attribute of spawn attributes object +.SH SYNOPSIS +.LP +.nf +#include <signal.h> +#include <spawn.h> + +\fBint\fR \fBposix_spawnattr_getsigignore_np\fR( + \fBconst posix_spawnattr_t *restrict\fR \fIattr\fR, + \fBsigset_t *restrict\fR \fIsigignore\fR); +.fi + +.LP +.nf +\fBint\fR \fBposix_spawnattr_setsigignore_np\fR( + \fBposix_spawnattr_t *restrict\fR \fIattr\fR, + \fBconst sigset_t *restrict\fR \fIsigignore\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBposix_spawnattr_getsigignore_np()\fR function obtains the value of the +\fIspawn-sigignore\fR attribute from the attributes object referenced by +\fIattr\fR. +.sp +.LP +The \fBposix_spawnattr_setsigignore_np()\fR function sets the +\fIspawn-sigignore\fR attribute in an initialized attributes object referenced +by \fIattr\fR. +.sp +.LP +The \fIspawn-sigignore\fR attribute represents the set of signals to be forced +to be ignored in the new process image (if \fBPOSIX_SPAWN_SETSIGIGN_NP\fR is +set in the spawn-flags attribute) by a spawn operation. The default value of +this attribute is an empty signal set. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBposix_spawnattr_getsigignore_np()\fR returns 0 +and stores the value of the \fIspawn-sigignore\fR attribute of \fIattr\fR into +the object referenced by the \fIsigignore\fR parameter. Otherwise, an error +value is returned to indicate the error. +.sp +.LP +Upon successful completion, \fBposix_spawnattr_setsigignore_np()\fR returns 0. +Otherwise, an error value is returned to indicate the error. +.SH ERRORS +.sp +.LP +These functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIattr\fR is invalid. +.RE + +.sp +.LP +The \fBposix_spawnattr_setsigignore_np()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of the attribute being set is not valid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBposix_spawn\fR(3C), \fBposix_spawnattr_destroy\fR(3C), +\fBposix_spawnattr_getflags\fR(3C), \fBposix_spawnattr_getpgroup\fR(3C), +\fBposix_spawnattr_getschedparam\fR(3C), +\fBposix_spawnattr_getschedpolicy\fR(3C), +\fBposix_spawnattr_setsigdefault\fR(3C), \fBposix_spawnattr_setsigmask\fR(3C), +\fBattributes\fR(5) +.SH NOTES +.sp +.LP +The \fBPOSIX_SPAWN_SETSIGIGN_NP\fR flag and the +\fBposix_spawnattr_getsigignore_np()\fR and +\fBposix_spawnattr_setsigignore_np()\fR functions are non-portable Solaris +extensions to the \fBposix_spawn\fR(3C) and \fBposix_spawnp()\fR interfaces. diff --git a/usr/src/man/man3c/posix_spawnattr_getsigmask.3c b/usr/src/man/man3c/posix_spawnattr_getsigmask.3c new file mode 100644 index 0000000000..f8b26a1225 --- /dev/null +++ b/usr/src/man/man3c/posix_spawnattr_getsigmask.3c @@ -0,0 +1,113 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH posix_spawnattr_getsigmask 3C "30 Jan 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +posix_spawnattr_getsigmask, posix_spawnattr_setsigmask \- get and set +spawn-sigmask attribute of spawn attributes object +.SH SYNOPSIS +.LP +.nf +#include <signal.h> +#include <spawn.h> + +\fBint\fR \fBposix_spawnattr_getsigmask\fR(\fBconst posix_spawnattr_t *restrict\fR \fIattr\fR, + \fBsigset_t *restrict\fR \fIsigmask\fR); +.fi + +.LP +.nf +\fBint\fR \fBposix_spawnattr_setsigmask\fR(\fBposix_spawnattr_t *restrict\fR \fIattr\fR, + \fBconst sigset_t *restrict\fR \fIsigmask\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBposix_spawnattr_getsigmask()\fR function obtains the value of the +\fIspawn-sigmask\fR attribute from the attributes object referenced by +\fIattr\fR. +.sp +.LP +The \fBposix_spawnattr_setsigmask()\fR function sets the \fIspawn-sigmask\fR +attribute in an initialized attributes object referenced by \fIattr\fR. +.sp +.LP +The \fIspawn-sigmask\fR attribute represents the signal mask in effect in the +new process image of a spawn operation (if \fBPOSIX_SPAWN_SETSIGMASK\fR is set +in the\fI spawn-flags\fR attribute). The default value of this attribute is +unspecified. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBposix_spawnattr_getsigmask()\fR returns 0 and +stores the value of the \fIspawn-sigmask\fR attribute of \fIattr\fR into the +object referenced by the \fIsigmask\fR parameter. Otherwise, an error number +is returned to indicate the error. +.sp +.LP +Upon successful completion, \fBposix_spawnattr_setsigmask()\fR returns 0. +Otherwise, an error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +These functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIattr\fR is invalid. +.RE + +.sp +.LP +The \fBposix_spawnattr_setsigmask()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of the attribute being set is not valid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBposix_spawn\fR(3C), \fBposix_spawnattr_destroy\fR(3C), +\fBposix_spawnattr_getflags\fR(3C), \fBposix_spawnattr_getpgroup\fR(3C), +\fBposix_spawnattr_getschedparam\fR(3C), +\fBposix_spawnattr_getschedpolicy\fR(3C), posix_spawnattr_getsigmask(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/printf.3c b/usr/src/man/man3c/printf.3c new file mode 100644 index 0000000000..d7819d9d18 --- /dev/null +++ b/usr/src/man/man3c/printf.3c @@ -0,0 +1,1184 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" Portions Copyright 1999, Forrest J. Cavalier III. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 1997, The Open Group. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical +.\" and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH printf 3C "7 Jan 2009" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +printf, fprintf, sprintf, snprintf, asprintf \- print formatted output +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBint\fR \fBprintf\fR(\fBconst char *restrict\fR \fIformat\fR, + \fB/*\fR \fIargs\fR*/ ...); +.fi + +.LP +.nf +\fBint\fR \fBfprintf\fR(\fBFILE *restrict\fR \fIstream\fR, \fBconst char *restrict\fR \fIformat\fR, + \fB/*\fR \fIargs\fR*/ ...); +.fi + +.LP +.nf +\fBint\fR \fBsprintf\fR(\fBchar *restrict\fR \fIs\fR, \fBconst char *restrict\fR \fIformat\fR, + \fB/*\fR \fIargs\fR*/ ...); +.fi + +.LP +.nf +\fBint\fR \fBsnprintf\fR(\fBchar *restrict\fR \fIs\fR, \fBsize_t\fR \fIn\fR, + \fBconst char *restrict\fR \fIformat\fR, \fB/*\fR \fIargs\fR*/ ...); +.fi + +.LP +.nf +\fBint\fR \fBasprintf\fR(\fBchar **\fR \fIret\fR, \fBconst char *restrict\fR \fIformat\fR, + \fB/*\fR \fIargs\fR*/ ...); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBprintf()\fR function places output on the standard output stream +\fBstdout\fR. +.sp +.LP +The \fBfprintf()\fR function places output on on the named output stream +\fIstream\fR. +.sp +.LP +The \fBsprintf()\fR function places output, followed by the null byte +(\fB\e0\fR), in consecutive bytes starting at \fIs\fR; it is the user's +responsibility to ensure that enough storage is available. +.sp +.LP +The \fBsnprintf()\fR function is identical to \fBsprintf()\fR with the addition +of the argument \fIn\fR, which specifies the size of the buffer referred to by +\fIs\fR. If \fIn\fR is 0, nothing is written and \fIs\fR can be a null pointer. +Otherwise, output bytes beyond the \fIn\fR-1st are 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. +.sp +.LP +The \fBasprintf()\fR function is the same as the \fBsprintf()\fR function +except that it returns, in the \fIret\fR argument, a pointer to a buffer +sufficiently large to hold the output string. This pointer should be passed to +\fBfree\fR(3C) to release the allocated storage when it is no longer needed. If +sufficient space cannot be allocated, the \fBasprintf()\fR function returns -1 +and sets \fIret\fR to be a \fINULL\fR pointer. +.sp +.LP +Each of these functions converts, formats, and prints its arguments under +control of the \fIformat\fR. The \fIformat\fR is a character string, beginning +and ending in its initial shift state, if any. The \fIformat\fR is composed of +zero or more directives: \fBordinary characters\fR, which are simply copied to +the output stream and \fBconversion specifications\fR, each of which results in +the fetching of zero or more arguments. The results are undefined if there are +insufficient arguments for the \fIformat\fR. If the \fIformat\fR is exhausted +while arguments remain, the excess arguments are evaluated but are otherwise +ignored. +.sp +.LP +Conversions can be applied to the \fIn\fRth argument after the \fIformat\fR in +the argument list, rather than to the next unused argument. In this case, the +conversion specifier \fB%\fR (see below) is replaced by the sequence +\fB%\fR\fIn\fR\fB$\fR, where \fIn\fR is a decimal integer in the range [1, +\fBNL_ARGMAX\fR], 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 \fBEXAMPLES\fR +section). +.sp +.LP +In format strings containing the \fB%\fR\fIn\fR\fB$\fR form of conversion +specifications, numbered arguments in the argument list can be referenced from +the format string as many times as required. +.sp +.LP +In format strings containing the \fB%\fR form of conversion specifications, +each argument in the argument list is used exactly once. +.sp +.LP +All forms of the \fBprintf()\fR functions allow for the insertion of a +language-dependent radix character in the output string. The radix character is +defined by the program's locale (category \fBLC_NUMERIC\fR). In the POSIX +locale, or in a locale where the radix character is not defined, the radix +character defaults to a period (\fB\&.\fR). +.SS "Conversion Specifications" +.sp +.LP +Each conversion specification is introduced by the \fB%\fR character or by the +character sequence \fB%\fR\fIn\fR\fB$\fR, after which the following appear in +sequence: +.RS +4 +.TP +.ie t \(bu +.el o +An optional field, consisting of a decimal digit string followed by a \fB$\fR, +specifying the next argument to be converted. If this field is not provided, +the \fIargs\fR following the last argument converted will be used. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Zero or more \fIflags\fR (in any order), which modify the meaning of the +conversion specification. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +An optional minimum \fIfield width\fR. If the converted value has fewer bytes +than the field width, it will be padded with spaces by default on the left; it +will be padded on the right, if the left-adjustment flag (\fB\(hy\fR), +described below, is given to the field width. The field width takes the form of +an asterisk (*), described below, or a decimal integer. +.sp +If the conversion specifier is \fBs\fR, a standard-conforming application (see +\fBstandards\fR(5)) interprets the field width as the minimum number of bytes +to be printed; an application that is not standard-conforming interprets the +field width as the minimum number of columns of screen display. For an +application that is not standard-conforming, \fB%10s\fR means if the converted +value has a screen width of 7 columns, 3 spaces would be padded on the right. +.sp +If the format is \fB%ws\fR, then the field width should be interpreted as the +minimum number of columns of screen display. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +An optional \fIprecision\fR that gives the minimum number of digits to appear +for the \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, and \fBX\fR conversions +(the field is padded with leading zeros); the number of digits to appear after +the radix character for the \fBa\fR, \fBA\fR, \fBe\fR, \fBE\fR, \fBf\fR, and +\fBF\fR conversions, the maximum number of significant digits for the \fBg\fR +and \fBG\fR conversions; or the maximum number of bytes to be printed from a +string in \fBs\fR and \fBS\fR conversions. The precision takes the form of a +period (.) followed either by an asterisk (*), 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 specifier, the behavior is undefined. +.sp +If the conversion specifier is \fBs\fR or \fBS\fR, a standard-conforming +application (see \fBstandards\fR(5)) interprets the precision as the maximum +number of bytes to be written; an application that is not standard-conforming +interprets the precision as the maximum number of columns of screen display. +For an application that is not standard-conforming, \fB%.5s\fR would print only +the portion of the string that would display in 5 screen columns. Only complete +characters are written. +.sp +For \fB%ws\fR, the precision should be interpreted as the maximum number of +columns of screen display. The precision takes the form of a period (\fB\&.\fR) +followed by a decimal digit string; a null digit string is treated as zero. +Padding specified by the precision overrides the padding specified by the field +width. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +An optional \fIlength modifier\fR that specified the size of the argument. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +A \fIconversion specifier\fR that indicates the type of conversion to be +applied. +.RE +.sp +.LP +A field width, or precision, or both can be indicated by an asterisk +(\fB*\fR) . In this case, an argument of type \fBint\fR supplies the field width or +precision. Arguments specifying field width, or precision, or both must appear +in that order before the argument, if any, to be converted. A negative field +width is taken as a \(mi flag followed by a positive field width. A negative +precision is taken as if the precision were omitted. In format strings +containing the \fB%\fR\fIn\fR\fB$\fR form of a conversion specification, a +field width or precision may be indicated by the sequence +\fB*\fR\fIm\fR\fB$\fR, where \fIm\fR is a decimal integer in the range [1, +\fBNL_ARGMAX\fR] giving the position in the argument list (after the format +argument) of an integer argument containing the field width or precision, for +example: +.sp +.in +2 +.nf +printf("%1$d:%2$.*3$d:%4$.*3$d\en", hour, min, precision, sec); +.fi +.in -2 + +.sp +.LP +The \fIformat\fR can contain either numbered argument specifications (that is, +\fB%\fR\fIn\fR\fB$\fR and \fB*\fR\fIm\fR\fB$\fR), or unnumbered argument +specifications (that is, \fB%\fR and \fB*\fR), but normally not both. The only +exception to this is that \fB%%\fR can be mixed with the \fB%\fR\fIn\fR\fB$\fR +form. The results of mixing numbered and unnumbered argument specifications in +a \fIformat\fR string are undefined. When numbered argument specifications are +used, specifying the \fIN\fRth argument requires that all the leading +arguments, from the first to the (\fIN-1\fR)th, are specified in the format +string. +.SS "Flag Characters" +.sp +.LP +The flag characters and their meanings are: +.sp +.ne 2 +.mk +.na +\fB\fB\&'\fR\fR +.ad +.RS 9n +.rt +The integer portion of the result of a decimal conversion (\fB%i\fR, \fB%d\fR, +\fB%u\fR, \fB%f\fR, \fB%F\fR, \fB%g\fR, or \fB%G\fR) will be formatted with +thousands' grouping characters. For other conversions the behavior is +undefined. The non-monetary grouping character is used. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\(mi\fR\fR +.ad +.RS 9n +.rt +The result of the conversion will be left-justified within the field. The +conversion will be right-justified if this flag is not specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB+\fR\fR +.ad +.RS 9n +.rt +The result of a signed conversion will always begin with a sign (+ or -). The +conversion will begin with a sign only when a negative value is converted if +this flag is not specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBspace\fR\fR +.ad +.RS 9n +.rt +If the first character of a signed conversion is not a sign or if a signed +conversion results in no characters, a space will be placed before the result. +This means that if the \fBspace\fR and \fB+\fR flags both appear, the space +flag will be ignored. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB#\fR\fR +.ad +.RS 9n +.rt +The value is to be converted to an alternate form. For \fBc\fR, \fBd\fR, +\fBi\fR, \fBs\fR, and \fBu\fR conversions, the flag has no effect. For an +\fBo\fR conversion, it increases the precision (if necessary) to force the +first digit of the result to be a zero. For \fBx\fR or \fBX\fR conversion, a +non-zero result will have \fB0x\fR (or \fB0X\fR) prepended to it. For \fBa\fR, +\fBA\fR, \fBe\fR, \fBE\fR, \fBf\fR, \fBF\fR, \fBg\fR, and \fBG\fR conversions, +the result will always contain a radix character, even if no digits follow the +radix character. Without this flag, the radix character appears in the result +of these conversions only if a digit follows it. For \fBg\fR and \fBG\fR +conversions, trailing zeros will not be removed from the result as they +normally are. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 9n +.rt +For \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, \fBX\fR, \fBa\fR, \fBA\fR, +\fBe\fR, \fBE\fR, \fBf\fR, \fBF\fR, \fBg\fR, and \fBG\fR conversions, leading +zeros (following any indication of sign or base) are used to pad to the field +width; no space padding is performed. If the \fB0\fR and \fB\(mi\fR flags both +appear, the \fB0\fR flag will be ignored. For \fBd\fR, \fBi\fR, \fBo\fR, +\fBu\fR, \fBx\fR, and \fBX\fR conversions, if a precision is specified, the +\fB0\fR flag will be ignored. If the \fB0\fR and \fB\&'\fR flags both appear, +the grouping characters are inserted before zero padding. For other +conversions, the behavior is undefined. +.RE + +.SS "Length Modifiers" +.sp +.LP +The length modifiers and their meanings are: +.sp +.ne 2 +.mk +.na +\fB\fBhh\fR\fR +.ad +.RS 16n +.rt +Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, or +\fBX\fR conversion specifier applies to a \fBsigned char\fR or \fBunsigned +char\fR argument (the argument will have been promoted according to the integer +promotions, but its value will be converted to \fBsigned char\fR or \fBunsigned +char\fR before printing); or that a following \fBn\fR conversion specifier +applies to a pointer to a \fBsigned char\fR argument. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBh\fR\fR +.ad +.RS 16n +.rt +Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, or +\fBX\fR conversion specifier applies to a \fBshort\fR or \fBunsigned short\fR +argument (the argument will have been promoted according to the integer +promotions, but its value will be converted to \fBshort\fR or \fBunsigned +short\fR before printing); or that a following \fBn\fR conversion specifier +applies to a pointer to a \fBshort\fR argument. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBl (ell)\fR\fR +.ad +.RS 16n +.rt +Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, or +\fBX\fR conversion specifier applies to a \fBlong\fR or \fBunsigned long\fR +argument; that a following \fBn\fR conversion specifier applies to a pointer to +a \fBlong\fR argument; that a following \fBc\fR conversion specifier applies to +a \fBwint_t\fR argument; that a following \fBs\fR conversion specifier applies +to a pointer to a \fBwchar_t\fR argument; or has no effect on a following +\fBa\fR, \fBA\fR, \fBe\fR, \fBE\fR, \fBf\fR, \fBF\fR, \fBg\fR, or \fBG\fR +conversion specifier. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBll (ell-ell)\fR\fR +.ad +.RS 16n +.rt +Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, or +\fBX\fR conversion specifier applies to a \fBlong long\fR or \fBunsigned long +long\fR argument; or that a following \fBn\fR conversion specifier applies to a +pointer to a \fBlong long\fR argument. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBj\fR\fR +.ad +.RS 16n +.rt +Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, or +\fBX\fR conversion specifier applies to an \fBintmax_t\fR or \fBuintmax_t\fR +argument; or that a following \fBn\fR conversion specifier applies to a pointer +to an \fBintmax_t\fR argument. See NOTES. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBz\fR\fR +.ad +.RS 16n +.rt +Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, or +\fBX\fR conversion specifier applies to a \fBsize_t\fR or the corresponding +signed integer type argument; or that a following \fBn\fR conversion specifier +applies to a pointer to a signed integer type corresponding to \fBsize_t\fR +argument. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBt\fR\fR +.ad +.RS 16n +.rt +Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, or +\fBX\fR conversion specifier applies to a \fBptrdiff_t\fR or the corresponding +unsigned type argument; or that a following n conversion specifier applies to a +pointer to a \fBptrdiff_t\fR argument. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBL\fR\fR +.ad +.RS 16n +.rt +Specifies that a following \fBa\fR, \fBA\fR, \fBe\fR, \fBE\fR, \fBf\fR, +\fBF\fR, \fBg\fR, or \fBG\fR conversion specifier applies to a \fBlong +double\fR argument. +.RE + +.sp +.LP +If a length modifier appears with any conversion specifier other than as +specified above, the behavior is undefined. +.SS "Conversion Specifiers" +.sp +.LP +Each conversion specifier results in fetching zero or more arguments. The +results are undefined if there are insufficient arguments for the format. If +the format is exhausted while arguments remain, the excess arguments are +ignored. +.sp +.LP +The conversion specifiers and their meanings are: +.sp +.ne 2 +.mk +.na +\fB\fBd\fR, \fBi\fR\fR +.ad +.RS 8n +.rt +The \fBint\fR argument is converted to a signed decimal in the style +\fB[\fR\(mi\fB]\fR\fIdddd\fR. The precision specifies the minimum number of +digits to appear; if the value being converted can be represented in fewer +digits, it will be expanded with leading zeros. The default precision is 1. The +result of converting 0 with an explicit precision of 0 is no characters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBo\fR\fR +.ad +.RS 8n +.rt +The \fBunsigned int\fR argument is converted to unsigned octal format in the +style \fIdddd\fR. The precision specifies the minimum number of digits to +appear; if the value being converted can be represented in fewer digits, it +will be expanded with leading zeros. The default precision is 1. The result of +converting 0 with an explicit precision of 0 is no characters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBu\fR\fR +.ad +.RS 8n +.rt +The \fBunsigned int\fR argument is converted to unsigned decimal format in the +style \fIdddd\fR. The precision specifies the minimum number of digits to +appear; if the value being converted can be represented in fewer digits, it +will be expanded with leading zeros. The default precision is 1. The result of +converting 0 with an explicit precision of 0 is no characters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBx\fR\fR +.ad +.RS 8n +.rt +The \fBunsigned int\fR argument is converted to unsigned hexadecimal format in +the style \fIdddd\fR; the letters \fBabcdef\fR are used. The precision +specifies the minimum number of digits to appear; if the value being converted +can be represented in fewer digits, it will be expanded with leading zeros. The +default precision is 1. The result of converting 0 with an explicit precision +of 0 is no characters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBX\fR\fR +.ad +.RS 8n +.rt +Behaves the same as the \fBx\fR conversion specifier except that letters +\fBABCDEF\fR are used instead of \fBabcdef\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBf\fR, \fBF\fR\fR +.ad +.RS 8n +.rt +The \fBdouble\fR argument is converted to decimal notation in the style +[\fB\(mi\fR]\fIddd\fR\fB\&.\fR\fIddd\fR, where the number of digits after the +radix character (see \fBsetlocale\fR(3C)) is equal to the precision +specification. If the precision is missing it is taken as 6; if the precision +is explicitly 0 and the \fB#\fR flag is not specified, no radix character +appears. If a radix character appears, at least 1 digit appears before it. The +converted value is rounded to fit the specified output format according to the +prevailing floating point rounding direction mode. If the conversion is not +exact, an inexact exception is raised. +.sp +For the \fBf\fR specifier, a double argument representing an infinity or NaN is +converted in the style of the \fBe\fR conversion specifier, except that for an +infinite argument, "infinity" or "Infinity" is printed when the precision is at +least 8 and "inf" or "Inf" is printed otherwise. +.sp +For the F specifier, a double argument representing an infinity or NaN is +converted in the SUSv3 style of the E conversion specifier, except that for an +infinite argument, "INFINITY" is printed when the precision is at least 8 and +or "INF" is printed otherwise. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBe\fR, \fBE\fR\fR +.ad +.RS 8n +.rt +The \fBdouble\fR argument is converted to the style +[\fB\(mi\fR]\fId\fR\fB\&.\fR\fIddd\fR\fBe\fR\fI\(+-dd\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. When the +precision is missing it is taken as 6; if the precision is 0 and the \fB#\fR +flag is not specified, no radix character appears. The \fBE\fR conversion +specifier will produce a number with \fBE\fR instead of \fBe\fR introducing the +exponent. The exponent always contains at least two digits. The converted value +is rounded to fit the specified output format according to the prevailing +floating point rounding direction mode. If the conversion is not exact, an +inexact exception is raised. +.sp +Infinity and NaN values are handled in one of the following ways: +.sp +.ne 2 +.mk +.na +\fBSUSv3\fR +.ad +.RS 11n +.rt +For the \fBe\fR specifier, a \fBdouble\fR argument representing an infinity is +printed as "[\(mi]\fBinfinity\fR", when the precision for the conversion is at +least 7 and as "[\(mi]\fBinf\fR" otherwise. A \fBdouble\fR argument +representing a NaN is printed as "[\(mi]\fBnan\fR". For the \fBE\fR specifier, +"\fBINF\fR", "\fBINFINITY\fR", and "\fBNAN\fR" are printed instead of +"\fBinf\fR", "\fBinfinity\fR", and "\fBnan\fR", respectively. Printing of the +sign follows the rules described above. +.RE + +.sp +.ne 2 +.mk +.na +\fBDefault\fR +.ad +.RS 11n +.rt +A \fBdouble\fR argument representing an infinity is printed as +"[\(mi]\fBInfinity\fR", when the precision for the conversion is at least 7 and +as "[\(mi]\fBInf\fR" otherwise. A double argument representing a NaN is printed +as "[\(mi]\fBNaN\fR". Printing of the sign follows the rules described above. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBg\fR, \fBG\fR\fR +.ad +.RS 8n +.rt +The \fBdouble\fR argument is printed in style \fBf\fR or \fBe\fR (or in style +\fBE\fR in the case of a \fBG\fR conversion specifier), with the precision +specifying the number of significant digits. If an explicit precision is 0, it +is taken as 1. The style used depends on the value converted: style \fBe\fR (or +\fBE\fR) will be used only if the exponent resulting from the conversion is +less than -4 or greater than or equal to the precision. Trailing zeros are +removed from the fractional part of the result. A radix character appears only +if it is followed by a digit. +.sp +A \fBdouble\fR argument representing an infinity or NaN is converted in the +style of the \fBe\fR or \fBE\fR conversion specifier, except that for an +infinite argument, "infinity", "INFINITY", or "Infinity" is printed when the +precision is at least 8 and "inf", "INF", or "Inf" is printed otherwise. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBa\fR, \fBA\fR\fR +.ad +.RS 8n +.rt +A \fBdouble\fR argument representing a floating-point number is converted in +the style "[-]0\fIxh\fR.\fIhhhhp\fR\(+-\fId\fR", where the single hexadecimal +digit preceding the radix point is 0 if the value converted is zero and 1 +otherwise and the number of hexadecimal digits after it is equal to the +precision; if the precision is missing, the number of digits printed after the +radix point is 13 for the conversion of a double value, 16 for the conversion +of a long double value on x86, and 28 for the conversion of a long double value +on SPARC; if the precision is zero and the '#' flag is not specified, no +decimal-point character will appear. The letters "\fBabcdef\fR" are used for +\fBa\fR conversion and the letters "\fBABCDEF\fR" for \fBA\fR conversion. The +\fBA\fR conversion specifier produces a number with '\fBX\fR' and '\fBP\fR' +instead of '\fBx\fR' and '\fBp\fR'. The exponent will 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 is zero. +.sp +The converted value is rounded to fit the specified output format according to +the prevailing floating point rounding direction mode. If the conversion is not +exact, an inexact exception is raised. +.sp +A \fBdouble\fR argument representing an infinity or NaN is converted in the +SUSv3 style of an \fBe\fR or \fBE\fR conversion specifier. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBc\fR\fR +.ad +.RS 8n +.rt +The \fBint\fR argument is converted to an \fBunsigned char\fR, and the +resulting byte is printed. +.sp +If an \fBl\fR (ell) qualifier is present, the \fBwint_t\fR argument is +converted as if by an \fBls\fR conversion specification with no precision and +an argument that points to a two-element array of type \fBwchar_t\fR, the first +element of which contains the \fBwint_t\fR argument to the \fBls\fR conversion +specification and the second element contains a null wide-character. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBC\fR\fR +.ad +.RS 8n +.rt +Same as \fBlc\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBwc\fR\fR +.ad +.RS 8n +.rt +The \fBint\fR argument is converted to a wide character (\fBwchar_t\fR), and +the resulting wide character is printed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBs\fR\fR +.ad +.RS 8n +.rt +The argument must be a pointer to an array of \fBchar\fR. Bytes from the array +are written up to (but not including) any terminating null byte. If a precision +is specified, a standard-conforming application (see \fBstandards\fR(5)) will +write only the number of bytes specified by precision; an application that is +not standard-conforming will write only the portion of the string that will +display in the number of columns of screen display specified by precision. If +the precision is not specified, it is taken to be infinite, so all bytes up to +the first null byte are printed. An argument with a null value will yield +undefined results. +.sp +If an \fBl\fR (ell) qualifier is present, the argument must be a pointer to an +array of type \fBwchar_t\fR. Wide-characters from the array are converted to +characters (each as if by a call to the \fBwcrtomb\fR(3C) function, with the +conversion state described by an \fBmbstate_t\fR object initialized to zero +before the first wide-character is converted) up to and including a terminating +null wide-character. The resulting characters are written up to (but not +including) the terminating null character (byte). If no precision is specified, +the array must contain a null wide-character. If a precision is specified, no +more than that many characters (bytes) are written (including shift sequences, +if any), and the array must 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 is a partial +character written. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBS\fR\fR +.ad +.RS 8n +.rt +Same as \fBls\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBws\fR\fR +.ad +.RS 8n +.rt +The argument must be a pointer to an array of \fBwchar_t\fR. Bytes from the +array are written up to (but not including) any terminating null character. If +the precision is specified, only that portion of the wide-character array that +will display in the number of columns of screen display specified by precision +will be written. If the precision is not specified, it is taken to be infinite, +so all wide characters up to the first null character are printed. An argument +with a null value will yield undefined results. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBp\fR\fR +.ad +.RS 8n +.rt +The argument must be a pointer to \fBvoid\fR. The value of the pointer is +converted to a set of sequences of printable characters, which should be the +same as the set of sequences that are matched by the \fB%p\fR conversion of the +\fBscanf\fR(3C) function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBn\fR\fR +.ad +.RS 8n +.rt +The argument must be a pointer to an integer into which is written the number +of bytes written to the output standard I/O stream so far by this call to one +of the \fBprintf()\fR functions. No argument is converted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%\fR\fR +.ad +.RS 8n +.rt +Print a \fB%\fR; no argument is converted. The entire conversion specification +must be %%. +.RE + +.sp +.LP +If a conversion specification does not match one of the above forms, the +behavior is undefined. +.sp +.LP +In no case does a non-existent or small field width cause truncation of a +field; if the result of a conversion is wider than the field width, the field +is simply expanded to contain the conversion result. Characters generated by +\fBprintf()\fR and \fBfprintf()\fR are printed as if the \fBputc\fR(3C) +function had been called. +.sp +.LP +The \fBst_ctime\fR and \fBst_mtime\fR fields of the file will be marked for +update between the call to a successful execution of \fBprintf()\fR or +\fBfprintf()\fR and the next successful completion of a call to +\fBfflush\fR(3C) or \fBfclose\fR(3C) on the same stream or a call to +\fBexit\fR(3C) or \fBabort\fR(3C). +.SH RETURN VALUES +.sp +.LP +The \fBprintf()\fR, \fBfprintf()\fR, \fBsprintf()\fR, and \fBasprintf()\fR +functions return the number of bytes transmitted (excluding the terminating +null byte in the case of \fBsprintf()\fR and \fBasprintf()\fR). +.sp +.LP +The \fBsnprintf()\fR function returns the number of bytes that would have been +written to \fIs\fR if \fIn\fR had been sufficiently large (excluding the +terminating null byte.) If the value of \fIn\fR is 0 on a call to +\fBsnprintf()\fR, \fIs\fR can be a null pointer and the number of bytes that +would have been written if \fIn\fR had been sufficiently large (excluding the +terminating null byte) is returned. +.sp +.LP +Each function returns a negative value if an output error was encountered. +.SH ERRORS +.sp +.LP +For the conditions under which \fBprintf()\fR and \fBfprintf()\fR will fail and +may fail, refer to \fBfputc\fR(3C) or \fBfputwc\fR(3C). +.sp +.LP +The \fBsnprintf()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEOVERFLOW\fR\fR +.ad +.RS 13n +.rt +The value of \fIn\fR is greater than \fBINT_MAX\fR or the number of bytes +needed to hold the output excluding the terminating null is greater than +\fBINT_MAX\fR. +.RE + +.sp +.LP +The \fBprintf()\fR, \fBfprintf()\fR, \fBsprintf()\fR, and \fBsnprintf()\fR +functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEILSEQ\fR\fR +.ad +.RS 10n +.rt +A wide-character code that does not correspond to a valid character has been +detected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +There are insufficient arguments. +.RE + +.sp +.LP +The \fBprintf()\fR, \fBfprintf()\fR, and \fBasprintf()\fR functions may fail +due to an underlying \fBmalloc\fR(3C) failure if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +Storage space is temporarily unavailable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient storage space is available. +.RE + +.SH USAGE +.sp +.LP +If the application calling the \fBprintf()\fR functions has any objects of type +\fBwint_t\fR or \fBwchar_t\fR, it must also include the header \fB<wchar.h>\fR +to have these objects defined. +.SS "Escape Character Sequences" +.sp +.LP +It is common to use the following escape sequences built into the C language +when entering format strings for the \fBprintf()\fR functions, but these +sequences are processed by the C compiler, not by the \fBprintf()\fR function. +.sp +.ne 2 +.mk +.na +\fB\fB\ea\fR\fR +.ad +.RS 7n +.rt +Alert. Ring the bell. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\eb\fR\fR +.ad +.RS 7n +.rt +Backspace. Move the printing position to one character before the current +position, unless the current position is the start of a line. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\ef\fR\fR +.ad +.RS 7n +.rt +Form feed. Move the printing position to the initial printing position of the +next logical page. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\en\fR\fR +.ad +.RS 7n +.rt +Newline. Move the printing position to the start of the next line. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\er\fR\fR +.ad +.RS 7n +.rt +Carriage return. Move the printing position to the start of the current line. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\et\fR\fR +.ad +.RS 7n +.rt +Horizontal tab. Move the printing position to the next implementation-defined +horizontal tab position on the current line. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\ev\fR\fR +.ad +.RS 7n +.rt +Vertical tab. Move the printing position to the start of the next +implementation-defined vertical tab position. +.RE + +.sp +.LP +In addition, the C language supports character sequences of the form +.sp +.LP +\eoctal-number +.sp +.LP +and +.sp +.LP +\ehex-number +.sp +.LP +which translates into the character represented by the octal or hexadecimal +number. For example, if ASCII representations are being used, the letter 'a' +may be written as '\e141' and 'Z' as '\e132'. This syntax is most frequently +used to represent the null character as '\e0'. This is exactly equivalent to +the numeric constant zero (0). Note that the octal number does not include the +zero prefix as it would for a normal octal constant. To specify a hexadecimal +number, omit the zero so that the prefix is an 'x' (uppercase 'X' is not +allowed in this context). Support for hexadecimal sequences is an ANSI +extension. See \fBstandards\fR(5). +.SH EXAMPLES +.LP +\fBExample 1 \fRTo print the language-independent date and time format, the +following statement could be used: +.sp +.in +2 +.nf +\fBprintf (format, weekday, month, day, hour, min);\fR +.fi +.in -2 + +.sp +.LP +For American usage, \fIformat\fR could be a pointer to the string: + +.sp +.in +2 +.nf +\fB"%s, %s %d, %d:%.2d\en"\fR +.fi +.in -2 + +.sp +.LP +producing the message: + +.sp +.in +2 +.nf +\fBSunday, July 3, 10:02\fR +.fi +.in -2 + +.sp +.LP +whereas for German usage, \fIformat\fR could be a pointer to the string: + +.sp +.in +2 +.nf +"%1$s, %3$d. %2$s, %4$d:%5$.2d\en" +.fi +.in -2 + +.sp +.LP +producing the message: + +.sp +.in +2 +.nf +Sonntag, 3. Juli, 10:02 +.fi +.in -2 + +.LP +\fBExample 2 \fRTo print a date and time in the form \fBSunday, July 3, +10:02\fR, where \fBweekday\fR and \fBmonth\fR are pointers to null-terminated +strings: +.sp +.in +2 +.nf +printf("%s, %s %i, %d:%.2d", weekday, month, day, hour, min); +.fi +.in -2 + +.LP +\fBExample 3 \fRTo print pi to 5 decimal places: +.sp +.in +2 +.nf +printf("pi = %.5f", 4 * atan(1.0)); +.fi +.in -2 + +.SS "Default" +.LP +\fBExample 4 \fRThe following example applies only to applications that are not +standard-conforming. To print a list of names in columns which are 20 +characters wide: +.sp +.in +2 +.nf +\fBprintf("%20s%20s%20s", lastname, firstname, middlename);\fR +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +CSIEnabled +_ +Interface StabilityCommitted +_ +MT-LevelSee below. +_ +StandardSee below. +.TE + +.sp +.LP +All of these functions can be used safely in multithreaded applications, as +long as \fBsetlocale\fR(3C) is not being called to change the locale. The +\fBsprintf()\fR and \fBsnprintf()\fR functions are Async-Signal-Safe. +.sp +.LP +See \fBstandards\fR(5) for the standards conformance of \fBprintf()\fR, +\fBfprintf()\fR, \fBsprintf()\fR, and \fBsnprintf()\fR. The \fBasprintf()\fR +function is modeled on the one that appears in the FreeBSD, NetBSD, and GNU C +libraries. +.SH SEE ALSO +.sp +.LP +\fBexit\fR(2), \fBlseek\fR(2), \fBwrite\fR(2), \fBabort\fR(3C), \fBecvt\fR(3C), +\fBexit\fR(3C), \fBfclose\fR(3C), \fBfflush\fR(3C), \fBfputwc\fR(3C), +\fBfree\fR(3C), \fBmalloc\fR(3C), \fBputc\fR(3C), \fBscanf\fR(3C), +\fBsetlocale\fR(3C), \fBstdio\fR(3C), \fBvprintf\fR(3C), \fBwcstombs\fR(3C), +\fBwctomb\fR(3C), \fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +If the \fBj\fR length modifier is used, 32-bit applications that were compiled +using \fBc89\fR on releases prior to Solaris 10 will experience undefined +behavior. +.sp +.LP +The \fBsnprintf()\fR return value when \fIn\fR = 0 was changed in the Solaris +10 release. The change was based on the SUSv3 specification. The previous +behavior was based on the initial SUSv2 specification, where \fBsnprintf()\fR +when \fIn\fR = 0 returns an unspecified value less than 1. diff --git a/usr/src/man/man3c/priv_addset.3c b/usr/src/man/man3c/priv_addset.3c new file mode 100644 index 0000000000..cba11c6480 --- /dev/null +++ b/usr/src/man/man3c/priv_addset.3c @@ -0,0 +1,241 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH priv_addset 3C "28 Jan 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +priv_addset, priv_allocset, priv_copyset, priv_delset, priv_emptyset, +priv_fillset, priv_freeset, priv_intersect, priv_inverse, priv_isemptyset, +priv_isequalset, priv_isfullset, priv_ismember, priv_issubset, priv_union \- +privilege set manipulation functions +.SH SYNOPSIS +.LP +.nf +#include <priv.h> + +\fBint\fR \fBpriv_addset\fR(\fBpriv_set_t *\fR\fIsp\fR, \fBconst char *\fR\fIpriv\fR); +.fi + +.LP +.nf +\fBpriv_set_t *\fR\fBpriv_allocset\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBpriv_copyset\fR(\fBconst priv_set_t *\fR\fIsrc\fR, \fBpriv_set_t *\fR\fIdst\fR); +.fi + +.LP +.nf +\fBint\fR \fBpriv_delset\fR(\fBpriv_set_t *\fR\fIsp\fR, \fBconst char *\fR\fIpriv\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBpriv_emptyset\fR(\fBpriv_set_t *\fR\fIsp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBpriv_fillset\fR(\fBpriv_set_t *\fR\fIsp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBpriv_freeset\fR(\fBpriv_set_t *\fR\fIsp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBpriv_intersect\fR(\fBconst priv_set_t *\fR\fIsrc\fR, \fBpriv_set_t *\fR\fIdst\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBpriv_inverse\fR(\fBpriv_set_t *\fR\fIsp\fR); +.fi + +.LP +.nf +\fBboolean_t\fR \fBpriv_isemptyset\fR(\fBconst priv_set_t *\fR\fIsp\fR); +.fi + +.LP +.nf +\fBboolean_t\fR \fBpriv_isequalset\fR(\fBconst priv_set_t *\fR\fIsrc\fR, \fBconst priv_set_t *\fR\fIdst\fR); +.fi + +.LP +.nf +\fBboolean_t\fR \fBpriv_isfullset\fR(\fBconst priv_set_t *\fR\fIsp\fR); +.fi + +.LP +.nf +\fBboolean_t\fR \fBpriv_ismember\fR(\fBconst priv_set_t *\fR\fIsp\fR, \fBconst char *\fR\fIpriv\fR); +.fi + +.LP +.nf +\fBboolean_t\fR \fBpriv_issubset\fR(\fBconst priv_set_t *\fR\fIsrc\fR, \fBconst priv_set_t *\fR\fIdst\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBpriv_union\fR(\fBconst priv_set_t *\fR\fIsrc\fR, \fBpriv_set_t *\fR\fIdst\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fIsp\fR, \fIsrc\fR, and \fIdst\fR arguments point to privilege sets. The +\fIpriv\fR argument points to a named privilege. +.sp +.LP +The \fBpriv_addset()\fR function adds the named privilege \fIpriv\fR to +\fIsp\fR. +.sp +.LP +The \fBpriv_allocset()\fR function allocates sufficient memory to contain a +privilege set. The value of the returned privilege set is indeterminate. The +function returns \fINULL\fR and sets \fBerrno\fR when it fails to allocate +memory. +.sp +.LP +The \fBpriv_copyset()\fR function copies the set \fIsrc\fR to \fIdst\fR. +.sp +.LP +The \fBpriv_delset()\fR function removes the named privilege \fIpriv\fR from +\fIsp\fR. +.sp +.LP +The \fBpriv_emptyset()\fR function clears all privileges from \fIsp\fR. +.sp +.LP +The \fBpriv_fillset()\fR function asserts all privileges in \fIsp\fR, including +the privileges not currently defined in the system. +.sp +.LP +The \fBpriv_freeset()\fR function frees the storage allocated by +\fBpriv_allocset()\fR. +.sp +.LP +The \fBpriv_intersect()\fR function intersects \fIsrc\fR with \fIdst\fR and +places the results in \fIdst\fR. +.sp +.LP +The \fBpriv_inverse()\fR function inverts the privilege set given as argument +in place. +.sp +.LP +The \fBpriv_isemptyset()\fR function checks whether the argument is an empty +set. +.sp +.LP +The \fBpriv_isequalset()\fR function checks whether the privilege set \fIsrc\fR +is equal to \fIdst\fR. +.sp +.LP +The \fBpriv_isfullset()\fR function checks whether the argument is a full set. +A full set is a set with all bits set, regardless of whether the privilege is +currently defined in the system. +.sp +.LP +The \fBpriv_ismember()\fR function checks whether the named privilege +\fIpriv\fR is a member of \fIsp\fR. +.sp +.LP +The \fBpriv_issubset()\fR function checks whether \fIsrc\fR is a subset of +\fIdst\fR. +.sp +.LP +The \fBpriv_union()\fR function takes the union of \fIsrc\fR and \fIdst\fR and +places the result in \fIdst\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBpriv_allocset()\fR returns a pointer to an +opaque data structure. It returns \fINULL\fR if memory allocation fails and +sets \fBerrno\fR to indicate the error. +.sp +.LP +Upon successful completion, \fBpriv_isemptyset()\fR, \fBpriv_isfullset()\fR, +\fBpriv_isequalset()\fR, \fBpriv_issubset()\fR, and \fBpriv_ismember()\fR +return \fBB_TRUE\fR. Otherwise, they return \fBB_FALSE\fR. +.sp +.LP +Upon successful completion, \fBpriv_delset()\fR and \fBpriv_addset()\fR return +0. Otherwise, they return -1 and set \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpriv_allocset()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +The physical limits of the system are exceeded by the memory allocation needed +to hold a privilege set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +There is insufficient memory for allocation to hold a privilege set. The +application can try again later. +.RE + +.sp +.LP +The \fBpriv_delset()\fR and \fBpriv_addset()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The privilege argument is not a valid privilege name. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBsetppriv\fR(2), \fBmalloc\fR(3C), \fBpriv_str_to_set\fR(3C), +\fBattributes\fR(5), \fBprivileges\fR(5) +.SH NOTES +.sp +.LP +The functions that compare sets operate on all bits of the set, regardless of +whether the specific privileges are currently defined in the system. diff --git a/usr/src/man/man3c/priv_set.3c b/usr/src/man/man3c/priv_set.3c new file mode 100644 index 0000000000..5c48f8c939 --- /dev/null +++ b/usr/src/man/man3c/priv_set.3c @@ -0,0 +1,143 @@ +'\" te +.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH priv_set 3C "25 Sep 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +priv_set, priv_ineffect \- change privilege sets and check whether privileges +are set +.SH SYNOPSIS +.LP +.nf +#include <priv.h> + +\fBint\fR \fBpriv_set\fR(\fBpriv_op_t\fR \fIop\fR, \fBpriv_ptype_t\fR \fIwhich\fR...); +.fi + +.LP +.nf +\fBboolean_t\fR \fBpriv_ineffect\fR(\fBconst char *\fR\fIpriv\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpriv_set()\fR function is a convenient wrapper for the \fBsetppriv\fR(2) +function. It takes three or more arguments. The operation argument, \fIop\fR, +can be one of \fBPRIV_OFF\fR, \fBPRIV_ON\fR or \fBPRIV_SET\fR. The \fIwhich\fR +argument is the name of the privilege set to change. The third argument is a +list of zero or more privilege names terminated with a null pointer. If +\fIwhich\fR is the special pseudo set \fBPRIV_ALLSETS\fR, the operation should +be applied to all privilege sets. +.sp +.LP +The specified privileges are converted to a binary privilege set and +\fBsetppriv()\fR is called with the same \fIop\fR and \fIwhich\fR arguments. +When called with \fBPRIV_ALLSETS\fR as the value for the \fIwhich\fR argument, +\fBsetppriv()\fR is called for each set in turn, aborting on the first failed +call. +.sp +.LP +The \fBpriv_ineffect()\fR function is a conventient wrapper for the +\fBgetppriv\fR(2) function. The \fIpriv\fR argument specifies the name of the +privilege for which this function checks its presence in the effective set. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBpriv_set()\fR return 0. Otherwise, -1 is +returned and \fBerrno\fR is set to indicate the error. +.sp +.LP +If \fIpriv\fR is a valid privilege that is a member of the effective set, +\fBpriv_ineffect()\fR returns \fBB_TRUE\fR. Otherwise, it returns \fBB_FALSE\fR +and sets \fBerrno\fR to incicate the error. +.SH ERRORS +.sp +.LP +The \fBpriv_set()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of \fIop\fR or \fIwhich\fR is out of range. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient memory was allocated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 10n +.rt +The application attempted to add privileges to \fBPRIV_LIMIT\fR or +\fBPRIV_PERMITTED\fR, or the application attempted to add privileges to +\fBPRIV_INHERITABLE\fR or \fBPRIV_EFFECTIVE\fR that were not in +\fBPRIV_PERMITTED\fR. +.RE + +.sp +.LP +The \fBpriv_ineffect()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The privilege specified by \fIpriv\fR is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient memory was allocated. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBsetppriv\fR(2), \fBpriv_str_to_set\fR(3C), \fBattributes\fR(5), +\fBprivileges\fR(5) diff --git a/usr/src/man/man3c/priv_str_to_set.3c b/usr/src/man/man3c/priv_str_to_set.3c new file mode 100644 index 0000000000..333dd92074 --- /dev/null +++ b/usr/src/man/man3c/priv_str_to_set.3c @@ -0,0 +1,233 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH priv_str_to_set 3C "6 Jan 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +priv_str_to_set, priv_set_to_str, priv_getbyname, priv_getbynum, +priv_getsetbyname, priv_getsetbynum, priv_gettext \- privilege name functions +.SH SYNOPSIS +.LP +.nf +#include <priv.h> + +\fBpriv_set_t *\fR\fBpriv_str_to_set\fR(\fBconst char *\fR\fIbuf\fR, \fBconst char *\fR\fIsep\fR, + \fBconst char **\fR\fIendptr\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBpriv_set_to_str\fR(\fBconst priv_set_t *\fR\fIset\fR, \fBchar\fR \fIsep\fR, \fBint\fR \fIflag\fR); +.fi + +.LP +.nf +\fBint\fR \fBpriv_getbyname\fR(\fBconst char *\fR\fIprivname\fR); +.fi + +.LP +.nf +\fBconst char *\fR\fBpriv_getbynum\fR(\fBint\fR \fIprivnum\fR); +.fi + +.LP +.nf +\fBint\fR \fBpriv_getsetbyname\fR(\fBconst char *\fR\fIprivsetname\fR); +.fi + +.LP +.nf +\fBconst char *\fR\fBpriv_getsetbynum\fR(\fBint\fR \fIprivname\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBpriv_gettext\fR(\fBconst char *\fR\fIprivname\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpriv_str_to_set()\fR function maps the privilege specification in +\fIbuf\fR to a privilege set. It returns a privilege set on success or +\fINULL\fR on failure. If an error occurs when parsing the string, a pointer to +the remainder of the string is stored in the object pointed to by \fIendptr\fR, +provided that \fIendptr\fR is not a null pointer. If an error occurs when +allocating memory, \fBerrno\fR is set and the object pointed to by \fIendptr\fR +is set to the null pointer, provided that \fIendptr\fR is not a null pointer. +.sp +.LP +The application is responsible for freeing the returned privilege set using +\fBpriv_freeset\fR(3C). +.sp +.LP +A privilege specification should contain one or more privilege names, separated +by characters in \fIsep\fR using the same algorithm as \fBstrtok\fR(3C). +Privileges can optionally be preceded by a dash (-) or an exclamation mark (!), +in which case they are excluded from the resulting set. The special strings +"none" for the empty set, "all" for the set of all privileges, "zone" for the +set of all privileges available within the caller's zone, and "basic" for the +set of basic privileges are also recognized. Set specifications are interpreted +from left to right. +.sp +.LP +The \fBpriv_set_to_str()\fR function converts the privilege set to a sequence +of privileges separated by \fIsep\fR, returning the a pointer to the +dynamically allocated result. The application is responsible for freeing the +memory using \fBfree\fR(3C). +.sp +.LP +To maintain future compatibility, the "basic" set of privileges is included as +"basic,!missing_basic_priv1,...". When further currently unprivileged +operations migrate to the basic privilege set, the conversion back of the +result with \fBpriv_str_to_set()\fR includes the additional basic privileges, +guaranteeing that the resulting privilege set carries the same privileges. This +behavior is the default and is equivalent to specifying a \fIflag\fR argument +of \fBPRIV_STR_PORT\fR. When specifying a \fIflag\fR argument of +\fBPRIV_STR_LIT\fR, the result does not treat basic privileges differently and +the privileges present are all literally presented in the output. A flag +argument of \fBPRIV_STR_SHORT\fR attempts to arrive at the shortest output, +using the tokens "basic", "zone", "all", and negated privileges. This output is +most useful for trace output. +.sp +.LP +The \fBpriv_getbyname()\fR and \fBpriv_getsetbyname()\fR functions map +privilege names and privilege set names to numbers. The numbers returned are +valid for the current kernel instance only and could change at the next boot. +Only the privilege names should be committed to persistent storage. The numbers +should not be committed to persistent storage. Both functions return -1 on +error, setting \fBerrno\fR to \fBEINVAL\fR. +.sp +.LP +The \fBpriv_getbynum()\fR and \fBpriv_getsetbynum()\fR functions map privileges +numbers to names. The strings returned point to shared storage that should not +be modified and is valid for the lifetime of the process. Both functions return +\fINULL\fR on error, setting \fBerrno\fR to \fBEINVAL\fR. +.sp +.LP +The \fBpriv_gettext()\fR function returns a pointer to a string consisting of +one or more newline-separated lines of text describing the privilege. The text +is localized using {\fBLC_MESSAGES\fR}. The application is responsibe for +freeing the memory returned. +.sp +.LP +These functions pick up privileges allocated during the lifetime of the process +using \fBpriv_getbyname\fR(9F) by refreshing the internal data structures when +necessary. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBpriv_str_to_set()\fR and \fBpriv_set_to_str()\fR +return a non-null pointer to allocated memory that should be freed by the +application using the appropriate functions when it is no longer referenced. +.sp +.LP +The \fBpriv_getbynum()\fR and \fBpriv_getsetbynum()\fR functions return +non-null pointers to constant memory that should not be modified or freed by +the application. Otherwise, \fINULL\fR is returned and \fBerrno\fR is set to +indicate the error. +.sp +.LP +Upon successful completion, \fBpriv_getbyname()\fR and +\fBpriv_getsetbyname()\fR return a non-negative integer. Otherwise, -1 is +returned and \fBerrno\fR is set to indicate the error. +.sp +.LP +Upon successful completion, \fBpriv_gettext()\fR returns a non-null value. It +returns \fINULL\fR if an error occurs or no descriptive text for the specified +privilege can be found. +.SH ERRORS +.sp +.LP +The \fBpriv_str_to_set()\fR and \fBpriv_set_to_str()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +The physical limits of the system are exceeded by the memory allocation needed +to hold a privilege set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +There is not enough memory available to allocate sufficient memory to hold a +privilege set, but the application could try again later. +.RE + +.sp +.LP +All of these functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +One or more of the arguments is invalid. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRList all the sets and privileges defined in the system. +.sp +.LP +The following example lists all the sets and privileges defined in the system. + +.sp +.in +2 +.nf +#include <priv.h> +#include <stdio.h> + +/* list all the sets and privileges defined in the system */ + +const char *name; +int i; + +printf("Each process has the following privilege sets:\en"); +for (i = 0; (name = priv_getsetbynum(i++)) != NULL; ) + printf("\et%s\en", name); + +printf("Each set can contain the following privileges:\en"); +for (i = 0; (name = priv_getbynum(i++)) != NULL; ) + printf("\et%s\en", name); +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfree\fR(3C), \fBpriv_set\fR(3C), \fBattributes\fR(5), \fBprivileges\fR(5), +\fBpriv_getbyname\fR(9F) diff --git a/usr/src/man/man3c/pset_getloadavg.3c b/usr/src/man/man3c/pset_getloadavg.3c new file mode 100644 index 0000000000..e0cabe5b8d --- /dev/null +++ b/usr/src/man/man3c/pset_getloadavg.3c @@ -0,0 +1,90 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pset_getloadavg 3C "28 Jun 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pset_getloadavg \- get system load averages for a processor set +.SH SYNOPSIS +.LP +.nf +#include <sys/pset.h> +#include <sys/loadavg.h> + +\fBint\fR \fBpset_getloadavg\fR(\fBpsetid_t\fR \fIpset\fR, \fBdouble\fR \fIloadavg\fR[\|], \fBint\fR \fInelem\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpset_getloadavg()\fR function returns the number of processes assigned +to the specified processor set that are in the system run queue, averaged over +various periods of time. Up to \fInelem\fR samples are retrieved and assigned +to successive elements of \fIloadavg\fR[\|]. The system imposes a maximum of 3 +samples, representing averages over the last 1, 5, and 15 minutes, +respectively. +.sp +.LP +The \fBLOADAVG_1MIN\fR, \fBLOADAVG_5MIN\fR, and \fBLOADAVG_15MIN\fR indices, +defined in <\fBsys/loadavg.h\fR>, can be used to extract the data from the +appropriate element of the \fIloadavg\fR[\|] array. +.sp +.LP +If pset is \fBPS_NONE\fR, the load average for processes not assigned to a +processor set is returned. +.sp +.LP +If pset is \fBPS_MYID\fR, the load average for the processor set to which the +caller is bound is returned. If the caller is not bound to a processor set, +the result is the same as if \fBPS_NONE\fR was specified. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the number of samples actually retrieved is +returned. If the load average was unobtainable or the processor set does not +exist, \(mi1 is returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpset_getloadavg()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The number of elements specified is less than 0, or an invalid processor set ID +was specified. +.sp +The caller is in a non-global zone, the pools facility is active, and the +specified processor set is not that of the zone's pool. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStable +_ +MT-LevelAsync-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBuptime\fR(1), \fBw\fR(1), \fBpsrset\fR(1M), \fBprstat\fR(1M), +\fBpset_bind\fR(2), \fBpset_create\fR(2), \fBKstat\fR(3PERL), +\fBattributes\fR(5) diff --git a/usr/src/man/man3c/psignal.3c b/usr/src/man/man3c/psignal.3c new file mode 100644 index 0000000000..8b76212041 --- /dev/null +++ b/usr/src/man/man3c/psignal.3c @@ -0,0 +1,58 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH psignal 3C "31 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +psignal, psiginfo \- system signal messages +.SH SYNOPSIS +.LP +.nf +#include <siginfo.h> + +\fBvoid\fR \fBpsignal\fR(\fBint\fR \fIsig\fR, \fBconst char *\fR\fIs\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBpsiginfo\fR(\fBsiginfo_t *\fR\fIpinfo\fR, \fBchar *\fR\fIs\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpsignal()\fR and \fBpsiginfo()\fR functions produce messages on the +standard error output describing a signal. The \fIsig\fR argument is a signal +that may have been passed as the first argument to a signal handler. The +\fIpinfo\fR argument is a pointer to a \fBsiginfo\fR structure that may have +been passed as the second argument to an enhanced signal handler. See +\fBsigaction\fR(2). The argument string \fIs\fR is printed first, followed by a +colon and a blank, followed by the message and a \fBNEWLINE\fR character. +.SH USAGE +.sp +.LP +Messages printed from these functions are in the native language specified by +the \fBLC_MESSAGES\fR locale category. See \fBsetlocale\fR(3C). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBsigaction\fR(2), \fBgettext\fR(3C), \fBperror\fR(3C), \fBsetlocale\fR(3C), +\fBsiginfo.h\fR(3HEAD), \fBsignal.h\fR(3HEAD), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/pthread_atfork.3c b/usr/src/man/man3c/pthread_atfork.3c new file mode 100644 index 0000000000..794a0f15a9 --- /dev/null +++ b/usr/src/man/man3c/pthread_atfork.3c @@ -0,0 +1,171 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright (c) 1995 IEEE All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Portions Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_atfork 3C "12 Dec 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_atfork \- register fork handlers +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <unistd.h> + +\fBint\fR \fBpthread_atfork\fR(\fBvoid (*\fR\fIprepare\fR) (void), \fBvoid (*\fR\fIparent\fR) (void), + \fBvoid (*\fR\fIchild\fR) (void)); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_atfork()\fR function declares fork handlers to be called prior +to and following \fBfork\fR(2), within the thread that called \fBfork()\fR. The +order of calls to \fBpthread_atfork()\fR is significant. +.sp +.LP +Before \fBfork()\fR processing begins, the \fIprepare\fR fork handler is +called. The \fIprepare\fR handler is not called if its address is \fINULL.\fR +.sp +.LP +The \fIparent\fR fork handler is called after \fBfork()\fR processing finishes +in the parent process, and the \fIchild\fR fork handler is called after +\fBfork()\fR processing finishes in the child process. If the address of +\fIparent\fR or \fIchild\fR is \fINULL\fR, then its handler is not called. +.sp +.LP +The \fIprepare\fR fork handler is called in \fBLIFO\fR (last-in first-out) +order, whereas the \fIparent\fR and \fIchild\fR fork handlers are called in +\fBFIFO\fR (first-in first-out) order. This calling order allows applications +to preserve locking order. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBpthread_atfork()\fR returns \fB0\fR. Otherwise, +an error number is returned. +.SH ERRORS +.sp +.LP +The \fBpthread_atfork()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR \fR +.ad +.RS 11n +.rt +Insufficient table space exists to record the fork handler addresses. +.RE + +.SH USAGE +.sp +.LP +Solaris threads do not offer \fBpthread_atfork()\fR functionality (there is no +\fBthr_atfork()\fR interface). However, a Solaris threads application can call +\fBpthread_atfork()\fR to ensure \fBfork()\fR-safety, since the two thread APIs +are interoperable. See\fBfork\fR(2) for information relating to \fBfork()\fR in +a Solaris threads environment in Solaris 10 relative to previous releases. +.SH EXAMPLES +.LP +\fBExample 1 \fRMake a library safe with respect to \fBfork()\fR. +.sp +.LP +All multithreaded applications that call \fBfork()\fR in a POSIX threads +program and do more than simply call \fBexec\fR(2) in the child of the fork +need to ensure that the child is protected from deadlock. + +.sp +.LP +Since the "fork-one" model results in duplicating only the thread that called +\fBfork()\fR, it is possible that at the time of the call another thread in the +parent owns a lock. This thread is not duplicated in the child, so no thread +will unlock this lock in the child. Deadlock occurs if the single thread in +the child needs this lock. + +.sp +.LP +The problem is more serious with locks in libraries. Since a library writer +does not know if the application using the library calls \fBfork()\fR, the +library must protect itself from such a deadlock scenario. If the application +that links with this library calls \fBfork()\fR and does not call \fBexec()\fR +in the child, and if it needs a library lock that may be held by some other +thread in the parent that is inside the library at the time of the fork, the +application deadlocks inside the library. + +.sp +.LP +The following describes how to make a library safe with respect to +\fBfork()\fR by using \fBpthread_atfork()\fR. + +.RS +4 +.TP +1. +Identify all locks used by the library (for example \fB{L1,\|.\|.\|.Ln}\fR). +Identify also the locking order for these locks (for example +\fB{L1\|.\|.\|.Ln}, as well\fR.) +.RE +.RS +4 +.TP +2. +Add a call to \fBpthread_atfork(f1, f2, f3)\fR in the library's +\fI\&.init\fR section. \fBf1\fR, \fBf2\fR, \fBf3\fR are defined as follows: +.RE +.sp +.in +2 +.nf +\fB f1(\|) + { + /* ordered in lock order */ + pthread_mutex_lock(L1); + pthread_mutex_lock(\|.\|.\|.); + pthread_mutex_lock(Ln); + } + + f2(\|) + { + pthread_mutex_unlock(L1); + pthread_mutex_unlock(\|.\|.\|.); + pthread_mutex_unlock(Ln); + } + + f3(\|) + { + pthread_mutex_unlock(L1); + pthread_mutex_unlock(\|.\|.\|.); + pthread_mutex_unlock(Ln); + }\fR +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBexec\fR(2), \fBfork\fR(2), \fBatexit\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_attr_getdetachstate.3c b/usr/src/man/man3c/pthread_attr_getdetachstate.3c new file mode 100644 index 0000000000..74fee5b341 --- /dev/null +++ b/usr/src/man/man3c/pthread_attr_getdetachstate.3c @@ -0,0 +1,102 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_attr_getdetachstate 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_attr_getdetachstate, pthread_attr_setdetachstate \- get or set +detachstate attribute +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_attr_setdetachstate\fR(\fBpthread_attr_t *\fR\fIattr\fR, + \fBint\fR \fIdetachstate\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_attr_getdetachstate\fR(\fBconst pthread_attr_t *\fR\fIattr\fR, + \fBint *\fR\fIdetachstate\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fIdetachstate\fR attribute controls whether the thread is created in a +detached state. If the thread is created detached, then use of the \fBID\fR of +the newly created thread by the \fBpthread_detach()\fR or \fBpthread_join()\fR +function is an error. +.sp +.LP +The \fBpthread_attr_setdetachstate()\fR and +\fBpthread_attr_getdetachstate()\fR, respectively, set and get the +\fIdetachstate\fR attribute in the \fIattr\fR object. +.sp +.LP +The \fIdetachstate\fR can be set to either \fBPTHREAD_CREATE_DETACHED\fR or +\fBPTHREAD_CREATE_JOINABLE.\fR A value of \fBPTHREAD_CREATE_DETACHED\fR causes +all threads created with \fIattr\fR to be in the detached state, whereas using +a value of \fBPTHREAD_CREATE_JOINABLE\fR causes all threads created with +\fIattr\fR to be in the joinable state. The default value of the +\fIdetachstate\fR attribute is \fBPTHREAD_CREATE_JOINABLE.\fR +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBpthread_attr_setdetachstate()\fR and +\fBpthread_attr_getdetachstate()\fR return a value of \fB0\fR. Otherwise, an +error number is returned to indicate the error. +.sp +.LP +The \fBpthread_attr_getdetachstate()\fR function stores the value of the +\fIdetachstate\fR attribute in \fIdetachstate\fR if successful. +.SH ERRORS +.sp +.LP +The \fBpthread_attr_setdetachstate()\fR or \fBpthread_attr_getdetachstate()\fR +functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +\fIattr\fR or \fIdetachstate\fR is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_attr_init\fR(3C), \fBpthread_attr_setstackaddr\fR(3C), +\fBpthread_attr_setstacksize\fR(3C), \fBpthread_create\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_attr_getguardsize.3c b/usr/src/man/man3c/pthread_attr_getguardsize.3c new file mode 100644 index 0000000000..877eb73b53 --- /dev/null +++ b/usr/src/man/man3c/pthread_attr_getguardsize.3c @@ -0,0 +1,159 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_attr_getguardsize 3C "23 mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_attr_getguardsize, pthread_attr_setguardsize \- get or set thread +guardsize attribute +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_attr_getguardsize\fR(\fBconst pthread_attr_t *restrict\fR \fIattr\fR, + \fBsize_t *restrict\fR \fIguardsize\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_attr_setguardsize\fR(\fBpthread_attr_t *\fR\fIattr\fR, \fBsize_t\fR \fIguardsize\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fIguardsize\fR attribute controls the size of the guard area for the +created thread's stack. The \fIguardsize\fR 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 results (possibly in a +\fBSIGSEGV\fR signal being delivered to the thread). +.sp +.LP +The \fIguardsize\fR attribute is provided to the application for two reasons: +.RS +4 +.TP +1. +Overflow protection can potentially result in wasted system resources. An +application that creates a large number of threads, and which knows its threads +will never overflow their stack, can save system resources by turning off guard +areas. +.RE +.RS +4 +.TP +2. +When threads allocate large data structures on the stack, large guard areas +may be needed to detect stack overflow. +.RE +.sp +.LP +The \fBpthread_attr_getguardsize()\fR function gets the \fIguardsize\fR +attribute in the \fIattr\fR object. This attribute is returned in the +\fIguardsize\fR parameter. +.sp +.LP +The \fBpthread_attr_setguardsize()\fR function sets the \fIguardsize\fR +attribute in the \fIattr\fR object. The new value of this attribute is obtained +from the \fIguardsize\fR parameter. If \fIguardsize\fR is \fB0\fR, a guard +area will not be provided for threads created with \fIattr\fR. If +\fIguardsize\fR is greater than \fB0\fR, a guard area of at least size +\fIguardsize\fR bytes is provided for each thread created with \fIattr\fR. +.sp +.LP +A conforming implementation is permitted to round up the value contained in +\fIguardsize\fR to a multiple of the configurable system variable +\fBPAGESIZE.\fR If an implementation rounds up the value of \fIguardsize\fR to +a multiple of \fBPAGESIZE,\fR a call to \fBpthread_attr_getguardsize()\fR +specifying \fIattr\fR will store in the \fIguardsize\fR parameter the guard +size specified by the previous \fBpthread_attr_setguardsize()\fR function +call. +.sp +.LP +The default value of the \fIguardsize\fR attribute is \fBPAGESIZE\fR bytes. +The actual value of \fBPAGESIZE\fR is implementation-dependent and may not be +the same on all implementations. +.sp +.LP +If the \fIstackaddr\fR attribute has been set (that is, the caller is +allocating and managing its own thread stacks), the \fIguardsize\fR attribute +is ignored and no protection will 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. +.SH RETURN VALUES +.sp +.LP +If successful, the \fBpthread_attr_getguardsize()\fR and +\fBpthread_attr_setguardsize()\fR functions return \fB0\fR. Otherwise, an +error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_attr_getguardsize()\fR and \fBpthread_attr_setguardsize()\fR +functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR \fR +.ad +.RS 11n +.rt +The attribute \fIattr\fR is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR \fR +.ad +.RS 11n +.rt +The parameter \fIguardsize\fR is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR \fR +.ad +.RS 11n +.rt +The parameter \fIguardsize\fR contains an invalid value. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBsysconf\fR(3C), \fBpthread_attr_init\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_attr_getinheritsched.3c b/usr/src/man/man3c/pthread_attr_getinheritsched.3c new file mode 100644 index 0000000000..d6de3aec55 --- /dev/null +++ b/usr/src/man/man3c/pthread_attr_getinheritsched.3c @@ -0,0 +1,124 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_attr_getinheritsched 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_attr_getinheritsched, pthread_attr_setinheritsched \- get or set +inheritsched attribute +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_attr_getinheritsched\fR(\fBconst pthread_attr_t *restrict\fR \fIattr\fR, + \fBint *restrict\fR \fIinheritsched\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_attr_setinheritsched\fR(\fBpthread_attr_t *\fR\fIattr\fR, \fBint\fR \fIinheritsched\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The functions \fBpthread_attr_setinheritsched()\fR and +\fBpthread_attr_getinheritsched()\fR, respectively, set and get the +\fIinheritsched\fR attribute in the \fIattr\fR argument. +.sp +.LP +When the attribute objects are used by \fBpthread_create()\fR, the +\fIinheritsched\fR attribute determines how the other scheduling attributes of +the created thread are to be set: +.sp +.ne 2 +.mk +.na +\fB\fBPTHREAD_INHERIT_SCHED\fR \fR +.ad +.RS 27n +.rt +Specifies that the scheduling policy and associated attributes are to be +inherited from the creating thread, and the scheduling attributes in this +\fIattr\fR argument are to be ignored. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPTHREAD_EXPLICIT_SCHED\fR \fR +.ad +.RS 27n +.rt +Specifies that the scheduling policy and associated attributes are to be set to +the corresponding values from this attribute object. +.RE + +.sp +.LP +The symbols \fBPTHREAD_INHERIT_SCHED\fR and \fBPTHREAD_EXPLICIT_SCHED\fR are +defined in the header \fB<pthread.h>\fR\&. +.SH RETURN VALUES +.sp +.LP +If successful, the \fBpthread_attr_setinheritsched()\fR and +\fBpthread_attr_getinheritsched()\fR functions return \fB0\fR. Otherwise, an +error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_attr_setinheritsched()\fR or +\fBpthread_attr_getinheritsched()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +\fIattr\fR or \fIinheritsched\fR is invalid. +.RE + +.SH USAGE +.sp +.LP +After these attributes have been set, a thread can be created with the +specified attributes using \fBpthread_create()\fR. Using these routines does +not affect the current running thread. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_attr_getschedparam\fR(3C), \fBpthread_attr_init\fR(3C), +\fBpthread_attr_setscope\fR(3C), \fBpthread_attr_setschedpolicy\fR(3C), +\fBpthread_create\fR(3C), \fBpthread_setschedparam\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_attr_getschedparam.3c b/usr/src/man/man3c/pthread_attr_getschedparam.3c new file mode 100644 index 0000000000..7a5d6e6e5a --- /dev/null +++ b/usr/src/man/man3c/pthread_attr_getschedparam.3c @@ -0,0 +1,108 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_attr_getschedparam 3C "1 Apr 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_attr_getschedparam, pthread_attr_setschedparam \- get or set schedparam +attribute +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_attr_getschedparam\fR(\fBconst pthread_attr_t *restrict\fR \fIattr\fR, + \fBstruct sched_param *restrict\fR \fIparam\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_attr_setschedparam\fR(\fBpthread_attr_t *restrict\fR \fIattr\fR, + \fBconst struct sched_param *restrict\fR \fIparam\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The functions \fBpthread_attr_setschedparam()\fR and +\fBpthread_attr_getschedparam()\fR, respectively, set and get the scheduling +parameter attributes in the \fIattr\fR argument. The contents of the +\fIparam\fR structure are defined in \fB<sched.h>\fR\&. The only required +member of \fIparam\fR is \fIsched_priority\fR. +.SH RETURN VALUES +.sp +.LP +If successful, the \fBpthread_attr_setschedparam()\fR and +\fBpthread_attr_getschedparam()\fR functions return \fB0\fR. Otherwise, an +error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_attr_setschedparam()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +\fIattr\fR is invalid. +.RE + +.sp +.LP +The \fBpthread_attr_getschedparam()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +\fIattr\fR or \fIparam\fR is invalid. +.RE + +.SH USAGE +.sp +.LP +After these attributes have been set, a thread can be created with the +specified attributes using \fBpthread_create()\fR. Using these routines does +not affect the current running thread. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_attr_init\fR(3C), \fBpthread_attr_setscope\fR(3C), +\fBpthread_attr_setinheritsched\fR(3C), \fBpthread_attr_setschedpolicy\fR(3C), +\fBpthread_create\fR(3C), \fBpthread_setschedparam\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_attr_getschedpolicy.3c b/usr/src/man/man3c/pthread_attr_getschedpolicy.3c new file mode 100644 index 0000000000..34b7f52c5e --- /dev/null +++ b/usr/src/man/man3c/pthread_attr_getschedpolicy.3c @@ -0,0 +1,105 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_attr_getschedpolicy 3C "1 Apr 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_attr_getschedpolicy, pthread_attr_setschedpolicy \- get or set +schedpolicy attribute +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_attr_getschedpolicy\fR(\fBconst pthread_attr_t *restrict\fR \fIattr\fR, + \fBint *restrict\fR \fIpolicy\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_attr_setschedpolicy\fR(\fBpthread_attr_t *\fR\fIattr\fR, \fBint\fR \fIpolicy\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The functions \fBpthread_attr_setschedpolicy()\fR and +\fBpthread_attr_getschedpolicy()\fR, respectively, set and get the +\fIschedpolicy\fR attribute in the \fIattr\fR argument. +.sp +.LP +Supported values of \fIpolicy\fR include \fBSCHED_FIFO,\fR \fBSCHED_RR\fR and +\fBSCHED_OTHER,\fR which are defined by the header \fB<sched.h>\fR. When +threads executing with the scheduling policy \fBSCHED_FIFO\fR or +\fBSCHED_RR\fR are waiting on a mutex, they acquire the mutex in priority order +when the mutex is unlocked. +.sp +.LP +See \fBsched.h\fR(3HEAD) for a description of all defined policy values. Valid +policy values can also be obtained from \fBpthread_getschedparam\fR(3C) and +\fBsched_getscheduler\fR(3C). +.SH RETURN VALUES +.sp +.LP +If successful, the \fBpthread_attr_setschedpolicy()\fR and +\fBpthread_attr_getschedpolicy()\fR functions return \fB0\fR. Otherwise, an +error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_attr_setschedpolicy()\fR or \fBpthread_attr_getschedpolicy()\fR +function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +\fIattr\fR or \fIpolicy\fR is invalid. +.RE + +.SH USAGE +.sp +.LP +After these attributes have been set, a thread can be created with the +specified attributes using \fBpthread_create()\fR. Using these routines does +not affect the current running thread. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_attr_init\fR(3C), \fBpthread_attr_setscope\fR(3C), +\fBpthread_attr_setinheritsched\fR(3C), \fBpthread_attr_setschedparam\fR(3C), +\fBpthread_create\fR(3C), \fBpthread_getschedparam\fR(3C), +\fBsched.h\fR(3HEAD), \fBsched_getscheduler\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_attr_getscope.3c b/usr/src/man/man3c/pthread_attr_getscope.3c new file mode 100644 index 0000000000..3dd4188996 --- /dev/null +++ b/usr/src/man/man3c/pthread_attr_getscope.3c @@ -0,0 +1,99 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_attr_getscope 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_attr_getscope, pthread_attr_setscope \- get or set contentionscope +attribute +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_attr_getscope\fR(\fBconst pthread_attr_t *restrict\fR \fIattr\fR, + \fBint *restrict\fR \fIcontentionscope\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_attr_setscope\fR(\fBpthread_attr_t *\fR\fIattr\fR, \fBint\fR \fIcontentionscope\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_attr_setscope()\fR and \fBpthread_attr_getscope()\fR functions +are used to set and get the \fIcontentionscope\fR attribute in the \fIattr\fR +object. +.sp +.LP +The \fIcontentionscope\fR attribute can have the value +\fBPTHREAD_SCOPE_SYSTEM\fR, signifying system scheduling contention scope, or +\fBPTHREAD_SCOPE_PROCESS\fR, signifying process scheduling contention scope. +.sp +.LP +The symbols \fBPTHREAD_SCOPE_SYSTEM\fR and \fBPTHREAD_SCOPE_PROCESS\fR are +defined by the header <\fBpthread.h\fR>. +.SH RETURN VALUES +.sp +.LP +If successful, the \fBpthread_attr_setscope()\fR and +\fBpthread_attr_getscope()\fR functions return \fB0\fR. Otherwise, an error +number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_attr_setscope()\fR, or \fBpthread_attr_getscope()\fR, function +may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +\fIattr\fR or \fIcontentionscope\fR is invalid. +.RE + +.SH USAGE +.sp +.LP +After these attributes have been set, a thread can be created with the +specified attributes using \fBpthread_create()\fR. Using these routines does +not affect the current running thread. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_attr_init\fR(3C), \fBpthread_attr_setinheritsched\fR(3C), +\fBpthread_attr_setschedpolicy\fR(3C), \fBpthread_attr_setschedparam\fR(3C), +\fBpthread_create\fR(3C), \fBpthread_setschedparam\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_attr_getstack.3c b/usr/src/man/man3c/pthread_attr_getstack.3c new file mode 100644 index 0000000000..951ffce866 --- /dev/null +++ b/usr/src/man/man3c/pthread_attr_getstack.3c @@ -0,0 +1,126 @@ +'\" te +.\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved. Portions Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_attr_getstack 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_attr_getstack, pthread_attr_setstack \- get or set stack attributes +.SH SYNOPSIS +.LP +.nf +cc \fB-mt\fR [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpthread\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <pthread.h> + +\fBint\fR \fBpthread_attr_getstack\fR(\fBconst pthread_attr_t *restrict\fR \fIattr\fR, + \fBvoid **restrict\fR \fIstackaddr\fR, \fBsize_t *restrict\fR \fIstacksize\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_attr_setstack\fR(\fBpthread_attr_t *\fR \fIattr\fR, \fBvoid *\fR\fIstackaddr\fR, + \fBsize_t\fR \fIstacksize\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_attr_getstack()\fR and \fBpthread_attr_setstack()\fR functions, +respectively, get and set the thread creation stack attributes \fIstackaddr\fR +and \fIstacksize\fR in the \fIattr\fR object. +.sp +.LP +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 is +\fIstackaddr\fR, and the size of the storage is \fIstacksize\fR bytes. The +\fIstacksize\fR argument must be at least {\fBPTHREAD_STACK_MIN\fR}. The +\fIstackaddr\fR argument must be aligned appropriately to be used as a stack; +for example, \fBpthread_attr_setstack()\fR might fail with \fBEINVAL\fR if +(\fIstackaddr\fR & 0x7) is not 0. All pages within the stack described by +\fIstackaddr\fR and \fIstacksize\fR are both readable and writable by the +thread. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, these functions return a 0; otherwise, an error +number is returned to indicate the error. +.sp +.LP +The \fBpthread_attr_getstack()\fR function stores the stack attribute values in +stackaddr and stacksize if successful. +.SH ERRORS +.sp +.LP +The \fBpthread_attr_setstack()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of \fIstacksize\fR is less than {\fBPTHREAD_STACK_MIN\fR}. +.RE + +.sp +.LP +The \fBpthread_attr_setstack()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 10n +.rt +The stack page(s) described by \fIstackaddr\fR and \fIstacksize\fR are not both +readable and writable by the thread. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of \fIstackaddr\fR does not have proper alignment to be used as a +stack, or (\fIstackaddr\fR + \fIstacksize\fR) lacks proper alignment. +.RE + +.SH USAGE +.sp +.LP +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. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelAsync-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_attr_init\fR(3C), \fBpthread_attr_setdetachstate\fR(3C), +\fBpthread_attr_setstacksize\fR(3C), \fBpthread_create\fR(3C), +\fBattributes\fR(5) diff --git a/usr/src/man/man3c/pthread_attr_getstackaddr.3c b/usr/src/man/man3c/pthread_attr_getstackaddr.3c new file mode 100644 index 0000000000..a5059b42db --- /dev/null +++ b/usr/src/man/man3c/pthread_attr_getstackaddr.3c @@ -0,0 +1,106 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_attr_getstackaddr 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_attr_getstackaddr, pthread_attr_setstackaddr \- get or set stackaddr +attribute +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_attr_getstackaddr\fR(\fBconst pthread_attr_t *restrict\fR \fIattr\fR, + \fBvoid **restrict\fR \fIstackaddr\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_attr_setstackaddr\fR(\fBpthread_attr_t *\fR\fIattr\fR, \fBvoid *\fR\fIstackaddr\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The functions \fBpthread_attr_setstackaddr()\fR and +\fBpthread_attr_getstackaddr()\fR, respectively, set and get the thread +creation \fIstackaddr\fR attribute in the \fIattr\fR object. The +\fIstackaddr\fR default is \fINULL\fR. See \fBpthread_create\fR(3C). +.sp +.LP +The \fIstackaddr\fR attribute specifies the location of storage to be used for +the created thread's stack. The size of the storage is at least +\fBPTHREAD_STACK_MIN.\fR +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBpthread_attr_setstackaddr()\fR and +\fBpthread_attr_getstackaddr()\fR return a value of \fB0\fR. Otherwise, an +error number is returned to indicate the error. +.sp +.LP +If successful, the \fBpthread_attr_getstackaddr()\fR function stores the +\fIstackaddr\fR attribute value in \fIstackaddr\fR. +.SH ERRORS +.sp +.LP +The \fBpthread_attr_setstackaddr()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +\fIattr\fR is invalid. +.RE + +.sp +.LP +The \fBpthread_attr_getstackaddr()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +\fIattr\fR or \fIstackaddr\fR is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_attr_init\fR(3C), \fBpthread_attr_setdetachstate\fR(3C), +\fBpthread_attr_setstacksize\fR(3C), \fBpthread_create\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_attr_getstacksize.3c b/usr/src/man/man3c/pthread_attr_getstacksize.3c new file mode 100644 index 0000000000..4bc3409a84 --- /dev/null +++ b/usr/src/man/man3c/pthread_attr_getstacksize.3c @@ -0,0 +1,91 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_attr_getstacksize 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_attr_getstacksize, pthread_attr_setstacksize \- get or set stacksize +attribute +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_attr_getstacksize\fR(\fBconst pthread_attr_t *restrict\fR \fIattr\fR, + \fBsize_t *restrict\fR \fIstacksize\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_attr_setstacksize\fR(\fBpthread_attr_t *\fR\fIattr\fR, \fBsize_t\fR \fIstacksize\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The functions \fBpthread_attr_setstacksize()\fR and +\fBpthread_attr_getstacksize()\fR, respectively, set and get the thread +creation \fIstacksize\fR attribute in the \fIattr\fR object. +.sp +.LP +The \fIstacksize\fR attribute defines the minimum stack size (in bytes) +allocated for the created threads stack. When the \fIstacksize\fR argument is +\fINULL\fR, the default stack size becomes \fB1\fR megabyte for 32-bit +processes and \fB2\fR megabytes for 64-bit processes. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBpthread_attr_setstacksize()\fR and +\fBpthread_attr_getstacksize()\fR return a value of \fB0\fR. Otherwise, an +error number is returned to indicate the error. The +\fBpthread_attr_getstacksize()\fR function stores the \fIstacksize\fR attribute +value in \fIstacksize\fR if successful. +.SH ERRORS +.sp +.LP +The \fBpthread_attr_setstacksize()\fR or \fBpthread_attr_getstacksize()\fR +function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +\fIattr\fR or \fIstacksize\fR is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_attr_init\fR(3C), \fBpthread_attr_setstackaddr\fR(3C), +\fBpthread_attr_setdetachstate\fR(3C), \fBpthread_create\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_attr_init.3c b/usr/src/man/man3c/pthread_attr_init.3c new file mode 100644 index 0000000000..191b46b5a9 --- /dev/null +++ b/usr/src/man/man3c/pthread_attr_init.3c @@ -0,0 +1,145 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_attr_init 3C "1 Apr 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_attr_init, pthread_attr_destroy \- initialize or destroy threads +attribute object +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_attr_init\fR(\fBpthread_attr_t *\fR\fIattr\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_attr_destroy\fR(\fBpthread_attr_t *\fR\fIattr\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The function \fBpthread_attr_init()\fR initializes a thread attributes object +\fIattr\fR with the default value for all of the individual attributes used by +a given implementation. +.sp +.LP +The resulting attribute object (possibly modified by setting individual +attribute values), when used by \fBpthread_create()\fR, defines the attributes +of the thread created. A single attributes object can be used in multiple +simultaneous calls to \fBpthread_create()\fR. +.sp +.LP +The \fBpthread_attr_init()\fR function initializes a thread attributes object ( +\fIattr\fR) with the default value for each attribute as follows: +.sp + +.sp +.TS +tab(); +cw(1.83i) cw(1.83i) cw(1.83i) +lw(1.83i) lw(1.83i) lw(1.83i) +. +AttributeDefault ValueMeaning of Default +_ +\fIcontentionscope\fR\fBPTHREAD_SCOPE_PROCESS\fRresource competition within process +\fIdetachstate\fR\fBPTHREAD_CREATE_JOINABLE\fRjoinable by other threads +\fIstackaddr\fR\fBNULL\fRstack allocated by system +\fIstacksize\fR01 or 2 megabyte +\fIpriority\fR0priority of the thread +\fIpolicy\fR\fBSCHED_OTHER\fRtraditional time-sharing policy +\fIinheritsched\fR\fBPTHREAD_INHERIT_SCHED\fRT{ +scheduling policy and parameters are inherited from the creating thread +T} +\fIguardsize\fR\fBPAGESIZE\fRT{ +size of guard area for a thread's created stack +T} +.TE + +.sp +.LP +The \fBpthread_attr_destroy()\fR function destroys a thread attributes object ( +\fIattr\fR), which cannot be reused until it is reinitialized. An +implementation may cause \fBpthread_attr_destroy()\fR to set \fIattr\fR to an +implementation-dependent invalid value. The behavior of using the attribute +after it has been destroyed is undefined. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBpthread_attr_init()\fR and +\fBpthread_attr_destroy()\fR return a value of \fB0\fR. Otherwise, an error +number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_attr_init()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient memory exists to initialize the thread attributes object. +.RE + +.sp +.LP +The \fBpthread_attr_destroy()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +\fIattr\fR is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBsysconf\fR(3C), \fBpthread_attr_getdetachstate\fR(3C), +\fBpthread_attr_getguardsize\fR(3C), \fBpthread_attr_getinheritsched\fR(3C), +\fBpthread_attr_getschedparam\fR(3C), \fBpthread_attr_getschedpolicy\fR(3C), +\fBpthread_attr_getscope\fR(3C), \fBpthread_attr_getstackaddr\fR(3C), +\fBpthread_attr_getstacksize\fR(3C), \fBpthread_attr_setdetachstate\fR(3C), +\fBpthread_attr_setguardsize\fR(3C), \fBpthread_attr_setinheritsched\fR(3C), +\fBpthread_attr_setschedparam\fR(3C), \fBpthread_attr_setschedpolicy\fR(3C), +\fBpthread_attr_setscope\fR(3C), \fBpthread_attr_setstackaddr\fR(3C), +\fBpthread_attr_setstacksize\fR(3C), \fBpthread_create\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_barrier_destroy.3c b/usr/src/man/man3c/pthread_barrier_destroy.3c new file mode 100644 index 0000000000..4aa7d5420b --- /dev/null +++ b/usr/src/man/man3c/pthread_barrier_destroy.3c @@ -0,0 +1,184 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_barrier_destroy 3C "30 Jan 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_barrier_destroy, pthread_barrier_init \- destroy and initialize a +barrier object +.SH SYNOPSIS +.LP +.nf +cc \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_barrier_destroy\fR(\fBpthread_barrier_t *\fR\fIbarrier\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_barrier_init\fR(\fBpthread_barrier_t *\fR\fIbarrier\fR, + \fBconst pthread_barrierattr_t *restrict\fR \fIattr\fR, \fBunsigned\fR \fIcount\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_barrier_destroy()\fR function destroys the barrier referenced by +\fIbarrier\fR and releases 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 \fBpthread_barrier_init()\fR. An implementation can use this +function to set barrier to an invalid value. The results are undefined if +\fBpthread_barrier_destroy()\fR is called when any thread is blocked on the +barrier, or if this function is called with an uninitialized barrier. +.sp +.LP +The \fBpthread_barrier_init()\fR function allocates any resources required to +use the barrier referenced by barrier and initializes the barrier with +attributes referenced by \fIattr\fR. If attr is \fINULL\fR, the default barrier +attributes are used; the effect is the same as passing the address of a default +barrier attributes object. The results are undefined if +\fBpthread_barrier_init()\fR is called when any thread is blocked on the +barrier (that is, has not returned from the \fBpthread_barrier_wait\fR(3C) +call). The results are undefined if a barrier is used without first being +initialized. The results are undefined if \fBpthread_barrier_init()\fR is +called specifying an already initialized barrier. +.sp +.LP +The \fIcount\fR argument specifies the number of threads that must call +\fBpthread_barrier_wait()\fR before any of them successfully return from the +call. The value specified by \fIcount\fR must be greater than 0. +.sp +.LP +If the \fBpthread_barrier_init()\fR function fails, the barrier is not +initialized and the contents of \fIbarrier\fR are undefined. +.sp +.LP +Only the object referenced by barrier can be used for performing +synchronization. The result of referring to copies of that object in calls to +\fBpthread_barrier_destroy()\fR or \fBpthread_barrier_wait()\fR is undefined. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, these functions returns 0. Otherwise, an error +number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_barrier_init()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +The system lacks the necessary resources to initialize another barrier. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIcount\fR is equal to 0. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient memory exists to initialize the barrier. +.RE + +.sp +.LP +The \fBpthread_barrier_init()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBUSY\fR\fR +.ad +.RS 10n +.rt +The implementation has detected an attempt to destroy a barrier while it is in +use (for example, while being used in a \fBpthread_barrier_wait()\fR call) by +another thread. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIattr\fR is invalid. +.RE + +.sp +.LP +The \fBpthread_barrier_destroy()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBUSY\fR\fR +.ad +.RS 10n +.rt +The implementation has detected an attempt to destroy a barrier while it is in +use (for example, while being used in a \fBpthread_barrier_wait()\fR call) by +another thread. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIbarrier\fR is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_barrier_wait\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_barrier_wait.3c b/usr/src/man/man3c/pthread_barrier_wait.3c new file mode 100644 index 0000000000..e02e87a44e --- /dev/null +++ b/usr/src/man/man3c/pthread_barrier_wait.3c @@ -0,0 +1,108 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_barrier_wait 3C "30 Jan 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_barrier_wait \- synchronize at a barrier +.SH SYNOPSIS +.LP +.nf +cc \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_barrier_wait\fR(\fBpthread_barrier_t *\fR\fIbarrier\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_barrier_wait()\fR function synchronizes participating threads at +the barrier referenced by \fIbarrier\fR. The calling thread blocks until the +required number of threads have called \fBpthread_barrier_wait()\fR specifying +the barrier. +.sp +.LP +When the required number of threads have called \fBpthread_barrier_wait()\fR +specifying the barrier, the constant \fBPTHREAD_BARRIER_SERIAL_THREAD\fR is +returned to one unspecified thread and 0 is returned to each of the remaining +threads. At this point, the barrier is reset to the state it had as a result of +the most recent \fBpthread_barrier_init\fR(3C) function that referenced it. +.sp +.LP +The constant \fBPTHREAD_BARRIER_SERIAL_THREAD\fR is defined in +<\fBpthread.h\fR> and its value is distinct from any other value returned by +\fBpthread_barrier_wait()\fR. +.sp +.LP +The results are undefined if this function is called with an uninitialized +barrier. +.sp +.LP +If a signal is delivered to a thread blocked on a barrier, upon return from the +signal handler the thread resumes 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 continues 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. +.sp +.LP +A thread that has blocked on a barrier does not prevent any unblocked thread +that is eligible to use the same processing resources from eventually making +forward progress in its execution. +.sp +.LP +Eligibility for processing resources is determined by the scheduling policy. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBpthread_barrier_wait()\fR function returns +\fBPTHREAD_BARRIER_SERIAL_THREAD\fR for a single (arbitrary) thread +synchronized at the barrier and 0 for each of the other threads. Otherwise, an +error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_barrier_wait()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIbarrier\fR does not refer to an initialized barrier +object. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_barrier_destroy\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_barrierattr_destroy.3c b/usr/src/man/man3c/pthread_barrierattr_destroy.3c new file mode 100644 index 0000000000..d9adc06151 --- /dev/null +++ b/usr/src/man/man3c/pthread_barrierattr_destroy.3c @@ -0,0 +1,110 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_barrierattr_destroy 3C "30 Jan 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_barrierattr_destroy, pthread_barrierattr_init \- destroy and initialize +barrier attributes object +.SH SYNOPSIS +.LP +.nf +cc \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_barrierattr_destroy\fR(\fBpthread_barrierattr_t *\fR\fIattr\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_barrierattr_init\fR(\fBpthread_barrierattr_t *\fR\fIattr\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_barrierattr_destroy()\fR function destroys a barrier attributes +object. A destroyed \fIattr\fR attributes object can be reinitialized using +\fBpthread_barrierattr_init()\fR. The results of otherwise referencing the +object after it has been destroyed are undefined. An implementation can cause +\fBpthread_barrierattr_destroy()\fR to set the object referenced by \fIattr\fR +to an invalid value. +.sp +.LP +The \fBpthread_barrierattr_init()\fR function initializes a barrier attributes +object \fIattr\fR with the default value for all of the attributes defined by +the implementation. +.sp +.LP +Results are undefined if \fBpthread_barrierattr_init()\fR is called specifying +an already initialized \fIattr\fR attributes object. +.sp +.LP +After a barrier attributes object has been used to initialize one or more +barriers, any function affecting the attributes object (including destruction) +does not affect any previously initialized barrier. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBpthread_barrierattr_destroy()\fR and +\fBpthread_barrierattr_init()\fR functions returns 0. Otherwise, an error +number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_barrierattr_init()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient memory exists to initialize the barrier attributes object. +.RE + +.sp +.LP +The \fBpthread_barrierattr_destroy()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIattr\fR is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_barrierattr_getpshared\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_barrierattr_getpshared.3c b/usr/src/man/man3c/pthread_barrierattr_getpshared.3c new file mode 100644 index 0000000000..654461c143 --- /dev/null +++ b/usr/src/man/man3c/pthread_barrierattr_getpshared.3c @@ -0,0 +1,122 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_barrierattr_getpshared 3C "30 Jan 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_barrierattr_getpshared, pthread_barrierattr_setpshared \- get and set +process-shared attribute of barrier attributes object +.SH SYNOPSIS +.LP +.nf +cc \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_barrierattr_getpshared\fR( + \fBconst pthread_barrierattr_t *restrict\fR \fIattr\fR, + \fBint *restrict\fR \fIpshared\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_barrierattr_setpshared\fR(\fBpthread_barrierattr_t *\fR\fIattr\fR, + \fBint\fR \fIpshared\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_barrierattr_getpshared()\fR function obtains the value of the +\fIprocess-shared\fR attribute from the attributes object referenced by +\fIattr\fR. The \fBpthread_barrierattr_setpshared()\fR function sets the +\fIprocess-shared\fR attribute in an initialized attributes object referenced +by \fIattr\fR. +.sp +.LP +The \fIprocess-shared\fR attribute is set to \fBPTHREAD_PROCESS_SHARED\fR to +permit a barrier to be operated upon by any thread that has access to the +memory where the barrier is allocated. If the \fIprocess-shared\fR attribute is +\fBPTHREAD_PROCESS_PRIVATE\fR, the barrier will 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. +.sp +.LP +The default value of the attribute is \fBPTHREAD_PROCESS_PRIVATE\fR. Both +constants \fBPTHREAD_PROCESS_SHARED\fR and \fBPTHREAD_PROCESS_PRIVATE\fR are +defined in <\fBpthread.h\fR>. +.sp +.LP +No barrier attributes other than the \fIprocess-shared\fR attribute are +provided. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBpthread_barrierattr_getpshared()\fR function +returns 0 and stores the value of the \fIprocess-shared\fR attribute of +\fIattr\fR into the object referenced by the \fIpshared\fR parameter. +Otherwise, an error number is returned to indicate the error. +.sp +.LP +Upon successful completion, the \fBpthread_barrierattr_setpshared()\fR function +returns 0. Otherwise, an error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +These functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIattr\fR is invalid. +.RE + +.sp +.LP +The \fBpthread_barrierattr_setpshared()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The new value specified for the \fIprocess-shared\fR attribute is not one of +the legal values \fBPTHREAD_PROCESS_SHARED\fR or \fBPTHREAD_PROCESS_PRIVATE\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_barrier_init\fR(3C), \fBpthread_barrierattr_destroy\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_cancel.3c b/usr/src/man/man3c/pthread_cancel.3c new file mode 100644 index 0000000000..84ee0d92de --- /dev/null +++ b/usr/src/man/man3c/pthread_cancel.3c @@ -0,0 +1,103 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_cancel 3C "2 Nov 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_cancel \- cancel execution of a thread +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_cancel\fR(\fBpthread_t\fR \fItarget_thread\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_cancel()\fR function requests that \fItarget_thread\fR be +canceled. +.sp +.LP +By default, cancellation is deferred until \fItarget_thread\fR reaches a +cancellation point. See \fBcancellation\fR(5). +.sp +.LP +Cancellation cleanup handlers for \fItarget_thread\fR are called when the +cancellation is acted on. Upon return of the last cancellation cleanup handler, +the thread-specific data destructor functions are called for +\fItarget_thread\fR. \fItarget_thread\fR is terminated when the last destructor +function returns. +.sp +.LP +A thread acting on a cancellation request runs with all signals blocked. All +thread termination functions, including cancellation cleanup handlers and +thread-specific data destructor functions, are called with all signals blocked. +.sp +.LP +The cancellation processing in \fItarget_thread\fR runs asynchronously with +respect to the calling thread returning from \fBpthread_cancel()\fR. +.SH RETURN VALUES +.sp +.LP +If successful, the \fBpthread_cancel()\fR function returns \fB0\fR. Otherwise, +an error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_cancel()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBESRCH\fR\fR +.ad +.RS 9n +.rt +No thread was found with an \fBID\fR corresponding to that specified by the +given thread \fBID,\fR \fItarget_thread\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_cleanup_pop\fR(3C), \fBpthread_cleanup_push\fR(3C), +\fBpthread_cond_wait\fR(3C), \fBpthread_cond_timedwait\fR(3C), +\fBpthread_exit\fR(3C), \fBpthread_join\fR(3C), +\fBpthread_setcancelstate\fR(3C), \fBpthread_setcanceltype\fR(3C), +\fBpthread_testcancel\fR(3C), \fBsetjmp\fR(3C), \fBattributes\fR(5), +\fBcancellation\fR(5), \fBcondition\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +See \fBcancellation\fR(5) for a discussion of cancellation concepts. diff --git a/usr/src/man/man3c/pthread_cleanup_pop.3c b/usr/src/man/man3c/pthread_cleanup_pop.3c new file mode 100644 index 0000000000..01681dc129 --- /dev/null +++ b/usr/src/man/man3c/pthread_cleanup_pop.3c @@ -0,0 +1,97 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Portions Copyright (c) 1995 IEEE. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_cleanup_pop 3C "4 Oct 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_cleanup_pop \- pop a thread cancellation cleanup handler +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBvoid\fR \fBpthread_cleanup_pop\fR(\fBint\fR \fIexecute\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_cleanup_pop()\fR function removes the cleanup handler routine at +the top of the cancellation cleanup stack of the calling thread and executes it +if \fIexecute\fR is non-zero. +.sp +.LP +When the thread calls \fBpthread_cleanup_pop()\fR with a non-zero \fIexecute\fR +argument, the argument at the top of the stack is popped and executed. An +argument of \fB0\fR pops the handler without executing it. +.sp +.LP +The \fBpthread_cleanup_push\fR(3C) and \fBpthread_cleanup_pop()\fR functions +can be implemented as macros. The application must ensure that they appear as +statements, and in pairs within the same lexical scope (that is, the +\fBpthread_cleanup_push()\fR macro can be thought to expand to a token list +whose first token is '{' with \fBpthread_cleanup_pop()\fR expanding to a token +list whose last token is the corresponding '}'). +.sp +.LP +The effect of the use of \fBreturn\fR, \fBbreak\fR, \fBcontinue\fR, and +\fBgoto\fR to prematurely leave a code block described by a pair of +\fBpthread_cleanup_push()\fR and \fBpthread_cleanup_pop()\fR function calls is +undefined. +.sp +.LP +Using \fBlongjmp()\fR or \fBsiglongjmp()\fR to jump into or out of a push/pop +pair can result in either the matching push or the matching pop statement not +getting executed. +.SH RETURN VALUES +.sp +.LP +The \fBpthread_cleanup_pop()\fR function returns no value. +.SH ERRORS +.sp +.LP +No errors are defined. +.sp +.LP +The \fBpthread_cleanup_pop()\fR function will not return an error code of +\fBEINTR\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_cancel\fR(3C), \fBpthread_cleanup_push\fR(3C), +\fBpthread_exit\fR(3C), \fBpthread_join\fR(3C), +\fBpthread_setcancelstate\fR(3C), \fBpthread_setcanceltype\fR(3C), +\fBpthread_testcancel\fR(3C), \fBsetjmp\fR(3C), \fBattributes\fR(5), +\fBcancellation\fR(5), \fBcondition\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +See \fBcancellation\fR(5) for a discussion of cancellation concepts. diff --git a/usr/src/man/man3c/pthread_cleanup_push.3c b/usr/src/man/man3c/pthread_cleanup_push.3c new file mode 100644 index 0000000000..5988078c67 --- /dev/null +++ b/usr/src/man/man3c/pthread_cleanup_push.3c @@ -0,0 +1,104 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright (c) 1995 IEEE. All Rights Reserved. +.\" Copyright (c) 1991, 1992, 1994, The X/Open Company Ltd. All Rights Reserved. +.\" Portions Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_cleanup_push 3C "2 Nov 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_cleanup_push \- push a thread cancellation cleanup handler +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBvoid\fR \fBpthread_cleanup_push\fR(\fBvoid (*\fR\fIhandler\fR) (void *), \fBvoid *\fR\fIarg\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_cleanup_push()\fR function pushes the specified cancellation +cleanup handler routine, \fIhandler\fR, onto the cancellation cleanup stack of +the calling thread. +.sp +.LP +When a thread exits or is canceled and its cancellation cleanup stack is not +empty, the cleanup handlers are invoked with the argument \fIarg\fR in last +in, first out (LIFO) order from the cancellation cleanup stack. +.sp +.LP +An exiting or cancelled thread runs with all signals blocked. All thread +termination functions, including cancellation cleanup handlers, are called with +all signals blocked. +.sp +.LP +The \fBpthread_cleanup_push()\fR and \fBpthread_cleanup_pop\fR(3C) functions +can be implemented as macros. The application must ensure that they appear as +statements, and in pairs within the same lexical scope (that is, the +\fBpthread_cleanup_push()\fR macro can be thought to expand to a token list +whose first token is '{' with \fBpthread_cleanup_pop()\fR expanding to a token +list whose last token is the corresponding '}'). +.sp +.LP +The effect of the use of \fBreturn\fR, \fBbreak\fR, \fBcontinue\fR, and +\fBgoto\fR to prematurely leave a code block described by a pair of +\fBpthread_cleanup_push()\fR and \fBpthread_cleanup_pop()\fR function calls is +undefined. +.sp +.LP +Using \fBlongjmp()\fR or \fBsiglongjmp()\fR to jump into or out of a push/pop +pair can cause either the matching push or the matching pop statement not +getting executed. +.SH RETURN VALUES +.sp +.LP +The \fBpthread_cleanup_push()\fR function returns no value. +.SH ERRORS +.sp +.LP +No errors are defined. +.sp +.LP +The \fBpthread_cleanup_push()\fR function will not return an error code of +\fBEINTR\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBlongjmp\fR(3C), \fBpthread_cancel\fR(3C), \fBpthread_cleanup_pop\fR(3C), +\fBpthread_exit\fR(3C), \fBpthread_join\fR(3C), +\fBpthread_setcancelstate\fR(3C), \fBpthread_setcanceltype\fR(3C), +\fBpthread_testcancel\fR(3C), \fBattributes\fR(5), \fBcancellation\fR(5), +\fBcondition\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +See \fBcancellation\fR(5) for a discussion of cancellation concepts. diff --git a/usr/src/man/man3c/pthread_cond_init.3c b/usr/src/man/man3c/pthread_cond_init.3c new file mode 100644 index 0000000000..7c1596708f --- /dev/null +++ b/usr/src/man/man3c/pthread_cond_init.3c @@ -0,0 +1,184 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_cond_init 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_cond_init, pthread_cond_destroy \- initialize or destroy condition +variables +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_cond_init\fR(\fBpthread_cond_t *restrict\fR \fIcond\fR, + \fBconst pthread_condattr_t *restrict\fR \fIattr\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_cond_destroy\fR(\fBpthread_cond_t *\fR\fIcond\fR +.fi + +.LP +.nf +\fBpthread_cond_t\fR \fIcond\fR= \fBPTHREAD_COND_INITIALIZER\fR; +.fi + +.SH DESCRIPTION +.sp +.LP +The function \fBpthread_cond_init()\fR initializes the condition variable +referenced by \fIcond\fR with attributes referenced by \fIattr\fR. If +\fIattr\fR is \fBNULL\fR, the default condition variable attributes are used; +the effect is the same as passing the address of a default condition variable +attributes object. See \fBpthread_condattr_init\fR(3C). Upon successful +initialization, the state of the condition variable becomes initialized. +.sp +.LP +Attempting to initialize an already initialized condition variable results in +undefined behavior. +.sp +.LP +The function \fBpthread_cond_destroy()\fR destroys the given condition variable +specified by \fIcond\fR; the object becomes, in effect, uninitialized. An +implementation may cause \fBpthread_cond_destroy()\fR to set the object +referenced by \fIcond\fR to an invalid value. A destroyed condition variable +object can be re-initialized using \fBpthread_cond_init()\fR; the results of +otherwise referencing the object after it has been destroyed are undefined. +.sp +.LP +It is 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. +.sp +.LP +In cases where default condition variable attributes are appropriate, the macro +\fBPTHREAD_COND_INITIALIZER\fR can be used to initialize condition variables +that are statically allocated. The effect is equivalent to dynamic +initialization by a call to \fBpthread_cond_init()\fR with parameter \fIattr\fR +specified as \fBNULL,\fR except that no error checks are performed. +.SH RETURN VALUES +.sp +.LP +If successful, the \fBpthread_cond_init()\fR and \fBpthread_cond_destroy()\fR +functions return \fB0\fR. Otherwise, an error number is returned to indicate +the error. The \fBEBUSY\fR and \fBEINVAL\fR error checks, if implemented, act +as if they were performed immediately at the beginning of processing for the +function and caused an error return prior to modifying the state of the +condition variable specified by \fIcond\fR. +.SH ERRORS +.sp +.LP +The \fBpthread_cond_init()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +The system lacked the necessary resources (other than memory) to initialize +another condition variable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient memory exists to initialize the condition variable. +.RE + +.sp +.LP +The \fBpthread_cond_init()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBUSY\fR\fR +.ad +.RS 10n +.rt +The implementation has detected an attempt to re-initialize the object +referenced by \fIcond\fR, a previously initialized, but not yet destroyed, +condition variable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIattr\fR is invalid. +.RE + +.sp +.LP +The \fBpthread_cond_destroy()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBUSY\fR\fR +.ad +.RS 10n +.rt +The implementation has detected an attempt to destroy the object referenced by +\fIcond\fR while it is referenced (for example, while being used in a +\fBpthread_cond_wait()\fR or \fBpthread_cond_timedwait()\fR) by another thread. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIcond\fR is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_cond_signal\fR(3C), \fBpthread_cond_broadcast\fR(3C), +\fBpthread_cond_wait\fR(3C), \fBpthread_cond_timedwait\fR(3C), +\fBpthread_condattr_init\fR(3C), \fBattributes\fR(5), \fBcondition\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_cond_signal.3c b/usr/src/man/man3c/pthread_cond_signal.3c new file mode 100644 index 0000000000..0959e39f0e --- /dev/null +++ b/usr/src/man/man3c/pthread_cond_signal.3c @@ -0,0 +1,112 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_cond_signal 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_cond_signal, pthread_cond_broadcast \- signal or broadcast a condition +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_cond_signal\fR(\fBpthread_cond_t *\fR\fIcond\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_cond_broadcast\fR(\fBpthread_cond_t *\fR\fIcond\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These two functions are used to unblock threads blocked on a condition +variable. +.sp +.LP +The \fBpthread_cond_signal()\fR call unblocks at least one of the threads that +are blocked on the specified condition variable \fIcond\fR (if any threads are +blocked on \fIcond\fR). +.sp +.LP +The \fBpthread_cond_broadcast()\fR call unblocks all threads currently blocked +on the specified condition variable \fIcond\fR. +.sp +.LP +If more than one thread is blocked on a condition variable, the scheduling +policy determines the order in which threads are unblocked. When each thread +unblocked as a result of a \fBpthread_cond_signal()\fR or +\fBpthread_cond_broadcast()\fR returns from its call to +\fBpthread_cond_wait()\fR or \fBpthread_cond_timedwait()\fR, the thread owns +the mutex with which it called \fBpthread_cond_wait()\fR or +\fBpthread_cond_timedwait()\fR. The thread(s) that are unblocked contend for +the mutex according to the scheduling policy (if applicable), and as if each +had called \fBpthread_mutex_lock()\fR. +.sp +.LP +The \fBpthread_cond_signal()\fR or \fBpthread_cond_broadcast()\fR functions may +be called by a thread whether or not it currently owns the mutex that threads +calling \fBpthread_cond_wait()\fR or \fBpthread_cond_timedwait()\fR have +associated with the condition variable during their waits; however, if +predictable scheduling behavior is required, then that mutex is locked by the +thread calling \fBpthread_cond_signal()\fR or \fBpthread_cond_broadcast()\fR. +.sp +.LP +The \fBpthread_cond_signal()\fR and \fBpthread_cond_broadcast()\fR functions +have no effect if there are no threads currently blocked on \fIcond\fR. +.SH RETURN VALUES +.sp +.LP +If successful, the \fBpthread_cond_signal()\fR and +\fBpthread_cond_broadcast()\fR functions return \fB0\fR. Otherwise, an error +number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_cond_signal()\fR and \fBpthread_cond_broadcast()\fR function +may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value \fIcond\fR does not refer to an initialized condition variable. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_cond_init\fR(3C), \fBpthread_cond_wait\fR(3C), +\fBpthread_cond_timedwait\fR(3C), \fBattributes\fR(5), \fBcondition\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_cond_wait.3c b/usr/src/man/man3c/pthread_cond_wait.3c new file mode 100644 index 0000000000..abf79de77e --- /dev/null +++ b/usr/src/man/man3c/pthread_cond_wait.3c @@ -0,0 +1,282 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_cond_wait 3C "11 Nov 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_cond_wait, pthread_cond_timedwait, pthread_cond_reltimedwait_np \- wait +on a condition +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_cond_wait\fR(\fBpthread_cond_t *restrict\fR \fIcond\fR, + \fBpthread_mutex_t *restrict\fR \fImutex\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_cond_timedwait\fR(\fBpthread_cond_t *restrict\fR \fIcond\fR, + \fBpthread_mutex_t *restrict\fR \fImutex\fR, + \fBconst struct timespec *restrict\fR \fIabstime\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_cond_reltimedwait_np\fR(\fBpthread_cond_t *\fR\fIcond\fR, + \fBpthread_mutex_t *\fR\fImutex\fR, \fBconst struct timespec *\fR\fIreltime\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_cond_wait()\fR, \fBpthread_cond_timedwait()\fR, and +\fBpthread_cond_reltimedwait_np()\fR functions are used to block on a condition +variable. They are called with \fImutex\fR locked by the calling thread or +undefined behavior will result. +.sp +.LP +These functions atomically release \fImutex\fR and cause the calling thread to +block on the condition variable \fIcond\fR. 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 +\fBpthread_cond_signal()\fR or \fBpthread_cond_broadcast()\fR in that thread +behaves as if it were issued after the about-to-block thread has blocked. +.sp +.LP +Upon successful return, the mutex has been locked and is owned by the calling +thread. If mutex is a robust mutex where an owner terminated while holding the +lock and the state is recoverable, the mutex is acquired even though the +function returns an error value. +.sp +.LP +When using condition variables there is always a boolean predicate, an +invariant, associated with each condition wait that must be true before the +thread should proceed. Spurious wakeups from the \fBpthread_cond_wait()\fR, +\fBpthread_cond_timedwait()\fR, or \fBpthread_cond_reltimedwait_np()\fR +functions could occur. Since the return from \fBpthread_cond_wait()\fR, +\fBpthread_cond_timedwait()\fR, or \fBpthread_cond_reltimedwait_np()\fR does +not imply anything about the value of this predicate, the predicate should +always be reevaluated. +.sp +.LP +The order in which blocked threads are awakened by \fBpthread_cond_signal()\fR +or \fBpthread_cond_broadcast()\fR is determined by the scheduling policy. See +\fBpthreads\fR(5). +.sp +.LP +The effect of using more than one mutex for concurrent +\fBpthread_cond_wait()\fR, \fBpthread_cond_timedwait()\fR, or +\fBpthread_cond_reltimedwait_np()\fR operations on the same condition variable +will result in undefined behavior. +.sp +.LP +A condition wait (whether timed or not) is a cancellation point. When the +cancelability enable state of a thread is set to \fBPTHREAD_CANCEL_DEFERRED\fR, +a side effect of acting upon a cancellation request while in a condition wait +is that the mutex is reacquired before calling the first cancellation cleanup +handler. +.sp +.LP +A thread that has been unblocked because it has been canceled while blocked in +a call to \fBpthread_cond_wait()\fR or \fBpthread_cond_timedwait()\fR does not +consume any condition signal that may be directed concurrently at the condition +variable if there are other threads blocked on the condition variable. +.sp +.LP +The \fBpthread_cond_timedwait()\fR function is the same as +\fBpthread_cond_wait()\fR except that an error is returned if the absolute time +specified by \fIabstime\fR passes (that is, system time equals or exceeds +\fIabstime\fR) before the condition \fIcond\fR is signaled or broadcast, or if +the absolute time specified by \fIabstime\fR has already been passed at the +time of the call. The \fIabstime\fR argument is of type \fBstruct timespec\fR, +defined in \fBtime.h\fR(3HEAD). When such time-outs occur, +\fBpthread_cond_timedwait()\fR will nonetheless release and reacquire the mutex +referenced by \fImutex\fR. The function \fBpthread_cond_timedwait()\fR is also +a cancellation point. +.sp +.LP +The \fBpthread_cond_reltimedwait_np()\fR function is a non-standard extension +provided by the Solaris version of POSIX threads as indicated by the +``\fB_np\fR'' (non-portable) suffix. The \fBpthread_cond_reltimedwait_np()\fR +function is the same as \fBpthread_cond_timedwait()\fR except that the +\fIreltime\fR argument specifies a non-negative time relative to the current +system time rather than an absolute time. The \fIreltime\fR argument is of type +\fBstruct timespec\fR, defined in \fBtime.h\fR(3HEAD). An error value is +returned if the relative time passes (that is, system time equals or exceeds +the starting system time plus the relative time) before the condition +\fIcond\fR is signaled or broadcast. When such timeouts occur, +\fBpthread_cond_reltimedwait_np()\fR releases and reacquires the mutex +referenced by \fImutex\fR. The \fBpthread_cond_reltimedwait_np()\fR function +is also a cancellation point. +.sp +.LP +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 returns \fB0\fR due to spurious +wakeup. +.SH RETURN VALUES +.sp +.LP +Except in the case of \fBETIMEDOUT\fR, \fBEOWNERDEAD\fR, or +\fBENOTRECOVERABLE\fR, all of these error checks act as if they were performed +immediately at the beginning of processing for the function and cause an error +return, in effect, prior to modifying the state of the mutex specified by +\fImutex\fR or the condition variable specified by \fIcond\fR. +.sp +.LP +Upon successful completion, \fB0\fR is returned. Otherwise, an error value is +returned to indicate the error. +.SH ERRORS +.sp +.LP +These functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 9n +.rt +The mutex type is \fBPTHREAD_MUTEX_ERRORCHECK\fR or the mutex is a robust +mutex, and the current thread does not own the mutex. +.RE + +.sp +.LP +The \fBpthread_cond_timedwait()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBETIMEDOUT\fR\fR +.ad +.RS 13n +.rt +The absolute time specified by \fIabstime\fR to \fBpthread_cond_timedwait()\fR +has passed. +.RE + +.sp +.LP +The \fBpthread_cond_reltimedwait_np()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 13n +.rt +The value specified by \fIreltime\fR is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBETIMEDOUT\fR\fR +.ad +.RS 13n +.rt +The relative time specified by \fIreltime\fR to +\fBpthread_cond_reltimedwait_np()\fR has passed. +.RE + +.sp +.LP +These functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIcond\fR, \fImutex\fR, \fIabstime\fR, or \fIreltime\fR +is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +Different mutexes were supplied for concurrent operations on the same condition +variable. +.RE + +.sp +.LP +If the mutex specified by \fImutex\fR is a robust mutex (initialized with the +robustness attribute \fBPTHREAD_MUTEX_ROBUST\fR), the +\fBpthread_cond_wait()\fR, \fBpthread_cond_timedwait()\fR, and +\fBpthread_cond_reltimedwait_np()\fR functions will, under the specified +conditions, return the following error values. For complete information, see +the \fBpthread_mutex_lock\fR(3C) and \fBpthread_mutexattr_setrobust\fR(3C) +manual pages. +.sp +.ne 2 +.mk +.na +\fB\fBEOWNERDEAD\fR\fR +.ad +.RS 19n +.rt +The last owner of this mutex died while holding the mutex, leaving the state it +was protecting possibly inconsistent. The mutex is now owned by the caller. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTRECOVERABLE\fR\fR +.ad +.RS 19n +.rt +The mutex was protecting state that has now been left irrecoverable. The mutex +has not been acquired. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_cond_signal\fR(3C), \fBpthread_cond_broadcast\fR(3C), +\fBpthread_mutex_lock\fR(3C), \fBpthread_mutexattr_getrobust\fR(3C), +\fBtime.h\fR(3HEAD), \fBattributes\fR(5), \fBcondition\fR(5), +\fBpthreads\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_condattr_getclock.3c b/usr/src/man/man3c/pthread_condattr_getclock.3c new file mode 100644 index 0000000000..6f9934a14c --- /dev/null +++ b/usr/src/man/man3c/pthread_condattr_getclock.3c @@ -0,0 +1,112 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_condattr_getclock 3C "30 Jan 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_condattr_getclock, pthread_condattr_setclock \- get and set the clock +selection condition variable attribute +.SH SYNOPSIS +.LP +.nf +cc \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_condattr_getclock\fR( + \fBconst pthread_condattr_t *restrict\fR \fIattr\fR, + \fBclockid_t *restrict\fR \fIclock_id\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_condattr_setclock\fR(\fBpthread_condattr_t *\fR\fIattr\fR + \fBclockid_t\fR \fIclock_id\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_condattr_getclock()\fR function obtains the value of the clock +attribute from the attributes object referenced by \fIattr\fR. The +\fBpthread_condattr_setclock()\fR function sets the clock attribute in an +initialized attributes object referenced by \fIattr\fR. If +\fBpthread_condattr_setclock()\fR is called with a \fIclock_id\fR argument that +refers to a CPU-time clock, the call fails. +.sp +.LP +The clock attribute is the clock ID of the clock that is used to measure the +timeout service of \fBpthread_cond_timedwait\fR(3C). The default value of the +clock attribute refers to the system clock. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBpthread_condattr_getclock()\fR function +returns 0 and stores the value of the clock attribute of \fIattr\fR into the +object referenced by the \fIclock_id\fR argument. Otherwise, an error number is +returned to indicate the error. +.sp +.LP +Upon successful completion, the \fBpthread_condattr_setclock()\fR function +returns 0. Otherwise, an error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +These functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIattr\fR is invalid. +.RE + +.sp +.LP +The \fBpthread_condattr_setclock()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIclock_id\fR does not refer to a known clock, or is a +CPU-time clock. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_cond_init\fR(3C), \fBpthread_cond_timedwait\fR(3C), +\fBpthread_condattr_destroy\fR(3C), \fBpthread_condattr_getpshared\fR(3C), +\fBpthread_create\fR(3C), \fBpthread_mutex_init\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_condattr_getpshared.3c b/usr/src/man/man3c/pthread_condattr_getpshared.3c new file mode 100644 index 0000000000..7601dbb160 --- /dev/null +++ b/usr/src/man/man3c/pthread_condattr_getpshared.3c @@ -0,0 +1,123 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_condattr_getpshared 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_condattr_getpshared, pthread_condattr_setpshared \- get or set +process-shared condition variable attributes +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_condattr_getpshared\fR( + \fBconst pthread_condattr_t *restrict\fR \fIattr\fR, + \fBint *restrict\fR \fIpshared\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_condattr_setpshared\fR(\fBpthread_condattr_t *\fR\fIattr\fR, + \fBint\fR \fIpshared\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_condattr_getpshared()\fR function obtains the value of the +\fIprocess-shared\fR attribute from the attributes object referenced by +\fIattr\fR. The \fBpthread_condattr_setpshared()\fR function is used to set the +\fIprocess-shared\fR attribute in an initialized attributes object referenced +by \fIattr\fR. +.sp +.LP +The \fIprocess-shared\fR attribute is set to \fBPTHREAD_PROCESS_SHARED\fR 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 +\fIprocess-shared\fR attribute is \fBPTHREAD_PROCESS_PRIVATE,\fR the condition +variable will 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 +\fBPTHREAD_PROCESS_PRIVATE.\fR +.sp +.LP +Additional attributes, their default values, and the names of the associated +functions to get and set those attribute values are implementation-dependent. +.SH RETURN VALUES +.sp +.LP +If successful, the \fBpthread_condattr_setpshared()\fR function returns +\fB0\fR. Otherwise, an error number is returned to indicate the error. +.sp +.LP +If successful, the \fBpthread_condattr_getpshared()\fR function returns +\fB0\fR and stores the value of the \fIprocess-shared\fR attribute of +\fIattr\fR into the object referenced by the \fIpshared\fR parameter. +Otherwise, an error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_condattr_getpshared()\fR and \fBpthread_condattr_setpshared()\fR +functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIattr\fR is invalid. +.RE + +.sp +.LP +The \fBpthread_condattr_setpshared()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The new value specified for the attribute is outside the range of legal values +for that attribute. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_condattr_init\fR(3C), \fBpthread_create\fR(3C), +\fBpthread_mutex_init\fR(3C), \fBpthread_cond_init\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_condattr_init.3c b/usr/src/man/man3c/pthread_condattr_init.3c new file mode 100644 index 0000000000..eae5001381 --- /dev/null +++ b/usr/src/man/man3c/pthread_condattr_init.3c @@ -0,0 +1,124 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_condattr_init 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_condattr_init, pthread_condattr_destroy \- initialize or destroy +condition variable attributes object +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_condattr_init\fR(\fBpthread_condattr_t *\fR\fIattr\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_condattr_destroy\fR(\fBpthread_condattr_t *\fR\fIattr\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_condattr_init()\fR function initializes a condition variable +attributes object \fIattr\fR with the default value for all of the attributes +defined by the implementation. +.sp +.LP +At present, the only attribute available is the scope of condition variables. +The default scope of the attribute is \fBPTHREAD_PROCESS_PRIVATE\fR. +.sp +.LP +Attempts to initialize previously initialized condition variable attributes +object will leave the storage allocated by the previous initialization +unallocated. +.sp +.LP +After a condition variable attributes object has been used to initialize one or +more condition variables, any function affecting the attributes object +(including destruction) does not affect any previously initialized condition +variables. +.sp +.LP +The \fBpthread_condattr_destroy()\fR function destroys a condition variable +attributes object; the object becomes, in effect, uninitialized. An +implementation may cause \fBpthread_condattr_destroy()\fR to set the object +referenced by \fIattr\fR to an invalid value. A destroyed condition variable +attributes object can be re-initialized using \fBpthread_condattr_init()\fR; +the results of otherwise referencing the object after it has been destroyed are +undefined. +.sp +.LP +Additional attributes, their default values, and the names of the associated +functions to get and set those attribute values are implementation-dependent. +.SH RETURN VALUES +.sp +.LP +If successful, the \fBpthread_condattr_init()\fR and +\fBpthread_condattr_destroy()\fR functions return \fB0\fR. Otherwise, an error +number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_condattr_init()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient memory exists to initialize the condition variable attributes +object. +.RE + +.sp +.LP +The \fBpthread_condattr_destroy()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIattr\fR is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_condattr_getpshared\fR(3C), \fBpthread_condattr_setpshared\fR(3C), +\fBpthread_cond_init\fR(3C), \fBpthread_create\fR(3C), +\fBpthread_mutex_init\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_create.3c b/usr/src/man/man3c/pthread_create.3c new file mode 100644 index 0000000000..eeeada69f5 --- /dev/null +++ b/usr/src/man/man3c/pthread_create.3c @@ -0,0 +1,324 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_create 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_create \- create a thread +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_create\fR(\fBpthread_t *restrict\fR \fIthread\fR, + \fBconst pthread_attr_t *restrict\fR \fIattr\fR, + \fBvoid *(*\fR\fIstart_routine\fR)(void*), \fBvoid *restrict\fR \fIarg\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_create()\fR function is used to create a new thread, with +attributes specified by \fIattr\fR, within a process. If \fIattr\fR is +\fINULL,\fR the default attributes are used. (See \fBpthread_attr_init\fR(3C)). +If the attributes specified by \fIattr\fR are modified later, the thread's +attributes are not affected. Upon successful completion, \fBpthread_create()\fR +stores the \fBID\fR of the created thread in the location referenced by +\fIthread\fR. +.sp +.LP +The thread is created executing \fIstart_routine\fR with \fIarg\fR as its sole +argument. If the \fIstart_routine\fR returns, the effect is as if there was an +implicit call to \fBpthread_exit()\fR using the return value of +\fIstart_routine\fR as the exit status. Note that the thread in which +\fBmain()\fR was originally invoked differs from this. When it returns from +\fBmain()\fR, the effect is as if there was an implicit call to \fBexit()\fR +using the return value of \fBmain()\fR as the exit status. +.sp +.LP +The signal state of the new thread is initialised as follows: +.RS +4 +.TP +.ie t \(bu +.el o +The signal mask is inherited from the creating thread. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The set of signals pending for the new thread is empty. +.RE +.sp +.LP +Default thread creation: +.sp +.in +2 +.nf +pthread_t tid; +void *start_func(void *), *arg; + +pthread_create(&tid, NULL, start_func, arg); +.fi +.in -2 + +.sp +.LP +This would have the same effect as: +.sp +.in +2 +.nf +\fBpthread_attr_t attr; + +pthread_attr_init(&attr); /* initialize attr with default */ + /* attributes */ +pthread_create(&tid, &attr, start_func, arg);\fR +.fi +.in -2 + +.sp +.LP +User-defined thread creation: To create a thread that is scheduled on a +system-wide basis, use: +.sp +.in +2 +.nf +pthread_attr_init(&attr); /* initialize attr with default */ + /* attributes */ +pthread_attr_setscope(&attr, PTHREAD_SCOPE_SYSTEM); + /* system-wide contention */ +pthread_create(&tid, &attr, start_func, arg); +.fi +.in -2 + +.sp +.LP +To customize the attributes for POSIX threads, see \fBpthread_attr_init\fR(3C). +.sp +.LP +A new thread created with \fBpthread_create()\fR uses the stack specified by +the \fIstackaddr\fR attribute, and the stack continues for the number of bytes +specified by the \fIstacksize\fR attribute. By default, the stack size is 1 +megabyte for 32-bit processes and 2 megabyte for 64-bit processes (see +\fBpthread_attr_setstacksize\fR(3C)). If the default is used for both the +\fIstackaddr\fR and \fIstacksize\fR attributes, \fBpthread_create()\fR creates +a stack for the new thread with at least 1 megabyte for 32-bit processes and 2 +megabyte for 64-bit processes. (For customizing stack sizes, see \fBNOTES\fR). +.sp +.LP +If \fBpthread_create()\fR fails, no new thread is created and the contents of +the location referenced by \fIthread\fR are undefined. +.SH RETURN VALUES +.sp +.LP +If successful, the \fBpthread_create()\fR function returns \fB0\fR. Otherwise, +an error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_create()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +The system lacked the necessary resources to create another thread, or the +system-imposed limit on the total number of threads in a process +\fBPTHREAD_THREADS_MAX\fR would be exceeded. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIattr\fR is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 10n +.rt +The caller does not have appropriate permission to set the required scheduling +parameters or scheduling policy. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRExample of concurrency with multithreading +.sp +.LP +The following is an example of concurrency with multithreading. Since POSIX +threads and Solaris threads are fully compatible even within the same process, +this example uses \fBpthread_create()\fR if you execute \fBa.out 0\fR, or +\fBthr_create()\fR if you execute \fBa.out 1\fR. + +.sp +.LP +Five threads are created that simultaneously perform a time-consuming function, +\fBsleep(\fR10\fB)\fR. If the execution of this process is timed, the results +will show that all five individual calls to sleep for ten-seconds completed in +about ten seconds, even on a uniprocessor. If a single-threaded process calls +\fBsleep(\fR10\fB)\fR five times, the execution time will be about 50-seconds. + +.sp +.LP +The command-line to time this process is: + +.sp +.ne 2 +.mk +.na +\fBPOSIX threading\fR +.ad +.RS 21n +.rt +/usr/bin/time a.out 0 +.RE + +.sp +.ne 2 +.mk +.na +\fBSolaris threading\fR +.ad +.RS 21n +.rt +/usr/bin/time a.out 1 +.RE + +.sp +.in +2 +.nf +/* cc thisfile.c -lthread -lpthread */ +#define _REENTRANT /* basic 3-lines for threads */ +#include <pthread.h> +#include <thread.h> + +#define NUM_THREADS 5 +#define SLEEP_TIME 10 + +void *sleeping(void *); /* thread routine */ +int i; +thread_t tid[NUM_THREADS]; /* array of thread IDs */ + +int +main(int argc, char *argv[]) +{ + if (argc == 1) { + printf("use 0 as arg1 to use pthread_create(\|)\en"); + printf("or use 1 as arg1 to use thr_create(\|)\en"); + return (1); + } + + switch (*argv[1]) { + case '0': /* POSIX */ + for ( i = 0; i < NUM_THREADS; i++) + pthread_create(&tid[i], NULL, sleeping, + (void *)SLEEP_TIME); + for ( i = 0; i < NUM_THREADS; i++) + pthread_join(tid[i], NULL); + break; + + case '1': /* Solaris */ + for ( i = 0; i < NUM_THREADS; i++) + thr_create(NULL, 0, sleeping, (void *)SLEEP_TIME, 0, + &tid[i]); + while (thr_join(0, NULL, NULL) == 0) + ; + break; + } /* switch */ + printf("main(\|) reporting that all %d threads have + terminated\en", i); + return (0); +} /* main */ + +void * +sleeping(void *arg) +{ + int sleep_time = (int)arg; + printf("thread %d sleeping %d seconds ...\en", thr_self(\|), + sleep_time); + sleep(sleep_time); + printf("\enthread %d awakening\en", thr_self(\|)); + return (NULL); +} +.fi +.in -2 + +.sp +.LP +If \fBmain()\fR had not waited for the completion of the other threads (using +\fBpthread_join\fR(3C) or \fBthr_join\fR(3C)), it would have continued to +process concurrently until it reached the end of its routine and the entire +process would have exited prematurely. See \fBexit\fR(2). + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfork\fR(2), \fBpthread_attr_init\fR(3C), \fBpthread_cancel\fR(3C), +\fBpthread_exit\fR(3C), \fBpthread_join\fR(3C), \fBsysconf\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +Multithreaded application threads execute independently of each other, so their +relative behavior is unpredictable. Therefore, it is possible for the thread +executing \fBmain()\fR to finish before all other user application threads. The +\fBpthread_join\fR(3C)function, on the other hand, must specify the terminating +thread (IDs) for which it will wait. +.sp +.LP +A user-specified stack size must be greater than the value +\fBPTHREAD_STACK_MIN\fR. A minimum stack size may not accommodate the stack +frame for the user thread function \fIstart_func\fR. If a stack size is +specified, it must accommodate \fIstart_func\fR requirements and the functions +that it may call in turn, in addition to the minimum requirement. +.sp +.LP +It is usually very difficult to determine the runtime stack requirements for a +thread. \fBPTHREAD_STACK_MIN\fR specifies how much stack storage is required to +execute a \fINULL\fR \fIstart_func\fR. The total runtime requirements for stack +storage are dependent on the storage required to do runtime linking, the amount +of storage required by library runtimes (as \fBprintf()\fR) that your thread +calls. Since these storage parameters are not known before the program runs, it +is best to use default stacks. If you know your runtime requirements or decide +to use stacks that are larger than the default, then it makes sense to specify +your own stacks. diff --git a/usr/src/man/man3c/pthread_detach.3c b/usr/src/man/man3c/pthread_detach.3c new file mode 100644 index 0000000000..0a769b4b90 --- /dev/null +++ b/usr/src/man/man3c/pthread_detach.3c @@ -0,0 +1,92 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_detach 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_detach \- detach a thread +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_detach\fR(\fBpthread_t\fR \fIthread\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_detach()\fR function is used to indicate to the implementation +that storage for the thread \fIthread\fR can be reclaimed when that thread +terminates. In other words, \fBpthread_detach()\fR dynamically resets the +\fIdetachstate\fR attribute of the thread to \fBPTHREAD_CREATE_DETACHED.\fR +After a successful call to this function, it would not be necessary to reclaim +the thread using \fBpthread_join()\fR. See \fBpthread_join\fR(3C). If +\fIthread\fR has not terminated, \fBpthread_detach()\fR will not cause it to +terminate. The effect of multiple \fBpthread_detach()\fR calls on the same +target thread is unspecified. +.SH RETURN VALUES +.sp +.LP +If successful, \fBpthread_detach()\fR returns \fB0\fR. Otherwise, an error +number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_detach()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The implementation has detected that the value specified by \fIthread\fR does +not refer to a joinable thread. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBESRCH\fR\fR +.ad +.RS 10n +.rt +No thread could be found corresponding to that specified by the given thread +\fBID.\fR +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_create\fR(3C), \fBpthread_join\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_equal.3c b/usr/src/man/man3c/pthread_equal.3c new file mode 100644 index 0000000000..01d8b7f01a --- /dev/null +++ b/usr/src/man/man3c/pthread_equal.3c @@ -0,0 +1,70 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_equal 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_equal \- compare thread IDs +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_equal\fR(\fBpthread_t\fR \fIt1\fR, \fBpthread_t\fR \fIt2\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_equal()\fR function compares the thread \fBIDs\fR \fIt1\fR and +\fIt2\fR. +.SH RETURN VALUES +.sp +.LP +The \fBpthread_equal()\fR function returns a non-zero value if \fIt1\fR and +\fIt2\fR are equal. Otherwise, \fB0\fR is returned. +.sp +.LP +If \fIt1\fR or \fIt2\fR is an invalid thread \fBID,\fR the behavior is +undefined. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_create\fR(3C), \fBpthread_self\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) +.SH NOTES +.sp +.LP +Solaris thread \fBIDs\fR do not require an equivalent function because the +\fBthread_t\fR structure is an unsigned int. diff --git a/usr/src/man/man3c/pthread_exit.3c b/usr/src/man/man3c/pthread_exit.3c new file mode 100644 index 0000000000..856c859e49 --- /dev/null +++ b/usr/src/man/man3c/pthread_exit.3c @@ -0,0 +1,100 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_exit 3C "2 Nov 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_exit \- terminate calling thread +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBvoid\fR \fBpthread_exit\fR(\fBvoid *\fR\fIvalue_ptr\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_exit()\fR function terminates the calling thread, in a similar +way that \fBexit\fR(3C) terminates the calling process. If the thread is not +detached, the exit status specified by \fIvalue_ptr\fR is made available to +any successful join with the terminating thread. See \fBpthread_join\fR(3C). +Any cancellation cleanup handlers that have been pushed and not yet popped are +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 will 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 \fBatexit()\fR routines that might exist. +.sp +.LP +An exiting thread runs with all signals blocked. All thread termination +functions, including cancellation cleanup handlers and thread-specific data +destructor functions, are called with all signals blocked. +.sp +.LP +An implicit call to \fBpthread_exit()\fR is made when a thread other than the +thread in which \fBmain()\fR was first invoked returns from the start routine +that was used to create it. The function's return value serves as the thread's +exit status. +.sp +.LP +The behavior of \fBpthread_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 \fBpthread_exit()\fR. +.sp +.LP +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 \fBpthread_exit()\fR \fIvalue_ptr\fR +parameter value. +.sp +.LP +The process exits with an exit status of \fB0\fR after the last thread has +been terminated. The behavior is as if the implementation called \fBexit()\fR +with a \fB0\fR argument at thread termination time. +.SH RETURN VALUES +.sp +.LP +The \fBpthread_exit()\fR function cannot return to its caller. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBexit\fR(3C), \fBpthread_cancel\fR(3C), \fBpthread_create\fR(3C), +\fBpthread_join\fR(3C), \fBpthread_key_create\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_getconcurrency.3c b/usr/src/man/man3c/pthread_getconcurrency.3c new file mode 100644 index 0000000000..f3f34317c0 --- /dev/null +++ b/usr/src/man/man3c/pthread_getconcurrency.3c @@ -0,0 +1,131 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_getconcurrency 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_getconcurrency, pthread_setconcurrency \- get or set level of +concurrency +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_getconcurrency\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_setconcurrency\fR(\fBint\fR \fInew_level\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +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. +.sp +.LP +The \fBpthread_setconcurrency()\fR function allows an application to inform +the threads implementation of its desired concurrency level, \fInew_level\fR. +The actual level of concurrency provided by the implementation as a result of +this function call is unspecified. +.sp +.LP +If \fInew_level\fR is \fB0\fR, it causes the implementation to maintain the +concurrency level at its discretion as if \fBpthread_setconcurrency()\fR was +never called. +.sp +.LP +The \fBpthread_getconcurrency()\fR function returns the value set by a +previous call to the \fBpthread_setconcurrency()\fR function. If the +\fBpthread_setconcurrency()\fR function was not previously called, this +function returns \fB0\fR to indicate that the implementation is maintaining +the concurrency level. +.sp +.LP +When an application calls \fBpthread_setconcurrency()\fR it is informing the +implementation of its desired concurrency level. The implementation uses this +as a hint, not a requirement. +.sp +.LP +If an implementation does not support multiplexing of user threads on top of +several kernel scheduled entities, the \fBpthread_setconcurrency()\fR and +\fBpthread_getconcurrency()\fR functions will be provided for source code +compatibility but they will have no effect when called. To maintain the +function semantics, the \fInew_level\fR parameter will be saved when +\fBpthread_setconcurrency()\fR is called so that a subsequent call to +\fBpthread_getconcurrency()\fR returns the same value. +.SH RETURN VALUES +.sp +.LP +If successful, the \fBpthread_setconcurrency()\fR function returns \fB0\fR. +Otherwise, an error number is returned to indicate the error. +.sp +.LP +The \fBpthread_getconcurrency()\fR function always returns the concurrency +level set by a previous call to \fBpthread_setconcurrency()\fR. If the +\fBpthread_setconcurrency()\fR function has never been called, +\fBpthread_getconcurrency()\fR returns \fB0\fR. +.SH ERRORS +.sp +.LP +The \fBpthread_setconcurrency()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fInew_level\fR is negative. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +The value specific by \fInew_level\fR would cause a system resource to be +exceeded. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_create\fR(3C), \fBpthread_attr_init\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_getschedparam.3c b/usr/src/man/man3c/pthread_getschedparam.3c new file mode 100644 index 0000000000..0a33807cf6 --- /dev/null +++ b/usr/src/man/man3c/pthread_getschedparam.3c @@ -0,0 +1,203 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_getschedparam 3C "1 Apr 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_getschedparam, pthread_setschedparam \- access dynamic thread +scheduling parameters +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_getschedparam\fR(\fBpthread_t\fR \fIthread\fR, \fBint *restrict\fR \fIpolicy\fR, + \fBstruct sched_param *restrict\fR \fIparam\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_setschedparam\fR(\fBpthread_t\fR \fIthread\fR, \fBint\fR \fIpolicy\fR, + \fBconst struct sched_param *\fR\fIparam\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_getschedparam()\fR and \fBpthread_setschedparam()\fR functions +allow the scheduling policy and scheduling parameters of individual threads +within a multithreaded process to be retrieved and set. Supported policies are +: +.sp +.ne 2 +.mk +.na +\fB\fBSCHED_OTHER\fR\fR +.ad +.RS 15n +.rt +traditional time-sharing scheduling class +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCHED_FIFO\fR\fR +.ad +.RS 15n +.rt +real-time class: run to completion +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCHED_RR\fR\fR +.ad +.RS 15n +.rt +real-time class: round-robin +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCHED_IA\fR\fR +.ad +.RS 15n +.rt +interactive time-sharing class +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCHED_FSS\fR\fR +.ad +.RS 15n +.rt +fair-share scheduling class +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCHED_FX\fR\fR +.ad +.RS 15n +.rt +fixed priority scheduling class +.RE + +.sp +.LP +See \fBpthreads\fR(5). The affected scheduling parameter is the +\fIsched_priority\fR member of the \fBsched_param\fR structure. +.sp +.LP +The \fBpthread_getschedparam()\fR function retrieves the scheduling policy and +scheduling parameters for the thread whose thread \fBID\fR is given by +\fIthread\fR and stores those values in \fIpolicy\fR and \fIparam\fR, +respectively. The priority value returned from \fBpthread_getschedparam()\fR is +the value specified by the most recent \fBpthread_setschedparam()\fR or +\fBpthread_create()\fR call affecting the target thread, and does not reflect +any temporary adjustments to its priority as a result of any priority +inheritance or ceiling functions. The \fBpthread_setschedparam()\fR function +sets the scheduling policy and associated scheduling parameters for the thread +whose thread \fBID\fR is given by \fIthread\fR to the policy and associated +parameters provided in \fIpolicy\fR and \fIparam\fR, respectively. +.sp +.LP +If the \fBpthread_setschedparam()\fR function fails, no scheduling parameters +will be changed for the target thread. +.SH RETURN VALUES +.sp +.LP +If successful, the \fBpthread_getschedparam()\fR and +\fBpthread_setschedparam()\fR functions return \fB0\fR. Otherwise, an error +number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_getschedparam()\fR and \fBpthread_gsetschedparam()\fR functions +will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBESRCH\fR\fR +.ad +.RS 9n +.rt +The value specified by \fIthread\fR does not refer to an existing thread. +.RE + +.sp +.LP +The \fBpthread_setschedparam()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIpolicy\fR or one of the scheduling parameters +associated with the scheduling policy \fIpolicy\fR is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 10n +.rt +The caller does not have the appropriate permission to set either the +scheduling parameters or the scheduling policy of the specified thread. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_attr_init\fR(3C), \fBsched_getparam\fR(3C), +\fBsched_get_priority_max\fR(3C)\fBsched_get_priority_max\fR(3C), +\fBsched_get_priority_min\fR(3C), \fBsched_setparam\fR(3C), +\fBsched_getscheduler\fR(3C), \fBsched_setscheduler\fR(3C), +\fBattributes\fR(5), \fBpthreads\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_getspecific.3c b/usr/src/man/man3c/pthread_getspecific.3c new file mode 100644 index 0000000000..31904adc5d --- /dev/null +++ b/usr/src/man/man3c/pthread_getspecific.3c @@ -0,0 +1,117 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_getspecific 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_getspecific, pthread_setspecific \- manage thread-specific data +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_setspecific\fR(\fBpthread_key_t\fR \fIkey\fR, \fBconst void *\fR\fIvalue\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBpthread_getspecific\fR(\fBpthread_key_t\fR \fIkey\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_setspecific()\fR function associates a thread-specific +\fIvalue\fR with a \fIkey\fR obtained by way of a previous call to +\fBpthread_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. +.sp +.LP +The \fBpthread_getspecific()\fR function returns the value currently bound to +the specified \fIkey\fR on behalf of the calling thread. +.sp +.LP +The effect of calling \fBpthread_setspecific()\fR or +\fBpthread_getspecific()\fR with a \fIkey\fR value not obtained from +\fBpthread_key_create()\fR or after \fIkey\fR has been deleted with +\fBpthread_key_delete()\fR is undefined. +.sp +.LP +Both \fBpthread_setspecific()\fR and \fBpthread_getspecific()\fR may be called +from a thread-specific data destructor function. However, calling +\fBpthread_setspecific()\fR from a destructor may result in lost storage or +infinite loops. +.SH RETURN VALUES +.sp +.LP +The \fBpthread_getspecific()\fR function returns the thread-specific data +value associated with the given \fIkey\fR. If no thread-specific data value is +associated with \fIkey\fR, then the value \fINULL\fR is returned. +.sp +.LP +Upon successful completion, the \fBpthread_setspecific()\fR function returns +\fB0\fR. Otherwise, an error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_setspecific()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient memory exists to associate the value with the key. +.RE + +.sp +.LP +The \fBpthread_setspecific()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The key value is invalid. +.RE + +.sp +.LP +The \fBpthread_getspecific()\fR function does not return errors. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_key_create\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_join.3c b/usr/src/man/man3c/pthread_join.3c new file mode 100644 index 0000000000..45e930b3a1 --- /dev/null +++ b/usr/src/man/man3c/pthread_join.3c @@ -0,0 +1,127 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_join 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_join \- wait for thread termination +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_join\fR(\fBpthread_t\fR \fIthread\fR, \fBvoid **\fR\fIstatus\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_join()\fR function suspends processing of the calling thread +until the target \fIthread\fR completes. \fIthread\fR must be a member of the +current process and it cannot be a detached thread. See +\fBpthread_create\fR(3C). +.sp +.LP +If two or more threads wait for the same thread to complete, all will suspend +processing until the thread has terminated, and then one thread will return +successfully and the others will return with an error of \fBESRCH\fR. The +\fBpthread_join()\fR function will not block processing of the calling thread +if the target \fIthread\fR has already terminated. +.sp +.LP +If a \fBpthread_join()\fR call returns successfully with a non-null +\fIstatus\fR argument, the value passed to \fBpthread_exit\fR(3C) by the +terminating thread will be placed in the location referenced by \fIstatus\fR. +.sp +.LP +If the \fBpthread_join()\fR calling thread is cancelled, then the target +\fIthread\fR will remain joinable by \fBpthread_join()\fR. However, the calling +thread may set up a cancellation cleanup handler on \fIthread\fR prior to the +join call, which may detach the target \fIthread\fR by calling +\fBpthread_detach\fR(3C). See \fBpthread_detach\fR(3C) and +\fBpthread_cancel\fR(3C). +.SH RETURN VALUES +.sp +.LP +If successful, \fBpthread_join()\fR returns \fB0\fR. Otherwise, an error number +is returned to indicate the error. +.SH ERRORS +.sp +.ne 2 +.mk +.na +\fB\fBEDEADLK\fR\fR +.ad +.RS 11n +.rt +A joining deadlock would occur, such as when a thread attempts to wait for +itself. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 11n +.rt +The thread corresponding to the given thread ID is a detached thread. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBESRCH\fR\fR +.ad +.RS 11n +.rt +No thread could be found corresponding to the given thread ID. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_cancel\fR(3C), \fBpthread_create\fR(3C), \fBpthread_detach\fR(3C), +\fBpthread_exit\fR(3C), \fBwait\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +The pthread_join(3C) function must specify the \fIthread\fR \fBID\fR for whose +termination it will wait. +.sp +.LP +Calling \fBpthread_join()\fR also "detaches" the thread; that is, +\fBpthread_join()\fR includes the effect of the \fBpthread_detach()\fR +function. If a thread were to be cancelled when blocked in +\fBpthread_join()\fR, an explicit detach would have to be performed in the +cancellation cleanup handler. The \fBpthread_detach()\fR function exists +primarily for this purpose. diff --git a/usr/src/man/man3c/pthread_key_create.3c b/usr/src/man/man3c/pthread_key_create.3c new file mode 100644 index 0000000000..49b40d5c3e --- /dev/null +++ b/usr/src/man/man3c/pthread_key_create.3c @@ -0,0 +1,221 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_key_create 3C "2 Nov 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_key_create, pthread_key_create_once_np \- create thread-specific data +key +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_key_create\fR(\fBpthread_key_t *\fR\fIkey\fR, + \fBvoid\fR (*\fIdestructor\fR)(\fBvoid*\fR)); +.fi + +.LP +.nf +\fBint\fR \fBpthread_key_create_once_np\fR(\fBpthread_key_t *\fR\fIkey\fR, + \fBvoid\fR (*\fIdestructor\fR)(\fBvoid*\fR)); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_key_create()\fR function creates a thread-specific data key +visible to all threads in the process. Key values provided by +\fBpthread_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 \fBpthread_setspecific()\fR are maintained on a per-thread +basis and persist for the life of the calling thread. +.sp +.LP +Upon key creation, the value \fINULL\fR is associated with the new key in all +active threads. Upon thread creation, the value \fINULL\fR is associated with +all defined keys in the new thread. +.sp +.LP +An optional destructor function may be associated with each key value. At +thread exit, if a key value has a non-\fINULL\fR destructor pointer, and the +thread has a non-\fINULL\fR value associated with that key, the function +pointed to is called with the current associated value as its sole argument. +Destructors can be called in any order. +.sp +.LP +If, after all the destructors have been called for all keys with +non-\fINULL\fR values, there are still some keys with non-\fINULL\fR values, +the process will be repeated. If, after at least +\fBPTHREAD_DESTRUCTOR_ITERATIONS\fR iterations of destructor calls for +outstanding non-\fINULL\fR values, there are still some keys with +non-\fINULL\fR values, the process is continued, even though this might result +in an infinite loop. +.sp +.LP +An exiting thread runs with all signals blocked. All thread termination +functions, including thread-specific data destructor functions, are called with +all signals blocked. +.sp +.LP +The \fBpthread_key_create_once_np()\fR function is identical to the +\fBpthread_key_create()\fR function except that the key referred to by +*\fIkey\fR must be statically initialized with the value +\fBPTHREAD_ONCE_KEY_NP\fR before calling \fBpthread_key_create_once_np()\fR, +and the key is created exactly once. This function call is equivalent to using +\fBpthread_once\fR(3C) to call a onetime initialization function that calls +\fBpthread_key_create()\fR to create the data key. +.SH RETURN VALUES +.sp +.LP +If successful, the \fBpthread_key_create()\fR and +\fBpthread_key_create_once_np()\fR functions store the newly created key value +at *\fIkey\fR and return \fB0\fR. Otherwise, an error number is returned to +indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_key_create()\fR and \fBpthread_key_create_once_np()\fR +functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +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 +\fBPTHREAD_KEYS_MAX\fR has been exceeded. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient memory exists to create the key. +.RE + +.sp +.LP +The \fBpthread_key_create()\fR and \fBpthread_key_create_once_np()\fR functions +will not return an error value of \fBEINTR\fR. +.SH EXAMPLES +.LP +\fBExample 1 \fRCall thread-specific data in the function from more than one +thread without special initialization. +.sp +.LP +In the following example, the thread-specific data in the function can be +called from more than one thread without special initialization. For each +argument passed to the executable, a thread is created and privately bound to +the string-value of that argument. + +.sp +.in +2 +.nf +/* cc -mt thisfile.c */ + +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <pthread.h> + +static void *thread_function(void *); +static void show_tsd(void); +static void cleanup(void*); + +#define MAX_THREADS 20 + +static pthread_key_t tsd_key = PTHREAD_ONCE_KEY_NP; + +int +main(int argc, char *argv[]) +{ + pthread_t tid[MAX_THREADS]; + int num_threads; + int i; + + if ((num_threads = argc - 1) > MAX_THREADS) + num_threads = MAX_THREADS; + for (i = 0; i < num_threads; i++) + pthread_create(&tid[i], NULL, thread_function, argv[i+1]); + for (i = 0; i < num_threads; i++) + pthread_join(tid[i], NULL); + return (0); +} + +static void * +thread_function(void *arg) +{ + char *data; + + pthread_key_create_once_np(&tsd_key, cleanup); + data = malloc(strlen(arg) + 1); + strcpy(data, arg); + pthread_setspecific(tsd_key, data); + show_tsd(); + return (NULL); +} + +static void +show_tsd() +{ + void *tsd = pthread_getspecific(tsd_key); + + printf("tsd for %d = %s\en", pthread_self(), (char *)tsd); +} + +/* application-specific clean-up function */ +static void +cleanup(void *tsd) +{ + printf("freeing tsd for %d = %s\en", pthread_self(), (char *)tsd); + free(tsd); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted. +_ +MT-LevelMT-Safe +_ +StandardSee below. +.TE + +.sp +.LP +For \fBpthread_key_create()\fR, see \fBstandards\fR(5). +.SH SEE ALSO +.sp +.LP +\fBpthread_once\fR(3C), \fBpthread_getspecific\fR(3C), +\fBpthread_setspecific\fR(3C), \fBpthread_key_delete\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_key_delete.3c b/usr/src/man/man3c/pthread_key_delete.3c new file mode 100644 index 0000000000..571b50ce43 --- /dev/null +++ b/usr/src/man/man3c/pthread_key_delete.3c @@ -0,0 +1,88 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_key_delete 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_key_delete \- delete thread-specific data key +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_key_delete\fR(\fBpthread_key_t\fR \fIkey\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_key_delete()\fR function deletes a thread-specific data key +previously returned by \fBpthread_key_create()\fR. The thread-specific data +values associated with \fIkey\fR need not be \fINULL\fR at the time +\fBpthread_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 +\fBpthread_key_delete()\fR is called. Any attempt to use \fIkey\fR following +the call to \fBpthread_key_delete()\fR results in undefined behaviour. +.sp +.LP +The \fBpthread_key_delete()\fR function is callable from within destructor +functions. No destructor functions will be invoked by +\fBpthread_key_delete()\fR. Any destructor function that may have been +associated with \fIkey\fR will no longer be called upon thread exit. +.SH RETURN VALUES +.sp +.LP +If successful, the \fBpthread_key_delete()\fR function returns \fB0\fR. +Otherwise, an error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_key_delete()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIkey\fR value is invalid. +.RE + +.sp +.LP +The \fBpthread_key_delete()\fR function will not return an error code of +\fBEINTR\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_key_create\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_kill.3c b/usr/src/man/man3c/pthread_kill.3c new file mode 100644 index 0000000000..8f2ddd733d --- /dev/null +++ b/usr/src/man/man3c/pthread_kill.3c @@ -0,0 +1,91 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_kill 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_kill \- send a signal to a thread +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <signal.h> +#include <pthread.h> + +\fBint\fR \fBpthread_kill\fR(\fBpthread_t\fR \fIthread\fR, \fBint\fR \fIsig\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_kill()\fR function sends the \fIsig\fR signal to the thread +designated by thread. The \fIthread\fR argument must be a member of the same +process as the calling thread. The \fIsig\fR argument must be one of the +signals listed in \fBsignal.h\fR(3HEAD), with the exception of \fBSIGCANCEL\fR +being reserved and off limits to \fBpthread_kill()\fR. If \fIsig\fR is 0, a +validity check is performed for the existence of the target thread; no signal +is sent. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the function returns a value of \fB0\fR. Otherwise +the function returns an error number. If the \fBpthread_kill()\fR function +fails, no signal is sent. +.SH ERRORS +.sp +.LP +The \fBpthread_kill()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBESRCH\fR\fR +.ad +.RS 10n +.rt +No thread could be found corresponding to that specified by the given thread +\fBID.\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of the \fIsig\fR argument is an invalid or unsupported signal number. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBkill\fR(1), \fBpthread_self\fR(3C), \fBpthread_sigmask\fR(3C), +\fBraise\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_mutex_getprioceiling.3c b/usr/src/man/man3c/pthread_mutex_getprioceiling.3c new file mode 100644 index 0000000000..d29046a8d3 --- /dev/null +++ b/usr/src/man/man3c/pthread_mutex_getprioceiling.3c @@ -0,0 +1,152 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_mutex_getprioceiling 3C "1 Apr 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_mutex_getprioceiling, pthread_mutex_setprioceiling \- change priority +ceiling of a mutex +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_mutex_getprioceiling\fR(\fBconst pthread_mutex_t *restrict\fR \fImutex\fR, + \fBint *restrict\fR \fIprioceiling\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_mutex_setprioceiling\fR(\fBpthread_mutex_t *restrict\fR \fImutex\fR, + \fBint\fR \fIprioceiling\fR, \fBint *restrict\fR \fIold_ceiling\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_mutex_getprioceiling()\fR function returns the current priority +ceiling of the mutex. +.sp +.LP +The \fBpthread_mutex_setprioceiling()\fR function either locks the mutex if it +is unlocked, or blocks until it can successfully lock the mutex, then it +changes the mutex's priority ceiling and releases the mutex. When the change is +successful, the previous value of the priority ceiling is returned in +\fIold_ceiling\fR. The process of locking the mutex need not adhere to the +priority protect protocol. +.sp +.LP +If the \fBpthread_mutex_setprioceiling()\fR function fails, the mutex priority +ceiling is not changed. +.sp +.LP +The ceiling value should be drawn from the range of priorities for the +\fBSCHED_FIFO\fR policy. When a thread acquires such a mutex, the policy of the +thread at mutex acquisition should match that from which the ceiling value was +derived (\fBSCHED_FIFO\fR, in this case). If a thread changes its scheduling +policy while holding a ceiling mutex, the behavior of +\fBpthread_mutex_lock()\fR and \fBpthread_mutex_unlock()\fR on this mutex is +undefined. See \fBpthread_mutex_lock\fR(3C). +.sp +.LP +The ceiling value should not be treated as a persistent value resident in a +\fBpthread_mutex_t\fR that is valid across upgrades of Solaris. The semantics +of the actual ceiling value are determined by the existing priority range for +the \fBSCHED_FIFO\fR policy, as returned by the \fBsched_get_priority_min()\fR +and \fBsched_get_priority_max()\fR functions (see +\fBsched_get_priority_min\fR(3C)) when called on the version of Solaris on +which the ceiling value is being utilized. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBpthread_mutex_getprioceiling()\fR and +\fBpthread_mutex_setprioceiling()\fR functions return \fB0\fR. Otherwise, an +error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_mutex_getprioceiling()\fR and +\fBpthread_mutex_setprioceiling()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fImutex\fR does not refer to a currently existing +mutex. +.RE + +.sp +.LP +The \fBpthread_mutex_setprioceiling()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The mutex was not initialized with its \fIprotocol\fR attribute having the +value of \fBPTHREAD_PRIO_PROTECT\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The priority requested by \fIprioceiling\fR is out of range. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 10n +.rt +The caller does not have the privilege to perform the operation. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_mutex_init\fR(3C), \fBpthread_mutex_lock\fR(3C), +\fBsched_get_priority_min\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_mutex_init.3c b/usr/src/man/man3c/pthread_mutex_init.3c new file mode 100644 index 0000000000..1f0cd42d92 --- /dev/null +++ b/usr/src/man/man3c/pthread_mutex_init.3c @@ -0,0 +1,214 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_mutex_init 3C "11 Nov 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_mutex_init, pthread_mutex_destroy \- initialize or destroy a mutex +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_mutex_init\fR(\fBpthread_mutex_t *restrict\fR \fImutex\fR, + \fBconst pthread_mutexattr_t *restrict\fR \fIattr\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_mutex_destroy\fR(\fBpthread_mutex_t *\fR\fImutex\fR); +.fi + +.LP +.nf +\fBpthread_mutex_t\fR \fImutex\fR= \fBPTHREAD_MUTEX_INITIALIZER\fR; +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_mutex_init()\fR function initializes the mutex referenced by +\fImutex\fR with attributes specified by \fIattr\fR. If \fIattr\fR is +\fINULL\fR, the default mutex attributes are used; the effect is the same as +passing the address of a default mutex attributes object. Upon successful +initialization, the state of the mutex becomes initialized and unlocked. +.sp +.LP +Except for robust mutexes, attempting to initialize an already initialized +mutex results in undefined behavior. +.sp +.LP +The \fBpthread_mutex_destroy()\fR function destroys the mutex object referenced +by \fImutex\fR; the mutex object becomes, in effect, uninitialized. A destroyed +mutex object can be re-initialized using \fBpthread_mutex_init()\fR; the +results of otherwise referencing the object after it has been destroyed are +undefined. +.sp +.LP +It is safe to destroy an initialized mutex that is unlocked. Attempting to +destroy a locked mutex results in undefined behavior. +.sp +.LP +In cases where default mutex attributes are appropriate, the macro +\fBPTHREAD_MUTEX_INITIALIZER\fR can be used to initialize mutexes that are +statically allocated. The effect is equivalent to dynamic initialization by a +call to \fBpthread_mutex_init()\fR with parameter \fIattr\fR specified as +\fINULL\fR, except that no error checks are performed. +.SH RETURN VALUES +.sp +.LP +If successful, the \fBpthread_mutex_init()\fR and \fBpthread_mutex_destroy()\fR +functions return \fB0\fR. Otherwise, an error number is returned to indicate +the error. +.SH ERRORS +.sp +.LP +The \fBpthread_mutex_init()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +The system lacked the necessary resources (other than memory) to initialize +another mutex. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBUSY\fR\fR +.ad +.RS 10n +.rt +An attempt was detected to re-initialize a robust mutex previously initialized +but not yet destroyed. See \fBpthread_mutexattr_setrobust\fR(3C). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +An attempt was detected to re-initialize a robust mutex previously initialized +with a different set of attributes. See \fBpthread_mutexattr_setrobust\fR(3C). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient memory exists to initialize the mutex. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 10n +.rt +The caller does not have the privilege to perform the operation. +.RE + +.sp +.LP +The \fBpthread_mutex_init()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBUSY\fR\fR +.ad +.RS 10n +.rt +An attempt was detected to re-initialize the object referenced by \fImutex\fR, +a mutex previously initialized but not yet destroyed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIattr\fR or \fImutex\fR is invalid. +.RE + +.sp +.LP +The \fBpthread_mutex_destroy()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBUSY\fR\fR +.ad +.RS 10n +.rt +An attempt was detected to destroy the object referenced by \fImutex\fR while +it is locked or referenced (for example, while being used in a +\fBpthread_cond_wait\fR(3C) or \fBpthread_cond_timedwait\fR(3C)) by another +thread. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fImutex\fR is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_cond_wait\fR(3C), \fBpthread_mutex_lock\fR(3C), +\fBpthread_mutexattr_setprioceiling\fR(3C), +\fBpthread_mutexattr_setprotocol\fR(3C), +\fBpthread_mutexattr_setpshared\fR(3C), \fBpthread_mutexattr_setrobust\fR(3C), +\fBpthread_mutexattr_settype\fR(3C), \fBattributes\fR(5), \fBmutex\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_mutex_lock.3c b/usr/src/man/man3c/pthread_mutex_lock.3c new file mode 100644 index 0000000000..aa1fcb7449 --- /dev/null +++ b/usr/src/man/man3c/pthread_mutex_lock.3c @@ -0,0 +1,304 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_mutex_lock 3C "11 Nov 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_unlock \- lock or +unlock a mutex +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_mutex_lock\fR(\fBpthread_mutex_t *\fR\fImutex\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_mutex_trylock\fR(\fBpthread_mutex_t *\fR\fImutex\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_mutex_unlock\fR(\fBpthread_mutex_t *\fR\fImutex\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The mutex object referenced by mutex is locked by calling +\fBpthread_mutex_lock()\fR. If the mutex is already locked, the calling thread +blocks until the mutex becomes available. This operation returns with the mutex +object referenced by mutex in the locked state with the calling thread as its +owner. +.sp +.LP +If the mutex type is \fBPTHREAD_MUTEX_NORMAL\fR, deadlock detection is not +provided. Attempting to relock the mutex causes deadlock. If a thread attempts +to unlock a mutex that it has not locked or a mutex that is unlocked, undefined +behavior results. +.sp +.LP +If the mutex type is \fBPTHREAD_MUTEX_ERRORCHECK\fR, then error checking is +provided. If a thread attempts to relock a mutex that it has already locked, an +error will be returned. If a thread attempts to unlock a mutex that it has not +locked or a mutex which is unlocked, an error will be returned. +.sp +.LP +If the mutex type is \fBPTHREAD_MUTEX_RECURSIVE\fR, then the mutex maintains +the concept of a lock count. When a thread successfully acquires a mutex for +the first time, the lock count is set to 1. Every time a thread relocks this +mutex, the lock count is incremented by one. Each time the thread unlocks the +mutex, the lock count is decremented by one. When the lock count reaches +\fB0\fR, the mutex becomes available for other threads to acquire. If a thread +attempts to unlock a mutex that it has not locked or a mutex that is unlocked, +an error will be returned. +.sp +.LP +If the mutex type is \fBPTHREAD_MUTEX_DEFAULT\fR, attempting to recursively +lock the mutex results in undefined behavior. Attempting to unlock the mutex +if it was not locked by the calling thread results in undefined behavior. +Attempting to unlock the mutex if it is not locked results in undefined +behavior. +.sp +.LP +The \fBpthread_mutex_trylock()\fR function is identical to +\fBpthread_mutex_lock()\fR except that if the mutex object referenced by +\fImutex\fR is currently locked (by any thread, including the current thread), +the call fails immediately with \fBEBUSY\fR. +.sp +.LP +The \fBpthread_mutex_unlock()\fR function releases the mutex object referenced +by \fImutex\fR. 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 \fImutex\fR when \fBpthread_mutex_unlock()\fR is called, +resulting in the mutex becoming available, the scheduling policy is used to +determine which thread will acquire the mutex. (In the case of +\fBPTHREAD_MUTEX_RECURSIVE\fR mutexes, the mutex becomes available when the +count reaches \fB0\fR and the calling thread no longer has any locks on this +mutex.) +.sp +.LP +If a signal is delivered to a thread waiting for a mutex, upon return from the +signal handler the thread resumes waiting for the mutex as if it was not +interrupted. +.SH RETURN VALUES +.sp +.LP +If successful, the \fBpthread_mutex_lock()\fR and +\fBpthread_mutex_unlock()\fR functions return \fB0\fR. Otherwise, an error +number is returned to indicate the error. +.sp +.LP +The \fBpthread_mutex_trylock()\fR function returns \fB0\fR if a lock on the +mutex object referenced by \fImutex\fR is acquired. Otherwise, an error number +is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_mutex_lock()\fR and \fBpthread_mutex_trylock()\fR functions +will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +The mutex could not be acquired because the maximum number of recursive locks +for mutex has been exceeded. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fImutex\fR was created with the protocol attribute having the value +\fBPTHREAD_PRIO_PROTECT\fR and the calling thread's priority is higher than the +mutex's current priority ceiling. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 10n +.rt +The mutex was created with the protocol attribute having the value +\fBPTHREAD_PRIO_PROTECT\fR and the calling thread is not in the real-time class +(\fBSCHED_RR\fR or \fBSCHED_FIFO\fR scheduling class). +.RE + +.sp +.LP +The \fBpthread_mutex_trylock()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBUSY\fR\fR +.ad +.RS 9n +.rt +The \fImutex\fR could not be acquired because it was already locked. +.RE + +.sp +.LP +The \fBpthread_mutex_lock()\fR, \fBpthread_mutex_trylock()\fR and +\fBpthread_mutex_unlock()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fImutex\fR does not refer to an initialized mutex +object. +.RE + +.sp +.LP +The \fBpthread_mutex_lock()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEDEADLK\fR\fR +.ad +.RS 11n +.rt +The current thread already owns the mutex. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 11n +.rt +The limit on the number of simultaneously held mutexes has been exceeded. +.RE + +.sp +.LP +The \fBpthread_mutex_unlock()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 9n +.rt +The mutex type is PTHREAD_MUTEX_ERRORCHECK or the mutex is a robust mutex, and +the current thread does not own the mutex. +.RE + +.sp +.LP +When a thread makes a call to \fBpthread_mutex_lock()\fR or +\fBpthread_mutex_trylock()\fR, if the mutex is initialized with the robustness +attribute having the value \fBPTHREAD_MUTEX_ROBUST\fR (see +\fBpthread_mutexattr_getrobust\fR(3C)), the call will return these error values +if: +.sp +.ne 2 +.mk +.na +\fB\fBEOWNERDEAD\fR\fR +.ad +.RS 19n +.rt +The last owner of this mutex died while holding the mutex, or the process +containing the owner of the mutex unmapped the memory containing the mutex or +performed one of the \fBexec\fR(2) functions. This mutex is now owned by the +caller. The caller must now attempt to make the state protected by the mutex +consistent. If it is able to clean up the state, then it should call +\fBpthread_mutex_consistent()\fR for the mutex and unlock the mutex. Subsequent +calls to \fBpthread_mutex_lock()\fR and \fBpthread_mutex_trylock()\fR will +behave normally, as before. If the caller is not able to clean up the state, +\fBpthread_mutex_consistent()\fR should not be called for the mutex, but the +mutex should be unlocked. Subsequent calls to \fBpthread_mutex_lock()\fR and +\fBpthread_mutex_trylock()\fR will fail to acquire the mutex with the error +value \fBENOTRECOVERABLE\fR. If the owner who acquired the lock with +\fBEOWNERDEAD\fR dies, the next owner will acquire the lock with +\fBEOWNERDEAD\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTRECOVERABLE\fR\fR +.ad +.RS 19n +.rt +The mutex trying to be acquired was protecting the state that has been left +irrecoverable by the mutex's last owner. The mutex has not been acquired. This +condition can occur when the lock was previously acquired with +\fBEOWNERDEAD\fR, and the owner was not able to clean up the state and unlocked +the mutex without calling \fBpthread_mutex_consistent()\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_mutex_consistent\fR(3C), \fBpthread_mutex_init\fR(3C), +\fBpthread_mutexattr_setprotocol\fR(3C), \fBpthread_mutexattr_setrobust\fR(3C), +\fBpthread_mutexattr_settype\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +In the current implementation of threads, \fBpthread_mutex_lock()\fR, +\fBpthread_mutex_unlock()\fR, \fBmutex_lock()\fR, \fBmutex_unlock()\fR, +\fBpthread_mutex_trylock()\fR, and \fBmutex_trylock()\fR do not validate the +mutex type. Therefore, an uninitialized mutex or a mutex with an invalid type +does not return \fBEINVAL\fR. Interfaces for mutexes with an invalid type have +unspecified behavior. +.sp +.LP +Uninitialized mutexes that are allocated locally may contain junk data. Such +mutexes need to be initialized using \fBpthread_mutex_init()\fR or +\fBmutex_init()\fR. diff --git a/usr/src/man/man3c/pthread_mutex_timedlock.3c b/usr/src/man/man3c/pthread_mutex_timedlock.3c new file mode 100644 index 0000000000..8b8b851e8e --- /dev/null +++ b/usr/src/man/man3c/pthread_mutex_timedlock.3c @@ -0,0 +1,136 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_mutex_timedlock 3C "5 Jun 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_mutex_timedlock, pthread_mutex_reltimedlock_np \- lock a mutex +.SH SYNOPSIS +.LP +.nf +cc \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <pthread.h> +#include <time.h> + +\fBint\fR \fBpthread_mutex_timedlock\fR(\fBpthread_mutex_t *restrict\fR \fImutex\fR, + \fBconst struct timespec *restrict\fR \fIabs_timeout\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_mutex_reltimedlock_np\fR(\fBpthread_mutex_t *restrict\fR \fImutex\fR, + \fBconst struct timespec *restrict\fR \fIrel_timeout\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_mutex_timedlock()\fR function locks the mutex object referenced +by \fImutex\fR. If the mutex is already locked, the calling thread blocks until +the mutex becomes available as in the \fBpthread_mutex_lock\fR(3C). If the +mutex cannot be locked without waiting for another thread to unlock the mutex, +this wait is terminated when the specified timeout expires. +.sp +.LP +The \fBpthread_mutex_reltimedlock_np()\fR function is identical to the +\fBpthread_mutex_timedlock()\fR function, except that the timeout is specified +as a relative time interval. +.sp +.LP +For \fBpthread_mutex_timedlock()\fR, the timeout expires when the absolute time +specified by \fIabs_timeout\fR passes, as measured by the clock on which +timeouts are based (that is, when the value of that clock equals or exceeds +\fIabs_timeout\fR), or if the absolute time specified by \fIabs_timeout\fR has +already been passed at the time of the call. +.sp +.LP +For \fBpthread_mutex_reltimedlock_np()\fR, the timeout expires when the time +interval specified by \fIrel_timeout\fR passes, as measured by the +\fBCLOCK_REALTIME\fR clock, or if the time interval specified by +\fIrel_timeout\fR is negative at the time of the call. +.sp +.LP +The resolution of the timeout is the resolution of the \fBCLOCK_REALTIME\fR +clock. The \fBtimespec\fR data type is defined in the \fB<time.h>\fRheader. +.sp +.LP +Under no circumstance will either function fail with a timeout if the mutex can +be locked immediately. The validity of the \fItimeout\fR parameter is not +checked if the mutex can be locked immediately. +.sp +.LP +As a consequence of the priority inheritance rules (for mutexes initialized +with the \fBPRIO_INHERIT\fR protocol), if a timed mutex wait is terminated +because its timeout expires, the priority of the owner of the mutex is adjusted +as necessary to reflect the fact that this thread is no longer among the +threads waiting for the mutex. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBpthread_mutex_timedlock()\fR and +\fBpthread_mutex_reltimedlock_np()\fR functions return 0. Otherwise, an error +number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_mutex_timedlock()\fR and \fBpthread_mutex_reltimedlock_np()\fR +functions will fail for the same reasons as \fBpthread_mutex_lock\fR(3C). In +addition, they will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 13n +.rt +The caller would have blocked and the \fItimeout\fR parameter specified a +nanoseconds field value less than zero or greater than or equal to 1,000 +million. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBETIMEDOUT\fR\fR +.ad +.RS 13n +.rt +The mutex could not be locked before the specified \fItimeout\fR expired. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilitySee below. +_ +MT-LevelMT-Safe +.TE + +.sp +.LP +The \fBpthread_mutex_timedlock()\fR is Standard. The +\fBpthread_mutex_reltimedlock_np()\fR function is Stable. +.SH SEE ALSO +.sp +.LP +\fBtime\fR(2), \fBpthread_mutex_destroy\fR(3C), \fBpthread_mutex_lock\fR(3C), +\fBpthread_mutex_trylock\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_mutexattr_getprioceiling.3c b/usr/src/man/man3c/pthread_mutexattr_getprioceiling.3c new file mode 100644 index 0000000000..42333985ca --- /dev/null +++ b/usr/src/man/man3c/pthread_mutexattr_getprioceiling.3c @@ -0,0 +1,136 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_mutexattr_getprioceiling 3C "1 Apr 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_mutexattr_getprioceiling, pthread_mutexattr_setprioceiling \- get or +set prioceiling attribute of mutex attribute object +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_mutexattr_getprioceiling\fR( + \fBconst pthread_mutexattr_t *restrict\fR \fIattr\fR, + \fBint *restrict\fR \fIprioceiling\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_mutexattr_setprioceiling\fR(\fBpthread_mutexattr_t *\fR\fIattr\fR, + \fBint\fR \fIprioceiling\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_mutexattr_getprioceiling()\fR and +\fBpthread_mutexattr_setprioceiling()\fR functions, respectively, get and set +the priority ceiling attribute of a mutex attribute object pointed to by +\fIattr\fR, which was previously created by the \fBpthread_mutexattr_init()\fR +function. +.sp +.LP +The \fIprioceiling\fR attribute contains the priority ceiling of initialized +mutexes. The values of \fIprioceiling\fR must be within the range of priorities +defined by \fBSCHED_FIFO\fR. +.sp +.LP +The \fIprioceiling\fR 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 must be set to a priority higher than or equal to +the highest priority of all the threads that may lock that mutex. +.sp +.LP +The ceiling value should be drawn from the range of priorities for the +\fBSCHED_FIFO\fR policy. When a thread acquires such a mutex, the policy of the +thread at mutex acquisition should match that from which the ceiling value was +derived (\fBSCHED_FIFO\fR, in this case). If a thread changes its scheduling +policy while holding a ceiling mutex, the behavior of +\fBpthread_mutex_lock()\fR and \fBpthread_mutex_unlock()\fR on this mutex is +undefined. See \fBpthread_mutex_lock\fR(3C). +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBpthread_mutexattr_getprioceiling()\fR and +\fBpthread_mutexattr_setprioceiling()\fR functions return \fB0\fR. Otherwise, +an error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_mutexattr_setprioceiling()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIattr\fR is \fINULL\fR or \fIprioceiling\fR is +invalid. +.RE + +.sp +.LP +The \fBpthread_mutexattr_getprioceiling()\fR and +\fBpthread_mutexattr_setprioceiling()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIattr\fR or \fIprioceiling\fR is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 10n +.rt +The caller does not have the privilege to perform the operation. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_cond_init\fR(3C), \fBpthread_create\fR(3C), +\fBpthread_mutex_init\fR(3C), \fBpthread_mutex_lock\fR(3C), +\fBsched_get_priority_min\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_mutexattr_getprotocol.3c b/usr/src/man/man3c/pthread_mutexattr_getprotocol.3c new file mode 100644 index 0000000000..e888e8f757 --- /dev/null +++ b/usr/src/man/man3c/pthread_mutexattr_getprotocol.3c @@ -0,0 +1,213 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_mutexattr_getprotocol 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_mutexattr_getprotocol, pthread_mutexattr_setprotocol \- get or set +protocol attribute of mutex attribute object +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_mutexattr_getprotocol\fR( + \fBconst pthread_mutexattr_t *restrict\fR \fIattr\fR, + \fBint *restrict\fR \fIprotocol\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_mutexattr_setprotocol\fR(\fBpthread_mutexattr_t *\fR\fIattr\fR, + \fBint\fR \fIprotocol\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_mutexattr_setprotocol()\fR and +\fBpthread_mutexattr_getprotocol()\fR functions, respectively, set and get the +protocol attribute of a mutex attribute object pointed to by \fIattr\fR, which +was previously created by the \fBpthread_mutexattr_init()\fR function. +.sp +.LP +The \fIprotocol\fR attribute defines the protocol to be followed in utilizing +mutexes. The value of \fIprotocol\fR may be one of \fBPTHREAD_PRIO_NONE\fR, +\fBPTHREAD_PRIO_INHERIT\fR, or \fBPTHREAD_PRIO_PROTECT\fR, which are defined by +the header <\fBpthread.h\fR>. +.sp +.LP +When a thread owns a mutex with the \fBPTHREAD_PRIO_NONE\fR protocol +attribute, its priority and scheduling are not affected by its mutex ownership. +.sp +.LP +When a thread is blocking higher priority threads because of owning one or more +mutexes with the \fBPTHREAD_PRIO_INHERIT\fR protocol attribute, it executes at +the higher of its priority or the priority of the highest priority thread +waiting on any of the mutexes owned by this thread and initialized with this +protocol. +.sp +.LP +When a thread owns one or more mutexes initialized with the +\fBPTHREAD_PRIO_PROTECT\fR protocol, it executes at the higher of its priority +or the highest of the priority ceilings of all the mutexes owned by this thread +and initialized with this attribute, regardless of whether other threads are +blocked on any of these mutexes. +.sp +.LP +While a thread is holding a mutex that has been initialized with the +\fBPRIO_INHERIT\fR or \fBPRIO_PROTECT\fR protocol attributes, it will 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 +\fBsched_setparam()\fR. Likewise, when a thread unlocks a mutex that has been +initialized with the \fBPRIO_INHERIT\fR or \fBPRIO_PROTECT\fR protocol +attributes, it will 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. +.sp +.LP +If a thread simultaneously owns several mutexes initialized with different +protocols, it will execute at the highest of the priorities that it would have +obtained by each of these protocols. +.sp +.LP +If a thread makes a call to \fBpthread_mutex_lock()\fR for a mutex that was +initialized with the protocol attribute \fBPTHREAD_PRIO_INHERIT\fR, and if the +calling thread becomes blocked because the mutex is owned by another thread, +then the owner thread inherits the priority level of the calling thread for as +long as it continues to own the mutex. The implementation updates its execution +priority to the maximum of its assigned priority and all its inherited +priorities. Furthermore, if this owner thread becomes blocked on another mutex, +the same priority inheritance effect will be propagated to the other owner +thread, in a recursive manner. +.sp +.LP +A thread that uses mutexes initialized with the \fBPTHREAD_PRIO_INHERIT\fR or +\fBPTHREAD_PRIO_PROTECT\fR \fIprotocol\fR attribute values should have its +scheduling policy equal to \fBSCHED_FIFO or SCHED_RR\fR (see +\fBpthread_attr_getschedparam\fR(3C) and \fBpthread_getschedparam\fR(3C)). +.sp +.LP +If a thread with scheduling policy equal to \fBSCHED_OTHER\fR uses a mutex +initialized with the \fBPTHREAD_PRIO_INHERIT\fR or \fBPTHREAD_PRIO_PROTECT\fR +\fIprotocol\fR attribute value, the effect on the thread's scheduling and +priority is unspecified. +.sp +.LP +The \fB_POSIX_THREAD_PRIO_INHERIT\fR and \fB_POSIX_THREAD_PRIO_PROTECT\fR +options are designed to provide features to solve priority inversion due to +mutexes. A priority inheritance or priority ceiling mutex is designed to +minimize the dispatch latency of a high priority thread when a low priority +thread is holding a mutex required by the high priority thread. This is a +specific need for the realtime application domain. +.sp +.LP +Threads created by realtime applications need to be such that their priorities +can influence their access to system resources (\fBCPU\fR resources, at least), +in competition with all threads running on the system. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBpthread_mutexattr_getprotocol()\fR and +\fBpthread_mutexattr_setprotocol()\fR functions return \fB0\fR. Otherwise, an +error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_mutexattr_getprotocol()\fR and +\fBpthread_mutexattr_setprotocol()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 11n +.rt +The value specified by \fIattr\fR is \fINULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR\fR +.ad +.RS 11n +.rt +Neither of the options \fB_POSIX_THREAD_PRIO_PROTECT\fR and +\fB_POSIX_THREAD_PRIO_INHERIT\fR is defined and the system does not support the +function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSUP\fR\fR +.ad +.RS 11n +.rt +The value specified by \fIprotocol\fR is an unsupported value. +.RE + +.sp +.LP +The \fBpthread_mutexattr_getprotocol()\fR and +\fBpthread_mutexattr_setprotocol()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIattr\fR or \fIprotocol\fR is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 10n +.rt +The caller does not have the privilege to perform the operation. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_attr_getschedparam\fR(3C), \fBpthread_mutex_init\fR(3C), +\fBpthread_mutexattr_init\fR(3C), \fBsched_setparam\fR(3C), +\fBsched_setscheduler\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_mutexattr_getpshared.3c b/usr/src/man/man3c/pthread_mutexattr_getpshared.3c new file mode 100644 index 0000000000..2b0e522e65 --- /dev/null +++ b/usr/src/man/man3c/pthread_mutexattr_getpshared.3c @@ -0,0 +1,118 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_mutexattr_getpshared 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_mutexattr_getpshared, pthread_mutexattr_setpshared \- get or set +process-shared attribute +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_mutexattr_getpshared\fR( + \fBconst pthread_mutexattr_t *restrict\fR \fIattr\fR, + \fBint *restrict\fR \fIpshared\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_mutexattr_setpshared\fR(\fBpthread_mutexattr_t *\fR\fIattr\fR, + \fBint\fR \fIpshared\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_mutexattr_getpshared()\fR function obtains the value of the +\fIprocess-shared\fR attribute from the attributes object referenced by +\fIattr\fR. The \fBpthread_mutexattr_setpshared()\fR function is used to set +the \fIprocess-shared\fR attribute in an initialized attributes object +referenced by \fIattr\fR. +.sp +.LP +The \fIprocess-shared\fR attribute is set to \fBPTHREAD_PROCESS_SHARED\fR 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 \fIprocess-shared\fR attribute is +\fBPTHREAD_PROCESS_PRIVATE\fR, the mutex will 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 is +\fBPTHREAD_PROCESS_PRIVATE\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBpthread_mutexattr_getpshared()\fR returns +\fB0\fR and stores the value of the \fIprocess-shared\fR attribute of +\fIattr\fR into the object referenced by the \fIpshared\fR parameter. +Otherwise, an error number is returned to indicate the error. +.sp +.LP +Upon successful completion, \fBpthread_mutexattr_setpshared()\fR returns +\fB0\fR. Otherwise, an error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_mutexattr_getpshared()\fR and +\fBpthread_mutexattr_setpshared()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIattr\fR is invalid. +.RE + +.sp +.LP +The \fBpthread_mutexattr_setpshared()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The new value specified for the attribute is outside the range of legal values +for that attribute. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_create\fR(3C), \fBpthread_mutex_init\fR(3C), +\fBpthread_mutexattr_init\fR(3C), \fBpthread_cond_init\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_mutexattr_gettype.3c b/usr/src/man/man3c/pthread_mutexattr_gettype.3c new file mode 100644 index 0000000000..79d1379b28 --- /dev/null +++ b/usr/src/man/man3c/pthread_mutexattr_gettype.3c @@ -0,0 +1,176 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_mutexattr_gettype 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_mutexattr_gettype, pthread_mutexattr_settype \- get or set mutex type +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_mutexattr_gettype\fR(\fBpthread_mutexattr_t *restrict\fR \fIattr\fR, + \fBint *restrict\fR \fItype\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_mutexattr_settype\fR(\fBpthread_mutexattr_t *\fR\fIattr\fR, \fBint\fR \fItype\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_mutexattr_gettype()\fR and \fBpthread_mutexattr_settype()\fR +functions respectively get and set the mutex \fItype\fR attribute. This +attribute is set in the \fItype\fR parameter to these functions. The default +value of the \fItype\fR attribute is \fBPTHREAD_MUTEX_DEFAULT\fR. +.sp +.LP +The type of mutex is contained in the \fItype\fR attribute of the mutex +attributes. Valid mutex types include: +.sp +.ne 2 +.mk +.na +\fB\fBPTHREAD_MUTEX_NORMAL\fR\fR +.ad +.RS 28n +.rt +This type of mutex does not detect deadlock. A thread attempting to relock this +mutex without first unlocking it will deadlock. Attempting to unlock a mutex +locked by a different thread results in undefined behavior. Attempting to +unlock an unlocked mutex results in undefined behavior. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPTHREAD_MUTEX_ERRORCHECK\fR\fR +.ad +.RS 28n +.rt +This type of mutex provides error checking. A thread attempting to relock this +mutex without first unlocking it will return with an error. A thread attempting +to unlock a mutex that another thread has locked will return with an error. A +thread attempting to unlock an unlocked mutex will return with an error. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPTHREAD_MUTEX_RECURSIVE\fR\fR +.ad +.RS 28n +.rt +A thread attempting to relock this mutex without first unlocking it will +succeed in locking the mutex. The relocking deadlock that can occur with +mutexes of type \fBPTHREAD_MUTEX_NORMAL\fR cannot occur with this type of +mutex. Multiple locks of this mutex require the same number of unlocks to +release the mutex before another thread can acquire the mutex. A thread +attempting to unlock a mutex that another thread has locked will return with an +error. A thread attempting to unlock an unlocked mutex will return with an +error. This type of mutex is only supported for mutexes whose process shared +attribute is \fBPTHREAD_PROCESS_PRIVATE\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPTHREAD_MUTEX_DEFAULT\fR\fR +.ad +.RS 28n +.rt +Attempting to recursively lock a mutex of this type results in undefined +behavior. Attempting to unlock a mutex of this type that was not locked by the +calling thread results in undefined behavior. Attempting to unlock a mutex of +this type that is not locked results in undefined behavior. An implementation +is allowed to map this mutex to one of the other mutex types. +.RE + +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBpthread_mutexattr_settype()\fR function +returns \fB0\fR. Otherwise, an error number is returned to indicate the error. +.sp +.LP +Upon successful completion, the \fBpthread_mutexattr_gettype()\fR function +returns \fB0\fR and stores the value of the \fItype\fR attribute of \fIattr\fR +in the object referenced by the \fItype\fR parameter. Otherwise an error number +is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_mutexattr_gettype()\fR and \fBpthread_mutexattr_settype()\fR +functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value \fBtype\fR is invalid. +.RE + +.sp +.LP +The \fBpthread_mutexattr_gettype()\fR and \fBpthread_mutexattr_settype()\fR +functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIattr\fR is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_cond_timedwait\fR(3C), \fBpthread_cond_wait\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +Application should not use a \fBPTHREAD_MUTEX_RECURSIVE\fR mutex with condition +variables because the implicit unlock performed for \fBpthread_cond_wait()\fR +or \fBpthread_cond_timedwait()\fR will not actually release the mutex (if it +had been locked multiple times). If this occurs, no other thread can satisfy +the condition of the predicate. diff --git a/usr/src/man/man3c/pthread_mutexattr_init.3c b/usr/src/man/man3c/pthread_mutexattr_init.3c new file mode 100644 index 0000000000..6849148304 --- /dev/null +++ b/usr/src/man/man3c/pthread_mutexattr_init.3c @@ -0,0 +1,112 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_mutexattr_init 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_mutexattr_init, pthread_mutexattr_destroy \- initialize or destroy +mutex attributes object +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_mutexattr_init\fR(\fBpthread_mutexattr_t *\fR\fIattr\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_mutexattr_destroy\fR(\fBpthread_mutexattr_t *\fR\fIattr\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_mutexattr_init()\fR function initializes a mutex attributes +object \fIattr\fR with the default value for all of the attributes defined by +the implementation. +.sp +.LP +The effect of initializing an already initialized mutex attributes object is +undefined. +.sp +.LP +After a mutex attributes object has been used to initialize one or more +mutexes, any function affecting the attributes object (including destruction) +does not affect any previously initialized mutexes. +.sp +.LP +The \fBpthread_mutexattr_destroy()\fR function destroys a mutex attributes +object; the object becomes, in effect, uninitialized. An implementation may +cause \fBpthread_mutexattr_destroy()\fR to set the object referenced by +\fIattr\fR to an invalid value. A destroyed mutex attributes object can be +re-initialized using \fBpthread_mutexattr_init()\fR; the results of otherwise +referencing the object after it has been destroyed are undefined. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBpthread_mutexattr_init()\fR and +\fBpthread_mutexattr_destroy()\fR return \fB0\fR. Otherwise, an error number is +returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_mutexattr_init()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient memory exists to initialize the mutex attributes object. +.RE + +.sp +.LP +The \fBpthread_mutexattr_destroy()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIattr\fR is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_cond_init\fR(3C), \fBpthread_create\fR(3C), +\fBpthread_mutex_init\fR(3C), \fBpthread_mutexattr_settype\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_once.3c b/usr/src/man/man3c/pthread_once.3c new file mode 100644 index 0000000000..606c697cc0 --- /dev/null +++ b/usr/src/man/man3c/pthread_once.3c @@ -0,0 +1,92 @@ +'\" te +.\" Copyright (c) 1995 IEEE. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2005, Sun Microsystems, Inc. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_once 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_once \- initialize dynamic package +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] + +#include <pthread.h> +\fBpthread_once_t\fR \fIonce_control\fR = \fBPTHREAD_ONCE_INIT\fR; + +\fBint\fR \fBpthread_once\fR(\fBpthread_once_t *\fR\fIonce_control\fR, + \fBvoid (*\fR\fIinit_routine\fR)(\fBvoid\fR)); +.fi + +.SH DESCRIPTION +.sp +.LP +If any thread in a process with a \fIonce_control\fR parameter makes a call to +\fBpthread_once()\fR, the first call will summon the \fBinit_routine()\fR, but +subsequent calls will not. The \fIonce_control\fR parameter determines whether +the associated initialization routine has been called. The \fBinit_routine()\fR +is complete upon return of \fBpthread_once()\fR. +.sp +.LP +\fBpthread_once()\fR is not a cancellation point; however, if the function +\fBinit_routine()\fR is a cancellation point and is canceled, the effect on +\fIonce_control\fR is the same as if \fBpthread_once()\fR had never been +called. +.sp +.LP +The constant \fBPTHREAD_ONCE_INIT\fR is defined in the \fB<pthread.h>\fR +header. +.sp +.LP +If \fIonce_control\fR has automatic storage duration or is not initialized by +\fBPTHREAD_ONCE_INIT\fR, the behavior of \fBpthread_once()\fR is undefined. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBpthread_once()\fR returns \fB0\fR. Otherwise, an +error number is returned to indicate the error. +.SH ERRORS +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR \fR +.ad +.RS 11n +.rt +\fIonce_control\fR or \fIinit_routine\fR is \fINULL\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +Solaris threads do not offer this functionality. diff --git a/usr/src/man/man3c/pthread_rwlock_init.3c b/usr/src/man/man3c/pthread_rwlock_init.3c new file mode 100644 index 0000000000..4296d5e072 --- /dev/null +++ b/usr/src/man/man3c/pthread_rwlock_init.3c @@ -0,0 +1,130 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_rwlock_init 3C "23 mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_rwlock_init, pthread_rwlock_destroy \- initialize or destroy read-write +lock object +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_rwlock_init\fR(\fBpthread_rwlock_t *restrict\fR \fIrwlock\fR, + \fBconst pthread_rwlockattr_t *restrict\fR \fIattr\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_rwlock_destroy\fR(\fBpthread_rwlock_t *\fR\fI*rwlock\fR); +.fi + +.LP +.nf +\fBpthread_rwlock_t\fR \fIrwlock\fR=\fBPTHREAD_RWLOCK_INITIALIZER\fR; +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_rwlock_init()\fR function initializes the read-write lock +referenced by \fIrwlock\fR with the attributes referenced by \fIattr\fR. If +\fIattr\fR is NULL, the default read-write lock attributes are 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 re-initialized. Upon successful initialization, the state of the +read-write lock becomes initialized and unlocked. Results are undefined if +\fBpthread_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. +.sp +.LP +If the \fBpthread_rwlock_init()\fR function fails, \fIrwlock\fR is not +initialized and the contents of \fIrwlock\fR are undefined. +.sp +.LP +The \fBpthread_rwlock_destroy()\fR function destroys the read-write lock object +referenced by \fIrwlock\fR and releases any resources used by the lock. The +effect of subsequent use of the lock is undefined until the lock is +re-initialized by another call to \fBpthread_rwlock_init()\fR. An +implementation may cause \fBpthread_rwlock_destroy()\fR to set the object +referenced by \fIrwlock\fR to an invalid value. Results are undefined if +\fBpthread_rwlock_destroy()\fR is called when any thread holds \fIrwlock\fR. +Attempting to destroy an uninitialized read-write lock results in undefined +behaviour. A destroyed read-write lock object can be re-initialized using +\fBpthread_rwlock_init()\fR; the results of otherwise referencing the +read-write lock object after it has been destroyed are undefined. +.sp +.LP +In cases where default read-write lock attributes are appropriate, the macro +\fBPTHREAD_RWLOCK_INITIALIZER\fR can be used to initialize read-write locks +that are statically allocated. The effect is equivalent to dynamic +initialization by a call to \fBpthread_rwlock_init()\fR with the parameter +\fIattr\fR specified as NULL, except that no error checks are performed. +.SH RETURN VALUES +.sp +.LP +If successful, the \fBpthread_rwlock_init()\fR and +\fBpthread_rwlock_destroy()\fR functions return \fB0\fR. Otherwise, an error +number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_rwlock_init()\fR and \fBpthread_rwlock_destroy()\fR functions +will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIattr\fR is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIrwlock\fR is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_rwlock_rdlock\fR(3C), \fBpthread_rwlock_unlock\fR(3C), +\fBpthread_rwlock_wrlock\fR(3C), \fBpthread_rwlockattr_init\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_rwlock_rdlock.3c b/usr/src/man/man3c/pthread_rwlock_rdlock.3c new file mode 100644 index 0000000000..0d4e7de778 --- /dev/null +++ b/usr/src/man/man3c/pthread_rwlock_rdlock.3c @@ -0,0 +1,152 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_rwlock_rdlock 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_rwlock_rdlock, pthread_rwlock_tryrdlock \- lock or attempt to lock +read-write lock object for reading +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_rwlock_rdlock\fR(\fBpthread_rwlock_t\fR \fI*rwlock\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_rwlock_tryrdlock\fR(\fBpthread_rwlock_t\fR \fI*rwlock\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_rwlock_rdlock()\fR function applies a read lock to the +read-write lock referenced by \fIrwlock\fR. The calling thread acquires the +read lock if a writer does not hold the lock and there are no writers blocked +on the lock. +.sp +.LP +The calling thread does 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 acquires the lock. If the read lock is not acquired, the calling +thread blocks until it can acquire the lock. +.sp +.LP +A thread can hold multiple concurrent read locks on \fIrwlock\fR (that is, +successfully call the \fBpthread_rwlock_rdlock()\fR function \fIn\fR times). If +so, the thread must perform matching unlocks (that is, it must call the +\fBpthread_rwlock_unlock()\fR function \fIn\fR times). +.sp +.LP +The maximum number of concurrent read locks that a thread can hold on one +read-write lock is currently set at 100,000, though this number could change in +a future release. There is no imposed limit on the number of different threads +that can apply a read lock to one read-write lock. +.sp +.LP +The \fBpthread_rwlock_tryrdlock()\fR function applies a read lock like the +\fBpthread_rwlock_rdlock()\fR function, with the exception that the function +fails if the equivalent \fBpthread_rwlock_rdlock()\fR call would have blocked +the calling thread. In no case will the \fBpthread_rwlock_tryrdlock()\fR +function ever bloc. It always either acquires the lock or fails and returns +immediately. +.sp +.LP +Results are undefined if any of these functions are called with an +uninitialized read-write lock. +.sp +.LP +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 VALUES +.sp +.LP +If successful, the \fBpthread_rwlock_rdlock()\fR function returns \fB0\fR. +Otherwise, an error number is returned to indicate the error. +.sp +.LP +The \fBpthread_rwlock_tryrdlock()\fR function returns \fB0\fR if the lock for +reading on the read-write lock object referenced by \fIrwlock\fR is acquired. +Otherwise an error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_rwlock_rdlock()\fR and \fBpthread_rwlock_tryrdlock()\fR +functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +The read lock could not be acquired because the maximum number of read locks by +the current thread for \fIrwlock\fR has been exceeded. +.RE + +.sp +.LP +The \fBpthread_rwlock_rdlock()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEDEADLK\fR\fR +.ad +.RS 11n +.rt +The current thread already owns the read-write lock for writing. +.RE + +.sp +.LP +The \fBpthread_rwlock_tryrdlock()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBUSY\fR\fR +.ad +.RS 9n +.rt +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. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_rwlock_init\fR(3C), \fBpthread_rwlock_wrlock\fR(3C), +\fBpthread_rwlockattr_init\fR(3C), \fBpthread_rwlock_unlock\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_rwlock_timedrdlock.3c b/usr/src/man/man3c/pthread_rwlock_timedrdlock.3c new file mode 100644 index 0000000000..cc55b6ea76 --- /dev/null +++ b/usr/src/man/man3c/pthread_rwlock_timedrdlock.3c @@ -0,0 +1,166 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_rwlock_timedrdlock 3C "30 Jan 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_rwlock_timedrdlock, pthread_rwlock_reltimedrdlock_np \- lock a +read-write lock for reading +.SH SYNOPSIS +.LP +.nf +cc \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <pthread.h> +#include <time.h> + +\fBint\fR \fBpthread_rwlock_timedrdlock\fR(\fBpthread_rwlock_t *restrict\fR \fIrwlock\fR, + \fBconst struct timespec *restrict\fR \fIabs_timeout\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_rwlock_reltimedrdlock_np\fR(\fBpthread_rwlock_t *restrict\fR \fIrwlock\fR, + \fBconst struct timespec *restrict\fR \fIrel_timeout\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_rwlock_timedrdlock()\fR function applies a read lock to the +read-write lock referenced by \fIrwlock\fR as in the +\fBpthread_rwlock_rdlock\fR(3C) function. If the lock cannot be acquired +without waiting for other threads to unlock the lock, this wait will be +terminated when the specified timeout expires. The timeout expires when the +absolute time specified by \fIabs_timeout\fR passes, as measured by the +\fBCLOCK_REALTIME clock\fR (that is, when the value of that clock equals or +exceeds \fIabs_timeout\fR), or if the absolute time specified by +\fIabs_timeout\fR has already been passed at the time of the call. +.sp +.LP +The \fBpthread_rwlock_reltimedrdlock_np()\fR function is identical to the +\fBpthread_rwlock_timedrdlock()\fR function, except that the timeout is +specified as a relative time interval. The timeout expires when the time +interval specified by \fIrel_timeout\fR passes, as measured by the +\fBCLOCK_REALTIME\fR clock, or if the time interval specified by +\fIrel_timeout\fR is negative at the time of the call. +.sp +.LP +The resolution of the timeout is the resolution of the \fBCLOCK_REALTIME\fR +clock. The \fBtimespec\fR data type is defined in the <\fBtime.h\fR> header. +Under no circumstances does either function fail with a timeout if the lock can +be acquired immediately. The validity of the timeout parameter need not be +checked if the lock can be immediately acquired. +.sp +.LP +If a signal that causes a signal handler to be executed is delivered to a +thread blocked on a read-write lock with a call to +\fBpthread_rwlock_timedrdlock()\fR or \fBpthread_rwlock_reltimedrdlock_np()\fR, +upon return from the signal handler the thread resumes waiting for the lock as +if it was not interrupted. +.sp +.LP +The calling thread might deadlock if at the time the call is made it holds a +write lock on rwlock. +.sp +.LP +The results are undefined if this function is called with an uninitialized +read-write lock. +.SH RETURN VALUES +.sp +.LP +The \fBpthread_rwlock_timedrdlock()\fR and +\fBpthread_rwlock_reltimedrdlock_np()\fR functions return 0 if the lock for +reading on the read-write lock object referenced by \fIrwlock\fR is acquired. +Otherwise, an error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_rwlock_timedrdlock()\fR and and +\fBpthread_rwlock_reltimedrdlock_np()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBETIMEDOUT\fR\fR +.ad +.RS 13n +.rt + The lock could not be acquired before the specified timeout expired. +.RE + +.sp +.LP +The \fBpthread_rwlock_timedrdlock()\fR and +\fBpthread_rwlock_reltimedrdlock_np()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 11n +.rt +The read lock could not be acquired because the maximum number of read locks +for lock would be exceeded. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEDEADLK\fR\fR +.ad +.RS 11n +.rt +The calling thread already holds a write lock on \fIrwlock\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 11n +.rt +The value specified by \fIrwlock\fR does not refer to an initialized read-write +lock object, or the timeout nanosecond value is less than zero or greater than +or equal to 1 000 million. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilitySee below. +_ +MT-LevelMT-Safe +.TE + +.sp +.LP +The \fBpthread_rwlock_timedrdlock()\fR function is Standard. The +\fBpthread_rwlock_reltimedrdlock_np()\fR is Stable. +.SH SEE ALSO +.sp +.LP +\fBpthread_rwlock_destroy\fR(3C), \fBpthread_rwlock_rdlock\fR(3C), +\fBpthread_rwlock_timedwrlock\fR(3C), \fBpthread_rwlock_trywrlock\fR(3C), +\fBpthread_rwlock_unlock\fR(3C), \fBpthread_rwlock_wrlock\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_rwlock_timedwrlock.3c b/usr/src/man/man3c/pthread_rwlock_timedwrlock.3c new file mode 100644 index 0000000000..73f055325e --- /dev/null +++ b/usr/src/man/man3c/pthread_rwlock_timedwrlock.3c @@ -0,0 +1,151 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_rwlock_timedwrlock 3C "30 Jan 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_rwlock_timedwrlock, pthread_rwlock_reltimedwrlock_np \- lock a +read-write lock for writing +.SH SYNOPSIS +.LP +.nf +cc \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <pthread.h> +#include <time.h> + +\fBint\fR \fBpthread_rwlock_timedwrlock\fR(\fBpthread_rwlock_t *restrict\fR \fIrwlock\fR, + \fBconst struct timespec *restrict\fR \fIabs_timeout\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_rwlock_reltimedwrlock_np\fR(\fBpthread_rwlock_t *restrict\fR \fIrwlock\fR, + \fBconst struct timespec *restrict\fR \fIrel_timeout\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_rwlock_timedwrlock()\fR function applies a write lock to the +read-write lock referenced by \fIrwlock\fR as in the +\fBpthread_rwlock_wrlock\fR(3C) function. If the lock cannot be acquired +without waiting for other threads to unlock the lock, this wait will be +terminated when the specified timeout expires. The timeout expires when the +absolute time specified by \fIabs_timeout\fR passes, as measured by the +\fBCLOCK_REALTIME\fR clock (that is, when the value of that clock equals or +exceeds \fIabs_timeout\fR), or if the absolute time specified by +\fIabs_timeout\fR has already been passed at the time of the call. +.sp +.LP +The \fBpthread_rwlock_reltimedwrlock_np()\fR function is identical to the +\fBpthread_rwlock_timedwrlock()\fR function, except that the timeout is +specified as a relative time interval. The timeout expires when the time +interval specified by \fIrel_timeout\fR passes, as measured by the +\fBCLOCK_REALTIME\fR clock, or if the time interval specified by +\fIrel_timeout\fR is negative at the time of the call. +.sp +.LP +The resolution of the timeout is the resolution of the \fBCLOCK_REALTIME\fR +clock. The \fBtimespec\fR data type is defined in the <\fBtime.h\fR> header. +Under no circumstances does either function fail with a timeout if the lock can +be acquired immediately. The validity of the a\fIbs_timeout\fR parameter need +not be checked if the lock can be immediately acquired. +.sp +.LP +If a signal that causes a signal handler to be executed is delivered to a +thread blocked on a read- write lock with a call to +\fBpthread_rwlock_timedwrlock()\fR or \fBpthread_rwlock_reltimedwrlock_np()\fR, +upon return from the signal handler the thread resumes waiting for the lock as +if it was not interrupted. +.sp +.LP +The calling thread can 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 VALUES +.sp +.LP +The \fBpthread_rwlock_timedwrlock()\fR and +\fBpthread_rwlock_reltimedwrlock_np()\fR functions return 0 if the lock for +writing on the read-write lock object referenced by \fIrwlock\fR is acquired. +Otherwise, an error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_rwlock_timedwrlock()\fR and +\fBpthread_rwlock_reltimedwrlock_np()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBETIMEDOUT\fR\fR +.ad +.RS 13n +.rt +The lock could not be acquired before the specified timeout expired. +.RE + +.sp +.LP +The \fBpthread_rwlock_timedwrlock()\fR and +\fBpthread_rwlock_reltimedwrlock_np()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEDEADLK\fR\fR +.ad +.RS 11n +.rt +The calling thread already holds the rwlock. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 11n +.rt +The value specified by \fIrwlock\fR does not refer to an initialized read-write +lock object, or the timeout nanosecond value is less than zero or greater than +or equal to 1,000 million. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilitySee below. +_ +MT-LevelMT-Safe +.TE + +.sp +.LP +The \fBpthread_rwlock_timedwrlock()\fR function is Standard. The +\fBpthread_rwlock_reltimedwrlock_np()\fR function is Stable. +.SH SEE ALSO +.sp +.LP +\fBpthread_rwlock_destroy\fR(3C), \fBpthread_rwlock_rdlock\fR(3C), +\fBpthread_rwlock_timedrdlock\fR(3C), \fBpthread_rwlock_trywrlock\fR(3C), +\fBpthread_rwlock_unlock\fR(3C), \fBpthread_rwlock_wrlock\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_rwlock_unlock.3c b/usr/src/man/man3c/pthread_rwlock_unlock.3c new file mode 100644 index 0000000000..aa75954ede --- /dev/null +++ b/usr/src/man/man3c/pthread_rwlock_unlock.3c @@ -0,0 +1,89 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright (c) 1997, The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_rwlock_unlock 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_rwlock_unlock \- unlock read-write lock object +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_rwlock_unlock\fR(\fBpthread_rwlock_t\fR \fI*rwlock\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_rwlock_unlock()\fR function is called to release a lock held on +the read-write lock object referenced by \fIrwlock\fR. Results are undefined if +the read-write lock \fIrwlock\fR is not held by the calling thread. +.sp +.LP +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 calling thread's last read lock on this read-write lock +object, then the calling thread is no longer one of the owners of the object. +If this function releases the last read lock for this read-write lock object, +the read-write lock object will be put in the unlocked state with no owners. +.sp +.LP +If this function is called to release a write lock for this read-write lock +object, the read-write lock object will be put in the unlocked state with no +owners. +.sp +.LP +If the call to the \fBpthread_rwlock_unlock()\fR function results in the +read-write lock object becoming unlocked and there are multiple threads waiting +to acquire the read-write lock object for writing, the scheduling policy is +used to determine which thread acquires the read-write lock object for writing. +If there are multiple threads waiting to acquire the read-write lock object for +reading, the scheduling policy is used to determine the order in which the +waiting threads acquire the read-write lock object for reading. If there are +multiple threads blocked on \fIrwlock\fR for both read locks and write locks, +it is unspecified whether the readers acquire the lock first or whether a +writer acquires the lock first. +.sp +.LP +Results are undefined if any of these functions are called with an +uninitialized read-write lock. +.SH RETURN VALUES +.sp +.LP +If successful, the \fBpthread_rwlock_unlock()\fR function returns \fB0\fR. +Otherwise, an error number is returned to indicate the error. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_rwlock_init\fR(3C), \fBpthread_rwlock_rdlock\fR(3C), +\fBpthread_rwlock_wrlock\fR(3C), \fBpthread_rwlockattr_init\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_rwlock_wrlock.3c b/usr/src/man/man3c/pthread_rwlock_wrlock.3c new file mode 100644 index 0000000000..fa0e756fca --- /dev/null +++ b/usr/src/man/man3c/pthread_rwlock_wrlock.3c @@ -0,0 +1,119 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_rwlock_wrlock 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_rwlock_wrlock, pthread_rwlock_trywrlock \- lock or attempt to lock +read-write lock object for writing +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_rwlock_wrlock\fR(\fBpthread_rwlock_t\fR \fI*rwlock\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_rwlock_trywrlock\fR(\fBpthread_rwlock_t\fR \fI*rwlock\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_rwlock_wrlock()\fR function applies a write lock to the +read-write lock referenced by \fIrwlock\fR. The calling thread acquires the +write lock if no other thread (reader or writer) holds the read-write lock +\fIrwlock\fR. Otherwise, the thread blocks until it can acquire the lock. +.sp +.LP +The \fBpthread_rwlock_trywrlock()\fR function applies a write lock like the +\fBpthread_rwlock_wrlock()\fR function, with the exception that the function +fails if any thread currently holds \fIrwlock\fR (for reading or writing). +.sp +.LP +Writers are favored over readers of the same priority to avoid writer +starvation. See \fBpthread_rwlock_rdlock\fR(3C). +.sp +.LP +Results are undefined if any of these functions are called with an +uninitialized read-write lock. +.sp +.LP +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 VALUES +.sp +.LP +If successful, the \fBpthread_rwlock_wrlock()\fR function returns \fB0\fR. +Otherwise, an error number is returned to indicate the error. +.sp +.LP +The \fBpthread_rwlock_trywrlock()\fR function returns \fB0\fR if the lock for +writing on the read-write lock object referenced by \fIrwlock\fR is acquired. +Otherwise an error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_rwlock_wrlock()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEDEADLK\fR\fR +.ad +.RS 11n +.rt +The current thread already owns the read-write lock for writing or reading. +.RE + +.sp +.LP +The \fBpthread_rwlock_trywrlock()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBUSY\fR\fR +.ad +.RS 9n +.rt +The read-write lock could not be acquired for writing because it was already +locked for reading or writing. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_rwlock_init\fR(3C), \fBpthread_rwlock_unlock\fR(3C), +\fBpthread_rwlockattr_init\fR(3C), \fBpthread_rwlock_rdlock\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_rwlockattr_getpshared.3c b/usr/src/man/man3c/pthread_rwlockattr_getpshared.3c new file mode 100644 index 0000000000..124d264b1f --- /dev/null +++ b/usr/src/man/man3c/pthread_rwlockattr_getpshared.3c @@ -0,0 +1,104 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_rwlockattr_getpshared 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_rwlockattr_getpshared, pthread_rwlockattr_setpshared \- get or set +process-shared attribute of read-write lock attributes object +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_rwlockattr_getpshared\fR( + \fBconst pthread_rwlockattr_t *restrict\fR \fIattr\fR, + \fBint *restrict\fR \fIpshared\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_rwlockattr_setpshared\fR(\fBpthread_rwlockattr_t *\fR\fIattr\fR, + \fBint\fR \fIpshared\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fIprocess-shared\fR attribute is set to \fBPTHREAD_PROCESS_SHARED\fR 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 +\fIprocess-shared\fR attribute is \fBPTHREAD_PROCESS_PRIVATE,\fR the +read-write lock will only be operated upon by threads created within the same +process as the thread that initialised the read-write lock; if threads of +differing processes attempt to operate on such a read-write lock, the behaviour +is undefined. The default value of the \fIprocess-shared\fR attribute is +\fBPTHREAD_PROCESS_PRIVATE.\fR +.sp +.LP +The \fBpthread_rwlockattr_getpshared()\fR function obtains the value of the +\fIprocess-shared\fR attribute from the initialised attributes object +referenced by \fIattr\fR. The \fBpthread_rwlockattr_setpshared()\fR function +is used to set the \fIprocess-shared\fR attribute in an initialised attributes +object referenced by attr. +.SH RETURN VALUES +.sp +.LP +If successful, the \fBpthread_rwlockattr_setpshared()\fR function returns +\fB0\fR. Otherwise, an error number is returned to indicate the error. +.sp +.LP +Upon successful completion, the \fBpthread_rwlockattr_getpshared()\fR returns +\fB0\fR and stores the value of the \fIprocess-shared\fR attribute of +\fIattr\fR into the object referenced by the \fIpshared\fR parameter. Otherwise +an error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_rwlockattr_getpshared()\fR and +\fBpthread_rwlockattr_setpshared()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIattr\fR or \fIpshared\fR is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_rwlock_init\fR(3C), \fBpthread_rwlock_rdlock\fR(3C), +\fBpthread_rwlock_unlock\fR(3C), \fBpthread_rwlock_wrlock\fR(3C), +\fBpthread_rwlockattr_init\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_rwlockattr_init.3c b/usr/src/man/man3c/pthread_rwlockattr_init.3c new file mode 100644 index 0000000000..8fa0bcb37d --- /dev/null +++ b/usr/src/man/man3c/pthread_rwlockattr_init.3c @@ -0,0 +1,113 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_rwlockattr_init 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_rwlockattr_init, pthread_rwlockattr_destroy \- initialize or destroy +read-write lock attributes object +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_rwlockattr_init\fR(\fBpthread_rwlockattr_t\fR \fI*attr\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_rwlockattr_destroy\fR(\fBpthread_rwlockattr_t\fR \fI*attr\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_rwlockattr_init()\fR function initializes a read-write lock +attributes object \fIattr\fR with the default value for all of the attributes +defined by the implementation. +.sp +.LP +Results are undefined if \fBpthread_rwlockattr_init()\fR is called specifying +an already initialized read-write lock attributes object. +.sp +.LP +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) does not affect any previously initialized read-write locks. +.sp +.LP +The \fBpthread_rwlockattr_destroy()\fR function destroys a read-write lock +attributes object. The effect of subsequent use of the object is undefined +until the object is re-initialized by another call to +\fBpthread_rwlockattr_init()\fR. An implementation can cause +\fBpthread_rwlockattr_destroy()\fR to set the object referenced by \fIattr\fR +to an invalid value. +.SH RETURN VALUES +.sp +.LP +If successful, the \fBpthread_rwlockattr_init()\fR and +\fBpthread_rwlockattr_destroy()\fR functions return \fB0\fR. Otherwise, an +error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_rwlockattr_init()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient memory exists to initialize the read-write lock attributes object. +.RE + +.sp +.LP +The \fBpthread_rwlockattr_destroy()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIattr\fR is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_rwlock_init\fR(3C), \fBpthread_rwlock_rdlock\fR(3C), +\fBpthread_rwlock_unlock\fR(3C), \fBpthread_rwlock_wrlock\fR(3C), +\fBpthread_rwlockattr_getpshared\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_self.3c b/usr/src/man/man3c/pthread_self.3c new file mode 100644 index 0000000000..2cf981fbe1 --- /dev/null +++ b/usr/src/man/man3c/pthread_self.3c @@ -0,0 +1,57 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright 1991, 1992, 1994, The X/Open Company Ltd. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_self 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_self \- get calling thread's ID +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] + +#include <pthread.h> + +\fBpthread_t\fR \fBpthread_self\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_self()\fR function returns the thread \fBID\fR of the calling +thread. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_create\fR(3C), \fBpthread_equal\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_setcancelstate.3c b/usr/src/man/man3c/pthread_setcancelstate.3c new file mode 100644 index 0000000000..8521a78cca --- /dev/null +++ b/usr/src/man/man3c/pthread_setcancelstate.3c @@ -0,0 +1,116 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 1995 IEEE All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_setcancelstate 3C "22 Jan 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_setcancelstate \- enable or disable cancellation +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_setcancelstate\fR(\fBint\fR \fIstate\fR, \fBint *\fR\fIoldstate\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_setcancelstate()\fR function atomically sets the calling +thread's cancellation state to the specified \fIstate\fR and if \fIoldstate\fR +is not \fINULL\fR, stores the previous cancellation \fIstate\fR in +\fIoldstate\fR. +.sp +.LP +The \fIstate\fR can be either of the following: +.sp +.ne 2 +.mk +.na +\fB\fBPTHREAD_CANCEL_ENABLE\fR\fR +.ad +.sp .6 +.RS 4n +This is the default. When cancellation is deferred (deferred cancellation is +also the default), cancellation occurs when the target thread reaches a +cancellation point and a cancel is pending. When cancellation is asynchronous, +receipt of a \fBpthread_cancel\fR(3C) call causes immediate cancellation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPTHREAD_CANCEL_DISABLE\fR\fR +.ad +.sp .6 +.RS 4n +When cancellation is deferred, all cancellation requests to the target thread +are held pending. When cancellation is asynchronous, all cancellation requests +to the target thread are held pending; as soon as cancellation is re-enabled, +pending cancellations are executed immediately. +.RE + +.sp +.LP +See \fBcancellation\fR(5) for the definition of a cancellation point and a +discussion of cancellation concepts. See \fBpthread_setcanceltype\fR(3C) for +explanations of deferred and asynchronous cancellation. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBpthread_setcancelstate()\fR, returns \fB0\fR. +Otherwise, an error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_setcancelstate()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The specified \fIstate\fR is not \fBPTHREAD_CANCEL_ENABLE\fR or +\fBPTHREAD_CANCEL_DISABLE\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_cancel\fR(3C), \fBpthread_cleanup_pop\fR(3C), +\fBpthread_cleanup_push\fR(3C), \fBpthread_exit\fR(3C), \fBpthread_join\fR(3C), +\fBpthread_setcanceltype\fR(3C), \fBpthread_testcancel\fR(3C), +\fBsetjmp\fR(3C), \fBattributes\fR(5), \fBcancellation\fR(5), +\fBcondition\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_setcanceltype.3c b/usr/src/man/man3c/pthread_setcanceltype.3c new file mode 100644 index 0000000000..9a3e98055b --- /dev/null +++ b/usr/src/man/man3c/pthread_setcanceltype.3c @@ -0,0 +1,116 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 1995 IEEE. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_setcanceltype 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_setcanceltype \- set cancellation type of a thread +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_setcanceltype\fR(\fBint\fR \fItype\fR, \fBint *\fR\fIoldtype\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_setcanceltype()\fR function atomically sets the calling thread's +cancellation type to the specified \fBtype\fR and, if \fIoldtype\fR is not +\fINULL,\fR stores the previous cancellation \fBtype\fR in \fIoldtype\fR. The +\fBtype\fR can be either of the following: +.sp +.ne 2 +.mk +.na +\fB\fBPTHREAD_CANCEL_DEFERRED\fR \fR +.ad +.sp .6 +.RS 4n +This is the default. When cancellation is enabled (enabled cancellation is also +the default), cancellation occurs when the target thread reaches a cancellation +point and a cancel is pending. When cancellation is disabled, all cancellation +requests to the target thread are held pending. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPTHREAD_CANCEL_ASYNCHRONOUS\fR \fR +.ad +.sp .6 +.RS 4n +When cancellation is enabled, receipt of a \fBpthread_cancel\fR(3C) call +causes immediate cancellation. When cancellation is disabled, all cancellation +requests to the target thread are held pending; as soon as cancellation is +re-enabled, pending cancellations are executed immediately. +.RE + +.sp +.LP +See \fBcancellation\fR(5) for the definition of a cancellation point and a +discussion of cancellation concepts. See \fBpthread_setcancelstate\fR(3C) for +explanations of enabling and disabling cancellation. +.sp +.LP +The \fBpthread_setcanceltype()\fR function is a cancellation point if +\fBtype\fR is called with \fBPTHREAD_CANCEL_ASYNCHRONOUS\fR and the +cancellation state is \fBPTHREAD_CANCEL_ENABLE.\fR +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBpthread_setcanceltype()\fR function returns +\fB0\fR. Otherwise, an error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_setcanceltype()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR \fR +.ad +.RS 11n +.rt +The specified \fBtype\fR is not \fBPTHREAD_CANCEL_DEFERRED\fR or +\fBPTHREAD_CANCEL_ASYNCHRONOUS.\fR +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_cancel\fR(3C), \fBpthread_cleanup_pop\fR(3C), +\fBpthread_cleanup_push\fR(3C), \fBpthread_exit\fR(3C), \fBpthread_join\fR(3C), +\fBpthread_setcancelstate\fR(3C), \fBpthread_testcancel\fR(3C), +\fBsetjmp\fR(3C), \fBattributes\fR(5), \fBcancellation\fR(5), +\fBcondition\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_setschedprio.3c b/usr/src/man/man3c/pthread_setschedprio.3c new file mode 100644 index 0000000000..1d941e028d --- /dev/null +++ b/usr/src/man/man3c/pthread_setschedprio.3c @@ -0,0 +1,101 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_setschedprio 3C "1 Apr 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_setschedprio \- dynamic thread scheduling parameters access +.SH SYNOPSIS +.LP +.nf +cc \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lpthread\fR [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_setschedprio\fR(\fBpthread_t\fR \fIthread\fR, \fBint\fR \fIprio\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_setschedprio()\fR function sets the scheduling priority for the +thread whose thread ID is given by \fIthread\fR to the value given by +\fIprio\fR. +.sp +.LP +If the \fBpthread_setschedprio()\fR function fails, the scheduling priority of +the target thread is not changed. +.SH RETURN VALUES +.sp +.LP +If successful, the \fBpthread_setschedprio()\fR function returns 0; otherwise, +an error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_setschedprio()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of \fIprio\fR is invalid for the scheduling policy of the specified +thread. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 10n +.rt +The caller does not have the appropriate permission to set the priority to the +value specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBESRCH\fR\fR +.ad +.RS 10n +.rt +The value specified by thread does not refer to an existing thread. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_getschedparam\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_sigmask.3c b/usr/src/man/man3c/pthread_sigmask.3c new file mode 100644 index 0000000000..0f6d72962d --- /dev/null +++ b/usr/src/man/man3c/pthread_sigmask.3c @@ -0,0 +1,370 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 1995 IEEE. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_sigmask 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_sigmask \- change or examine calling thread's signal mask +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> +#include <signal.h> + +\fBint\fR \fBpthread_sigmask\fR(\fBint\fR \fIhow\fR, \fBconst sigset_t *\fR\fIset\fR, \fBsigset_t *\fR\fIoset\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_sigmask()\fR function changes or examines a calling thread's +signal mask. Each thread has its own signal mask. A new thread inherits the +calling thread's signal mask and priority; however, pending signals are not +inherited. Signals pending for a new thread will be empty. +.sp +.LP +If the value of the argument \fIset\fR is not \fINULL\fR, \fIset\fR points to a +set of signals that can modify the currently blocked set. If the value of +\fIset\fR is \fINULL\fR, the value of \fIhow\fR is insignificant and the +thread's signal mask is unmodified; thus, \fBpthread_sigmask()\fR can be used +to inquire about the currently blocked signals. +.sp +.LP +The value of the argument \fIhow\fR specifies the method in which the set is +changed and takes one of the following values: +.sp +.ne 2 +.mk +.na +\fB\fBSIG_BLOCK\fR\fR +.ad +.RS 15n +.rt +\fIset\fR corresponds to a set of signals to block. They are added to the +current signal mask. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIG_UNBLOCK\fR\fR +.ad +.RS 15n +.rt +\fIset\fR corresponds to a set of signals to unblock. These signals are deleted +from the current signal mask. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIG_SETMASK\fR\fR +.ad +.RS 15n +.rt +\fIset\fR corresponds to the new signal mask. The current signal mask is +replaced by \fBset\fR. +.RE + +.sp +.LP +If the value of \fIoset\fR is not \fINULL\fR, it points to the location where +the previous signal mask is stored. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBpthread_sigmask()\fR function returns +\fB0\fR. Otherwise, it returns a non-zero value. +.SH ERRORS +.sp +.LP +The \fBpthread_sigmask()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of \fIhow\fR is not defined and \fIoset\fR is \fINULL\fR. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRCreate a default thread that can serve as a signal +catcher/handler with its own signal mask. +.sp +.LP +The following example shows how to create a default thread that can serve as a +signal catcher/handler with its own signal mask. \fBnew\fR will have a +different value from the creator's signal mask. + +.sp +.LP +As POSIX threads and Solaris threads are fully compatible even within the same +process, this example uses \fBpthread_create\fR(3C) if you execute \fBa.out +0\fR, or \fBthr_create\fR(3C) if you execute \fBa.out 1\fR. + +.sp +.LP +In this example: + +.RS +4 +.TP +.ie t \(bu +.el o +The \fBsigemptyset\fR(3C) function initializes a null signal set, \fBnew\fR. +The \fBsigaddset\fR(3C) function packs the signal, \fBSIGINT\fR, into that new +set. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Either \fBpthread_sigmask()\fR or \fBthr_sigsetmask()\fR is used to mask the +signal, \fBSIGINT\fR (CTRL-C), from the calling thread, which is \fBmain()\fR. +The signal is masked to guarantee that only the new thread will receive this +signal. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBpthread_create()\fR or \fBthr_create()\fR creates the signal-handling +thread. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Using \fBpthread_join\fR(3C) or \fBthr_join\fR(3C), \fBmain()\fR then waits for +the termination of that signal-handling thread, whose \fBID\fR number is +\fBuser_threadID\fR; \fBmain()\fR will then \fBsleep\fR(3C) for 2 seconds, +after which the program terminates. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The signal-handling thread, \fBhandler\fR: +.RS +4 +.TP +.ie t \(bu +.el o +Assigns the handler \fBinterrupt()\fR to handle the signal \fBSIGINT\fR, by the +call to \fBsigaction\fR(2). +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Resets its own signal set to \fInot block\fR the signal, \fBSIGINT\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Sleeps for 8 seconds to allow time for the user to deliver the signal, +\fBSIGINT\fR, by pressing the \fBCTRL-C\fR. +.RE +.RE +.sp +.in +2 +.nf +/* cc thisfile.c -lthread -lpthread */ +#define _REENTRANT /* basic first 3-lines for threads */ +#include <pthread.h> +#include <thread.h> +thread_t user_threadID; +sigset_t new; +void *handler(\|), interrupt(\|); + +int +main( int argc, char *argv[\|] ) { + test_argv(argv[1]); + + sigemptyset(&new); + sigaddset(&new, SIGINT); + switch(*argv[1]) { + + case '0': /* POSIX */ + pthread_sigmask(SIG_BLOCK, &new, NULL); + pthread_create(&user_threadID, NULL, handler, + argv[1]); + pthread_join(user_threadID, NULL); + break; + + case '1': /* Solaris */ + thr_sigsetmask(SIG_BLOCK, &new, NULL); + thr_create(NULL, 0, handler, argv[1], 0, + &user_threadID); + thr_join(user_threadID, NULL, NULL); + break; + } /* switch */ + + printf("thread handler, # %d, has exited\en",user_threadID); + sleep(2); + printf("main thread, # %d is done\en", thr_self(\|)); + return (0) +} /* end main */ + +struct sigaction act; + +void * +handler(char *argv1) +{ + act.sa_handler = interrupt; + sigaction(SIGINT, &act, NULL); + switch(*argv1) { + case '0': /* POSIX */ + pthread_sigmask(SIG_UNBLOCK, &new, NULL); + break; + case '1': /* Solaris */ + thr_sigsetmask(SIG_UNBLOCK, &new, NULL); + break; + } + printf("\en Press CTRL-C to deliver SIGINT signal to the + process\en"); + sleep(8); /* give user time to hit CTRL-C */ + return (NULL) +} + +void +interrupt(int sig) +{ + printf("thread %d caught signal %d\en", thr_self(\|), sig); +} + +void test_argv(char argv1[\|]) { + if(argv1 == NULL) { + printf("use 0 as arg1 to use thr_create(\|);\en \e + or use 1 as arg1 to use pthread_create(\|)\en"); + exit(NULL); + } +} +.fi +.in -2 + +.sp +.LP +In the last example, the \fBhandler\fR thread served as a signal-handler while +also taking care of activity of its own (in this case, sleeping, although it +could have been some other activity). A thread could be completely dedicated to +signal-handling simply by waiting for the delivery of a selected signal by +blocking with \fBsigwait\fR(2). The two subroutines in the previous example, +\fBhandler()\fR and \fBinterrupt()\fR, could have been replaced with the +following routine: + +.sp +.in +2 +.nf +void * +handler(void *unused) +{ + int signal; + printf("thread %d is waiting for you to press the CTRL-C keys\en", + thr_self(\|)); + sigwait(&new, &signal); + printf("thread %d has received the signal %d \en", thr_self(\|), + signal); + return (NULL); +} +/* pthread_create(\|) and thr_create(\|) would use NULL instead + of argv[1] for the arg passed to handler(\|) */ +.fi +.in -2 + +.sp +.LP +In this routine, one thread is dedicated to catching and handling the signal +specified by the set \fBnew\fR, which allows \fBmain()\fR and all of its other +sub-threads, created \fIafter\fR \fBpthread_sigmask()\fR or +\fBthr_sigsetmask()\fR masked that signal, to continue uninterrupted. Any use +of \fBsigwait\fR(2) should be such that all threads block the signals passed +to \fBsigwait\fR(2) at all times. Only the thread that calls \fBsigwait()\fR +will get the signals. The call to \fBsigwait\fR(2) takes two arguments. + +.sp +.LP +For this type of background dedicated signal-handling routine, a Solaris daemon +thread can be used by passing the argument \fBTHR_DAEMON\fR to +\fBthr_create\fR(3C). + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe and Async-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBsigaction\fR(2), \fBsigprocmask\fR(2), \fBsigwait\fR(2), +\fBcond_wait\fR(3C), \fBpthread_cancel\fR(3C), \fBpthread_create\fR(3C), +\fBpthread_join\fR(3C), \fBpthread_self\fR(3C), \fBsigaddset\fR(3C), +\fBsigemptyset\fR(3C), \fBsigsetops\fR(3C), \fBsleep\fR(3C), +\fBattributes\fR(5), \fBcancellation\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +It is not possible to block signals that cannot be caught or ignored (see +\fBsigaction\fR(2)). It is also not possible to block or unblock +\fBSIGCANCEL\fR, as \fBSIGCANCEL\fR is reserved for the implementation of POSIX +thread cancellation (see \fBpthread_cancel\fR(3C) and \fBcancellation\fR(5)). +This restriction is quietly enforced by the standard C library. +.sp +.LP +Using \fBsigwait\fR(2) in a dedicated thread allows asynchronously generated +signals to be managed synchronously; however, \fBsigwait\fR(2) should never be +used to manage synchronously generated signals. +.sp +.LP +Synchronously generated signals are exceptions that are generated by a thread +and are directed at the thread causing the exception. Since \fBsigwait()\fR +blocks waiting for signals, the blocking thread cannot receive a synchronously +generated signal. +.sp +.LP +The \fBsigprocmask\fR(2) function behaves the same as if +\fBpthread_sigmask()\fR has been called. POSIX leaves the semantics of the call +to \fBsigprocmask\fR(2) unspecified in a multi-threaded process, so programs +that care about POSIX portability should not depend on this semantic. +.sp +.LP +If a signal is delivered while a thread is waiting on a condition variable, the +\fBcond_wait\fR(3C) function will be interrupted and the handler will be +executed. The state of the lock protecting the condition variable is undefined +while the thread is executing the signal handler. +.sp +.LP +Although \fBpthread_sigmask()\fR is Async-Signal-Safe with respect to the +Solaris environment, this safeness is not guaranteed to be portable to other +POSIX domains. +.sp +.LP +Signals that are generated synchronously should not be masked. If such a signal +is blocked and delivered, the receiving process is killed. diff --git a/usr/src/man/man3c/pthread_spin_destroy.3c b/usr/src/man/man3c/pthread_spin_destroy.3c new file mode 100644 index 0000000000..8d36d03a2b --- /dev/null +++ b/usr/src/man/man3c/pthread_spin_destroy.3c @@ -0,0 +1,146 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_spin_destroy 3C "30 Jan 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_spin_destroy, pthread_spin_init \- destroy or initialize a spin lock +object +.SH SYNOPSIS +.LP +.nf +cc \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_spin_destroy\fR(\fBpthread_spinlock_t *\fR\fIlock\fR); +.fi + +.LP +.nf +\fBint\fR \fBpthread_spin_init\fR(\fBpthread_spinlock_t *\fR\fIlock\fR, \fBint\fR \fIpshared\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_spin_destroy()\fR function destroys the spin lock referenced by +\fIlock\fR 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 +\fBpthread_spin_init()\fR. The results are undefined if +\fBpthread_spin_destroy()\fR is called when a thread holds the lock, or if this +function is called with an uninitialized thread spin lock. +.sp +.LP +The \fBpthread_spin_init()\fR function allocates any resources required to use +the spin lock referenced by \fIlock\fR and initialize the lock to an unlocked +state. +.sp +.LP +If the Thread Process-Shared Synchronization option is supported and the value +of \fIpshared\fR is \fBPTHREAD_PROCESS_SHARED\fR, the spin lock can 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. +.sp +.LP +If the Thread Process-Shared Synchronization option is supported and the value +of \fIpshared\fR is \fBPTHREAD_PROCESS_PRIVATE\fR, or if the option is not +supported, the spin lock can 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. +.sp +.LP +The results are undefined if \fBpthread_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. +.sp +.LP +If the \fBpthread_spin_init()\fR function fails, the lock is not initialized +and the contents of \fIlock\fR are undefined. +.sp +.LP +Only the object referenced by \fIlock\fR can be used for performing +synchronization. +.sp +.LP +The result of referring to copies of that object in calls to +\fBpthread_spin_destroy()\fR, \fBpthread_spin_lock\fR(3C), +\fBpthread_spin_trylock\fR(3C), or \fBpthread_spin_unlock\fR(3C) is undefined. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, these functions returns 0. Otherwise, an error +number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_spin_init()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +The system lacks the necessary resources to initialize another spin lock. +.RE + +.sp +.LP +These functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBUSY\fR\fR +.ad +.RS 10n +.rt +The system has detected an attempt to initialize or destroy a spin lock while +it is in use (for example, while being used in a \fBpthread_spin_lock()\fR +call) by another thread. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIlock\fR is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_spin_lock\fR(3C), \fBpthread_spin_unlock\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_spin_lock.3c b/usr/src/man/man3c/pthread_spin_lock.3c new file mode 100644 index 0000000000..da6c83fbaa --- /dev/null +++ b/usr/src/man/man3c/pthread_spin_lock.3c @@ -0,0 +1,119 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_spin_lock 3C "30 Jan 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_spin_lock, pthread_spin_trylock \- lock a spin lock object +.SH SYNOPSIS +.LP +.nf +cc \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_spin_lock\fR(\fBpthread_spinlock_t *\fR\fIlock\fR); +.fi + +.LP +.nf +#include <pthread.h> + +\fBint\fR \fBpthread_spin_trylock\fR(\fBpthread_spinlock_t *\fR\fIlock\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_spin_lock()\fR function locks the spin lock referenced by +\fIlock\fR. The calling thread acquires the lock if it is not held by another +thread. Otherwise, the thread spins (that is, does not return from the +\fBpthread_spin_lock call()\fR) until the lock becomes available. The results +are undefined if the calling thread holds the lock at the time the call is +made. +.sp +.LP +The \fBpthread_spin_trylock()\fR function locks the spin lock referenced by +\fIlock\fR if it is not held by any thread. Otherwise, the function fails. +.sp +.LP +The results are undefined if either of these functions is called with an +uninitialized spin lock. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, these functions returns 0. Otherwise, an error +number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_spin_trylock()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBUSY\fR\fR +.ad +.RS 9n +.rt +A thread currently holds the lock. +.RE + +.sp +.LP +These functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified by \fIlock\fR does not refer to an initialized spin lock +object. +.RE + +.sp +.LP +The \fBpthread_spin_lock()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEDEADLK\fR\fR +.ad +.RS 11n +.rt +The calling thread already holds the lock. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_spin_destroy\fR(3C), \fBpthread_spin_unlock\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_spin_unlock.3c b/usr/src/man/man3c/pthread_spin_unlock.3c new file mode 100644 index 0000000000..e65fdf2d06 --- /dev/null +++ b/usr/src/man/man3c/pthread_spin_unlock.3c @@ -0,0 +1,90 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_spin_unlock 3C "30 Jan 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_spin_unlock \- unlock a spin lock object +.SH SYNOPSIS +.LP +.nf +cc \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBint\fR \fBpthread_spin_unlock\fR(\fBpthread_spinlock_t *\fR\fIlock\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_spin_unlock()\fR function releases the spin lock referenced by +\fIlock\fR which was locked with the \fBpthread_spin_lock\fR(3C) or +\fBpthread_spin_trylock\fR(3C) functions. The results are undefined if the lock +is not held by the calling thread. If there are threads spinning on the lock +when \fBpthread_spin_unlock()\fR is called, the lock becomes available and an +unspecified spinning thread acquires the lock. +.sp +.LP +The results are undefined if this function is called with an uninitialized +thread spin lock. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBpthread_spin_unlock()\fR function returns 0. +Otherwise, an error number shall be returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBpthread_spin_unlock()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +An invalid argument was specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 10n +.rt +The calling thread does not hold the lock. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_spin_destroy\fR(3C), \fBpthread_spin_lock\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/pthread_testcancel.3c b/usr/src/man/man3c/pthread_testcancel.3c new file mode 100644 index 0000000000..3e62a3cd20 --- /dev/null +++ b/usr/src/man/man3c/pthread_testcancel.3c @@ -0,0 +1,93 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pthread_testcancel 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +pthread_testcancel \- create cancellation point in the calling thread +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ] +#include <pthread.h> + +\fBvoid\fR \fBpthread_testcancel\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpthread_testcancel()\fR function forces testing for cancellation. This +is useful when you need to execute code that runs for long periods without +encountering cancellation points; such as a library routine that executes +long-running computations without cancellation points. This type of code can +block cancellation for unacceptable long periods of time. One strategy for +avoiding blocking cancellation for long periods, is to insert calls to +\fBpthread_testcancel()\fR in the long-running computation code and to setup a +cancellation handler in the library code, if required. +.SH RETURN VALUES +.sp +.LP +The \fBpthread_testcancel()\fR function returns \fBvoid\fR. +.SH ERRORS +.sp +.LP +The \fBpthread_testcancel()\fR function does not return errors. +.SH EXAMPLES +.sp +.LP +See \fBcancellation\fR(5) for an example of using \fBpthread_testcancel()\fR to +force testing for cancellation and a discussion of cancellation concepts. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(3), \fBpthread_cleanup_pop\fR(3C), \fBpthread_cleanup_push\fR(3C), +\fBpthread_exit\fR(3C), \fBpthread_join\fR(3C), +\fBpthread_setcancelstate\fR(3C), \fBpthread_setcanceltype\fR(3C), +\fBsetjmp\fR(3C), \fBattributes\fR(5), \fBcancellation\fR(5), +\fBcondition\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +The \fBpthread_testcancel()\fR function has no effect if cancellation is +disabled. +.sp +.LP +Use \fBpthread_testcancel()\fR with \fBpthread_setcanceltype()\fR called with +its \fIcanceltype\fR set to \fBPTHREAD_CANCEL_DEFERRED\fR. The +\fBpthread_testcancel()\fR function operation is undefined if +\fBpthread_setcanceltype()\fR was called with its \fIcanceltype\fR argument set +to \fBPTHREAD_CANCEL_ASYNCHRONOUS\fR. +.sp +.LP +It is possible to kill a thread when it is holding a resource, such as lock or +allocated memory. If that thread has not setup a cancellation cleanup handler +to release the held resource, the application is "cancel-unsafe". See +\fBattributes\fR(5) for a discussion of Cancel-Safety, Deferred-Cancel-Safety, +and Asynchronous-Cancel-Safety. diff --git a/usr/src/man/man3c/ptrace.3c b/usr/src/man/man3c/ptrace.3c new file mode 100644 index 0000000000..30a5ca51ef --- /dev/null +++ b/usr/src/man/man3c/ptrace.3c @@ -0,0 +1,249 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ptrace 3C "22 Mar 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +ptrace \- allows a parent process to control the execution of a child process +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> +#include <sys/types.h> + +\fBint\fR \fBptrace\fR(\fBint\fR \fIrequest\fR, \fBpid_t\fR \fIpid\fR, \fBint\fR \fIaddr\fR, \fBint\fR \fIdata\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBptrace()\fR function allows a parent process to control the execution of +a child process. Its primary use is for the implementation of breakpoint +debugging. The child process behaves normally until it encounters a signal (see +\fBsignal.h\fR(3HEAD)), at which time it enters a stopped state and its parent +is notified by the \fBwait\fR(3C) function. When the child is in the stopped +state, its parent can examine and modify its "core image" using \fBptrace()\fR. +Also, the parent can cause the child either to terminate or continue, with the +possibility of ignoring the signal that caused it to stop. +.sp +.LP +The \fIrequest\fR argument determines the action to be taken by \fBptrace()\fR +and is one of the following: +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 5n +.rt +This request must be issued by the child process if it is to be traced by its +parent. It turns on the child's trace flag that stipulates that the child +should be left in a stopped state on receipt of a signal rather than the state +specified by \fIfunc\fR (see \fBsignal\fR(3C)). The \fIpid\fR, \fIaddr\fR, and +\fIdata\fR arguments are ignored, and a return value is not defined for this +request. Peculiar results ensue if the parent does not expect to trace the +child. +.RE + +.sp +.LP +The remainder of the requests can only be used by the parent process. For each, +\fIpid\fR is the process \fBID\fR of the child. The child must be in a stopped +state before these requests are made. +.sp +.ne 2 +.mk +.na +\fB\fB1, 2\fR\fR +.ad +.RS 8n +.rt +With these requests, the word at location \fIaddr\fR in the address space of +the child is returned to the parent process. If instruction and data space are +separated, request \fB1\fR returns a word from instruction space, and request +\fB2\fR returns a word from data space. If instruction and data space are not +separated, either request \fB1\fR or request \fB2\fR may be used with equal +results. The \fIdata\fR argument is ignored. These two requests fail if +\fIaddr\fR is not the start address of a word, in which case \fB\(mi1\fR is +returned to the parent process and the parent's \fBerrno\fR is set to +\fBEIO\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB3\fR\fR +.ad +.RS 8n +.rt +With this request, the word at location \fIaddr\fR in the child's user area in +the system's address space (see <\fBsys/user.h\fR>) is returned to the parent +process. The \fIdata\fR argument is ignored. This request fails if \fIaddr\fR +is not the start address of a word or is outside the user area, in which case +\fB\(mi1\fR is returned to the parent process and the parent's \fBerrno\fR is +set to \fBEIO\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB4, 5\fR\fR +.ad +.RS 8n +.rt +With these requests, the value given by the \fIdata\fR argument is written into +the address space of the child at location \fIaddr\fR. If instruction and data +space are separated, request \fB4\fR writes a word into instruction space, and +request \fB5\fR writes a word into data space. If instruction and data space +are not separated, either request \fB4\fR or request \fB5\fR may be used with +equal results. On success, the value written into the address space of the +child is returned to the parent. These two requests fail if \fIaddr\fR is not +the start address of a word. On failure \fB\(mi1\fR is returned to the parent +process and the parent's \fBerrno\fR is set to \fBEIO\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB6\fR\fR +.ad +.RS 8n +.rt +With this request, a few entries in the child's user area can be written. +\fIdata\fR gives the value that is to be written and \fIaddr\fR is the location +of the entry. The few entries that can be written are the general registers and +the condition codes of the Processor Status Word. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB7\fR\fR +.ad +.RS 8n +.rt +This request causes the child to resume execution. If the \fIdata\fR argument +is 0, all pending signals including the one that caused the child to stop are +canceled before it resumes execution. If the \fIdata\fR argument is a valid +signal number, the child resumes execution as if it had incurred that signal, +and any other pending signals are canceled. The \fIaddr\fR argument must be +equal to 1 for this request. On success, the value of \fIdata\fR is returned +to the parent. This request fails if \fIdata\fR is not 0 or a valid signal +number, in which case \fB\(mi1\fR is returned to the parent process and the +parent's \fBerrno\fR is set to \fBEIO\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB8\fR\fR +.ad +.RS 8n +.rt +This request causes the child to terminate with the same consequences as +\fBexit\fR(2). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB9\fR\fR +.ad +.RS 8n +.rt +This request sets the trace bit in the Processor Status Word of the child and +then executes the same steps as listed above for request \fB7\fR. The trace bit +causes an interrupt on completion of one machine instruction. This effectively +allows single stepping of the child. +.RE + +.sp +.LP +To forestall possible fraud, \fBptrace()\fR inhibits the set-user-ID facility +on subsequent calls to one of the \fBexec\fR family of functions (see +\fBexec\fR(2)). If a traced process calls one of these functions, it stops +before executing the first instruction of the new image showing signal +\fBSIGTRAP\fR. +.SH ERRORS +.sp +.LP +The \fBptrace()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 9n +.rt +The \fIrequest\fR argument is an illegal number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 9n +.rt +The calling process does not have appropriate privileges to control the calling +process. See \fBproc\fR(4). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBESRCH\fR\fR +.ad +.RS 9n +.rt +The \fIpid\fR argument identifies a child that does not exist or has not +executed a \fBptrace()\fR call with request \fB0\fR. +.RE + +.SH USAGE +.sp +.LP +The \fBptrace()\fR function is available only with the 32-bit version of +\fBlibc\fR(3LIB). It is not available with the 64-bit version of this library. +.sp +.LP +The \fB/proc\fR debugging interfaces should be used instead of \fBptrace()\fR, +which provides quite limited debugger support and is itself implemented using +the \fB/proc\fR interfaces. There is no actual \fBptrace()\fR system call in +the kernel. See \fBproc\fR(4) for descriptions of the \fB/proc\fR debugging +interfaces. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBexec\fR(2), \fBexit\fR(2), \fBlibc\fR(3LIB), \fBsignal\fR(3C), +\fBsignal.h\fR(3HEAD), \fBwait\fR(3C), \fBproc\fR(4), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/ptsname.3c b/usr/src/man/man3c/ptsname.3c new file mode 100644 index 0000000000..d621dc5191 --- /dev/null +++ b/usr/src/man/man3c/ptsname.3c @@ -0,0 +1,65 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ptsname 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +ptsname \- get name of the slave pseudo-terminal device +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBchar *\fR\fBptsname\fR(\fBint\fR \fIfildes\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBptsname()\fR function returns the name of the slave pseudo-terminal +device associated with a master pseudo-terminal device. \fIfildes\fR is a file +descriptor returned from a successful open of the master device. +\fBptsname()\fR returns a pointer to a string containing the null-terminated +path name of the slave device of the form \fB/dev/pts/N\fR, where \fBN\fR is a +non-negative integer. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the function \fBptsname()\fR returns a pointer to a +string which is the name of the pseudo-terminal slave device. This value points +to a static data area that is overwritten by each call to \fBptsname()\fR. Upon +failure, \fBptsname()\fR returns \fINULL\fR. This could occur if \fIfildes\fR +is an invalid file descriptor or if the slave device name does not exist in +the file system. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBopen\fR(2), \fBgrantpt\fR(3C), \fBttyname\fR(3C), \fBunlockpt\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man3c/putenv.3c b/usr/src/man/man3c/putenv.3c new file mode 100644 index 0000000000..7de0f3d8b6 --- /dev/null +++ b/usr/src/man/man3c/putenv.3c @@ -0,0 +1,101 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH putenv 3C "7 Aug 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +putenv \- change or add value to environment +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBint\fR \fBputenv\fR(\fBchar *\fR\fIstring\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBputenv()\fR function makes the value of the environment variable +\fIname\fR equal to \fIvalue\fR by altering an existing variable or creating a +new one. In either case, the string pointed to by \fIstring\fR becomes part of +the environment, so altering the string will change the environment. +.sp +.LP +The \fIstring\fR argument points to a string of the form +\fIname\fR\fB=\fR\fIvalue\fR. The space used by \fIstring\fR is no longer used +once a new string-defining \fIname\fR is passed to \fBputenv()\fR. +.sp +.LP +The \fBputenv()\fR function uses \fBmalloc\fR(3C) to enlarge the environment. +.sp +.LP +After \fBputenv()\fR is called, environment variables are not in alphabetical +order. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBputenv()\fR returns 0. Otherwise, it returns a +non-zero value and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBputenv()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient memory was available. +.RE + +.SH USAGE +.sp +.LP +The \fBputenv()\fR function can be safely called from multithreaded programs. +Caution must be exercised when using this function and \fBgetenv\fR(3C) in +multithreaded programs. These functions examine and modify the environment +list, which is shared by all threads in a program. The system prevents the +list from being accessed simultaneously by two different threads. It does not, +however, prevent two threads from successively accessing the environment list +using \fBputenv()\fR or \fBgetenv()\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBexec\fR(2), \fBgetenv\fR(3C), \fBmalloc\fR(3C), \fBattributes\fR(5), +\fBenviron\fR(5), \fBstandards\fR(5) +.SH WARNINGS +.sp +.LP +The \fIstring\fR argument should not be an automatic variable. It should be +declared static if it is declared within a function because it cannot be +automatically declared. A potential error is to call \fBputenv()\fR with a +pointer to an automatic variable as the argument and to then exit the calling +function while \fIstring\fR is still part of the environment. diff --git a/usr/src/man/man3c/putpwent.3c b/usr/src/man/man3c/putpwent.3c new file mode 100644 index 0000000000..9344ca241d --- /dev/null +++ b/usr/src/man/man3c/putpwent.3c @@ -0,0 +1,58 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH putpwent 3C "29 Dec 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +putpwent \- write password file entry +.SH SYNOPSIS +.LP +.nf +#include <pwd.h> + +\fBint\fR \fBputpwent\fR(\fBconst struct passwd *\fR\fIp\fR, \fBFILE *\fR\fIf\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBputpwent()\fR function is the inverse of \fBgetpwent()\fR. See +\fBgetpwnam\fR(3C). Given a pointer to a \fBpasswd\fR structure created by +\fBgetpwent()\fR, \fBgetpwuid()\fR, or \fBgetpwnam()\fR, \fBputpwent()\fR +writes a line on the stream \fIf\fR that matches the format of +\fB/etc/passwd\fR. +.SH RETURN VALUES +.sp +.LP +The \fBputpwent()\fR function returns a non-zero value if an error was detected +during its operation. Otherwise, it returns \fB0\fR. +.SH USAGE +.sp +.LP +The \fBputpwent()\fR function is of limited utility, since most password files +are maintained as Network Information Service (NIS) files that cannot be +updated with this function. For this reason, the use of this function is +discouraged. If used at all, it should be used with \fBputspent\fR(3C) to +update the shadow file. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgetpwnam\fR(3C), \fBputspent\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/puts.3c b/usr/src/man/man3c/puts.3c new file mode 100644 index 0000000000..df382e46cd --- /dev/null +++ b/usr/src/man/man3c/puts.3c @@ -0,0 +1,78 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH puts 3C "18 Jun 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +puts, fputs \- put a string on a stream +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBint\fR \fBputs\fR(\fBconst char *\fR\fIs\fR); +.fi + +.LP +.nf +\fBint\fR \fBfputs\fR(\fBconst char *\fR\fIs\fR, \fBFILE *\fR\fIstream\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBputs()\fR function writes the string pointed to by \fIs\fR, followed by +a \fBNEWLINE\fR character, to the standard output stream \fBstdout\fR (see +\fBIntro\fR(3)). The terminating null byte is not written. +.sp +.LP +The \fBfputs()\fR function writes the null-terminated string pointed to by +\fIs\fR to the named output \fIstream\fR. The terminating null byte is not +written. +.sp +.LP +The \fBst_ctime\fR and \fBst_mtime\fR fields of the file will be marked for +update between the successful execution of \fBfputs()\fR and the next +successful completion of a call to \fBfflush\fR(3C) or \fBfclose\fR(3C) on the +same stream or a call to \fBexit\fR(2) or \fBabort\fR(3C). +.SH RETURN VALUES +.sp +.LP +On successful completion, both functions return the number of bytes written; +otherwise they return \fBEOF\fR and set \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +Refer to \fBfputc\fR(3C). +.SH USAGE +.sp +.LP +Unlike \fBputs()\fR, the \fBfputs()\fR function does not write a NEWLINE +character at the end of the string. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBexit\fR(2), \fBwrite\fR(2), \fBIntro\fR(3), \fBabort\fR(3C), +\fBfclose\fR(3C), \fBferror\fR(3C), \fBfflush\fR(3C), \fBfopen\fR(3C), +\fBfputc\fR(3C), \fBprintf\fR(3C), \fBstdio\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/putspent.3c b/usr/src/man/man3c/putspent.3c new file mode 100644 index 0000000000..c7e6131093 --- /dev/null +++ b/usr/src/man/man3c/putspent.3c @@ -0,0 +1,80 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH putspent 3C "23 Jan 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +putspent \- write shadow password file entry +.SH SYNOPSIS +.LP +.nf +#include <shadow.h> + +\fBint\fR \fBputspent\fR(\fBconst struct spwd *\fR\fIp\fR, \fBFILE *\fR\fIfp\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBputspent()\fR function is the inverse of \fBgetspent()\fR. See +\fBgetspnam\fR(3C). Given a pointer to a \fBspwd\fR structure created by +\fBgetspent()\fR or \fBgetspnam()\fR, \fBputspent()\fR writes a line on the +stream \fIfp\fR that matches the format of \fB/etc/shadow\fR. +.sp +.LP +The \fBspwd\fR structure contains the following members: +.sp +.in +2 +.nf +\fBchar *sp_namp; +char *sp_pwdp; +int sp_lstchg; +int sp_min; +int sp_max; +int sp_warn; +int sp_inact; +int sp_expire; +unsigned int sp_flag;\fR +.fi +.in -2 + +.sp +.LP +If the \fBsp_min\fR, \fBsp_max\fR, \fBsp_lstchg\fR, \fBsp_warn\fR, +\fBsp_inact\fR, or \fBsp_expire\fR member of the \fBspwd\fR structure is +\(mi1, or if \fBsp_flag\fR is 0, the corresponding \fB/etc/shadow\fR field is +cleared. +.SH RETURN VALUES +.sp +.LP +The \fBputspent()\fR function returns a non-zero value if an error was +detected during its operation. Otherwise, it returns \fB0\fR. +.SH USAGE +.sp +.LP +Since this function is for internal use only, compatibility is not guaranteed. +For this reason, its use is discouraged. If used at all, if should be used with +\fBputpwent\fR(3C) to update the password file. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgetpwnam\fR(3C), \fBgetspnam\fR(3C), \fBputpwent\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/putws.3c b/usr/src/man/man3c/putws.3c new file mode 100644 index 0000000000..42ee660a66 --- /dev/null +++ b/usr/src/man/man3c/putws.3c @@ -0,0 +1,55 @@ +'\" te +.\" Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH putws 3C "22 Apr 1997" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +putws \- convert a string of Process Code characters to EUC characters +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> +#include <widec.h> + +\fBint\fR \fBputws\fR(\fBwchar_t *\fR\fIs\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBputws()\fR function converts the Process Code string (terminated by a +\fB(wchar_t)NULL\fR) pointed to by \fIs\fR, to an Extended Unix Code (EUC) +string followed by a \fBNEWLINE\fR character, and writes it to the standard +output stream \fBstdout\fR. It does not write the terminal null character. +.SH RETURN VALUES +.sp +.LP +The \fBputws()\fR function returns the number of Process Code characters +transformed and written. It returns \fBEOF\fR if it attempts to write to a +file that has not been opened for writing. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBferror\fR(3C), \fBfopen\fR(3C), \fBfread\fR(3C), \fBgetws\fR(3C), +\fBprintf\fR(3C), \fBputwc\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/qsort.3c b/usr/src/man/man3c/qsort.3c new file mode 100644 index 0000000000..de1dafb952 --- /dev/null +++ b/usr/src/man/man3c/qsort.3c @@ -0,0 +1,122 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH qsort 3C "6 Dec 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +qsort \- quick sort +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBvoid\fR \fBqsort\fR(\fBvoid *\fR\fIbase\fR, \fBsize_t\fR \fInel\fR, \fBsize_t\fR \fIwidth\fR, + \fBint (*\fR\fIcompar\fR)(const void *, const void *)); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBqsort()\fR function is an implementation of the quick-sort algorithm. It +sorts a table of data in place. The contents of the table are sorted in +ascending order according to the user-supplied comparison function. +.sp +.LP +The \fIbase\fR argument points to the element at the base of the table. The +\fInel\fR argument is the number of elements in the table. The \fIwidth\fR +argument specifies the size of each element in bytes. The \fIcompar\fR +argument is the name of the comparison function, which is called with two +arguments that point to the elements being compared. +.sp +.LP +The function must return an integer less than, equal to, or greater than zero +to indicate if the first argument is to be considered less than, equal to, or +greater than the second argument. +.sp +.LP +The contents of the table are sorted in ascending order according to the user +supplied comparison function. +.SH USAGE +.sp +.LP +The \fBqsort()\fR function safely allows concurrent access by multiple threads +to disjoint data, such as overlapping subtrees or tables. +.SH EXAMPLES +.LP +\fBExample 1 \fRProgram sorts. +.sp +.LP +The following program sorts a simple array: + +.sp +.in +2 +.nf +#include <stdlib.h> +#include <stdio.h> + +static int +intcompare(const void *p1, const void *p2) +{ + int i = *((int *)p1); + int j = *((int *)p2); + + if (i > j) + return (1); + if (i < j) + return (-1); + return (0); +} + +int +main() +{ + int i; + int a[10] = { 9, 8, 7, 6, 5, 4, 3, 2, 1, 0 }; + size_t nelems = sizeof (a) / sizeof (int); + + qsort((void *)a, nelems, sizeof (int), intcompare); + + for (i = 0; i < nelems; i++) { + (void) printf("%d ", a[i]); + } + + (void) printf("\en"); + return (0); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBsort\fR(1), \fBbsearch\fR(3C), \fBlsearch\fR(3C), \fBstring\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +The comparison function need not compare every byte, so arbitrary data may be +contained in the elements in addition to the values being compared. +.sp +.LP +The relative order in the output of two items that compare as equal is +unpredictable. diff --git a/usr/src/man/man3c/raise.3c b/usr/src/man/man3c/raise.3c new file mode 100644 index 0000000000..ef5aa03e97 --- /dev/null +++ b/usr/src/man/man3c/raise.3c @@ -0,0 +1,65 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH raise 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +raise \- send a signal to the executing thread +.SH SYNOPSIS +.LP +.nf +#include <signal.h> + +\fBint\fR \fBraise\fR(\fBint\fR \fIsig\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBraise()\fR function sends the signal \fIsig\fR to the executing thread. +If a signal handler is called, the raise function does not return until after +the signal handler returns. +.sp +.LP +The effect of the raise function is equivalent to calling: +.sp +.in +2 +.nf +pthread_kill(pthread_self(), sig); +.fi +.in -2 + +.sp +.LP +See the \fBpthread_kill\fR(3C) manual page for a detailed list of failure +conditions and the \fBsignal.h\fR(3HEAD) manual page for a list of signals. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is +returned and \fBerrno\fR is set to indicate the error. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_kill\fR(3C), \fBpthread_self\fR(3C), \fBsignal.h\fR(3HEAD), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/rand.3c b/usr/src/man/man3c/rand.3c new file mode 100644 index 0000000000..2d76432f10 --- /dev/null +++ b/usr/src/man/man3c/rand.3c @@ -0,0 +1,89 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rand 3C "19 May 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +rand, srand, rand_r \- simple random-number generator +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBint\fR \fBrand\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBsrand\fR(\fBunsigned int\fR \fIseed\fR); +.fi + +.LP +.nf +\fBint\fR \fBrand_r\fR(\fBunsigned int *\fR\fIseed\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBrand()\fR function uses a multiplicative congruential random-number +generator with period 2^32 that returns successive pseudo-random numbers in the +range of 0 to \fBRAND_MAX\fR (defined in <\fBstdlib.h\fR>). +.sp +.LP +The \fBsrand()\fR function uses the argument \fIseed\fR as a seed for a new +sequence of pseudo-random numbers to be returned by subsequent calls to +\fBrand()\fR. If \fBsrand()\fR is then called with the same \fIseed\fR value, +the sequence of pseudo-random numbers will be repeated. If \fBrand()\fR is +called before any calls to \fBsrand()\fR have been made, the same sequence will +be generated as when \fBsrand()\fR is first called with a \fIseed\fR value of +1. +.sp +.LP +The \fBrand_r()\fR function has the same functionality as \fBrand()\fR except +that a pointer to a seed \fIseed\fR must be supplied by the caller. If +\fBrand_r()\fR is called with the same initial value for the object pointed to +by seed and that object is not modified between successive calls to +\fBrand_r()\fR, the same sequence as that produced by calls to \fBrand()\fR +will be generated. +.sp +.LP +The \fBrand()\fR and \fBsrand()\fR functions provide per-process pseudo-random +streams shared by all threads. The same effect can be achieved if all threads +call \fBrand_r()\fR with a pointer to the same seed object. The \fBrand_r()\fR +function allows a thread to generate a private pseudo-random stream by having +the seed object be private to the thread. +.SH USAGE +.sp +.LP +The spectral properties of \fBrand()\fR are limited. The \fBdrand48\fR(3C) +function provides a better, more elaborate random-number generator. +.sp +.LP +When compiling multithreaded applications, the \fB_REENTRANT\fR flag must be +defined on the compile line. This flag should be used only in multithreaded +applications. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBdrand48\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/random.3c b/usr/src/man/man3c/random.3c new file mode 100644 index 0000000000..bb4f3598d0 --- /dev/null +++ b/usr/src/man/man3c/random.3c @@ -0,0 +1,215 @@ +'\" te +.\" Copyright (c) 1983 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, +.\" X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.TH random 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +random, srandom, initstate, setstate \- pseudorandom number functions +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBlong\fR \fBrandom\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBsrandom\fR(\fBunsigned int\fR \fIseed\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBinitstate\fR(\fBunsigned int\fR \fIseed\fR, \fBchar\fR \fI*state\fR, \fBsize_t\fR \fIsize\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBsetstate\fR(\fBconst char *\fR\fIstate\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBrandom()\fR function uses a nonlinear additive feedback random-number +generator employing a default state array size of 31 long integers to return +successive pseudo-random numbers in the range from 0 to 2^31 \(mi1. The period +of this random-number generator is approximately 16 x (2^31 \(mi1). The size of +the state array determines the period of the random-number generator. +Increasing the state array size increases the period. +.sp +.LP +The \fBsrandom()\fR function initializes the current state array using the +value of \fIseed\fR. +.sp +.LP +The \fBrandom()\fR and \fBsrandom()\fR functions have (almost) the same calling +sequence and initialization properties as \fBrand()\fR and \fBsrand()\fR (see +\fBrand\fR(3C)). The difference is that \fBrand\fR(3C) produces a much less +random sequence\(emin fact, the low dozen bits generated by rand go through a +cyclic pattern. All the bits generated by \fBrandom()\fR are usable. +.sp +.LP +The algorithm from \fBrand()\fR is used by \fBsrandom()\fR to generate the 31 +state integers. Because of this, different \fBsrandom()\fR seeds often produce, +within an offset, the same sequence of low order bits from \fBrandom()\fR. If +low order bits are used directly, \fBrandom()\fR should be initialized with +\fBsetstate()\fR using high quality random values. +.sp +.LP +Unlike \fBsrand()\fR, \fBsrandom()\fR does not return the old seed because the +amount of state information used is much more than a single word. Two other +routines are provided to deal with restarting/changing random number +generators. With 256 bytes of state information, the period of the +random-number generator is greater than 2^69, which should be sufficient for +most purposes. +.sp +.LP +Like \fBrand\fR(3C), \fBrandom()\fR produces by default a sequence of numbers +that can be duplicated by calling \fBsrandom()\fR with 1 as the seed. +.sp +.LP +The \fBinitstate()\fR and \fBsetstate()\fR functions handle restarting and +changing random-number generators. The \fBinitstate()\fR function allows a +state array, pointed to by the \fIstate\fR argument, to be initialized for +future use. The \fBsize\fR argument, which specifies the size in bytes of the +state array, is used by \fBinitstate()\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. For values smaller than 8, \fBrandom()\fR uses a simple linear +congruential random number generator. The \fIseed\fR argument specifies a +starting point for the random-number sequence and provides for restarting at +the same point. The \fBinitstate()\fR function returns a pointer to the +previous state information array. +.sp +.LP +If \fBinitstate()\fR has not been called, then \fBrandom()\fR behaves as though +\fBinitstate()\fR had been called with \fIseed\fR\|=\|1 and \fIsize\fR\|=\|128. +.sp +.LP +If \fBinitstate()\fR is called with \fIsize\fR\|<\|8, then \fBrandom()\fR uses +a simple linear congruential random number generator. +.sp +.LP +Once a state has been initialized, \fBsetstate()\fR allows switching between +state arrays. The array defined by the \fIstate\fR argument is used for further +random-number generation until \fBinitstate()\fR is called or \fBsetstate()\fR +is called again. The \fBsetstate()\fR function returns a pointer to the +previous state array. +.SH RETURN VALUES +.sp +.LP +The \fBrandom()\fR function returns the generated pseudo-random number. +.sp +.LP +The \fBsrandom()\fR function returns no value. +.sp +.LP +Upon successful completion, \fBinitstate()\fR and \fBsetstate()\fR return a +pointer to the previous state array. Otherwise, a null pointer is returned. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH USAGE +.sp +.LP +After initialization, a state array can be restarted at a different point in +one of two ways: +.RS +4 +.TP +.ie t \(bu +.el o +The \fBinitstate()\fR function can be used, with the desired seed, state array, +and size of the array. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The \fBsetstate()\fR function, with the desired state, can be used, followed by +\fBsrandom()\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. +.RE +.SH EXAMPLES +.LP +\fBExample 1 \fRInitialize an array. +.sp +.LP +The following example demonstrates the use of \fBinitstate()\fR to intialize an +array. It also demonstrates how to initialize an array and pass it to +\fBsetstate()\fR. + +.sp +.in +2 +.nf +# include <stdlib.h> +static unsigned int state0[32]; +static unsigned int state1[32] = { + 3, + 0x9a319039, 0x32d9c024, 0x9b663182, 0x5da1f342, + 0x7449e56b, 0xbeb1dbb0, 0xab5c5918, 0x946554fd, + 0x8c2e680f, 0xeb3d799f, 0xb11ee0b7, 0x2d436b86, + 0xda672e2a, 0x1588ca88, 0xe369735d, 0x904f35f7, + 0xd7158fd6, 0x6fa6f051, 0x616e6b96, 0xac94efdc, + 0xde3b81e0, 0xdf0a6fb5, 0xf103bc02, 0x48f340fb, + 0x36413f93, 0xc622c298, 0xf5a42ab8, 0x8a88d77b, + 0xf5ad9d0e, 0x8999220b, 0x27fb47b9 + }; +main() { + unsigned seed; + int n; + seed = 1; + n = 128; + (void)initstate(seed, (char *)state0, n); + printf("random() = %d0\en", random()); + (void)setstate((char *)state1); + printf("random() = %d0\en", random()); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSee \fBNOTES\fR below. +.TE + +.SH SEE ALSO +.sp +.LP +\fBdrand48\fR(3C), \fBrand\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +The \fBrandom()\fR and \fBsrandom()\fR functions are unsafe in multithreaded +applications. +.sp +.LP +Use of these functions in multithreaded applications is unsupported. +.sp +.LP +For \fBinitstate()\fR and \fBsetstate()\fR, the \fIstate\fR argument must be +aligned on an \fBint\fR boundary. +.sp +.LP +Newer and better performing random number generators such as \fBaddrans()\fR +and \fBlcrans()\fR are available with the SUNWspro package. diff --git a/usr/src/man/man3c/rctl_walk.3c b/usr/src/man/man3c/rctl_walk.3c new file mode 100644 index 0000000000..eb9698e0fc --- /dev/null +++ b/usr/src/man/man3c/rctl_walk.3c @@ -0,0 +1,112 @@ +'\" te +.\" Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rctl_walk 3C " 2001" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +rctl_walk \- visit registered rctls on current system +.SH SYNOPSIS +.LP +.nf +#include <rctl.h> + +\fBint\fR \fBrctl_walk\fR(\fBint (*\fR\fIcallback\fR)(const char *\fIrctlname\fR, void *\fIwalk_data\fR), + \fBvoid *\fR\fIinit_data\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBrctl_walk()\fR function provides a mechanism for the application author +to examine all active resource controls (rctls) on the current system. The +\fIcallback\fR function provided by the application is given the name of an +rctl at each invocation and can use the \fIwalk_data\fR to record its own +state. The callback function should return non-zero if it encounters an error +condition or attempts to terminate the walk prematurely; otherwise the callback +function should return 0. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBrctl_walk()\fR returns 0. It returns \(mi1 if +the \fIcallback\fR function returned a non-zero value or if the walk +encountered an error, in which case \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBrctl_walk()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +There is insufficient memory available to set up the initial data for the walk. +.RE + +.sp +.LP +Other returned error values are presumably caused by the \fIcallback\fR +function. +.SH EXAMPLES +.LP +\fBExample 1 \fRCount the number of rctls available on the system. +.sp +.LP +The following example counts the number of resource controls on the system. + +.sp +.in +2 +.nf +#include <sys/types.h> +#include <rctl.h> +#include <stdio.h> + +typedef struct wdata { + uint_t count; +} wdata_t; + +wdata_t total_count; + +int +simple_callback(const char *name, void *pvt) +{ + wdata_t *w = (wdata_t *)pvt; + w->count++; + return (0); +} + +\&... + +total_count.count = 0; +errno = 0; +if (rctl_walk(simple_callback, &total_count)) == 0) + (void) printf("count = %u\en", total_count.count); +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBsetrctl\fR(2), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/rctlblk_set_value.3c b/usr/src/man/man3c/rctlblk_set_value.3c new file mode 100644 index 0000000000..a89ac7fb5c --- /dev/null +++ b/usr/src/man/man3c/rctlblk_set_value.3c @@ -0,0 +1,482 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rctlblk_set_value 3C "15 May 2006" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +rctlblk_set_value, rctlblk_get_firing_time, rctlblk_get_global_action, +rctlblk_get_global_flags, rctlblk_get_local_action, rctlblk_get_local_flags, +rctlblk_get_privilege, rctlblk_get_recipient_pid, rctlblk_get_value, +rctlblk_get_enforced_value, rctlblk_set_local_action, rctlblk_set_local_flags, +rctlblk_set_privilege, rctlblk_set_recipient_pid, rctlblk_size \- manipulate +resource control blocks +.SH SYNOPSIS +.LP +.nf +#include <rctl.h> + +\fBhrtime_t\fR \fBrctlblk_get_firing_time\fR(\fBrctlblk_t *\fR\fIrblk\fR); +.fi + +.LP +.nf +\fBint\fR \fBrctlblk_get_global_action\fR(\fBrctlblk_t *\fR\fIrblk\fR); +.fi + +.LP +.nf +\fBint\fR \fBrctlblk_get_global_flags\fR(\fBrctlblk_t *\fR\fIrblk\fR); +.fi + +.LP +.nf +\fBint\fR \fBrctlblk_get_local_action\fR(\fBrctlblk_t *\fR\fIrblk\fR, \fBint *\fR\fIsignalp\fR); +.fi + +.LP +.nf +\fBint\fR \fBrctlblk_get_local_flags\fR(\fBrctlblk_t *\fR\fIrblk\fR); +.fi + +.LP +.nf +\fBrctl_priv_t\fR \fBrctlblk_get_privilege\fR(\fBrctlblk_t *\fR\fIrblk\fR); +.fi + +.LP +.nf +\fBid_t\fR \fBrctlblk_get_recipient_pid\fR(\fBrctlblk_t *\fR\fIrblk\fR); +.fi + +.LP +.nf +\fBrctl_qty_t\fR \fBrctlblk_get_value\fR(\fBrctlblk_t *\fR\fIrblk\fR); +.fi + +.LP +.nf +\fBrctl_qty_t\fR \fBrctlblk_get_enforced_value\fR(\fBrctlblk_t *\fR\fIrblk\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBrctlblk_set_local_action\fR(\fBrctlblk_t *\fR\fIrblk\fR, \fBrctl_action_t\fR \fIaction\fR, + \fBint\fR \fIsignal\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBrctlblk_set_local_flags\fR(\fBrctlblk_t *\fR\fIrblk\fR, \fBint\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBrctlblk_set_privilege\fR(\fBrctlblk_t *\fR\fIrblk\fR, \fBrctl_priv_t\fR \fIprivilege\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBrctlblk_set_value\fR(\fBrctlblk_t *\fR\fIrblk\fR, \fBrctl_qty_t\fR \fIvalue\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBrctlblk_set_recipient_pid\fR(\fBid_t\fR\fIpid\fR); +.fi + +.LP +.nf +\fBsize_t\fR \fBrctlblk_size\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The resource control block routines allow the establishment or retrieval of +values from a resource control block used to transfer information using the +\fBgetrctl\fR(2) and \fBsetrctl\fR(2) functions. Each of the routines accesses +or sets the resource control block member corresponding to its name. Certain +of these members are read-only and do not possess set routines. +.sp +.LP +The firing time of a resource control block is 0 if the resource control +action-value has not been exceeded for its lifetime on the process. Otherwise +the firing time is the value of \fBgethrtime\fR(3C) at the moment the action on +the resource control value was taken. +.sp +.LP +The global actions and flags are the action and flags set by \fBrctladm\fR(1M). +These values cannot be set with \fBsetrctl\fR(2). Valid global actions are +listed in the table below. Global flags are generally a published property of +the control and are not modifiable. +.sp +.ne 2 +.mk +.na +\fB\fBRCTL_GLOBAL_DENY_ALWAYS\fR\fR +.ad +.RS 28n +.rt +The action taken when a control value is exceeded on this control will always +include denial of the resource. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRCTL_GLOBAL_DENY_NEVER\fR\fR +.ad +.RS 28n +.rt +The action taken when a control value is exceeded on this control will always +exclude denial of the resource; the resource will always be granted, although +other actions can also be taken. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRCTL_GLOBAL_SIGNAL_NEVER\fR\fR +.ad +.RS 28n +.rt +No signal actions are permitted on this control. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRCTL_GLOBAL_CPU_TIME\fR\fR +.ad +.RS 28n +.rt +The valid signals available as local actions include the \fBSIGXCPU\fR signal. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRCTL_GLOBAL_FILE_SIZE\fR\fR +.ad +.RS 28n +.rt +The valid signals available as local actions include the \fBSIGXFSZ\fR signal. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRCTL_GLOBAL_INFINITE\fR\fR +.ad +.RS 28n +.rt +This resource control supports the concept of an unlimited value; generally +true only of accumulation-oriented resources, such as CPU time. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRCTL_GLOBAL_LOWERABLE\fR\fR +.ad +.RS 28n +.rt +Non-privileged callers are able to lower the value of privileged resource +control values on this control. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRCTL_GLOBAL_NOACTION\fR\fR +.ad +.RS 28n +.rt +No global action will be taken when a resource control value is exceeded on +this control. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRCTL_GLOBAL_NOBASIC\fR\fR +.ad +.RS 28n +.rt +No values with the \fBRCPRIV_BASIC\fR privilege are permitted on this control. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRCTL_GLOBAL_SYSLOG\fR\fR +.ad +.RS 28n +.rt +A standard message will be logged by the \fBsyslog\fR(3C) facility when any +resource control value on a sequence associated with this control is exceeded. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRCTL_GLOBAL_SYSLOG_NEVER\fR\fR +.ad +.RS 28n +.rt +The resource control does not support the \fBsyslog()\fR global action. +Exceeding a resource control value on this control will not result in a message +logged by the \fBsyslog()\fR facility. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRCTL_GLOBAL_UNOBSERVABLE\fR\fR +.ad +.RS 28n +.rt +The resource control (generally on a task- or project-related control) does not +support observational control values. An \fBRCPRIV_BASIC\fR privileged control +value placed by a process on the task or process will generate an action only +if the value is exceeded by that process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRCTL_GLOBAL_BYTES\fR\fR +.ad +.RS 28n +.rt +This resource control represents a number of bytes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRCTL_GLOBAL_SECONDS\fR\fR +.ad +.RS 28n +.rt +This resource control represents a quantity of time in seconds. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRCTL_GLOBAL_COUNT\fR\fR +.ad +.RS 28n +.rt +This resource control represents an integer count. +.RE + +.sp +.LP +The local action and flags are those on the current resource control value +represented by this resource control block. Valid actions and flags are listed +in the table below. In the case of \fBRCTL_LOCAL_SIGNAL\fR, the second argument +to \fBrctlblk_set_local_action()\fR contains the signal to be sent. Similarly, +the signal to be sent is copied into the integer location specified by the +second argument to \fBrctlblk_get_local_action()\fR. A restricted set of +signals is made available for normal use by the resource control facility: +\fBSIGBART\fR, \fBSIGXRES\fR, \fBSIGHUP\fR, \fBSIGSTOP\fR, \fBSIGTERM\fR, and +\fBSIGKILL\fR. Other signals are permitted due to global properties of a +specific control. Calls to \fBsetrctl()\fR with illegal signals will fail. +.sp +.ne 2 +.mk +.na +\fB\fBRCTL_LOCAL_DENY\fR\fR +.ad +.RS 23n +.rt +When this resource control value is encountered, the request for the resource +will be denied. Set on all values if \fBRCTL_GLOBAL_DENY_ALWAYS\fR is set for +this control; cleared on all values if \fBRCTL_GLOBAL_DENY_NEVER\fR is set for +this control. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRCTL_LOCAL_MAXIMAL\fR\fR +.ad +.RS 23n +.rt +This resource control value represents a request for the maximum amount of +resource for this control. If \fBRCTL_GLOBAL_INFINITE\fR is set for this +resource control, \fBRCTL_LOCAL_MAXIMAL\fR indicates an unlimited resource +control value, one that will never be exceeded. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRCTL_LOCAL_NOACTION\fR\fR +.ad +.RS 23n +.rt +No local action will be taken when this resource control value is exceeded. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRCTL_LOCAL_SIGNAL\fR\fR +.ad +.RS 23n +.rt +The specified signal, sent by \fBrctlblk_set_local_action()\fR, will be sent to +the process that placed this resource control value in the value sequence. This +behavior is also true for signal actions on project and task resource controls. +The specified signal is sent only to the recipient process, not all processes +within the project or task. +.RE + +.sp +.LP +The \fBrctlblk_get_recipient_pid()\fR function returns the value of the process +ID that placed the resource control value for basic rctls. For privileged or +system rctls, \fBrctlblk_get_recipient_pid()\fR returns -1. +.sp +.LP +The \fBrctlblk_set_recipient_pid()\fR function sets the recipient \fIpid\fR for +a basic rctl. When \fBsetrctl\fR(2) is called with the flag +\fBRCTL_USE_RECIPIENT_PID\fR, this \fIpid\fR is used. Otherwise, the PID of the +calling process is used. Only privileged users can set the recipient PID to one +other than the PID of the calling process. Process-scoped rctls must have a +recipient PID that matches the PID of the calling process. +.sp +.LP +The \fBrctlblk_get_privilege()\fR function returns the privilege of the +resource control block. Valid privileges are \fBRCPRIV_BASIC\fR, +\fBRCPRIV_PRIVILEGED\fR, and \fBRCPRIV_SYSTEM\fR. System resource controls are +read-only. Privileged resource controls require the {\fBPRIV_SYS_RESOURCE\fR} +privilege to write, unless the \fBRCTL_GLOBAL_LOWERABLE\fR global flag is set, +in which case unprivileged applications can lower the value of a privileged +control. +.sp +.LP +The \fBrctlblk_get_value()\fR and \fBrctlblk_set_value()\fR functions return or +establish the enforced value associated with the resource control. In cases +where the process, task, or project associated with the control possesses fewer +capabilities than allowable by the current value, the value returned by +\fBrctlblk_get_enforced_value()\fR will differ from that returned by +\fBrctlblk_get_value()\fR. This capability difference arises with processes +using an address space model smaller than the maximum address space model +supported by the system. +.sp +.LP +The \fBrctlblk_size()\fR function returns the size of a resource control block +for use in memory allocation. The \fBrctlblk_t *\fR type is an opaque pointer +whose size is not connected with that of the resource control block itself. Use +of \fBrctlblk_size()\fR is illustrated in the example below. +.SH RETURN VALUES +.sp +.LP +The various set routines have no return values. Incorrectly composed resource +control blocks will generate errors when used with \fBsetrctl\fR(2) or +\fBgetrctl\fR(2). +.SH ERRORS +.sp +.LP +No error values are returned. Incorrectly constructed resource control blocks +will be rejected by the system calls. +.SH EXAMPLES +.LP +\fBExample 1 \fRDisplay the contents of a fetched resource control block. +.sp +.LP +The following example displays the contents of a fetched resource control +block. + +.sp +.in +2 +.nf +#include <rctl.h> +#include <stdio.h> +#include <stdlib.h> + +rctlblk_t *rblk; +int rsignal; +int raction; + +if ((rblk = malloc(rctlblk_size())) == NULL) { + (void) perror("rblk malloc"); + exit(1); +} + +if (getrctl("process.max-cpu-time", NULL, rblk, RCTL_FIRST) == -1) { + (void) perror("getrctl"); + exit(1); +} + +main() +{ + raction = rctlblk_get_local_action(rblk, &rsignal), + (void) printf("Resource control for %s\en", + "process.max-cpu-time"); + (void) printf("Process ID: %d\en", + rctlblk_get_recipient_pid(rblk)); + (void) printf("Privilege: %x\en" + rctlblk_get_privilege(rblk)); + (void) printf("Global flags: %x\en" + rctlblk_get_global_flags(rblk)); + (void) printf("Global actions: %x\en" + rctlblk_get_global_action(rblk)); + (void) printf("Local flags: %x\en" + rctlblk_get_local_flags(rblk)); + (void) printf("Local action: %x (%d)\en" + raction, raction == RCTL_LOCAL_SIGNAL ? rsignal : 0); + (void) printf("Value: %llu\en", + rctlblk_get_value(rblk)); + (void) printf("\tEnforced value: %llu\en", + rctlblk_get_enforced_value(rblk)); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBrctladm\fR(1M), \fBgetrctl\fR(2), \fBsetrctl\fR(2), \fBgethrtime\fR(3C), +\fBattributes\fR(5) diff --git a/usr/src/man/man3c/re_comp.3c b/usr/src/man/man3c/re_comp.3c new file mode 100644 index 0000000000..bda9d7944e --- /dev/null +++ b/usr/src/man/man3c/re_comp.3c @@ -0,0 +1,86 @@ +'\" te +.\" Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH re_comp 3C "26 Feb 1997" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +re_comp, re_exec \- compile and execute regular expressions +.SH SYNOPSIS +.LP +.nf +#include <re_comp.h> + +\fBchar *\fR\fBre_comp\fR(\fBconst char *\fR\fIstring\fR); +.fi + +.LP +.nf +\fBint\fR \fBre_exec\fR(\fBconst char *\fR\fIstring\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBre_comp()\fR function converts a regular expression string (RE) into an +internal form suitable for pattern matching. The \fBre_exec()\fR function +compares the string pointed to by the \fIstring\fR argument with the last +regular expression passed to \fBre_comp()\fR. +.sp +.LP +If \fBre_comp()\fR is called with a null pointer argument, the current regular +expression remains unchanged. +.sp +.LP +Strings passed to both \fBre_comp()\fR and \fBre_exec()\fR must be terminated +by a null byte, and may include \fBNEWLINE\fR characters. +.sp +.LP +The \fBre_comp()\fR and \fBre_exec()\fR functions support \fIsimple regular +expressions\fR, which are defined on the \fBregexp\fR(5) manual page. The +regular expressions of the form \fB\e{\fRm\fB\e}\fR, \fB\e{\fRm,\fB\e}\fR, or +\fB\e{\fRm,n\fB\e}\fR are not supported. +.SH RETURN VALUES +.sp +.LP +The \fBre_comp()\fR function returns a null pointer when the string pointed to +by the \fIstring\fR argument is successfully converted. Otherwise, a pointer +to one of the following error message strings is returned: +.sp +.in +2 +.nf +No previous regular expression +Regular expression too long +unmatched \e\|( +missing ] +too many \e\|(\|\e\|) pairs +unmatched \e\|) +.fi +.in -2 + +.sp +.LP +Upon successful completion, \fBre_exec()\fR returns \fB1\fR if \fIstring\fR +matches the last compiled regular expression. Otherwise, \fBre_exec()\fR +returns \fB0\fR if \fIstring\fR fails to match the last compiled regular +expression, and \fB\(mi1\fR if the compiled regular expression is invalid +(indicating an internal error). +.SH ERRORS +.sp +.LP +No errors are defined. +.SH USAGE +.sp +.LP +For portability to implementations conforming to X/Open standards prior to SUS, +\fBregcomp\fR(3C) and \fBregexec\fR(3C) are preferred to these functions. See +\fBstandards\fR(5). +.SH SEE ALSO +.sp +.LP +\fBgrep\fR(1), \fBregcmp\fR(1), \fBregcmp\fR(3C), \fBregcomp\fR(3C), +\fBregexec\fR(3C), \fBregexpr\fR(3GEN), \fBregexp\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/readdir.3c b/usr/src/man/man3c/readdir.3c new file mode 100644 index 0000000000..5b6d2b25e2 --- /dev/null +++ b/usr/src/man/man3c/readdir.3c @@ -0,0 +1,304 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH readdir 3C "26 Jun 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +readdir, readdir_r \- read directory +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <dirent.h> + +\fBstruct dirent *\fR\fBreaddir\fR(\fBDIR *\fR\fIdirp\fR); +.fi + +.LP +.nf +\fBstruct dirent *\fR\fBreaddir_r\fR(\fBDIR *\fR\fIdirp\fR, \fBstruct dirent *\fR\fIentry\fR); +.fi + +.SS "Standard conforming" +.LP +.nf +cc [ \fIflag\fR... ] \fIfile\fR... \fB-D_POSIX_PTHREAD_SEMANTICS\fR [ \fIlibrary\fR... ] + +\fBint\fR \fBreaddir_r\fR(\fBDIR *restrict\fR \fIdirp\fR, \fBstruct dirent *restrict\fR \fIentry\fR, + \fBstruct dirent **restrict\fR \fIresult\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The type \fBDIR\fR, which is defined in the header <\fBdirent.h\fR>, represents +a \fIdirectory stream\fR, which is an ordered sequence of all the directory +entries in a particular directory. Directory entries represent files. Files can +be removed from a directory or added to a directory asynchronously to the +operation of \fBreaddir()\fR and \fBreaddir_r()\fR. +.SS "\fBreaddir()\fR" +.sp +.LP +The \fBreaddir()\fR function returns a pointer to a structure representing the +directory entry at the current position in the directory stream specified by +the argument \fIdirp\fR, and positions the directory stream at the next entry. +It returns a null pointer upon reaching the end of the directory stream. The +structure \fBdirent\fR defined by the \fB<dirent.h>\fR header describes a +directory entry. +.sp +.LP +The \fBreaddir()\fR function will not return directory entries containing empty +names. If entries for . (dot) or .. (dot-dot) exist, one entry will be returned +for dot and one entry will be returned for dot-dot; otherwise they will not be +returned. +.sp +.LP +The pointer returned by \fBreaddir()\fR points to data that can be overwritten +by another call to \fBreaddir()\fR on the same directory stream. These data are +not overwritten by another call to \fBreaddir()\fR on a different directory +stream. +.sp +.LP +If a file is removed from or added to the directory after the most recent call +to \fBopendir\fR(3C) or \fBrewinddir\fR(3C), whether a subsequent call to +\fBreaddir()\fR returns an entry for that file is unspecified. +.sp +.LP +The \fBreaddir()\fR function can buffer several directory entries per actual +read operation. It marks for update the \fBst_atime\fR field of the directory +each time the directory is actually read. +.sp +.LP +After a call to \fBfork\fR(2), either the parent or child (but not both) can +continue processing the directory stream using \fBreaddir()\fR, +\fBrewinddir()\fR or \fBseekdir\fR(3C). If both the parent and child processes +use these functions, the result is undefined. +.sp +.LP +If the entry names a symbolic link, the value of the \fBd_ino\fR member is +unspecified. +.SS "\fBreaddir_r()\fR" +.sp +.LP +Unless the end of the directory stream has been reached or an error occurred, +the \fBreaddir_r()\fR function initializes the \fBdirent\fR structure +referenced by \fBentry\fR to represent the directory entry at the current +position in the directory stream referred to by \fIdirp\fR, and positions the +directory stream at the next entry. +.sp +.LP +The caller must allocate storage pointed to by \fIentry\fR to be large enough +for a \fBdirent\fR structure with an array of \fBchar\fR \fBd_name\fR member +containing at least \fBNAME_MAX\fR (that is, \fBpathconf(directory, +_PC_NAME_MAX\fR)) plus one elements. (\fB_PC_NAME_MAX\fR is defined in +<\fBunistd.h\fR>.) +.sp +.LP +The \fBreaddir_r()\fR function will not return directory entries containing +empty names. It is unspecified whether entries are returned for . (dot) or .. +(dot-dot). +.sp +.LP +If a file is removed from or added to the directory after the most recent call +to \fBopendir()\fR or \fBrewinddir()\fR, whether a subsequent call to +\fBreaddir_r()\fR returns an entry for that file is unspecified. +.sp +.LP +The \fBreaddir_r()\fR function can buffer several directory entries per actual +read operation. It marks for update the \fBst_atime\fR field of the directory +each time the directory is actually read. +.sp +.LP +The standard-conforming version (see \fBstandards\fR(5)) of the +\fBreaddir_r()\fR function performs all of the actions described above and sets +the pointer pointed to by \fIresult\fR. If a directory entry is returned, the +pointer will be set to the same value as the \fIentry\fR argument; otherwise, +it will be set to \fINULL\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBreaddir()\fR and the default \fBreaddir_r()\fR +return a pointer to an object of type \fBstruct dirent\fR. When an error is +encountered, a null pointer is returned and \fBerrno\fR is set to indicate the +error. When the end of the directory is encountered, a null pointer is returned +and \fBerrno\fR is not changed. +.sp +.LP +The standard-conforming \fBreaddir_r()\fR returns \fB0\fR if the end of the +directory is encountered or a directory entry is stored in the structure +referenced by \fIentry\fR. Otherwise, an error number is returned to indicate +the failure. +.SH ERRORS +.sp +.LP +The \fBreaddir()\fR and \fBreaddir_r()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEOVERFLOW\fR\fR +.ad +.RS 13n +.rt +One of the values in the structure to be returned cannot be represented +correctly. +.RE + +.sp +.LP +The \fBreaddir()\fR and \fBreaddir_r()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIdirp\fR argument does not refer to an open directory stream. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 10n +.rt +The current position of the directory stream is invalid. +.RE + +.SH USAGE +.sp +.LP +The \fBreaddir()\fR and \fBreaddir_r()\fR functions should be used in +conjunction with \fBopendir()\fR, \fBclosedir()\fR, and \fBrewinddir()\fR to +examine the contents of the directory. Since \fBreaddir()\fR and the default +\fBreaddir_r()\fR return a null pointer both at the end of the directory and on +error, an application wanting to check for error situations should set +\fBerrno\fR to 0 before calling either of these functions. If \fBerrno\fR is +set to non-zero on return, an error occurred. +.sp +.LP +It is safe to use \fBreaddir()\fR in a threaded application, so long as only +one thread reads from the directory stream at any given time. The +\fBreaddir()\fR function is generally preferred over the \fBreaddir_r()\fR +function. +.sp +.LP +The standard-conforming \fBreaddir_r()\fR returns the error number if an error +occurred. It returns 0 on success (including reaching the end of the directory +stream). +.sp +.LP +The \fBreaddir()\fR and \fBreaddir_r()\fR functions have transitional +interfaces for 64-bit file offsets. See \fBlf64\fR(5). +.SH EXAMPLES +.LP +\fBExample 1 \fRSearch the current directory for the entry \fIname\fR. +.sp +.LP +The following sample program will search the current directory for each of the +arguments supplied on the command line: + +.sp +.in +2 +.nf +#include <sys/types.h> +#include <dirent.h> +#include <errno.h> +#include <stdio.h> +#include <strings.h> + +static void lookup(const char *arg) +{ + DIR *dirp; + struct dirent *dp; + + if ((dirp = opendir(".")) == NULL) { + perror("couldn't open '.'"); + return; + } + + do { + errno = 0; + if ((dp = readdir(dirp)) != NULL) { + if (strcmp(dp->d_name, arg) != 0) + continue; + + (void) printf("found %s\en", arg); + (void) closedir(dirp); + return; + } + } while (dp != NULL); + + if (errno != 0) + perror("error reading directory"); + else + (void) printf("failed to find %s\en", arg); + (void) closedir(dirp); + return; +} + +int main(int argc, char *argv[]) +{ + int i; + for (i = 1; i < argc; i++) + lookup(argv[i]); + return (0); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSee below. +.TE + +.sp +.LP +The \fBreaddir()\fR function is Unsafe. The \fBreaddir_r()\fR function is Safe. +.SH SEE ALSO +.sp +.LP +\fBfork\fR(2), \fBlstat\fR(2), \fBsymlink\fR(2), \fBIntro\fR(3), +\fBclosedir\fR(3C), \fBopendir\fR(3C), \fBrewinddir\fR(3C), \fBscandir\fR(3C), +\fBseekdir\fR(3C), \fBattributes\fR(5), \fBlf64\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +When compiling multithreaded programs, see the \fBMULTITHREADED APPLICATIONS\fR +section of \fBIntro\fR(3). +.sp +.LP +Solaris 2.4 and earlier releases provided a \fBreaddir_r()\fR interface as +specified in POSIX.1c Draft 6. The final POSIX.1c standard changed the +interface as described above. Support for the Draft 6 interface is provided for +compatibility only and might not be supported in future releases. New +applications and libraries should use the standard-conforming interface. +.sp +.LP +For POSIX.1c-conforming applications, the \fB_POSIX_PTHREAD_SEMANTICS\fR and +\fB_REENTRANT\fR flags are automatically turned on by defining the +\fB_POSIX_C_SOURCE\fR flag with a value >= 199506L. diff --git a/usr/src/man/man3c/realpath.3c b/usr/src/man/man3c/realpath.3c new file mode 100644 index 0000000000..91142373ed --- /dev/null +++ b/usr/src/man/man3c/realpath.3c @@ -0,0 +1,194 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH realpath 3C "9 Oct 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +realpath \- resolve pathname +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBchar *\fR\fBrealpath\fR(\fBconst char *restrict\fR \fIfile_name\fR, + \fBchar *restrict\fR \fIresolved_name\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBrealpath()\fR function derives, from the pathname pointed to by +\fIfile_name\fR, an absolute pathname that names the same file, whose +resolution does not involve "\fB\&.\fR", "\fB\&..\fR", or symbolic links. The +generated pathname is stored as a null-terminated string, up to a maximum of +{\fBPATH_MAX\fR} bytes (defined in \fBlimits.h\fR(3HEAD)), in the buffer +pointed to by \fIresolved_name\fR. +.SH RETURN VALUES +.sp +.LP +On successful completion, \fBrealpath()\fR returns a pointer to the resolved +name. Otherwise, \fBrealpath()\fR returns a null pointer and sets \fBerrno\fR +to indicate the error, and the contents of the buffer pointed to by +\fIresolved_name\fR are left in an indeterminate state. +.SH ERRORS +.sp +.LP +The \fBrealpath()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 16n +.rt +Read or search permission was denied for a component of \fIfile_name\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 16n +.rt +Either the \fIfile_name\fR or \fIresolved_name\fR argument is a null pointer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 16n +.rt +An error occurred while reading from the file system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBELOOP\fR\fR +.ad +.RS 16n +.rt +Too many symbolic links were encountered in resolving \fIfile_name\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBELOOP\fR\fR +.ad +.RS 16n +.rt +A loop exists in symbolic links encountered during resolution of the +\fIfile_name\fR argument. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +The \fIfile_name\fR argument is longer than {\fBPATH_MAX\fR} or a pathname +component is longer than {\fBNAME_MAX\fR}. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 16n +.rt +A component of \fIfile_name\fR does not name an existing file or +\fIfile_name\fR points to an empty string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTDIR\fR\fR +.ad +.RS 16n +.rt +A component of the path prefix is not a directory. +.RE + +.sp +.LP +The \fBrealpath()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +Pathname resolution of a symbolic link produced an intermediate result whose +length exceeds {\fBPATH_MAX\fR}. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 16n +.rt +Insufficient storage space is available. +.RE + +.SH USAGE +.sp +.LP +The \fBrealpath()\fR function operates on null-terminated strings. +.sp +.LP +Execute permission is required for all the directories in the given and the +resolved path. +.sp +.LP +The \fBrealpath()\fR function might fail to return to the current directory if +an error occurs. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgetcwd\fR(3C), \fBlimits.h\fR(3HEAD), \fBsysconf\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/reboot.3c b/usr/src/man/man3c/reboot.3c new file mode 100644 index 0000000000..0ed8c30bc9 --- /dev/null +++ b/usr/src/man/man3c/reboot.3c @@ -0,0 +1,103 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH reboot 3C "22 Mar 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +reboot \- reboot system or halt processor +.SH SYNOPSIS +.LP +.nf +#include <sys/reboot.h> + +\fBint\fR \fBreboot\fR(\fBint\fR \fIhowto\fR, \fBchar *\fR\fIbootargs\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBreboot()\fR function reboots the system. The \fIhowto\fR argument +specifies the behavior of the system while rebooting and is a mask constructed +by a bitwise-inclusive-OR of flags from the following list: +.sp +.ne 2 +.mk +.na +\fB\fBRB_AUTOBOOT\fR\fR +.ad +.RS 15n +.rt +The machine is rebooted from the root filesystem on the default boot device. +This is the default behavior. See \fBboot\fR(1M) and \fBkernel\fR(1M). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRB_HALT\fR\fR +.ad +.RS 15n +.rt +The processor is simply halted; no reboot takes place. This option should be +used with caution. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRB_ASKNAME\fR\fR +.ad +.RS 15n +.rt +Interpreted by the bootstrap program and kernel, causing the user to be asked +for pathnames during the bootstrap. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRB_DUMP\fR\fR +.ad +.RS 15n +.rt +The system is forced to panic immediately without any further processing and a +crash dump is written to the dump device (see \fBdumpadm\fR(1M)) before +rebooting. +.RE + +.sp +.LP +Any other \fIhowto\fR argument causes the kernel file to boot. +.sp +.LP +The interpretation of the \fIbootargs\fR argument is platform-dependent. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBreboot()\fR never returns. Otherwise, +\fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBreboot()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 9n +.rt +The {\fBPRIV_SYS_CONFIG\fR} privilege is not asserted in the effective set of +the calling process. +.RE + +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(1M), \fBboot\fR(1M), \fBdumpadm\fR(1M), \fBhalt\fR(1M), +\fBinit\fR(1M), \fBkernel\fR(1M), \fBreboot\fR(1M), \fBuadmin\fR(2) diff --git a/usr/src/man/man3c/regcmp.3c b/usr/src/man/man3c/regcmp.3c new file mode 100644 index 0000000000..c5773d44bd --- /dev/null +++ b/usr/src/man/man3c/regcmp.3c @@ -0,0 +1,225 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH regcmp 3C "14 Nov 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +regcmp, regex \- compile and execute regular expression +.SH SYNOPSIS +.LP +.nf +#include <libgen.h> + +\fBchar *\fR\fBregcmp\fR(\fBconst char *\fR\fIstring1\fR, /* \fBchar *\fR\fIstring2\fR */ ..., + \fBint\fR /*(\fBchar*\fR)0*/); +.fi + +.LP +.nf +\fBchar *\fR\fBregex\fR(\fBconst char *\fR\fIre\fR, \fBconst char *\fR\fIsubject\fR, + /* \fBchar *\fR\fIret0\fR */ ...); +.fi + +.LP +.nf +extern char *__loc1; +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBregcmp()\fR function compiles a regular expression (consisting of the +concatenated arguments) and returns a pointer to the compiled form. The +\fBmalloc\fR(3C) function is used to create space for the compiled form. It is +the user's responsibility to free unneeded space so allocated. A \fINULL\fR +return from \fBregcmp()\fR indicates an incorrect argument. \fBregcmp\fR(1) has +been written to generally preclude the need for this routine at execution time. +.sp +.LP +The \fBregex()\fR function executes a compiled pattern against the subject +string. Additional arguments are passed to receive values back. The +\fBregex()\fR function returns \fINULL\fR on failure or a pointer to the next +unmatched character on success. A global character pointer \fB__loc1\fR points +to where the match began. The \fBregcmp()\fR and \fBregex()\fR functions were +mostly borrowed from the editor \fBed\fR(1); however, the syntax and semantics +have been changed slightly. The following are the valid symbols and associated +meanings. +.sp +.ne 2 +.mk +.na +\fB\fB[\|]\|*\|.^\fR\fR +.ad +.RS 18n +.rt +This group of symbols retains its meaning as described on the \fBregexp\fR(5) +manual page. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB$\fR\fR +.ad +.RS 18n +.rt +Matches the end of the string; \fB\en\fR matches a newline. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\(mi\fR\fR +.ad +.RS 18n +.rt +Within brackets the minus means \fIthrough\fR. For example, \fB[a\(miz]\fR is +equivalent to \fB[abcd\|.\|.\|.xyz]\fR. The \fB\(mi\fR can appear as itself +only if used as the first or last character. For example, the character class +expression \fB[]\(mi]\fR matches the characters \fB]\fR and \fB\(mi\fR\&. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB+\fR\fR +.ad +.RS 18n +.rt +A regular expression followed by \fB+\fR means \fIone or more times\fR. For +example, \fB[0\(mi9]+\fR is equivalent to \fB[0\(mi9][0\(mi9]*.\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB{\fR\fIm\fR} {\fIm,\fR} {\fIm,u\fR}\fR +.ad +.RS 18n +.rt +Integer values enclosed in \fB{\|}\fR indicate the number of times the +preceding regular expression is to be applied. The value \fIm\fR is the minimum +number and \fIu\fR is a number, less than 256, which is the maximum. If only +\fIm\fR is present (that is, \fB{\fR\fIm\fR\fB}\fR), it indicates the exact +number of times the regular expression is to be applied. The value +\fB{\fR\fIm\fR\fB,}\fR is analogous to \fB{\fR\fIm,infinity\fR\fB}\fR. The plus +(\fB+\fR) and star (\fB*\fR) operations are equivalent to \fB{1,}\fR and +\fB{0,}\fR respectively. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB( ... )$\fR\fIn\fR\fR +.ad +.RS 18n +.rt +The value of the enclosed regular expression is to be returned. The value will +be stored in the (\fIn\fR+1)th argument following the subject argument. At +most, ten enclosed regular expressions are allowed. The \fBregex()\fR function +makes its assignments unconditionally. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB( ... )\fR\fR +.ad +.RS 18n +.rt +Parentheses are used for grouping. An operator, for example, \fB*\fR, \fB+\fR, +\fB{\|}\fR, can work on a single character or a regular expression enclosed in +parentheses. For example, \fB(a*(cb+)*)$0\fR. By necessity, all the above +defined symbols are special. They must, therefore, be escaped with a \fB\e\fR +(backslash) to be used as themselves. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRExample matching a leading newline in the subject string. +.sp +.LP +The following example matches a leading newline in the subject string pointed +at by cursor. + +.sp +.in +2 +.nf +char *cursor, *newcursor, *ptr; + .\|.\|. +newcursor = regex((ptr = regcmp("^\en", (char *)0)), cursor); +free(ptr); +.fi +.in -2 + +.sp +.LP +The following example matches through the string \fBTesting3\fR and returns the +address of the character after the last matched character (the ``\fB4\fR''). +The string \fBTesting3\fR is copied to the character array \fBret0\fR. + +.sp +.in +2 +.nf +char ret0[9]; +char *newcursor, *name; + .\|.\|. +name = regcmp("([A\(miZa\(miz][A\(miza\(miz0\(mi9]{0,7})$0", (char *)0); +newcursor = regex(name, "012Testing345", ret0); +.fi +.in -2 + +.sp +.LP +The following example applies a precompiled regular expression in \fBfile.i\fR +(see \fBregcmp\fR(1)) against \fIstring\fR. + +.sp +.in +2 +.nf +\fB#include "file.i" +char *string, *newcursor; + .\|.\|. +newcursor = regex(name, string);\fR +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBed\fR(1), \fBregcmp\fR(1), \fBmalloc\fR(3C), \fBattributes\fR(5), +\fBregexp\fR(5) +.SH NOTES +.sp +.LP +The user program may run out of memory if \fBregcmp()\fR is called iteratively +without freeing the vectors no longer required. +.sp +.LP +When compiling multithreaded applications, the \fB_REENTRANT\fR flag must be +defined on the compile line. This flag should only be used in multithreaded +applications. diff --git a/usr/src/man/man3c/regcomp.3c b/usr/src/man/man3c/regcomp.3c new file mode 100644 index 0000000000..9bee9c808f --- /dev/null +++ b/usr/src/man/man3c/regcomp.3c @@ -0,0 +1,657 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH regcomp 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +regcomp, regexec, regerror, regfree \- regular expression matching +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <regex.h> + +\fBint\fR \fBregcomp\fR(\fBregex_t *restrict\fR \fIpreg\fR, \fBconst char *restrict\fR \fIpattern\fR, + \fBint\fR \fIcflags\fR); +.fi + +.LP +.nf +\fBint\fR \fBregexec\fR(\fBconst regex_t *restrict\fR \fIpreg\fR, + \fBconst char *restrict\fR \fIstring\fR, \fBsize_t\fR \fInmatch\fR, + \fBregmatch_t\fR \fIpmatch\fR[restrict], \fBint\fR \fIeflags\fR); +.fi + +.LP +.nf +\fBsize_t\fR \fBregerror\fR(\fBint\fR \fIerrcode\fR, \fBconst regex_t *restrict\fR \fIpreg\fR, + \fBchar *restrict\fR \fIerrbuf\fR, \fBsize_t\fR \fIerrbuf_size\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBregfree\fR(\fBregex_t *\fR\fIpreg\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions interpret \fIbasic\fR and \fIextended\fR regular expressions +(described on the \fBregex\fR(5) manual page). +.sp +.LP +The structure type \fBregex_t\fR contains at least the following member: +.sp +.ne 2 +.mk +.na +\fB\fBsize_t\fR \fBre_nsub\fR\fR +.ad +.RS 18n +.rt +Number of parenthesised subexpressions. +.RE + +.sp +.LP +The structure type \fBregmatch_t\fR contains at least the following members: +.sp +.ne 2 +.mk +.na +\fB\fBregoff_t\fR \fBrm_so\fR\fR +.ad +.RS 18n +.rt +Byte offset from start of \fIstring\fR to start of substring. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBregoff_t\fR \fBrm_eo\fR\fR +.ad +.RS 18n +.rt +Byte offset from start of \fIstring\fR of the first character after the end of +substring. +.RE + +.SS "\fBregcomp()\fR" +.sp +.LP +The \fBregcomp()\fR function will compile the regular expression contained in +the string pointed to by the \fIpattern\fR argument and place the results in +the structure pointed to by \fIpreg\fR. The \fIcflags\fR argument is the +bitwise inclusive \fBOR\fR of zero or more of the following flags, which are +defined in the header \fB<regex.h>\fR: +.sp +.ne 2 +.mk +.na +\fB\fBREG_EXTENDED\fR\fR +.ad +.RS 16n +.rt +Use Extended Regular Expressions. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBREG_ICASE\fR\fR +.ad +.RS 16n +.rt +Ignore case in match. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBREG_NOSUB\fR\fR +.ad +.RS 16n +.rt +Report only success/fail in \fBregexec()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBREG_NEWLINE\fR\fR +.ad +.RS 16n +.rt +Change the handling of \fBNEWLINE\fR characters, as described in the text. +.RE + +.sp +.LP +The default regular expression type for \fIpattern\fR is a Basic Regular +Expression. The application can specify Extended Regular Expressions using the +\fBREG_EXTENDED\fR \fIcflags\fR flag. +.sp +.LP +If the \fBREG_NOSUB\fR flag was not set in \fIcflags\fR, then \fBregcomp()\fR +will set \fIre_nsub\fR to the number of parenthesised subexpressions (delimited +by \e(\e) in basic regular expressions or () in extended regular expressions) +found in \fI pattern\fR. +.SS "\fBregexec()\fR" +.sp +.LP +The \fBregexec()\fR function compares the null-terminated string specified by +\fIstring\fR with the compiled regular expression \fIpreg\fR initialized by a +previous call to \fBregcomp()\fR. The \fIeflags\fR argument is the bitwise +inclusive \fBOR\fR of zero or more of the following flags, which are defined in +the header <\fBregex.h\fR>: +.sp +.ne 2 +.mk +.na +\fB\fBREG_NOTBOL\fR\fR +.ad +.RS 14n +.rt +The first character of the string pointed to by \fIstring\fR is not the +beginning of the line. Therefore, the circumflex character (\fI^\fR), when +taken as a special character, will not match the beginning of \fIstring\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBREG_NOTEOL\fR\fR +.ad +.RS 14n +.rt +The last character of the string pointed to by \fIstring\fR is not the end of +the line. Therefore, the dollar sign (\fI$\fR), when taken as a special +character, will not match the end of \fIstring\fR. +.RE + +.sp +.LP +If \fInmatch\fR is zero or \fBREG_NOSUB\fR was set in the \fIcflags\fR argument +to \fBregcomp()\fR, then \fBregexec()\fR will ignore the \fIpmatch\fR argument. +Otherwise, the \fIpmatch\fR argument must point to an array with at least +\fInmatch\fR elements, and \fBregexec()\fR will fill in the elements of that +array with offsets of the substrings of \fIstring\fR that correspond to the +parenthesised subexpressions of \fIpattern\fR: +\fIpmatch\fR\fB[\fR\fIi\fR\fB]\fR.\fIrm_so\fR will be the byte offset of the +beginning and \fIpmatch\fR\fB[\fR\fIi\fR\fB]\fR.\fIrm_eo\fR will be one greater +than the byte offset of the end of substring \fIi\fR. (Subexpression \fIi\fR +begins at the \fIi\fRth matched open parenthesis, counting from 1.) Offsets in +\fIpmatch\fR\fB[0]\fR identify the substring that corresponds to the entire +regular expression. Unused elements of \fIpmatch\fR up to +\fIpmatch\fR\fB[\fR\fInmatch\fR\fB\(mi1]\fR will be filled with \fB\(mi1\fR\&. +If there are more than \fInmatch\fR subexpressions in \fIpattern\fR +(\fIpattern\fR itself counts as a subexpression), then \fBregexec()\fR will +still do the match, but will record only the first \fInmatch\fR substrings. +.sp +.LP +When matching a basic or extended regular expression, any given parenthesised +subexpression of \fIpattern\fR might participate in the match of several +different substrings of \fIstring\fR, or it might not match any substring even +though the pattern as a whole did match. The following rules are used to +determine which substrings to report in \fIpmatch\fR when matching regular +expressions: +.sp +.ne 2 +.mk +.na +\fB1.\fR +.ad +.RS 6n +.rt +If subexpression \fIi\fR in a regular expression is not contained within +another subexpression, and it participated in the match several times, then the +byte offsets in \fIpmatch\fR\fB[\fR\fIi\fR\fB]\fR will delimit the last such +match. +.RE + +.sp +.ne 2 +.mk +.na +\fB2.\fR +.ad +.RS 6n +.rt +If subexpression \fIi\fR is not contained within another subexpression, and it +did not participate in an otherwise successful match, the byte offsets in +\fIpmatch\fR\fB[\fR\fIi\fR\fB]\fR will be \fB\(mi1\fR\&. A subexpression does +not participate in the match when: +.sp +\fB*\fR or \fB\e{\e} \fR appears immediately after the subexpression in a basic +regular expression, or \fB*\fR, \fB?\fR, or \fB{\|}\fR appears immediately +after the subexpression in an extended regular expression, and the +subexpression did not match (matched zero times) +.sp +or +.sp +\fB|\fR is used in an extended regular expression to select this subexpression +or another, and the other subexpression matched. +.RE + +.sp +.ne 2 +.mk +.na +\fB3.\fR +.ad +.RS 6n +.rt +If subexpression \fIi\fR is contained within another subexpression \fIj\fR, and +\fIi\fR is not contained within any other subexpression that is contained +within \fIj\fR, and a match of subexpression \fIj\fR is reported in +\fIpmatch\fR\fB[\fR\fIj\fR\fB]\fR, then the match or non-match of subexpression +\fIi\fR reported in \fIpmatch\fR\fB[\fR\fIi\fR\fB]\fR will be as described in +1. and 2. above, but within the substring reported in +\fIpmatch\fR\fB[\fR\fIj\fR\fB]\fR rather than the whole string. +.RE + +.sp +.ne 2 +.mk +.na +\fB4.\fR +.ad +.RS 6n +.rt +If subexpression \fIi\fR is contained in subexpression \fIj\fR, and the byte +offsets in \fIpmatch\fR\fB[\fR\fIj\fR\fB]\fR are \fB\(mi1\fR, then the pointers +in \fIpmatch\fR\fB[\fR\fIi\fR\fB]\fR also will be \fB\(mi1\fR\&. +.RE + +.sp +.ne 2 +.mk +.na +\fB5.\fR +.ad +.RS 6n +.rt +If subexpression \fIi\fR matched a zero-length string, then both byte offsets +in \fIpmatch\fR\fB[\fR\fIi\fR\fB]\fR will be the byte offset of the character +or \fINULL\fR terminator immediately following the zero-length string. +.RE + +.sp +.LP +If, when \fBregexec()\fR is called, the locale is different from when the +regular expression was compiled, the result is undefined. +.sp +.LP +If \fBREG_NEWLINE\fR is not set in \fIcflags\fR, then a \fBNEWLINE\fR character +in \fIpattern\fR or \fIstring\fR will be treated as an ordinary character. If +\fBREG_NEWLINE\fR is set, then newline will be treated as an ordinary character +except as follows: +.sp +.ne 2 +.mk +.na +\fB1.\fR +.ad +.RS 6n +.rt +A \fBNEWLINE\fR character in \fIstring\fR will not be matched by a period +outside a bracket expression or by any form of a non-matching list. +.RE + +.sp +.ne 2 +.mk +.na +\fB2.\fR +.ad +.RS 6n +.rt +A circumflex (^) in \fIpattern\fR, when used to specify expression anchoring +will match the zero-length string immediately after a newline in \fIstring\fR, +regardless of the setting of \fBREG_NOTBOL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB3.\fR +.ad +.RS 6n +.rt +A dollar-sign ($) in \fIpattern\fR, when used to specify expression anchoring, +will match the zero-length string immediately before a newline in \fIstring\fR, +regardless of the setting of \fBREG_NOTEOL.\fR +.RE + +.SS "\fBregfree()\fR" +.sp +.LP +The \fBregfree()\fR function frees any memory allocated by \fBregcomp()\fR +associated with \fIpreg\fR. +.sp +.LP +The following constants are defined as error return values: +.sp +.ne 2 +.mk +.na +\fB\fBREG_NOMATCH\fR\fR +.ad +.RS 16n +.rt +The \fBregexec()\fR function failed to match. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBREG_BADPAT\fR\fR +.ad +.RS 16n +.rt +Invalid regular expression. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBREG_ECOLLATE\fR\fR +.ad +.RS 16n +.rt +Invalid collating element referenced. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBREG_ECTYPE\fR\fR +.ad +.RS 16n +.rt +Invalid character class type referenced. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBREG_EESCAPE\fR\fR +.ad +.RS 16n +.rt +Trailing \e in pattern. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBREG_ESUBREG\fR\fR +.ad +.RS 16n +.rt +Number in \e\fIdigit\fR invalid or in error. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBREG_EBRACK\fR\fR +.ad +.RS 16n +.rt +\fB[\|]\fR imbalance. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBREG_ENOSYS\fR\fR +.ad +.RS 16n +.rt +The function is not supported. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBREG_EPAREN\fR\fR +.ad +.RS 16n +.rt +\fB\e(\|\e)\fR or \fB()\fR imbalance. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBREG_EBRACE\fR\fR +.ad +.RS 16n +.rt +\e{ \e} imbalance. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBREG_BADBR\fR\fR +.ad +.RS 16n +.rt +Content of \e{ \e} invalid: not a number, number too large, more than two +numbers, first larger than second. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBREG_ERANGE\fR\fR +.ad +.RS 16n +.rt +Invalid endpoint in range expression. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBREG_ESPACE\fR\fR +.ad +.RS 16n +.rt +Out of memory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBREG_BADRPT\fR\fR +.ad +.RS 16n +.rt +?, * or + not preceded by valid regular expression. +.RE + +.SS "\fBregerror()\fR" +.sp +.LP +The \fBregerror()\fR function provides a mapping from error codes returned by +\fBregcomp()\fR and \fBregexec()\fR to unspecified printable strings. It +generates a string corresponding to the value of the \fIerrcode\fR argument, +which must be the last non-zero value returned by \fBregcomp()\fR or +\fBregexec()\fR with the given value of \fIpreg\fR. If \fIerrcode\fR is not +such a value, an error message indicating that the error code is invalid is +returned. +.sp +.LP +If \fIpreg\fR is a \fINULL\fR pointer, but \fIerrcode\fR is a value returned by +a previous call to \fBregexec()\fR or \fBregcomp()\fR, the \fBregerror()\fR +still generates an error string corresponding to the value of \fIerrcode\fR. +.sp +.LP +If the \fIerrbuf_size\fR argument is not zero, \fBregerror()\fR will place the +generated string into the buffer of size \fIerrbuf_size\fR bytes pointed to by +\fIerrbuf\fR. If the string (including the terminating \fBNULL)\fR cannot fit +in the buffer, \fBregerror()\fR will truncate the string and null-terminate the +result. +.sp +.LP +If \fIerrbuf_size\fR is zero, \fBregerror()\fR ignores the \fIerrbuf\fR +argument, and returns the size of the buffer needed to hold the generated +string. +.sp +.LP +If the \fIpreg\fR argument to \fBregexec()\fR or \fBregfree()\fR is not a +compiled regular expression returned by \fBregcomp()\fR, the result is +undefined. A \fIpreg\fR is no longer treated as a compiled regular expression +after it is given to \fBregfree()\fR. +.sp +.LP +See \fBregex\fR(5) for BRE (Basic Regular Expression) Anchoring. +.SH RETURN VALUES +.sp +.LP +On successful completion, the \fBregcomp()\fR function returns \fB0\fR. +Otherwise, it returns an integer value indicating an error as described in +<\fBregex.h\fR>, and the content of \fIpreg\fR is undefined. +.sp +.LP +On successful completion, the \fBregexec()\fR function returns \fB0\fR. +Otherwise it returns \fBREG_NOMATCH\fR to indicate no match, or +\fBREG_ENOSYS\fR to indicate that the function is not supported. +.sp +.LP +Upon successful completion, the \fBregerror()\fR function returns the number of +bytes needed to hold the entire generated string. Otherwise, it returns \fB0\fR +to indicate that the function is not implemented. +.sp +.LP +The \fBregfree()\fR function returns no value. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH USAGE +.sp +.LP +An application could use: +.sp +.LP +\fBregerror(code,preg,(char *)NULL,(size_t)0)\fR +.sp +.LP +to find out how big a buffer is needed for the generated string, \fBmalloc\fR a +buffer to hold the string, and then call \fBregerror()\fR again to get the +string (see \fBmalloc\fR(3C)). Alternately, it could allocate a fixed, static +buffer that is big enough to hold most strings, and then use \fBmalloc()\fR to +allocate a larger buffer if it finds that this is too small. +.SH EXAMPLES +.LP +\fBExample 1 \fRExample to match string against the extended regular expression +in pattern. +.sp +.in +2 +.nf +#include <regex.h> +/* +* Match string against the extended regular expression in +* pattern, treating errors as no match. +* +* return 1 for match, 0 for no match +*/ + +int +match(const char *string, char *pattern) +{ + int status; + regex_t re; + 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 +.in -2 + +.sp +.LP +The following demonstrates how the \fBREG_NOTBOL\fR flag could be used with +\fBregexec()\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 +.in +2 +.nf +(void) regcomp (&re, pattern, 0); +/* this call to regexec(\|) finds the first match on the line */ +error = regexec (&re, &buffer[0], 1, &pm, 0); +while (error == 0) { /* while matches found */ + /* substring found between pm.rm_so and pm.rm_eo */ + /* This call to regexec(\|) finds the next match */ + error = regexec (&re, buffer + pm.rm_eo, 1, &pm, REG_NOTBOL); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +CSIEnabled +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBfnmatch\fR(3C), \fBglob\fR(3C), \fBmalloc\fR(3C), \fBsetlocale\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5), \fBregex\fR(5) +.SH NOTES +.sp +.LP +The \fBregcomp()\fR function can be used safely in a multithreaded application +as long as \fBsetlocale\fR(3C) is not being called to change the locale. diff --git a/usr/src/man/man3c/remove.3c b/usr/src/man/man3c/remove.3c new file mode 100644 index 0000000000..bcf320538f --- /dev/null +++ b/usr/src/man/man3c/remove.3c @@ -0,0 +1,59 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH remove 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +remove \- remove file +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBint\fR \fBremove\fR(\fBconst char *\fR\fIpath\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBremove()\fR function causes the file or empty directory whose name is +the string pointed to by \fIpath\fR to be no longer accessible by that name. A +subsequent attempt to open that file using that name will fail, unless the file +is created anew. +.sp +.LP +For files, \fBremove()\fR is identical to \fBunlink()\fR. For directories, +\fBremove()\fR is identical to \fBrmdir()\fR. +.sp +.LP +See \fBrmdir\fR(2) and \fBunlink\fR(2) for a detailed list of failure +conditions. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBremove()\fR returns \fB0\fR. Otherwise, it +returns \fB\(mi1\fR and sets \fBerrno\fR to indicate an error. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBrmdir\fR(2), \fBunlink\fR(2), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/rewind.3c b/usr/src/man/man3c/rewind.3c new file mode 100644 index 0000000000..f2701e7944 --- /dev/null +++ b/usr/src/man/man3c/rewind.3c @@ -0,0 +1,82 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rewind 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +rewind \- reset file position indicator in a stream +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBvoid\fR \fBrewind\fR(\fBFILE *\fR\fIstream\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The call: +.sp +.in +2 +.nf +rewind(stream) +.fi +.in -2 + +.sp +.LP +is equivalent to: +.sp +.in +2 +.nf +(void) fseek(stream, 0L, SEEK_SET) +.fi +.in -2 + +.sp +.LP +except that \fBrewind()\fR also clears the error indicator. +.SH RETURN VALUES +.sp +.LP +The \fBrewind()\fR function returns no value. +.SH ERRORS +.sp +.LP +Refer to \fBfseek\fR(3C) with the exception of \fBEINVAL\fR which does not +apply. +.SH USAGE +.sp +.LP +Because \fBrewind()\fR does not return a value, an application wishing to +detect errors should clear \fBerrno\fR, then call \fBrewind()\fR, and if +\fBerrno\fR is non-zero, assume an error has occurred. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfseek\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/rewinddir.3c b/usr/src/man/man3c/rewinddir.3c new file mode 100644 index 0000000000..53e1f1289a --- /dev/null +++ b/usr/src/man/man3c/rewinddir.3c @@ -0,0 +1,73 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rewinddir 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +rewinddir \- reset position of directory stream to the beginning of a directory +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <dirent.h> + +\fBvoid\fR \fBrewinddir\fR(\fBDIR *\fR\fIdirp\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBrewinddir()\fR function resets the position of the directory stream to +which \fIdirp\fR refers to the beginning of the directory. It also causes the +directory stream to refer to the current state of the corresponding directory, +as a call to \fBopendir\fR(3C) would have done. If \fIdirp\fR does not refer +to a directory stream, the effect is undefined. +.sp +.LP +After a call to the \fBfork\fR(2) function, either the parent or child (but not +both) may continue processing the directory stream using \fBreaddir\fR(3C), +\fBrewinddir()\fR or \fBseekdir\fR(3C). If both the parent and child processes +use these functions, the result is undefined. +.SH RETURN VALUES +.sp +.LP +The \fBrewinddir()\fR function does not return a value. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH USAGE +.sp +.LP +The \fBrewinddir()\fR function should be used in conjunction with +\fBopendir()\fR, \fBreaddir()\fR, and \fBclosedir\fR(3C) to examine the +contents of the directory. This method is recommended for portability. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfork\fR(2), \fBclosedir\fR(3C), \fBopendir\fR(3C), \fBreaddir\fR(3C), +\fBseekdir\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/rwlock.3c b/usr/src/man/man3c/rwlock.3c new file mode 100644 index 0000000000..21ad7bf460 --- /dev/null +++ b/usr/src/man/man3c/rwlock.3c @@ -0,0 +1,270 @@ +'\" te +.\" Copyright (c) 1998 Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rwlock 3C "14 May 1998" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +rwlock, rwlock_init, rwlock_destroy, rw_rdlock, rw_wrlock, rw_tryrdlock, +rw_trywrlock, rw_unlock \- multiple readers, single writer locks +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR...[ \fIlibrary\fR... ] + +#include <synch.h> + +\fBint\fR \fBrwlock_init\fR(\fBrwlock_t *\fR\fIrwlp\fR, \fBint\fR \fItype\fR, \fBvoid *\fR \fIarg\fR); +.fi + +.LP +.nf +\fBint\fR \fBrwlock_destroy\fR(\fBrwlock_t *\fR\fIrwlp\fR); +.fi + +.LP +.nf +\fBint\fR \fBrw_rdlock\fR(\fBrwlock_t *\fR\fIrwlp\fR); +.fi + +.LP +.nf +\fBint\fR \fBrw_wrlock\fR(\fBrwlock_t *\fR\fIrwlp\fR); +.fi + +.LP +.nf +\fBint\fR \fBrw_unlock\fR(\fBrwlock_t *\fR\fIrwlp\fR); +.fi + +.LP +.nf +\fBint\fR \fBrw_tryrdlock\fR(\fBrwlock_t *\fR\fIrwlp\fR); +.fi + +.LP +.nf +\fBint\fR \fBrw_trywrlock\fR(\fBrwlock_t *\fR\fIrwlp\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +Many threads can have simultaneous read-only access to data, while only one +thread can have write access at any given time. Multiple read access with +single write access is controlled by locks, which are generally used to protect +data that is frequently searched. +.sp +.LP +Readers/writer locks can synchronize threads in this process and other +processes if they are allocated in writable memory and shared among +cooperating processes (see \fBmmap\fR(2)), and are initialized for this +purpose. +.sp +.LP +Additionally, readers/writer locks must be initialized prior to use. +\fBrwlock_init()\fR The readers/writer lock pointed to by \fIrwlp\fR is +initialized by \fBrwlock_init()\fR. A readers/writer lock is capable of having +several types of behavior, which is specified by \fBtype\fR. \fIarg\fR is +currently not used, although a future type may define new behavior parameters +by way of \fIarg\fR. +.sp +.LP +The \fItype\fR argument can be one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBUSYNC_PROCESS\fR \fR +.ad +.RS 18n +.rt +The readers/writer lock can synchronize threads in this process and other +processes. The readers/writer lock should be initialized by only one process. +\fIarg\fR is ignored. A readers/writer lock initialized with this type, must be +allocated in memory shared between processses, i.e. either in Sys V shared +memory (see \fBshmop\fR(2)) or in memory mapped to a file (see \fBmmap\fR(2)). +It is illegal to initialize the object this way and to not allocate it in such +shared memory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUSYNC_THREAD\fR \fR +.ad +.RS 18n +.rt +The readers/writer lock can synchronize threads in this process, only. +\fIarg\fR is ignored. +.RE + +.sp +.LP +Additionally, readers/writer locks can be initialized by allocation in zeroed +memory. A \fBtype\fR of \fBUSYNC_THREAD\fR is assumed in this case. Multiple +threads must not simultaneously initialize the same readers/writer lock. And a +readers/writer lock must not be re-initialized while in use by other threads. +.sp +.LP +The following are default readers/writer lock initialization (intra-process): +.sp +.in +2 +.nf +rwlock_t rwlp; +rwlock_init(&rwlp, NULL, NULL); + +.fi +.in -2 + +.sp +.LP +or +.sp +.in +2 +.nf +rwlock_init(&rwlp, USYNC_THREAD, NULL); +.fi +.in -2 + +.sp +.LP +or +.sp +.in +2 +.nf +rwlock_t rwlp = DEFAULTRWLOCK; +.fi +.in -2 + +.sp +.LP +The following is a customized readers/writer lock initialization +(inter-process): +.sp +.in +2 +.nf +rwlock_init(&rwlp, USYNC_PROCESS, NULL); +.fi +.in -2 + +.sp +.LP +Any state associated with the readers/writer lock pointed to by \fIrwlp\fR are +destroyed by \fBrwlock_destroy()\fR and the readers/writer lock storage space +is not released. +.sp +.LP +\fBrw_rdlock()\fR gets a read lock on the readers/writer lock pointed to by +\fIrwlp\fR. If the readers/writer lock is currently locked for writing, the +calling thread blocks until the write lock is freed. Multiple threads may +simultaneously hold a read lock on a readers/writer lock. +.sp +.LP +\fBrw_tryrdlock()\fR trys to get a read lock on the readers/writer lock pointed +to by \fIrwlp\fR. If the readers/writer lock is locked for writing, it returns +an error; otherwise, the read lock is acquired. +.sp +.LP +\fBrw_wrlock()\fR gets a write lock on the readers/writer lock pointed to by +\fIrwlp\fR. If the readers/writer lock is currently locked for reading or +writing, the calling thread blocks until all the read and write locks are +freed. At any given time, only one thread may have a write lock on a +readers/writer lock. +.sp +.LP +\fBrw_trywrlock()\fR trys to get a write lock on the readers/writer lock +pointed to by \fIrwlp\fR. If the readers/writer lock is currently locked for +reading or writing, it returns an error. +.sp +.LP +\fBrw_unlock()\fR unlocks a readers/writer lock pointed to by \fIrwlp\fR, if +the readers/writer lock is locked and the calling thread holds the lock for +either reading or writing. One of the other threads that is waiting for the +readers/writer lock to be freed will be unblocked, provided there is other +waiting threads. If the calling thread does not hold the lock for either +reading or writing, no error status is returned, and the program's behavior is +unknown. +.SH RETURN VALUES +.sp +.LP +If successful, these functions return \fB0\fR. Otherwise, a non-zero value is +returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBrwlock_init()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR \fR +.ad +.RS 11n +.rt +\fBtype\fR is invalid. +.RE + +.sp +.LP +The \fBrw_tryrdlock()\fR or \fBrw_trywrlock()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBUSY\fR \fR +.ad +.RS 10n +.rt +The reader or writer lock pointed to by \fIrwlp\fR was already locked. +.RE + +.sp +.LP +These functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR \fR +.ad +.RS 11n +.rt +\fIrwlp\fR or \fIarg\fR points to an illegal address. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBmmap\fR(2), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +These interfaces also available by way of: +.sp +.LP +\fB#include\fR \fB<thread.h>\fR +.sp +.LP +If multiple threads are waiting for a readers/writer lock, the acquisition +order is random by default. However, some implementations may bias acquisition +order to avoid depriving writers. The current implementation favors writers +over readers. diff --git a/usr/src/man/man3c/scandir.3c b/usr/src/man/man3c/scandir.3c new file mode 100644 index 0000000000..abc2ca00a2 --- /dev/null +++ b/usr/src/man/man3c/scandir.3c @@ -0,0 +1,106 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scandir 3C "4 May 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +scandir, alphasort \- scan a directory +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <dirent.h> + +\fBint\fR \fBscandir\fR(\fBconst char *\fR\fIdirname\fR, \fBstruct dirent *\fR(*\fInamelist\fR[]), + \fBint\fR (*\fIselect\fR)(const struct dirent *), + \fBint\fR (*\fIdcomp\fR)(\fBconst struct dirent **\fR, + \fBconst struct dirent **\fR)); +.fi + +.LP +.nf +\fBint\fR \fBalphasort\fR(\fBconst struct dirent **\fR\fId1\fR, + \fBconst struct dirent **\fR\fId2\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBscandir()\fR function reads the directory \fIdirname\fR using +\fBreaddir\fR(3C) and builds an array of pointers to directory entries using +\fBmalloc\fR(3C). The \fInamelist\fR argument is a pointer to an array of +structure pointers. The \fIselect\fR argument is a pointer to a routine that is +called with a pointer to a directory entry and returns a non-zero value if the +directory entry is included in the array. If this pointer is \fINULL\fR, then +all the directory entries are included. The \fIdcomp\fR argument is a pointer +to a routine that is passed to \fBqsort\fR(3C), which sorts the completed +array. If this pointer is \fINULL\fR, the array is not sorted. +.sp +.LP +The \fBalphasort()\fR function can be used as the \fIdcomp\fR() function +parameter for the \fBscandir()\fR function to sort the directory entries into +alphabetical order, as if by the \fBstrcoll\fR(3C) function. Its arguments are +the two directory entries to compare. +.SH RETURN VALUES +.sp +.LP +The \fBscandir()\fR function returns the number of entries in the array and a +pointer to the array through the \fInamelist\fR argument. When an error is +encountered, \fBscandir()\fR returns -1 and \fBerrno\fR is set to indicate the +error. +.sp +.LP +The \fBalphasort()\fR function returns an integer greater than, equal to, or +less than 0 if the directory entry name pointed to by \fId1\fR is greater than, +equal to, or less than the directory entry name pointed to by \fId2\fR when +both are interpreted as appropriate to the current locale. There is no return +value reserved to indicate an error. +.SH ERRORS +.sp +.LP +The \fBscandir()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEOVERFLOW\fR\fR +.ad +.RS 13n +.rt +The number of directory entries exceeds the number that can be represented by +an \fBint\fR. +.RE + +.SH USAGE +.sp +.LP +The \fBscandir()\fR and \fBalphasort()\fR functions have transitional +interfaces for 64-bit file offsets. See \fBlf64\fR(5). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStable +_ +MT-LevelSee below. +.TE + +.sp +.LP +The \fBscandir()\fR function is Unsafe. The \fBalphasort()\fR function is Safe. +.SH SEE ALSO +.sp +.LP +\fBmalloc\fR(3C), \fBqsort\fR(3C), \fBreaddir\fR(3C), \fBstrcoll\fR(3C), +\fBattributes\fR(5), \fBlf64\fR(5) diff --git a/usr/src/man/man3c/scanf.3c b/usr/src/man/man3c/scanf.3c new file mode 100644 index 0000000000..2a0b46f144 --- /dev/null +++ b/usr/src/man/man3c/scanf.3c @@ -0,0 +1,758 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 1997, The Open Group. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scanf 3C "10 Jul 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +scanf, fscanf, sscanf, vscanf, vfscanf, vsscanf \- convert formatted input +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBint\fR \fBscanf\fR(\fBconst char *restrict\fR \fIformat\fR...); +.fi + +.LP +.nf +\fBint\fR \fBfscanf\fR(\fBFILE *restrict\fR \fIstream\fR, \fBconst char *restrict\fR \fIformat\fR...); +.fi + +.LP +.nf +\fBint\fR \fBsscanf\fR(\fBconst char *restrict\fR \fIs\fR, \fBconst char *restrict\fR \fIformat\fR...); +.fi + +.LP +.nf +#include <stdarg.h> +#include <stdio.h> + +\fBint\fR \fBvscanf\fR(\fBconst char *\fR\fIformat\fR, \fBva_list\fR \fIarg\fR); +.fi + +.LP +.nf +\fBint\fR \fBvfscanf\fR(\fBFILE *\fR\fIstream\fR, \fBconst char *\fR\fIformat\fR, \fBva_list\fR \fIarg\fR); +.fi + +.LP +.nf +\fBint\fR \fBvsscanf\fR(\fBconst char *\fR\fIs\fR, \fBconst char *\fR\fIformat\fR, \fBva_list\fR \fIarg\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBscanf()\fR function reads from the standard input stream \fBstdin\fR. +.sp +.LP +The \fBfscanf()\fR function reads from the named input \fIstream\fR. +.sp +.LP +The \fBsscanf()\fR function reads from the string \fIs\fR. +.sp +.LP +The \fBvscanf()\fR, \fBvfscanf()\fR, and \fBvsscanf()\fR functions are +equivalent to the \fBscanf()\fR, \fBfscanf()\fR, and \fBsscanf()\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 the +<\fBstdarg.h\fR> header . These functions do not invoke the \fBva_end()\fR +macro. Applications using these functions should call \fBva_end\fR(\fIap\fR) +afterwards to clean up. +.sp +.LP +Each function reads bytes, interprets them according to a format, and stores +the results in its arguments. Each expects, as arguments, a control string +\fIformat\fR described below, and a set of \fIpointer\fR 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 are evaluated but are otherwise ignored. +.sp +.LP +Conversions can be applied to the \fInth\fR argument after the \fIformat\fR in +the argument list, rather than to the next unused argument. In this case, the +conversion character \fB%\fR (see below) is replaced by the sequence +\fB%\fR\fIn\fR\fB$\fR, where \fIn\fR is a decimal integer in the range [1, +\fBNL_ARGMAX\fR]. This feature provides for the definition of format strings +that select arguments in an order appropriate to specific languages. In format +strings containing the \fB%\fR\fIn\fR\fB$\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. +.sp +.LP +The \fIformat\fR can contain either form of a conversion specification, that +is, \fB%\fR or \fB%\fR\fIn\fR\fB$\fR, but the two forms cannot normally be +mixed within a single \fIformat\fR string. The only exception to this is that +\fB%%\fR or \fB%*\fR can be mixed with the \fB%\fR\fIn\fR\fB$\fR form. +.sp +.LP +The \fBscanf()\fR function in all its forms allows for detection of a +language-dependent radix character in the input string. The radix character is +defined in the program's locale (category \fBLC_NUMERIC\fR). In the POSIX +locale, or in a locale where the radix character is not defined, the radix +character defaults to a period (.). +.sp +.LP +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: +.RS +4 +.TP +.ie t \(bu +.el o +one or more \fIwhite-space characters\fR (space, tab, newline, vertical-tab or +form-feed characters); +.RE +.RS +4 +.TP +.ie t \(bu +.el o +an \fIordinary character\fR (neither \fB%\fR nor a white-space character); or +.RE +.RS +4 +.TP +.ie t \(bu +.el o +a \fIconversion specification\fR. +.RE +.SS "Conversion Specifications" +.sp +.LP +Each conversion specification is introduced by the character \fB%\fR or the +character sequence \fB%\fR\fIn\fR\fB$\fR, after which the following appear in +sequence: +.RS +4 +.TP +.ie t \(bu +.el o +An optional assignment-suppressing character \fB*\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +An optional non-zero decimal integer that specifies the maximum field width. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +An option length modifier that specifies the size of the receiving object. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +A conversion specifier character that specifies the type of conversion to be +applied. The valid conversion characters are described below. +.RE +.sp +.LP +The \fBscanf()\fR functions execute each directive of the format in turn. If a +directive fails, as detailed below, the function returns. Failures are +described as input failures (due to the unavailability of input bytes) or +matching failures (due to inappropriate input). +.sp +.LP +A directive composed of one or more white-space characters is 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. +.sp +.LP +A directive that is an ordinary character is executed as follows. The next byte +is read from the input and compared with the byte that comprises the directive; +if the comparison shows that they are not equivalent, the directive fails, and +the differing and subsequent bytes remain unread. +.sp +.LP +A directive that is a conversion specification defines a set of matching input +sequences, as described below for each conversion character. A conversion +specification is executed in the following steps: +.sp +.LP +Input white-space characters (as specified by \fBisspace\fR(3C)) are skipped, +unless the conversion specification includes a \fB[\fR, \fBc\fR, \fBC\fR, or +\fBn\fR conversion character. +.sp +.LP +An item is read from the input unless the conversion specification includes an +\fBn\fR conversion character. The length of the item read is limited to any +specified maximum field width, which is interpreted in either characters or +bytes depending on the conversion character. In Solaris default mode, the input +item is defined as the longest sequence of input bytes that forms a matching +sequence. In some cases, \fBscanf()\fR might need to read several extra +characters beyond the end of the input item to find the end of a matching +sequence. In C99/SUSv3 mode, the input item is defined as the longest sequence +of input bytes that is, or is a prefix of, a matching sequence. With this +definition, \fBscanf()\fR need only read at most one character beyond the end +of the input item. Therefore, in C99/SUSv3 mode, some sequences that are +acceptable to \fBstrtod\fR(3C), \fBstrtol\fR(3C), and similar functions are +unacceptable to \fBscanf()\fR. In either mode, \fBscanf()\fR attempts to push +back any excess bytes read using \fBungetc\fR(3C). Assuming all such attempts +succeed, the first byte, if any, after the input item remains unread. If the +length of the input item is 0, the conversion fails. 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. +.sp +.LP +Except in the case of a \fB%\fR conversion character, the input item (or, in +the case of a \fB%\fR\fIn\fR conversion specification, the count of input +bytes) is 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 \fB*\fR, the result of the conversion is placed +in the object pointed to by the first argument following the \fIformat\fR +argument that has not already received a conversion result if the conversion +specification is introduced by \fB%\fR, or in the \fIn\fRth argument if +introduced by the character sequence \fB%\fR\fIn\fR\fB$\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. +.SS "Length Modifiers" +.sp +.LP +The length modifiers and their meanings are: +.sp +.ne 2 +.mk +.na +\fB\fBhh\fR\fR +.ad +.RS 16n +.rt +Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, +\fBX\fR, or \fBn\fR conversion specifier applies to an argument with type +pointer to \fBsigned char\fR or \fBunsigned char\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBh\fR\fR +.ad +.RS 16n +.rt +Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, +\fBX\fR, or \fBn\fR conversion specifier applies to an argument with type +pointer to \fBshort\fR or \fBunsigned short\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBl\fR (ell)\fR +.ad +.RS 16n +.rt +Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, +\fBX\fR, or \fBn\fR conversion specifier applies to an argument with type +pointer to \fBlong\fR or \fBunsigned long\fR; that a following \fBa\fR, +\fBA\fR, \fBe\fR, \fBE\fR, \fBf\fR, \fBF\fR, \fBg\fR, or \fBG\fR conversion +specifier applies to an argument with type pointer to \fBdouble\fR; or that a +following \fBc\fR, \fBs\fR, or \fB[\fR conversion specifier applies to an +argument with type pointer to \fBwchar_t\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBll\fR (ell-ell)\fR +.ad +.RS 16n +.rt +Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, +\fBX\fR, or \fBn\fR conversion specifier applies to an argument with type +pointer to \fBlong long\fR or \fBunsigned long long\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBj\fR\fR +.ad +.RS 16n +.rt +Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, +\fBX\fR, or \fBn\fR conversion specifier applies to an argument with type +pointer to \fBintmax_t\fR or \fBuintmax_t\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBz\fR\fR +.ad +.RS 16n +.rt +Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, +\fBX\fR, or \fBn\fR conversion specifier applies to an argument with type +pointer to \fBsize_t\fR or the corresponding signed integer type. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBt\fR\fR +.ad +.RS 16n +.rt +Specifies that a following \fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, +\fBX\fR, or \fBn\fR conversion specifier applies to an argument with type +pointer to \fBptrdiff_t\fR or the corresponding \fBunsigned\fR type. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBL\fR\fR +.ad +.RS 16n +.rt +Specifies that a following \fBa\fR, \fBA\fR, \fBe\fR, \fBE\fR, \fBf\fR, +\fBF\fR, \fBg\fR, or \fBG\fR conversion specifier applies to an argument with +type pointer to \fBlong double\fR. +.RE + +.sp +.LP +If a length modifier appears with any conversion specifier other than as +specified above, the behavior is undefined. +.SS "Conversion Characters" +.sp +.LP +The following conversion characters are valid: +.sp +.ne 2 +.mk +.na +\fB\fBd\fR\fR +.ad +.RS 11n +.rt +Matches an optionally signed decimal integer, whose format is the same as +expected for the subject sequence of \fBstrtol\fR(3C) with the value 10 for the +\fIbase\fR argument. In the absence of a size modifier, the corresponding +argument must be a pointer to \fBint\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBi\fR\fR +.ad +.RS 11n +.rt +Matches an optionally signed integer, whose format is the same as expected for +the subject sequence of \fBstrtol()\fR with 0 for the \fIbase\fR argument. In +the absence of a size modifier, the corresponding argument must be a pointer to +\fBint\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBo\fR\fR +.ad +.RS 11n +.rt +Matches an optionally signed octal integer, whose format is the same as +expected for the subject sequence of \fBstrtoul\fR(3C) with the value 8 for the +\fIbase\fR argument. In the absence of a size modifier, the corresponding +argument must be a pointer to \fBunsigned int\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBu\fR\fR +.ad +.RS 11n +.rt +Matches an optionally signed decimal integer, whose format is the same as +expected for the subject sequence of \fBstrtoul()\fR with the value 10 for the +\fIbase\fR argument. In the absence of a size modifier, the corresponding +argument must be a pointer to \fBunsigned int\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBx\fR\fR +.ad +.RS 11n +.rt +Matches an optionally signed hexadecimal integer, whose format is the same as +expected for the subject sequence of \fBstrtoul()\fR with the value 16 for the +\fIbase\fR argument. In the absence of a size modifier, the corresponding +argument must be a pointer to \fBunsigned int\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBa\fR,\fBe\fR,\fBf\fR,\fBg\fR\fR +.ad +.RS 11n +.rt +Matches an optionally signed floating-point number, infinity, or NaN, whose +format is the same as expected for the subject sequence of \fBstrtod\fR(3C). In +the absence of a size modifier, the corresponding argument must be a pointer to +\fBfloat\fR. The \fBe\fR, \fBf\fR, and \fBg\fR specifiers match hexadecimal +floating point values only in C99/SUSv3 (see \fBstandards\fR(5)) mode, but the +\fBa\fR specifier always matches hexadecimal floating point values. +.sp +These conversion specifiers match any subject sequence accepted by +\fBstrtod\fR(3C), including the INF, INFINITY, NAN, and +NAN(\fIn-char-sequence\fR) forms. The result of the conversion is the same as +that of calling \fBstrtod()\fR (or \fBstrtof()\fR or \fBstrtold()\fR) with the +matching sequence, including the raising of floating point exceptions and the +setting of \fBerrno\fR to \fBERANGE\fR, if applicable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBs\fR\fR +.ad +.RS 11n +.rt +Matches a sequence of bytes that are not white-space characters. The +corresponding argument must be a pointer to the initial byte of an array of +\fBchar\fR, \fBsigned char\fR, or \fBunsigned char\fR large enough to accept +the sequence and a terminating null character code, which will be added +automatically. +.sp +If an \fBl\fR (ell) qualifier is present, the input is a sequence of characters +that begins in the initial shift state. Each character is converted to a +wide-character as if by a call to the \fBmbrtowc\fR(3C) function, with the +conversion state described by an \fBmbstate_t\fR object initialized to zero +before the first character is converted. The corresponding argument must be a +pointer to an array of \fBwchar_t\fR large enough to accept the sequence and +the terminating null wide-character, which will be added automatically. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB[\fR\fR +.ad +.RS 11n +.rt +Matches a non-empty sequence of characters from a set of expected characters +(the \fIscanset\fR). The normal skip over white-space characters is suppressed +in this case. The corresponding argument must be a pointer to the initial byte +of an array of \fBchar\fR, \fBsigned char\fR, or \fBunsigned char\fR large +enough to accept the sequence and a terminating null byte, which will be added +automatically. +.sp +If an \fBl\fR (ell) qualifier is present, the input is 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 \fBmbrtowc()\fR function, +with the conversion state described by an \fBmbstate_t\fR object initialized to +zero before the first character is converted. The corresponding argument must +be a pointer to an array of \fBwchar_t\fR large enough to accept the sequence +and the terminating null wide-character, which will be added automatically. +.sp +The conversion specification includes all subsequent characters in the +\fIformat\fR string up to and including the matching right square bracket +(\fB]\fR). The characters between the square brackets (the \fIscanlist\fR) +comprise the scanset, unless the character after the left square bracket is a +circumflex (\fB^\fR), in which case the scanset contains all characters that do +not appear in the scanlist between the circumflex and the right square bracket. +If the conversion specification begins with \fB[\|]\fR or \fB[^]\fR, the right +square bracket is included in the scanlist and the next right square bracket is +the matching right square bracket that ends the conversion specification; +otherwise the first right square bracket is the one that ends the conversion +specification. If a \fB-\fR is in the scanlist and is not the first character, +nor the second where the first character is a \fB^\fR, nor the last character, +it indicates a range of characters to be matched. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBc\fR\fR +.ad +.RS 11n +.rt +Matches a sequence of characters of the number specified by the field width (1 +if no field width is present in the conversion specification). The +corresponding argument must be a pointer to the initial byte of an array of +\fBchar\fR, \fBsigned char\fR, or \fBunsigned char\fR large enough to accept +the sequence. No null byte is added. The normal skip over white-space +characters is suppressed in this case. +.sp +If an \fBl\fR (ell) qualifier is present, the input is 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 \fBmbrtowc()\fR function, +with the conversion state described by an \fBmbstate_t\fR object initialized to +zero before the first character is converted. The corresponding argument must +be a pointer to an array of \fBwchar_t\fR large enough to accept the resulting +sequence of wide-characters. No null wide-character is added. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBp\fR\fR +.ad +.RS 11n +.rt +Matches the set of sequences that is the same as the set of sequences that is +produced by the \fB%p\fR conversion of the corresponding \fBprintf\fR(3C) +functions. The corresponding argument must be a pointer to a pointer to +\fBvoid\fR. If the input item is a value converted earlier during the same +program execution, the pointer that results will compare equal to that value; +otherwise the behavior of the \fB%p\fR conversion is undefined. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBn\fR\fR +.ad +.RS 11n +.rt +No input is consumed. The corresponding argument must be a pointer to the +integer into which is to be written the number of bytes read from the input so +far by this call to the \fBscanf()\fR functions. Execution of a \fB%n\fR +conversion specification does not increment the assignment count returned at +the completion of execution of the function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBC\fR\fR +.ad +.RS 11n +.rt +Same as \fBlc\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBS\fR\fR +.ad +.RS 11n +.rt +Same as \fBls\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%\fR\fR +.ad +.RS 11n +.rt +Matches a single \fB%\fR; no conversion or assignment occurs. The complete +conversion specification must be \fB%%\fR. +.RE + +.sp +.LP +If a conversion specification is invalid, the behavior is undefined. +.sp +.LP +The conversion characters \fBA\fR, \fBE\fR, \fBF\fR, \fBG\fR, and \fBX\fR are +also valid and behave the same as, respectively, \fBa\fR, \fBe\fR, \fBf\fR, +\fBg\fR, and \fBx\fR. +.sp +.LP +If end-of-file is encountered during input, conversion is terminated. If +end-of-file occurs before any bytes matching the current conversion +specification (except for \fB%n\fR) have been read (other than leading +white-space characters, where permitted), execution of the current conversion +specification terminates 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) is terminated with +an input failure. +.sp +.LP +Reaching the end of the string in \fBsscanf()\fR is equivalent to encountering +end-of-file for \fBfscanf()\fR. +.sp +.LP +If conversion terminates on a conflicting input, the offending input is left +unread in the input. Any trailing white space (including newline characters) is +left unread unless matched by a conversion specification. The success of +literal matches and suppressed assignments is only directly determinable via +the \fB%n\fR conversion specification. +.sp +.LP +The \fBfscanf()\fR and \fBscanf()\fR functions may mark the \fBst_atime\fR +field of the file associated with \fIstream\fR for update. The \fBst_atime\fR +field will be marked for update by the first successful execution of +\fBfgetc\fR(3C), \fBfgets\fR(3C), \fBfread\fR(3C), \fBfscanf(\|),\fR +\fBgetc\fR(3C), \fBgetchar\fR(3C), \fBgets\fR(3C), or \fBscanf()\fR using +\fIstream\fR that returns data not supplied by a prior call to +\fBungetc\fR(3C). +.SH RETURN VALUES +.sp +.LP +Upon successful completion, these functions return the number of successfully +matched and assigned input items; this number can be 0 in the event of an early +matching failure. If the input ends before the first matching failure or +conversion, \fBEOF\fR is returned. If a read error occurs the error indicator +for the stream is set, \fBEOF\fR is returned, and \fBerrno\fR is set to +indicate the error. +.SH ERRORS +.sp +.LP +For the conditions under which the \fBscanf()\fR functions will fail and may +fail, refer to \fBfgetc\fR(3C) or \fBfgetwc\fR(3C). +.sp +.LP +In addition, \fBfscanf()\fR may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEILSEQ\fR\fR +.ad +.RS 10n +.rt +Input byte sequence does not form a valid character. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +There are insufficient arguments. +.RE + +.SH USAGE +.sp +.LP +If the application calling the \fBscanf()\fR functions has any objects of type +\fBwint_t\fR or \fBwchar_t,\fR it must also include the header \fB<wchar.h>\fR +to have these objects defined. +.SH EXAMPLES +.LP +\fBExample 1 \fRThe call: +.sp +.in +2 +.nf +int i, n; float x; char name[50]; +n = scanf("%d%f%s", &i, &x, name) +.fi +.in -2 + +.sp +.LP +with the input line: + +.sp +.in +2 +.nf +25 54.32E-1 Hamster +.fi +.in -2 + +.sp +.LP +will assign to \fIn\fR the value 3, to \fIi\fR the value 25, to \fIx\fR the +value 5.432, and \fIname\fR will contain the string Hamster. + +.LP +\fBExample 2 \fRThe call: +.sp +.in +2 +.nf +int i; float x; char name[50]; +(void) scanf("%2d%f%*d %[0123456789]", &i, &x, name); +.fi +.in -2 + +.sp +.LP +with input: + +.sp +.in +2 +.nf +56789 0123 56a72 +.fi +.in -2 + +.sp +.LP +will assign 56 to \fIi\fR, 789.0 to \fIx\fR, skip 0123, and place the string +56\e0 in \fIname\fR. The next call to \fBgetchar\fR(3C) will return the +character \fBa\fR. + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +CSIEnabled +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBfgetc\fR(3C), \fBfgets\fR(3C), \fBfgetwc\fR(3C), \fBfread\fR(3C), +\fBisspace\fR(3C), \fBprintf\fR(3C), \fBsetlocale\fR(3C), \fBstrtod\fR(3C), +\fBstrtol\fR(3C), \fBstrtoul\fR(3C), \fBwcrtomb\fR(3C), \fBungetc\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +The behavior of the conversion specifier "%%" has changed for all of the +functions described on this manual page. Previously the "%%" specifier accepted +a "%" character from input only if there were no preceding whitespace +characters. The new behavior accepts "%" even if there are preceding +whitespace characters. This new behavior now aligns with the description on +this manual page and in various standards. If the old behavior is desired, the +conversion specification "%*[%]" can be used. diff --git a/usr/src/man/man3c/sched_get_priority_max.3c b/usr/src/man/man3c/sched_get_priority_max.3c new file mode 100644 index 0000000000..c73a79125f --- /dev/null +++ b/usr/src/man/man3c/sched_get_priority_max.3c @@ -0,0 +1,90 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH sched_get_priority_max 3C "1 Apr 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +sched_get_priority_max, sched_get_priority_min \- get scheduling parameter +limits +.SH SYNOPSIS +.LP +.nf +#include <sched.h> + +\fBint\fR \fBsched_get_priority_max\fR(\fBint\fR \fIpolicy\fR); +.fi + +.LP +.nf +\fBint\fR \fBsched_get_priority_min\fR(\fBint\fR \fIpolicy\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsched_get_priority_max()\fR and \fBsched_get_priority_min()\fR functions +return the appropriate maximum or minimum, respectfully, for the scheduling +policy specified by \fIpolicy\fR. +.sp +.LP +The value of \fIpolicy\fR is one of the scheduling policy values defined in +<\fBsched.h\fR>. +.SH RETURN VALUES +.sp +.LP +If successful, the \fBsched_get_priority_max()\fR and +\fBsched_get_priority_min()\fR functions return the appropriate maximum or +minimum priority values, respectively. If unsuccessful, they return \fB\(mi1\fR +and set \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBsched_get_priority_max()\fR and \fBsched_get_priority_min()\fR +functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of the \fIpolicy\fR parameter does not represent a defined scheduling +policy. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibrt\fR(3LIB), \fBsched.h\fR(3HEAD), \fBsched_getparam\fR(3C), +\fBsched_setparam\fR(3C), \fBsched_getscheduler\fR(3C), +\fBsched_rr_get_interval\fR(3C), \fBsched_setscheduler\fR(3C), +\fBtime.h\fR(3HEAD), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/sched_getparam.3c b/usr/src/man/man3c/sched_getparam.3c new file mode 100644 index 0000000000..fcd3964abb --- /dev/null +++ b/usr/src/man/man3c/sched_getparam.3c @@ -0,0 +1,98 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH sched_getparam 3C "1 Apr 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +sched_getparam \- get scheduling parameters +.SH SYNOPSIS +.LP +.nf +#include <sched.h> + +\fBint\fR \fBsched_getparam\fR(\fBpid_t\fR \fIpid\fR, \fBstruct sched_param *\fR\fIparam\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsched_getparam()\fR function returns the scheduling parameters of a +process specified by \fIpid\fR in the \fBsched_param\fR structure pointed to by +\fIparam\fR. The only required member of \fIparam\fR is \fIsched_priority\fR. +.sp +.LP +If a process specified by \fIpid\fR exists and if the calling process has +permission, the scheduling parameters for the process whose process ID is equal +to \fIpid\fR will be returned. +.sp +.LP +If \fIpid\fR is 0, the scheduling parameters for the calling process will be +returned. The behavior of the \fBsched_getparam()\fR function is unspecified if +the value of \fIpid\fR is negative. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBsched_getparam()\fR function returns +\fB0\fR. If the call to \fBsched_getparam()\fR is unsuccessful, the function +returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBsched_getparam()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 9n +.rt +The requesting process does not have permission to obtain the scheduling +parameters of the specified process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBESRCH\fR\fR +.ad +.RS 9n +.rt +No process can be found corresponding to that specified by \fIpid\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibrt\fR(3LIB), \fBsched.h\fR(3HEAD), \fBsched_getscheduler\fR(3C), +\fBsched_setparam\fR(3C), \fBsched_setscheduler\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/sched_getscheduler.3c b/usr/src/man/man3c/sched_getscheduler.3c new file mode 100644 index 0000000000..ee76da92f3 --- /dev/null +++ b/usr/src/man/man3c/sched_getscheduler.3c @@ -0,0 +1,101 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH sched_getscheduler 3C "1 Apr 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +sched_getscheduler \- get scheduling policy +.SH SYNOPSIS +.LP +.nf +#include <sched.h> + +\fBint\fR \fBsched_getscheduler\fR(\fBpid_t\fR \fIpid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsched_getscheduler()\fR function returns the scheduling policy of the +process specified by \fIpid\fR. If the value of \fIpid\fR is negative, the +behavior of the \fBsched_getscheduler()\fR function is unspecified. +.sp +.LP +The values that can be returned by \fBsched_getscheduler()\fR are defined in +the header <\fBsched.h\fR> and described on the \fBsched_setscheduler\fR(3C) +manual page. +.sp +.LP +If a process specified by \fIpid\fR exists and if the calling process has +permission, the scheduling policy will be returned for the process whose +process ID is equal to \fIpid\fR. +.sp +.LP +If \fIpid\fR is 0, the scheduling policy will be returned for the calling +process. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBsched_getscheduler()\fR function returns the +scheduling policy of the specified process. If unsuccessful, the function +returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBsched_getscheduler()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 9n +.rt +The requesting process does not have permission to determine the scheduling +policy of the specified process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBESRCH\fR\fR +.ad +.RS 9n +.rt +No process can be found corresponding to that specified by \fIpid\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibrt\fR(3LIB), \fBsched.h\fR(3HEAD), \fBsched_getparam\fR(3C), +\fBsched_setparam\fR(3C), \fBsched_setscheduler\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/sched_rr_get_interval.3c b/usr/src/man/man3c/sched_rr_get_interval.3c new file mode 100644 index 0000000000..ae69a39540 --- /dev/null +++ b/usr/src/man/man3c/sched_rr_get_interval.3c @@ -0,0 +1,78 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH sched_rr_get_interval 3C "1 Apr 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +sched_rr_get_interval \- get execution time limits +.SH SYNOPSIS +.LP +.nf +#include <sched.h> + +\fBint\fR \fBsched_rr_get_interval\fR(\fBpid_t\fR \fIpid\fR, + \fBstruct timespec *\fR\fIinterval\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsched_rr_get_interval()\fR function updates the \fBtimespec\fR structure +referenced by the \fIinterval\fR argument to contain the current execution time +limit (that is, time quantum) for the process specified by \fIpid\fR. If +\fIpid\fR is 0, the current execution time limit for the calling process will +be returned. +.SH RETURN VALUES +.sp +.LP +If successful, the \fBsched_rr_get_interval()\fR function returns \fB0\fR. +Otherwise, it returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBsched_rr_get_interval()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBESRCH\fR\fR +.ad +.RS 9n +.rt +No process can be found corresponding to that specified by \fIpid\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibrt\fR(3LIB), \fBsched.h\fR(3HEAD), \fBsched_getparam\fR(3C), +\fBsched_setparam\fR(3C), \fBsched_get_priority_max\fR(3C), +\fBsched_getscheduler\fR(3C), \fBsched_setscheduler\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/sched_setparam.3c b/usr/src/man/man3c/sched_setparam.3c new file mode 100644 index 0000000000..f9cf8d82ff --- /dev/null +++ b/usr/src/man/man3c/sched_setparam.3c @@ -0,0 +1,136 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH sched_setparam 3C "1 Apr 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +sched_setparam \- set scheduling parameters +.SH SYNOPSIS +.LP +.nf +#include <sched.h> + +\fBint\fR \fBsched_setparam\fR(\fBpid_t\fR \fIpid\fR, \fBconst struct sched_param *\fR\fIparam\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsched_setparam()\fR function sets the scheduling parameters of the +process specified by \fIpid\fR to the values specified by the \fBsched_param\fR +structure pointed to by \fIparam\fR. The value of the \fIsched_priority\fR +member in the \fBsched_param\fR structure is any integer within the inclusive +priority range for the current scheduling policy of the process specified by +\fIpid\fR. Higher numerical values for the priority represent higher +priorities. If the value of \fIpid\fR is negative, the behavior of the +\fBsched_setparam()\fR function is unspecified. +.sp +.LP +If a process specified by \fIpid\fR exists and if the calling process has +permission, the scheduling parameters will be set for the process whose process +\fBID\fR is equal to \fIpid\fR. The real or effective user \fBID\fR of the +calling process must match the real or saved (from \fBexec\fR(2)) user +\fBID\fR of the target process unless the effective user \fBID\fR of the +calling process is \fB0\fR. See \fBIntro\fR(2). +.sp +.LP +If \fIpid\fR is zero, the scheduling parameters will be set for the calling +process. +.sp +.LP +The target process, whether it is running or not running, resumes execution +after all other runnable processes of equal or greater priority have been +scheduled to run. +.sp +.LP +If the priority of the process specified by the \fIpid\fR argument is set +higher than that of the lowest priority running process and if the specified +process is ready to run, the process specified by the \fIpid\fR argument +preempts a lowest priority running process. Similarly, if the process calling +\fBsched_setparam()\fR sets its own priority lower than that of one or more +other non-empty process lists, then the process that is the head of the highest +priority list also preempts the calling process. Thus, in either case, the +originating process might not receive notification of the completion of the +requested priority change until the higher priority process has executed. +.SH RETURN VALUES +.sp +.LP +If successful, the \fBsched_setparam()\fR function returns \fB0\fR. +.sp +.LP +If the call to \fBsched_setparam()\fR is unsuccessful, the priority remains +unchanged, and the function returns \fB\(mi1\fR and sets \fBerrno\fR to +indicate the error. +.SH ERRORS +.sp +.LP +The \fBsched_setparam()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +One or more of the requested scheduling parameters is outside the range defined +for the scheduling policy of the specified \fIpid\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 10n +.rt +The requesting process does not have permission to set the scheduling +parameters for the specified process, or does not have the appropriate +privilege to invoke \fBsched_setparam()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBESRCH\fR\fR +.ad +.RS 10n +.rt +No process can be found corresponding to that specified by \fIpid\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(2), \fBexec\fR(2), \fBlibrt\fR(3LIB), \fBsched.h\fR(3HEAD), +\fBsched_getparam\fR(3C), \fBsched_getscheduler\fR(3C), +\fBsched_setscheduler\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/sched_setscheduler.3c b/usr/src/man/man3c/sched_setscheduler.3c new file mode 100644 index 0000000000..c9f4ae0864 --- /dev/null +++ b/usr/src/man/man3c/sched_setscheduler.3c @@ -0,0 +1,138 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH sched_setscheduler 3C "1 Apr 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +sched_setscheduler \- set scheduling policy and scheduling parameters +.SH SYNOPSIS +.LP +.nf +#include <sched.h> + +\fBint\fR \fBsched_setscheduler\fR(\fBpid_t\fR \fIpid\fR, \fBint\fR \fIpolicy\fR, + \fBconst struct sched_param *\fR\fIparam\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsched_setscheduler()\fR function sets the scheduling policy and +scheduling parameters of the process specified by \fIpid\fR to \fIpolicy\fR and +the parameters specified in the \fBsched_param\fR structure pointed to by +\fIparam\fR, respectively. The value of the \fBsched_priority\fR member in the +\fBsched_param\fR structure is any integer within the inclusive priority range +for the scheduling policy specified by \fIpolicy\fR. The +\fBsched_setscheduler()\fR function ignores the other members of the +\fBsched_param\fR structure. If the value of \fIpid\fR is negative, the +behavior of the \fBsched_setscheduler()\fR function is unspecified. +.sp +.LP +The possible values for the \fIpolicy\fR parameter are defined in the header +<\fBsched.h\fR> (see \fBsched.h\fR(3HEAD)): +.sp +.LP +If a process specified by \fIpid\fR exists and if the calling process has +permission, the scheduling policy and scheduling parameters are set for the +process whose process \fBID\fR is equal to \fIpid.\fR The real or effective +user \fBID\fR of the calling process must match the real or saved (from +\fBexec\fR(2)) user \fBID\fR of the target process unless the effective user +\fBID\fR of the calling process is 0. See \fBIntro\fR(2). +.sp +.LP +If \fIpid\fR is 0, the scheduling policy and scheduling parameters are set for +the calling process. +.sp +.LP +To change the \fIpolicy\fR of any process to either of the real time policies +\fBSCHED_FIFO\fR or \fBSCHED_RR\fR, the calling process must either have the +\fBSCHED_FIFO\fR or \fBSCHED_RR\fR policy or have an effective user \fBID\fR of +\fB0\fR. +.sp +.LP +The \fBsched_setscheduler()\fR function is considered successful if it succeeds +in setting the scheduling policy and scheduling parameters of the process +specified by \fIpid\fR to the values specified by \fIpolicy\fR and the +structure pointed to by \fIparam\fR, respectively. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the function returns the former scheduling policy +of the specified process. If the \fBsched_setscheduler()\fR function fails to +complete successfully, the policy and scheduling paramenters remain unchanged, +and the function returns \(mi1 and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBsched_setscheduler()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of \fIpolicy\fR is invalid, or one or more of the parameters +contained in \fIparam\fR is outside the valid range for the specified +scheduling policy. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 10n +.rt +The requesting process does not have permission to set either or both of the +scheduling parameters or the scheduling policy of the specified process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBESRCH\fR\fR +.ad +.RS 10n +.rt +No process can be found corresponding to that specified by \fIpid.\fR +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBpriocntl\fR(1), \fBIntro\fR(2), \fBexec\fR(2), \fBpriocntl\fR(2), +\fBlibrt\fR(3LIB), \fBsched.h\fR(3HEAD), \fBsched_get_priority_max\fR(3C), +\fBsched_getparam\fR(3C), \fBsched_getscheduler\fR(3C), +\fBsched_setparam\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/sched_yield.3c b/usr/src/man/man3c/sched_yield.3c new file mode 100644 index 0000000000..182b2cacec --- /dev/null +++ b/usr/src/man/man3c/sched_yield.3c @@ -0,0 +1,63 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH sched_yield 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +sched_yield \- yield processor +.SH SYNOPSIS +.LP +.nf +#include <sched.h> + +\fBint\fR \fBsched_yield\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsched_yield()\fR function forces the running thread to relinquish the +processor until the process again becomes the head of its process list. It +takes no arguments. +.SH RETURN VALUES +.sp +.LP +If successful, \fBsched_yield()\fR returns \fB0\fR, otherwise, it returns +\fB\(mi1\fR, and sets \fBerrno\fR to indicate the error condition. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibrt\fR(3LIB), \fBsched.h\fR(3HEAD), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/schedctl_init.3c b/usr/src/man/man3c/schedctl_init.3c new file mode 100644 index 0000000000..f2ee505330 --- /dev/null +++ b/usr/src/man/man3c/schedctl_init.3c @@ -0,0 +1,133 @@ +'\" te +.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH schedctl_init 3C "28 May 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +schedctl_init, schedctl_lookup, schedctl_exit, schedctl_start, schedctl_stop \- +preemption control +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <schedctl.h> + +\fBschedctl_t *\fR\fBschedctl_init\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBschedctl_t *\fR\fBschedctl_lookup\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBschedctl_exit\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBschedctl_start\fR(\fBschedctl_t *\fR\fIptr\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBschedctl_stop\fR(\fBschedctl_t *\fR\fIptr\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions provide limited control over the scheduling of a thread (see +\fBthreads\fR(5)). They allow a running thread to give a hint to the kernel +that preemptions of that thread should be avoided. The most likely use for +these functions is to block preemption while holding a spinlock. Improper use +of this facility, including attempts to block preemption for sustained periods +of time, may result in reduced performance. +.sp +.LP +The \fBschedctl_init()\fR function initializes preemption control for the +calling thread and returns a pointer used to refer to the data. If +\fBschedctl_init()\fR is called more than once by the same thread, the most +recently returned pointer is the only valid one. +.sp +.LP +The \fBschedctl_lookup()\fR function returns the currently allocated preemption +control data associated with the calling thread that was previously returned by +\fBschedctl_init()\fR. This can be useful in programs where it is difficult to +maintain local state for each thread. +.sp +.LP +The \fBschedctl_exit()\fR function removes the preemption control data +associated with the calling thread. +.sp +.LP +The \fBschedctl_start()\fR macro gives a hint to the kernel scheduler that +preemption should be avoided on the current thread. The pointer passed to the +macro must be the same as the pointer returned by the call to +\fBschedctl_init()\fR by the current thread. The behavior of the program when +other values are passed is undefined. +.sp +.LP +The \fBschedctl_stop()\fR macro removes the hint that was set by +\fBschedctl_start()\fR. As with \fBschedctl_start()\fR, the pointer passed to +the macro must be the same as the pointer returned by the call to +\fBschedctl_init()\fR by the current thread. +.sp +.LP +The \fBschedctl_start()\fR and \fBschedctl_stop()\fR macros are intended to be +used to bracket short critical sections, such as the time spent holding a +spinlock. Other uses, including the failure to call \fBschedctl_stop()\fR soon +after calling \fBschedctl_start()\fR, might result in poor performance. +.SH RETURN VALUES +.sp +.LP +The \fBschedctl_init()\fR function returns a pointer to a \fBschedctl_t\fR +structure if the initialization was successful, or \fINULL\fR otherwise. The +\fBschedctl_lookup()\fR function returns a pointer to a \fBschedctl_t\fR +structure if the data for that thread was found, or \fINULL\fR otherwise. +.SH ERRORS +.sp +.LP +No errors are returned. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStable +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpriocntl\fR(1), \fBexec\fR(2), \fBfork\fR(2), \fBpriocntl\fR(2), +\fBattributes\fR(5), \fBthreads\fR(5) +.SH NOTES +.sp +.LP +Preemption control is intended for use by threads belonging to the time-sharing +(TS), interactive (IA), fair-share (FSS), and fixed-priority (FX) scheduling +classes. If used by threads in other scheduling classes, such as real-time +(RT), no errors will be returned but \fBschedctl_start()\fR and +\fBschedctl_stop()\fR will not have any effect. +.sp +.LP +The data used for preemption control are not copied in the child of a +\fBfork\fR(2). Thus, if a process containing threads using preemption control +calls \fBfork\fR and the child does not immediately call \fBexec\fR(2), each +thread in the child must call \fBschedctl_init()\fR again prior to any future +uses of \fBschedctl_start()\fR and \fBschedctl_stop()\fR. Failure to do so will +result in undefined behavior. diff --git a/usr/src/man/man3c/seekdir.3c b/usr/src/man/man3c/seekdir.3c new file mode 100644 index 0000000000..578d12d127 --- /dev/null +++ b/usr/src/man/man3c/seekdir.3c @@ -0,0 +1,67 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH seekdir 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +seekdir \- set position of directory stream +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <dirent.h> + +\fBvoid\fR \fBseekdir\fR(\fBDIR *\fR\fIdirp\fR, \fBlong int\fR \fIloc\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBseekdir()\fR function sets the position of the next \fBreaddir\fR(3C) +operation on the directory stream specified by \fIdirp\fR to the position +specified by \fIloc\fR. The value of \fIloc\fR should have been returned from +an earlier call to \fBtelldir\fR(3C). The new position reverts to the one +associated with the directory stream when \fBtelldir()\fR was performed. +.sp +.LP +If the value of \fIloc\fR was not obtained from an earlier call to +\fBtelldir()\fR or if a call to \fBrewinddir\fR(3C) occurred between the call +to \fBtelldir\fR \fB()\fR and the call to \fBseekdir()\fR, the results of +subsequent calls to \fBreaddir()\fR are unspecified. +.SH RETURN VALUES +.sp +.LP +The \fBseekdir()\fR function returns no value. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBopendir\fR(3C), \fBreaddir\fR(3C), \fBrewinddir\fR(3C), \fBtelldir\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/select.3c b/usr/src/man/man3c/select.3c new file mode 100644 index 0000000000..0be08d4352 --- /dev/null +++ b/usr/src/man/man3c/select.3c @@ -0,0 +1,435 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH select 3C "1 Nov 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +select, pselect, FD_SET, FD_CLR, FD_ISSET, FD_ZERO \- synchronous I/O +multiplexing +.SH SYNOPSIS +.LP +.nf +#include <sys/time.h> + +\fBint\fR \fBselect\fR(\fBint\fR \fInfds\fR, + \fBfd_set *restrict\fR \fIreadfds\fR, \fBfd_set *restrict\fR \fIwritefds\fR, + \fBfd_set *restrict\fR \fIerrorfds\fR, + \fBstruct timeval *restrict\fR \fItimeout\fR); +.fi + +.LP +.nf +\fBint\fR \fBpselect\fR(\fBint\fR \fInfds\fR, + \fBfd_set *restrict\fR \fIreadfds\fR, \fBfd_set *restrict\fR \fIwritefds\fR, + \fBfd_set *restrict\fR \fIerrorfds\fR, + \fBconst struct timespec *restrict\fR \fItimeout\fR, + \fBconst sigset_t *restrict\fR \fIsigmask\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBFD_SET\fR(\fBint\fR \fIfd\fR, \fBfd_set *\fR\fIfdset\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBFD_CLR\fR(\fBint\fR \fIfd\fR, \fBfd_set *\fR\fIfdset\fR); +.fi + +.LP +.nf +\fBint\fR \fBFD_ISSET\fR(\fBint\fR \fIfd\fR, \fBfd_set *\fR\fIfdset\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBFD_ZERO\fR(\fBfd_set *\fR\fIfdset\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpselect()\fR function examines the file descriptor sets whose addresses +are passed in the \fIreadfds\fR, \fIwritefds\fR, and \fIerrorfds\fR parameters +to see if some of their descriptors are ready for reading, are ready for +writing, or have an exceptional condition pending, respectively. +.sp +.LP +The \fBselect()\fR function is equivalent to the \fBpselect()\fR function, +except as follows: +.RS +4 +.TP +.ie t \(bu +.el o +For the \fBselect()\fR function, the timeout period is given in seconds and +microseconds in an argument of type \fBstruct timeval\fR, whereas for the +\fBpselect()\fR function the timeout period is given in seconds and nanoseconds +in an argument of type \fBstruct timespec\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The \fBselect()\fR function has no \fIsigmask\fR argument. It behaves as +\fBpselect()\fR does when \fIsigmask\fR is a null pointer. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Upon successful completion, the \fBselect()\fR function might modify the object +pointed to by the \fItimeout\fR argument. +.RE +.sp +.LP +The \fBselect()\fR and \fBpselect()\fR functions support regular files, +terminal and pseudo-terminal devices, STREAMS-based files, FIFOs, pipes, and +sockets. The behavior of \fBselect()\fR and \fBpselect()\fR on file descriptors +that refer to other types of file is unspecified. +.sp +.LP +The \fInfds\fR argument specifies the range of file descriptors to be tested. +The first \fInfds\fR descriptors are checked in each set; that is, the +descriptors from zero through \fInfds\fR-1 in the descriptor sets are examined. +.sp +.LP +If the \fIreadfs\fR argument is not a null pointer, it points to an object of +type \fBfd_set\fR 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. +.sp +.LP +If the \fIwritefs\fR argument is not a null pointer, it points to an object of +type \fBfd_set\fR 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. +.sp +.LP +If the \fIerrorfds\fR argument is not a null pointer, it points to an object of +type \fBfd_set\fR 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. +.sp +.LP +Upon successful completion, the objects pointed to by the \fIreadfs\fR, +\fIwritefs\fR, and \fIerrorfds\fR arguments are modified to indicate which file +descriptors are ready for reading, ready for writing, or have an error +condition pending, respectively, and return the total number of ready +descriptors in all the output sets. For each file descriptor less than +\fInfds\fR, the corresponding bit will be set on successful completion if it +was set on input and the associated condition is true for that file descriptor. +.sp +.LP +If none of the selected descriptors are ready for the requested operation, the +\fBselect()\fR or \fBpselect()\fR function blocks until at least one of the +requested operations becomes ready, until the timeout occurs, or until +interrupted by a signal. The \fItimeout\fR parameter controls how long the +\fBselect()\fR or \fBpselect()\fR function takes before timing out. If the +\fItimeout\fR 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 returns. If the +\fItimeout\fR parameter is a null pointer, then the call to \fBselect()\fR or +\fBpselect()\fR blocks indefinitely until at least one descriptor meets the +specified criteria. To effect a poll, the \fItimeout\fR parameter should not be +a null pointer, and should point to a zero-valued \fBtimespec\fR structure. +.sp +.LP +The use of a \fItimeout\fR does not affect any pending timers set up by +\fBalarm\fR(2), \fBualarm\fR(3C), or \fBsetitimer\fR(2). +.sp +.LP +If \fIsigmask\fR is not a null pointer, then the \fBpselect()\fR function +replaces the signal mask of the process by the set of signals pointed to by +\fIsigmask\fR before examining the descriptors, and restores the signal mask of +the process before returning. +.sp +.LP +A descriptor is considered ready for reading when a call to an input function +with \fBO_NONBLOCK\fR 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 will be considered ready for reading.) +.sp +.LP +A descriptor is considered ready for writing when a call to an output function +with \fBO_NONBLOCK\fR clear would not block, whether or not the function would +transfer data successfully. +.sp +.LP +If a socket has a pending error, it is 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, if the operation +is meaningless for a particular file type, \fBselect()\fR or \fBpselect()\fR +indicates that the descriptor is ready for read or write operations and +indicates that the descriptor has no exceptional condition pending. +.sp +.LP +If a descriptor refers to a socket, the implied input function is the +\fBrecvmsg\fR(3XNET) function with parameters requesting normal and ancillary +data, such that the presence of either type causes the socket to be marked as +readable. The presence of out-of-band data is checked if the socket option +\fBSO_OOBINLINE\fR has been enabled, as out-of-band data is enqueued with +normal data. If the socket is currently listening, then it is marked as +readable if an incoming connection request has been received, and a call to the +accept function completes without blocking. +.sp +.LP +If a descriptor refers to a socket, the implied output function is the +\fBsendmsg\fR(3XNET) function supplying an amount of normal data equal to the +current value of the \fBSO_SNDLOWAT\fR option for the socket. If a non-blocking +call to the connect function has been made for a socket, and the connection +attempt has either succeeded or failed leaving a pending error, the socket is +marked as writable. +.sp +.LP +A socket is considered to have an exceptional condition pending if a receive +operation with \fBO_NONBLOCK\fR clear for the open file description and with +the \fBMSG_OOB\fR flag set would return out-of-band data without blocking. (It +is protocol-specific whether the \fBMSG_OOB\fR flag would be used to read +out-of-band data.) A socket will also be considered to have an exceptional +condition pending if an out-of-band data mark is present in the receive queue. +.sp +.LP +A file descriptor for a socket that is listening for connections will indicate +that it is ready for reading, when connections are available. A file +descriptor for a socket that is connecting asynchronously will indicate that it +is ready for writing, when a connection has been established. +.sp +.LP +Selecting true for reading on a socket descriptor upon which a +\fBlisten\fR(3XNET) call has been performed indicates that a subsequent +\fBaccept\fR(3XNET) call on that descriptor will not block. +.sp +.LP +If the \fItimeout\fR argument is not a null pointer, it points to an object of +type \fBstruct timeval\fR that specifies a maximum interval to wait for the +selection to complete. If the \fItimeout\fR argument points to an object of +type \fBstruct timeval\fR whose members are 0, \fBselect()\fR does not block. +If the \fItimeout\fR argument is a null pointer, \fBselect()\fR blocks until an +event causes one of the masks to be returned with a valid (non-zero) value. If +the time limit expires before any event occurs that would cause one of the +masks to be set to a non-zero value, \fBselect()\fR completes successfully and +returns 0. +.sp +.LP +If the \fIreadfs\fR, \fIwritefs\fR, and \fIerrorfds\fR arguments are all null +pointers and the \fItimeout\fR argument is not a null pointer, \fBselect()\fR +or \fBpselect()\fR blocks for the time specified, or until interrupted by a +signal. If the \fIreadfs\fR, \fIwritefs\fR, and \fIerrorfds\fR arguments are +all null pointers and the \fItimeout\fR argument is a null pointer, +\fBselect()\fR blocks until interrupted by a signal. +.sp +.LP +File descriptors associated with regular files always select true for ready to +read, ready to write, and error conditions. +.sp +.LP +On failure, the objects pointed to by the \fIreadfs\fR, \fIwritefs\fR, and +\fIerrorfds\fR arguments are not 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 \fIreadfs\fR, \fIwritefs\fR, and +\fIerrorfds\fR arguments have all bits set to 0. +.sp +.LP +File descriptor masks of type \fBfd_set\fR can be initialized and tested with +the macros \fBFD_CLR()\fR, \fBFD_ISSET()\fR, \fBFD_SET()\fR, and +\fBFD_ZERO()\fR. +.sp +.ne 2 +.mk +.na +\fB\fBFD_CLR\fR(\fIfd\fR, &\fIfdset\fR)\fR +.ad +.RS 24n +.rt +Clears the bit for the file descriptor \fIfd\fR in the file descriptor set +\fIfdset\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFD_ISSET\fR(\fIfd\fR, &\fIfdset\fR)\fR +.ad +.RS 24n +.rt +Returns a non-zero value if the bit for the file descriptor \fIfd\fR is set in +the file descriptor set pointed to by \fIfdset\fR, and 0 otherwise. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFD_SET\fR(\fIfd\fR, &\fIfdset\fR)\fR +.ad +.RS 24n +.rt +Sets the bit for the file descriptor \fIfd\fR in the file descriptor set +\fIfdset\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFD_ZERO\fR(&\fIfdset\fR)\fR +.ad +.RS 24n +.rt +Initializes the file descriptor set \fIfdset\fR to have zero bits for all file +descriptors. +.RE + +.sp +.LP +The behavior of these macros is undefined if the \fIfd\fR argument is less than +0 or greater than or equal to \fBFD_SETSIZE\fR, or if \fIfd\fR is not a valid +file descriptor, or if any of the arguments are expressions with side effects. +.SH RETURN VALUES +.sp +.LP +On successful completion, \fBselect()\fR and \fBpselect()\fR return the total +number of bits set in the bit masks. Otherwise, \fB\(mi1\fR is returned and +\fBerrno\fR is set to indicate the error. +.sp +.LP +The \fBFD_CLR()\fR, \fBFD_SET()\fR, and \fBFD_ZERO()\fR macros return no value. +The \fBFD_ISSET()\fR macro returns a non-zero value if the bit for the file +descriptor \fIfd\fR is set in the file descriptor set pointed to by +\fIfdset\fR, and \fB0\fR otherwise. +.SH ERRORS +.sp +.LP +The \fBselect()\fR and \fBpselect()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +One or more of the file descriptor sets specified a file descriptor that is not +a valid open file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 10n +.rt +The function was interrupted before any of the selected events occurred and +before the timeout interval expired. +.sp +If \fBSA_RESTART\fR has been set for the interrupting signal, it is +implementation-dependent whether \fBselect()\fR restarts or returns with +\fBEINTR\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +An invalid timeout interval was specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fInfds\fR argument is less than 0 or greater than \fBFD_SETSIZE\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +One of the specified file descriptors refers to a STREAM or multiplexer that is +linked (directly or indirectly) downstream from a multiplexer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +A component of the pointed-to time limit is outside the acceptable range: +\fBt_sec\fR must be between \fB0\fR and 10^8, inclusive. \fBt_usec\fR must be +greater than or equal to \fB0\fR, and less than 10^6. +.RE + +.SH USAGE +.sp +.LP +The \fBpoll\fR(2) function is preferred over this function. It must be used +when the number of file descriptors exceeds \fBFD_SETSIZE\fR. +.sp +.LP +The use of a timeout does not affect any pending timers set up by +\fBalarm\fR(2), \fBualarm\fR(3C) or \fBsetitimer\fR(2). +.sp +.LP +On successful completion, the object pointed to by the \fItimeout\fR argument +may be modified. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBalarm\fR(2), \fBfcntl\fR(2), \fBpoll\fR(2), \fBread\fR(2), +\fBsetitimer\fR(2), \fBwrite\fR(2), \fBaccept\fR(3SOCKET), +\fBlisten\fR(3SOCKET), \fBualarm\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) +.SH NOTES +.sp +.LP +The default value for \fBFD_SETSIZE\fR (currently 1024) is larger than the +default limit on the number of open files. To accommodate 32-bit applications +that wish to use a larger number of open files with \fBselect()\fR, it is +possible to increase this size at compile time by providing a larger definition +of \fBFD_SETSIZE\fR before the inclusion of any system-supplied header. The +maximum supported size for \fBFD_SETSIZE\fR is 65536. The default value is +already 65536 for 64-bit applications. diff --git a/usr/src/man/man3c/sem_close.3c b/usr/src/man/man3c/sem_close.3c new file mode 100644 index 0000000000..f0277ae754 --- /dev/null +++ b/usr/src/man/man3c/sem_close.3c @@ -0,0 +1,107 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH sem_close 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +sem_close \- close a named semaphore +.SH SYNOPSIS +.LP +.nf +#include <semaphore.h> + +\fBint\fR \fBsem_close\fR(\fBsem_t *\fR\fIsem\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsem_close()\fR function is used to indicate that the calling process is +finished using the named semaphore indicated by \fIsem\fR. The effects of +calling \fBsem_close()\fR for an unnamed semaphore (one created by +\fBsem_init\fR(3C)) are undefined. The \fBsem_close()\fR function deallocates +(that is, make available for reuse by a subsequent \fBsem_open\fR(3C) 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 +\fIsem\fR by this process is undefined. If the semaphore has not been removed +with a successful call to \fBsem_unlink\fR(3C), then \fBsem_close()\fR has no +effect on the state of the semaphore. If the \fBsem_unlink\fR(3C) function has +been successfully invoked for \fIname\fR after the most recent call to +\fBsem_open\fR(3C) with \fBO_CREAT\fR for this semaphore, then when all +processes that have opened the semaphore close it, the semaphore is no longer +be accessible. +.SH RETURN VALUES +.sp +.LP +If successful, \fBsem_close()\fR returns \fB0\fR, otherwise it returns +\fB\(mi1\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBsem_close()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR \fR +.ad +.RS 11n +.rt +The \fIsem\fR argument is not a valid semaphore descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR \fR +.ad +.RS 11n +.rt +The \fBsem_close()\fR function is not supported by the system. +.RE + +.SH USAGE +.sp +.LP +The \fBsem_close()\fR function should not be called for an unnamed semaphore +initialized by \fBsem_init\fR(3C). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBsem_init\fR(3C), \fBsem_open\fR(3C), \fBsem_unlink\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +Solaris 2.6 was the first release to support the Asynchronous Input and Output +option. Prior to this release, this function always returned \fB\(mi1\fR and +set \fBerrno\fR to \fBENOSYS\fR. diff --git a/usr/src/man/man3c/sem_destroy.3c b/usr/src/man/man3c/sem_destroy.3c new file mode 100644 index 0000000000..8712ae64c4 --- /dev/null +++ b/usr/src/man/man3c/sem_destroy.3c @@ -0,0 +1,95 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH sem_destroy 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +sem_destroy \- destroy an unnamed semaphore +.SH SYNOPSIS +.LP +.nf +#include <semaphore.h> + +\fBint\fR \fBsem_destroy\fR(\fBsem_t *\fR\fIsem\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsem_destroy()\fR function is used to destroy the unnamed semaphore +indicated by \fIsem\fR. Only a semaphore that was created using +\fBsem_init\fR(3C) may be destroyed using \fBsem_destroy()\fR; the effect of +calling \fBsem_destroy()\fR with a named semaphore is undefined. The effect of +subsequent use of the semaphore \fIsem\fR is undefined until \fIsem\fR is +re-initialized by another call to \fBsem_init\fR(3C). +.sp +.LP +It is safe to destroy an initialised 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 VALUES +.sp +.LP +If successful, \fBsem_destroy()\fR returns \fB0\fR, otherwise it returns +\fB\(mi1\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBsem_destroy()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR \fR +.ad +.RS 11n +.rt +The \fIsem\fR argument is not a valid semaphore. +.RE + +.sp +.LP +The \fBsem_destroy()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBUSY\fR \fR +.ad +.RS 10n +.rt +There are currently processes (or LWPs or threads) blocked on the semaphore. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBsem_init\fR(3C), \fBsem_open\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/sem_getvalue.3c b/usr/src/man/man3c/sem_getvalue.3c new file mode 100644 index 0000000000..45a641e772 --- /dev/null +++ b/usr/src/man/man3c/sem_getvalue.3c @@ -0,0 +1,98 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH sem_getvalue 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +sem_getvalue \- get the value of a semaphore +.SH SYNOPSIS +.LP +.nf +#include <semaphore.h> + +\fBint\fR \fBsem_getvalue\fR(\fBsem_t *restrict\fR \fIsem\fR, \fBint *restrict\fR \fIsval\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsem_getvalue()\fR function updates the location referenced by the +\fIsval\fR argument to have the value of the semaphore referenced by \fIsem\fR +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. +.sp +.LP +If \fIsem\fR is locked, then the value returned by \fBsem_getvalue()\fR is +either zero or a negative number whose absolute value represents the number of +processes waiting for the semaphore at some unspecified time during the call. +.sp +.LP +The value set in \fIsval\fR may be 0 or positive. If \fIsval\fR is 0, there may +be other processes (or LWPs or threads) waiting for the semaphore; if +\fIsval\fR is positive, no process is waiting. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBsem_getvalue()\fR returns \fB0\fR. Otherwise, it +returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBsem_getvalue()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR \fR +.ad +.RS 11n +.rt +The \fIsem\fR argument does not refer to a valid semaphore. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR \fR +.ad +.RS 11n +.rt +The \fBsem_getvalue()\fR function is not supported by the system. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBsemctl\fR(2), \fBsemget\fR(2), \fBsemop\fR(2), \fBsem_post\fR(3C), +\fBsem_wait\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/sem_init.3c b/usr/src/man/man3c/sem_init.3c new file mode 100644 index 0000000000..919f2b9d83 --- /dev/null +++ b/usr/src/man/man3c/sem_init.3c @@ -0,0 +1,140 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical +.\" and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH sem_init 3C "9 Jul 2009" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +sem_init \- initialize an unnamed semaphore +.SH SYNOPSIS +.LP +.nf +#include <semaphore.h> + +\fBint\fR \fBsem_init\fR(\fBsem_t *\fR\fIsem\fR, \fBint\fR \fIpshared\fR, \fBunsigned int\fR \fIvalue\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsem_init()\fR function is used to initialize the unnamed semaphore +referred to by \fIsem\fR. The value of the initialized semaphore is +\fIvalue\fR. Following a successful call to \fBsem_init()\fR, the semaphore may +be used in subsequent calls to \fBsem_wait\fR(3C), \fBsem_trywait\fR(3C), +\fBsem_post\fR(3C), and \fBsem_destroy\fR(3C). This semaphore remains usable +until the semaphore is destroyed. +.sp +.LP +If the \fIpshared\fR argument has a non-zero value, then the semaphore is +shared between processes; in this case, any process that can access the +semaphore \fIsem\fR can use \fIsem\fR for performing \fBsem_wait\fR(3C), +\fBsem_trywait\fR(3C), \fBsem_post\fR(3C), and \fBsem_destroy\fR(3C) +operations. +.sp +.LP +Only \fIsem\fR itself may be used for performing synchronization. The result of +referring to copies of \fIsem\fR in calls to \fBsem_wait\fR(3C), +\fBsem_trywait\fR(3C), \fBsem_post\fR(3C), and \fBsem_destroy\fR(3C), is +undefined. +.sp +.LP +If the \fIpshared\fR argument is zero, then the semaphore is shared between +threads of the process; any thread in this process can use \fIsem\fR for +performing \fBsem_wait\fR(3C), \fBsem_trywait\fR(3C), \fBsem_post\fR(3C), and +\fBsem_destroy\fR(3C) operations. The use of the semaphore by threads other +than those created in the same process is undefined. +.sp +.LP +Attempting to initialize an already initialized semaphore results in undefined +behavior. +.sp +.LP +The \fBsem_open\fR(3C) function is used with named semaphores. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the function initializes the semaphore in +\fIsem\fR. Otherwise, it returns \fB\(mi1\fR and sets \fBerrno\fR to indicate +the error. +.SH ERRORS +.sp +.LP +The \fBsem_init()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR \fR +.ad +.RS 11n +.rt +The \fIvalue\fR argument exceeds \fBSEM_VALUE_MAX\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSPC\fR \fR +.ad +.RS 11n +.rt +A resource required to initialize the semaphore has been exhausted, or the +resources have reached the limit on semaphores (\fBSEM_NSEMS_MAX\fR). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR \fR +.ad +.RS 11n +.rt +The \fBsem_init()\fR function is not supported by the system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR \fR +.ad +.RS 11n +.rt +The process lacks the appropriate privileges to initialize the semaphore. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBsem_destroy\fR(3C), \fBsem_open\fR(3C), \fBsem_post\fR(3C), +\fBsem_wait\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/sem_open.3c b/usr/src/man/man3c/sem_open.3c new file mode 100644 index 0000000000..81e9d280a2 --- /dev/null +++ b/usr/src/man/man3c/sem_open.3c @@ -0,0 +1,269 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical +.\" and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH sem_open 3C "9 Jul 2009" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +sem_open \- initialize/open a named semaphore +.SH SYNOPSIS +.LP +.nf +#include <semaphore.h> + +\fBsem_t *\fR\fBsem_open\fR(\fBconst char *\fR\fIname\fR, \fBint\fR \fIoflag\fR, + \fB/* unsigned long\fR \fImode\fR, \fBunsigned int\fR \fIvalue\fR */ ...); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsem_open()\fR function establishes a connection between a named +semaphore and a process (or LWP or thread). Following a call to +\fBsem_open()\fR with semaphore name \fIname\fR, the process may reference the +semaphore associated with \fIname\fR using the address returned from the call. +This semaphore may be used in subsequent calls to \fBsem_wait\fR(3C), +\fBsem_trywait\fR(3C), \fBsem_post\fR(3C), and \fBsem_close\fR(3C). The +semaphore remains usable by this process until the semaphore is closed by a +successful call to \fBsem_close\fR(3C), \fB_Exit\fR(2), or one of the +\fBexec\fR functions. +.sp +.LP +The \fIoflag\fR argument controls whether the semaphore is created or merely +accessed by the call to \fBsem_open()\fR. The following flag bits may be set in +\fIoflag\fR: +.sp +.ne 2 +.mk +.na +\fB\fBO_CREAT\fR\fR +.ad +.RS 11n +.rt +This flag is used to create a semaphore if it does not already exist. If +\fBO_CREAT\fR is set and the semaphore already exists, then \fBO_CREAT\fR has +no effect, except as noted under \fB\fR\fBO_EXCL.\fR Otherwise, +\fBsem_open()\fR creates a named semaphore. The \fBO_CREAT\fR flag requires a +third and a fourth argument: \fImode\fR, which is of type \fBmode_t\fR, and +\fIvalue\fR, which is of type \fBunsigned int\fR. The semaphore is created with +an initial value of \fIvalue\fR. Valid initial values for semaphores are less +than or equal to \fBSEM_VALUE_MAX.\fR +.sp +The user \fBID\fR of the semaphore is set to the effective user \fBID\fR of the +process; the group \fBID\fR of the semaphore is set to a system default group +\fBID\fR or to the effective group \fBID\fR of the process. The permission bits +of the semaphore are set to the value of the \fImode\fR argument except those +set in the file mode creation mask of the process (see \fBumask\fR(2)). When +bits in \fImode\fR other than the file permission bits are specified, the +effect is unspecified. +.sp +After the semaphore named \fIname\fR has been created by \fBsem_open()\fR with +the \fBO_CREAT\fR flag, other processes can connect to the semaphore by calling +\fBsem_open()\fR with the same value of \fIname\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBO_EXCL\fR\fR +.ad +.RS 11n +.rt +If \fBO_EXCL\fR and \fBO_CREAT\fR are set, \fBsem_open()\fR fails if the +semaphore \fIname\fR 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 \fBsem_open()\fR with \fBO_EXCL\fR and \fBO_CREAT\fR +set. If \fBO_EXCL\fR is set and \fBO_CREAT\fR is not set, the effect is +undefined. +.RE + +.sp +.LP +If flags other than \fBO_CREAT\fR and \fBO_EXCL\fR are specified in the +\fIoflag\fR parameter, the effect is unspecified. +.sp +.LP +The \fIname\fR 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 \fIname\fR argument conforms to +the construction rules for a pathname. The first character of \fIname\fR must +be a slash (/) character and the remaining characters of \fIname\fR cannot +include any slash characters. For maximum portability, \fIname\fR should +include no more than 14 characters, but this limit is not enforced. +.sp +.LP +If a process makes multiple successful calls to \fBsem_open()\fR with the same +value for \fIname\fR, the same semaphore address is returned for each such +successful call, provided that there have been no calls to \fBsem_unlink\fR(3C) +for this semaphore. +.sp +.LP +References to copies of the semaphore produce undefined results. +.sp +.LP +The \fBsem_init\fR(3C) function is used with unnamed semaphores. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the function returns the address of the semaphore. +Otherwise, it will return a value of \fBSEM_FAILED\fR and set \fBerrno\fR to +indicate the error. The symbol \fBSEM_FAILED\fR is defined in the header +\fB<semaphore.h>\fR\&. No successful return from \fBsem_open()\fR will return +the value \fB\fR\fBSEM_FAILED.\fR +.SH ERRORS +.sp +.LP +If any of the following conditions occur, the \fBsem_open()\fR function will +return \fBSEM_FAILED\fR and set \fBerrno\fR to the corresponding value: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 16n +.rt +The named semaphore exists and the \fBO_RDWR\fR permissions are denied, or the +named semaphore does not exist and permission to create the named semaphore is +denied. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEEXIST\fR\fR +.ad +.RS 16n +.rt +\fBO_CREAT\fR and \fBO_EXCL\fR are set and the named semaphore already exists. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 16n +.rt +The \fBsem_open()\fR function was interrupted by a signal. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 16n +.rt +The \fBsem_open()\fR operation is not supported for the given name, or +\fBO_CREAT\fR was set in \fIoflag\fR and \fIvalue\fR is greater than +\fBSEM_VALUE_MAX\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 16n +.rt +The number of open semaphore descriptors in this process exceeds +\fBSEM_NSEMS_MAX\fR, or the number of open file descriptors in this process +exceeds \fBOPEN_MAX\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +The length of \fIname\fR string exceeds \fIPATH_MAX\fR, or a pathname component +is longer than \fINAME_MAX\fR while \fB_POSIX_NO_TRUNC\fR is in effect. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENFILE\fR\fR +.ad +.RS 16n +.rt +Too many semaphores are currently open in the system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 16n +.rt +\fBO_CREAT\fR is not set and the named semaphore does not exist. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSPC\fR\fR +.ad +.RS 16n +.rt +There is insufficient space for the creation of the new named semaphore. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR\fR +.ad +.RS 16n +.rt +The \fBsem_open()\fR function is not supported by the system. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBexec\fR(2), \fBexit\fR(2), \fBumask\fR(2), \fBsem_close\fR(3C), +\fBsem_init\fR(3C), \fBsem_post\fR(3C), \fBsem_unlink\fR(3C), +\fBsem_wait\fR(3C), \fBsysconf\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/sem_post.3c b/usr/src/man/man3c/sem_post.3c new file mode 100644 index 0000000000..e67147083a --- /dev/null +++ b/usr/src/man/man3c/sem_post.3c @@ -0,0 +1,125 @@ +'\" te +.\" Copyright (c) 1997, The Open Group. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH sem_post 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +sem_post \- increment the count of a semaphore +.SH SYNOPSIS +.LP +.nf +#include <semaphore.h> + +\fBint\fR \fBsem_post\fR(\fBsem_t *\fR\fIsem\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsem_post()\fR function unlocks the semaphore referenced by \fIsem\fR by +performing a semaphore unlock operation on that semaphore. +.sp +.LP +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. +.sp +.LP +If the value of the semaphore resulting from this operation is 0, then one of +the threads blocked waiting for the semaphore will be allowed to return +successfully from its call to \fBsem_wait\fR(3C). If the symbol +\fB_POSIX_PRIORITY_SCHEDULING\fR is defined, the thread to be unblocked will +be chosen in a manner appropriate to the scheduling policies and parameters in +effect for the blocked threads. In the case of the schedulers \fBSCHED_FIFO\fR +and \fBSCHED_RR\fR, the highest priority waiting thread will 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 +will be unblocked. If the symbol \fB_POSIX_PRIORITY_SCHEDULING\fR is not +defined, the choice of a thread to unblock is unspecified. +.SH RETURN VALUES +.sp +.LP +If successful, \fBsem_post()\fR returns \fB0\fR; otherwise it returns +\fB\(mi1\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBsem_post()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR \fR +.ad +.RS 14n +.rt +The \fIsem\fR argument does not refer to a valid semaphore. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR \fR +.ad +.RS 14n +.rt +The \fBsem_post()\fR function is not supported by the system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOVERFLOW\fR \fR +.ad +.RS 14n +.rt +The semaphore value exceeds \fBSEM_VALUE_MAX\fR. +.RE + +.SH USAGE +.sp +.LP +The \fBsem_post()\fR function is reentrant with respect to signals and may be +invoked from a signal-catching function. The semaphore functionality described +on this manual page is for the POSIX (see \fBstandards\fR(5)) threads +implementation. For the documentation of the Solaris threads interface, see +\fBsemaphore\fR(3C)). +.SH EXAMPLES +.sp +.LP +See \fBsem_wait\fR(3C). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelAsync-Signal-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBsched_setscheduler\fR(3C), \fBsem_wait\fR(3C), \fBsemaphore\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/sem_timedwait.3c b/usr/src/man/man3c/sem_timedwait.3c new file mode 100644 index 0000000000..4da84b09e0 --- /dev/null +++ b/usr/src/man/man3c/sem_timedwait.3c @@ -0,0 +1,169 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH sem_timedwait 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +sem_timedwait, sem_reltimedwait_np \- lock a semaphore +.SH SYNOPSIS +.LP +.nf +#include <semaphore.h> +#include <time.h> + +\fBint\fR \fBsem_timedwait\fR(\fBsem_t *restrict\fR \fIsem\fR, + \fBconst struct timespec *restrict\fR \fIabs_timeout\fR); +.fi + +.LP +.nf +\fBint\fR \fBsem_reltimedwait_np\fR(\fBsem_t *restrict\fR \fIsem\fR, + \fBconst struct timespec *restrict\fR \fIrel_timeout\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsem_timedwait()\fR function locks the semaphore referenced by \fIsem\fR +as in the \fBsem_wait\fR(3C) function. However, if the semaphore cannot be +locked without waiting for another process or thread to unlock the semaphore by +performing a \fBsem_post\fR(3C) function, this wait is terminated when the +specified timeout expires. +.sp +.LP +The \fBsem_reltimedwait_np()\fR function is identical to the +\fBsem_timedwait()\fR function, except that the timeout is specified as a +relative time interval. +.sp +.LP +For \fBsem_timedwait()\fR, the timeout expires when the absolute time specified +by \fIabs_timeout\fR passes, as measured by the \fBCLOCK_REALTIME\fR clock +(that is, when the value of that clock equals or exceeds \fIabs_timeout\fR), or +if the absolute time specified by \fIabs_timeout\fR has already been passed at +the time of the call. +.sp +.LP +For \fBsem_reltimedwait_np()\fR, the timeout expires when the time interval +specified by \fIrel_timeout\fR passes, as measured by the \fBCLOCK_REALTIME\fR +clock, or if the time interval specified by \fIrel_timeout\fR is negative at +the time of the call. +.sp +.LP +The resolution of the timeout is the resolution of the \fBCLOCK_REALTIME\fR +clock. The \fBtimespec\fR data type is defined as a structure in the +<\fBtime.h\fR> header. +.sp +.LP +Under no circumstance does the function fail with a timeout if the semaphore +can be locked immediately. The validity of the \fIabs_timeout\fR need not be +checked if the semaphore can be locked immediately. +.SH RETURN VALUES +.sp +.LP +The \fBsem_timedwait()\fR and \fBsem_reltimedwait_np()\fR functions return 0 if +the calling process successfully performed the semaphore lock operation on the +semaphore designated by \fIsem\fR. If the call was unsuccessful, the state of +the semaphore is be unchanged and the function returns -1 and sets \fBerrno\fR +to indicate the error. +.SH ERRORS +.sp +.LP +The \fBsem_timedwait()\fR and \fBsem_reltimedwait_np()\fR functions will fail +if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 13n +.rt +The \fIsem\fR argument does not refer to a valid semaphore. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 13n +.rt +The process or thread would have blocked, and the timeout parameter specified a +nanoseconds field value less than zero or greater than or equal to 1,000 +million. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBETIMEDOUT\fR\fR +.ad +.RS 13n +.rt +The semaphore could not be locked before the specified timeout expired. +.RE + +.sp +.LP +The \fBsem_timedwait()\fR and \fBsem_reltimedwait_np()\fR functions may fail +if: +.sp +.ne 2 +.mk +.na +\fB\fBEDEADLK\fR\fR +.ad +.RS 11n +.rt +A deadlock condition was detected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 11n +.rt +A signal interrupted this function. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommmitted +_ +MT-LevelMT-Safe +_ +StandardSee below. +.TE + +.sp +.LP +For \fBsem_timedwait()\fR, see \fBstandards\fR(5). +.SH SEE ALSO +.sp +.LP +\fBsemctl\fR(2), \fBsemget\fR(2), \fBsemop\fR(2), \fBtime\fR(2), +\fBsem_post\fR(3C), \fBsem_trywait\fR(3C)\fBsem_wait\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/sem_unlink.3c b/usr/src/man/man3c/sem_unlink.3c new file mode 100644 index 0000000000..f91cccae70 --- /dev/null +++ b/usr/src/man/man3c/sem_unlink.3c @@ -0,0 +1,123 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH sem_unlink 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +sem_unlink \- remove a named semaphore +.SH SYNOPSIS +.LP +.nf +#include <semaphore.h> + +\fBint\fR \fBsem_unlink\fR(\fBconst char *\fR\fIname\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsem_unlink()\fR function removes the semaphore named by the string +\fIname\fR. If the semaphore named by \fIname\fR is currently referenced by +other processes, then \fBsem_unlink()\fR has no effect on the state of the +semaphore. If one or more processes have the semaphore open when +\fBsem_unlink()\fR is called, destruction of the semaphore is postponed until +all references to the semaphore have been destroyed by calls to +\fBsem_close\fR(3C), \fB_Exit\fR(2), or one of the \fBexec\fR functions (see +\fBexec\fR(2)) . Calls to \fBsem_open\fR(3C) to re-create or re-connect to the +semaphore refer to a new semaphore after \fBsem_unlink()\fR is called. The +\fBsem_unlink()\fR call does not block until all references have been +destroyed; it returns immediately. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBsem_unlink()\fR returns \fB0\fR. Otherwise, the +semaphore is not changed and the function returns a value of \fB\(mi1\fR and +sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBsem_unlink()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR \fR +.ad +.RS 17n +.rt +Permission is denied to unlink the named semaphore. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR \fR +.ad +.RS 17n +.rt +The length of \fIname\fR string exceeds \fIPATH_MAX\fR, or a pathname component +is longer than \fINAME_MAX\fR while \fB_POSIX_NO_TRUNC\fR is in effect. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR \fR +.ad +.RS 17n +.rt +The named semaphore does not exist. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR \fR +.ad +.RS 17n +.rt +The \fBsem_unlink()\fR function is not supported by the system. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBexec\fR(2), \fBexit\fR(2), \fBsem_close\fR(3C), \fBsem_open\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +Solaris 2.6 was the first release to support the Asynchronous Input and Output +option. Prior to this release, this function always returned \fB\(mi1\fR and +set \fBerrno\fR to \fBENOSYS\fR. diff --git a/usr/src/man/man3c/sem_wait.3c b/usr/src/man/man3c/sem_wait.3c new file mode 100644 index 0000000000..a8068979a3 --- /dev/null +++ b/usr/src/man/man3c/sem_wait.3c @@ -0,0 +1,209 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH sem_wait 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +sem_wait, sem_trywait \- acquire or wait for a semaphore +.SH SYNOPSIS +.LP +.nf +#include <semaphore.h> + +\fBint\fR \fBsem_wait\fR(\fBsem_t *\fR\fIsem\fR); +.fi + +.LP +.nf +\fBint\fR \fBsem_trywait\fR(\fBsem_t *\fR\fIsem\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsem_wait()\fR function locks the semaphore referenced by \fIsem\fR by +performing a semaphore lock operation on that semaphore. If the semaphore value +is currently zero, then the calling thread will not return from the call to +\fBsem_wait()\fR until it either locks the semaphore or the call is interrupted +by a signal. The \fBsem_trywait()\fR function locks the semaphore referenced by +\fIsem\fR only if the semaphore is currently not locked; that is, if the +semaphore value is currently positive. Otherwise, it does not lock the +semaphore. +.sp +.LP +Upon successful return, the state of the semaphore is locked and remains locked +until the \fBsem_post\fR(3C) function is executed and returns successfully. +.sp +.LP +The \fBsem_wait()\fR function is interruptible by the delivery of a signal. +.SH RETURN VALUES +.sp +.LP +The \fBsem_wait()\fR and \fBsem_trywait()\fR functions return \fB0\fR if the +calling process successfully performed the semaphore lock operation on the +semaphore designated by \fIsem\fR. If the call was unsuccessful, the state of +the semaphore is unchanged, and the function returns \fB\(mi1\fR and sets +\fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBsem_wait()\fR and \fBsem_trywait()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR \fR +.ad +.RS 11n +.rt +The \fIsem\fR function does not refer to a valid semaphore. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR \fR +.ad +.RS 11n +.rt +The \fBsem_wait()\fR and \fBsem_trywait()\fR functions are not supported by the +system. +.RE + +.sp +.LP +The \fBsem_trywait()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR \fR +.ad +.RS 11n +.rt +The semaphore was already locked, so it cannot be immediately locked by the +\fBsem_trywait()\fR operation. +.RE + +.sp +.LP +The \fBsem_wait()\fR and \fBsem_trywait()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEDEADLK\fR \fR +.ad +.RS 12n +.rt +A deadlock condition was detected; that is, two separate processes are waiting +for an available resource to be released via a semaphore "held" by the other +process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR \fR +.ad +.RS 12n +.rt +A signal interrupted this function. +.RE + +.SH USAGE +.sp +.LP +Realtime applications may encounter priority inversion when using semaphores. +The problem occurs when a high priority thread "locks" (that is, waits on) a +semaphore that is about to be "unlocked" (that is, posted) by a low priority +thread, but the low priority thread is preempted by a medium priority thread. +This scenario leads to priority inversion; a high priority thread is blocked by +lower priority threads for an unlimited period of time. During system design, +realtime programmers must take into account the possibility of this kind of +priority inversion. They can deal with it in a number of ways, such as by +having critical sections that are guarded by semaphores execute at a high +priority, so that a thread cannot be preempted while executing in its critical +section. +.SH EXAMPLES +.LP +\fBExample 1 \fRThe customer waiting-line in a bank may be analogous to the +synchronization scheme of a semaphore utilizing \fBsem_wait()\fR and +\fBsem_trywait()\fR: +.sp +.in +2 +.nf +#include <errno.h> +#define TELLERS 10 +sem_t bank_line; /* semaphore */ +int banking_hours(), deposit_withdrawal; +void *customer(), do_business(), skip_banking_today(); +thread_t tid; +\&... + +sem_init(&bank_line,TRUE,TELLERS); /* 10 tellers + available */ +while(banking_hours()) + thr_create(NULL, NULL, customer, + (void *)deposit_withdrawal, THREAD_NEW_LWP, &tid); +\&... + +void * +customer(deposit_withdrawal) +void *deposit_withdrawal; +{ + int this_customer, in_a_hurry = 50; + this_customer = rand() % 100; + if (this_customer == in_a_hurry) { + if (sem_trywait(&bank_line) != 0) + if (errno == EAGAIN) { /* no teller available */ + skip_banking_today(this_customer); + return; + } /*else go immediately to available teller + & decrement bank_line*/ + } + else + sem_wait(&bank_line); /* wait for next teller, + then proceed, and decrement bank_line */ + do_business((int *)deposit_withdrawal); + sem_getvalue(&bank_line,&num_tellers); + sem_post(&bank_line); /* increment bank_line; + this_customer's teller is now available */ +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBsem_post\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/semaphore.3c b/usr/src/man/man3c/semaphore.3c new file mode 100644 index 0000000000..e58f749e88 --- /dev/null +++ b/usr/src/man/man3c/semaphore.3c @@ -0,0 +1,323 @@ +'\" te +.\" Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved. +.\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 1995 IEEE. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH semaphore 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +semaphore, sema_init, sema_destroy, sema_wait, sema_trywait, sema_post \- +semaphores +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR... ] \fIfile\fR... -lthread -lc [ \fIlibrary\fR... ] +#include <synch.h> + +\fBint\fR \fBsema_init\fR(\fBsema_t *\fR\fIsp\fR, \fBunsigned int\fR \fIcount\fR, \fBint\fR \fItype\fR, + \fBvoid *\fR \fIarg\fR); +.fi + +.LP +.nf +\fBint\fR \fBsema_destroy\fR(\fBsema_t *\fR\fIsp\fR); +.fi + +.LP +.nf +\fBint\fR \fBsema_wait\fR(\fBsema_t *\fR\fIsp\fR); +.fi + +.LP +.nf +\fBint\fR \fBsema_trywait\fR(\fBsema_t *\fR\fIsp\fR); +.fi + +.LP +.nf +\fBint\fR \fBsema_post\fR(\fBsema_t *\fR\fIsp\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +A semaphore is a non-negative integer count and is generally used to coordinate +access to resources. The initial semaphore count is set to the number of free +resources, then threads slowly increment and decrement the count as resources +are added and removed. If the semaphore count drops to 0, which means no +available resources, threads attempting to decrement the semaphore will block +until the count is greater than 0. +.sp +.LP +Semaphores can synchronize threads in this process and other processes if they +are allocated in writable memory and shared among the cooperating processes +(see \fBmmap\fR(2)), and have been initialized for this purpose. +.sp +.LP +Semaphores must be initialized before use; semaphores pointed to by \fIsp\fR to +\fIcount\fR are initialized by \fBsema_init()\fR. The \fItype\fR argument can +assign several different types of behavior to a semaphore. No current type uses +\fIarg\fR, although it may be used in the future. +.sp +.LP +The \fItype\fR argument may be one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBUSYNC_PROCESS\fR \fR +.ad +.RS 18n +.rt +The semaphore can synchronize threads in this process and other processes. +Initializing the semaphore should be done by only one process. A semaphore +initialized with this type must be allocated in memory shared between +processes, either in Sys V shared memory (see \fBshmop\fR(2)), or in memory +mapped to a file (see \fBmmap\fR(2)). It is illegal to initialize the object +this way and not allocate it in such shared memory. \fIarg\fR is ignored. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUSYNC_THREAD\fR \fR +.ad +.RS 18n +.rt +The semaphore can synchronize threads only in this process. The \fIarg\fR +argument is ignored. \fBUSYNC_THREAD\fR does not support multiple mappings to +the same logical synch object. If you need to \fBmmap()\fR a synch object to +different locations within the same address space, then the synch object should +be initialized as a shared object \fBUSYNC_PROCESS\fR for Solaris threads and +\fBPTHREAD_PROCESS_PRIVATE\fR for POSIX threads. +.RE + +.sp +.LP +A semaphore must not be simultaneously initialized by multiple threads, nor +re-initialized while in use by other threads. +.sp +.LP +Default semaphore initialization (intra-process): +.sp +.in +2 +.nf +sema_t sp; +int count = 1; +sema_init(&sp, count, NULL, NULL); +.fi +.in -2 + +.sp +.LP +or +.sp +.in +2 +.nf +sema_init(&sp, count, USYNC_THREAD, NULL); +.fi +.in -2 + +.sp +.LP +Customized semaphore initialization (inter-process): +.sp +.in +2 +.nf +\fBsema_t sp; +int count = 1; +sema_init(&sp, count, USYNC_PROCESS, NULL);\fR +.fi +.in -2 + +.sp +.LP +The \fBsema_destroy()\fR function destroys any state related to the semaphore +pointed to by \fIsp\fR. The semaphore storage space is not released. +.sp +.LP +The \fBsema_wait()\fR function blocks the calling thread until the semaphore +count pointed to by \fIsp\fR is greater than 0, and then it atomically +decrements the count. +.sp +.LP +The \fBsema_trywait()\fR function atomically decrements the semaphore count +pointed to by \fIsp\fR, if the count is greater than 0; otherwise, it returns +an error. +.sp +.LP +The \fBsema_post()\fR function atomically increments the semaphore count +pointed to by \fIsp\fR. If there are any threads blocked on the semaphore, one +will be unblocked. +.sp +.LP +The semaphore functionality described on this man page is for the Solaris +threads implementation. For the POSIX-conforming semaphore interface +documentation, see \fBsem_close\fR(3C), \fBsem_destroy\fR(3C), +\fBsem_getvalue\fR(3C), \fBsem_init\fR(3C), \fBsem_open\fR(3C), +\fBsem_post\fR(3C), \fBsem_unlink\fR(3C), and \fBsem_wait\fR(3C). +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fB0\fR is returned; otherwise, a non-zero value +indicates an error. +.SH ERRORS +.sp +.LP +These functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR \fR +.ad +.RS 11n +.rt +The \fIsp\fR argument does not refer to a valid semaphore. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR \fR +.ad +.RS 11n +.rt +Either the \fIsp\fR or \fIarg\fR argument points to an illegal address. +.RE + +.sp +.LP +The \fBsema_wait()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR \fR +.ad +.RS 10n +.rt +The wait was interrupted by a signal or \fBfork()\fR. +.RE + +.sp +.LP +The \fBsema_trywait()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBUSY\fR \fR +.ad +.RS 10n +.rt +The semaphore pointed to by \fIsp\fR has a 0 count. +.RE + +.sp +.LP +The \fBsema_post()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEOVERFLOW\fR \fR +.ad +.RS 14n +.rt +The semaphore value pointed to by \fIsp\fR exceeds \fBSEM_VALUE_MAX\fR. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRThe customer waiting-line in a bank is analogous to the +synchronization scheme of a semaphore using \fBsema_wait()\fR and +\fBsema_trywait()\fR: +.sp +.in +2 +.nf +/* cc [ flag \|.\|.\|. ] file \|.\|.\|. -lthread [ library \|.\|.\|. ] */ +#include <errno.h> +#define TELLERS 10 +sema_t tellers; /* semaphore */ +int banking_hours(), deposit_withdrawal; +void*customer(), do_business(), skip_banking_today(); +\&.\|.\|. + +sema_init(&tellers, TELLERS, USYNC_THREAD, NULL); + /* 10 tellers available */ +while(banking_hours()) + pthread_create(NULL, NULL, customer, deposit_withdrawal); +\&.\|.\|. + +void * +customer(int deposit_withdrawal) +{ + int this_customer, in_a_hurry = 50; + this_customer = rand() % 100; + + if (this_customer == in_a_hurry) { + if (sema_trywait(&tellers) != 0) + if (errno == EBUSY){ /* no teller available */ + skip_banking_today(this_customer); + return; + } /* else go immediately to available teller and + decrement tellers */ + } + else + sema_wait(&tellers); /* wait for next teller, then + proceed, and decrement tellers */ + + do_business(deposit_withdrawal); + sema_post(&tellers); /* increment tellers; this_customer's + teller is now available */ +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelAsync-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBmmap\fR(2), \fBshmop\fR(2), \fBsem_close\fR(3C), \fBsem_destroy\fR(3C), +\fBsem_getvalue\fR(3C), \fBsem_init\fR(3C), \fBsem_open\fR(3C), +\fBsem_post\fR(3C), \fBsem_unlink\fR(3C), \fBsem_wait\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +These functions are also available by way of: +.sp +.in +2 +.nf +#include <thread.h> +.fi +.in -2 + +.sp +.LP +By default, there is no defined order of unblocking for multiple threads +waiting for a semaphore. diff --git a/usr/src/man/man3c/setbuf.3c b/usr/src/man/man3c/setbuf.3c new file mode 100644 index 0000000000..1ee1c23aeb --- /dev/null +++ b/usr/src/man/man3c/setbuf.3c @@ -0,0 +1,126 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH setbuf 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +setbuf, setvbuf \- assign buffering to a stream +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBvoid\fR \fBsetbuf\fR(\fBFILE *\fR\fIstream\fR, \fBchar *\fR\fIbuf\fR); +.fi + +.LP +.nf +\fBint\fR \fBsetvbuf\fR(\fBFILE *\fR\fIstream\fR, \fBchar *\fR\fIbuf\fR, \fBint\fR \fItype\fR, \fBsize_t\fR \fIsize\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsetbuf()\fR function may be used after the stream pointed to by +\fIstream\fR (see \fBIntro\fR(3)) is opened but before it is read or written. +It causes the array pointed to by \fIbuf\fR to be used instead of an +automatically allocated buffer. If \fIbuf\fR is the null pointer, input/output +will be completely unbuffered. The constant \fBBUFSIZ\fR, defined in the +<\fBstdio.h\fR> header, indicates the size of the array pointed to by +\fIbuf\fR. +.sp +.LP +The \fBsetvbuf()\fR function may be used after a stream is opened but before +it is read or written. The \fItype\fR argument determines how \fIstream\fR +will be buffered. Legal values for \fItype\fR (defined in <\fBstdio.h\fR>) +are: +.sp +.ne 2 +.mk +.na +\fB\fB_IOFBF\fR\fR +.ad +.RS 10n +.rt +Input/output to be fully buffered. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_IOLBF\fR\fR +.ad +.RS 10n +.rt +Output to be line buffered; the buffer will be flushed when a \fBNEWLINE\fR is +written, the buffer is full, or input is requested. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB_IONBF\fR\fR +.ad +.RS 10n +.rt +Input/output to be completely unbuffered. +.RE + +.sp +.LP +If \fIbuf\fR is not the null pointer, the array it points to will be used for +buffering, instead of an automatically allocated buffer. The \fIsize\fR +argument specifies the size of the buffer to be used. If input/output is +unbuffered, \fIbuf\fR and \fIsize\fR are ignored. +.sp +.LP +For a further discussion of buffering, see \fBstdio\fR(3C). +.SH RETURN VALUES +.sp +.LP +If an illegal value for \fItype\fR is provided, \fBsetvbuf()\fR returns a +non-zero value. Otherwise, it returns \fB0\fR. +.SH USAGE +.sp +.LP +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. +.sp +.LP +When using \fBsetbuf()\fR, \fIbuf\fR should always be sized using \fBBUFSIZ\fR. +If the array pointed to by \fIbuf\fR is larger than \fBBUFSIZ\fR, a portion of +\fIbuf\fR will not be used. If \fIbuf\fR is smaller than \fBBUFSIZ\fR, other +memory may be unexpectedly overwritten. +.sp +.LP +Parts of \fBbuf\fR will be used for internal bookkeeping of the stream and, +therefore, \fBbuf\fR will contain less than \fIsize\fR bytes when full. It is +recommended that \fBstdio\fR(3C) be used to handle buffer allocation when +using \fBsetvbuf()\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfopen\fR(3C), \fBgetc\fR(3C), \fBmalloc\fR(3C), \fBputc\fR(3C), +\fBstdio\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/setbuffer.3c b/usr/src/man/man3c/setbuffer.3c new file mode 100644 index 0000000000..da90348042 --- /dev/null +++ b/usr/src/man/man3c/setbuffer.3c @@ -0,0 +1,72 @@ +'\" te +.\" Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH setbuffer 3C "13 May 1997" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +setbuffer, setlinebuf \- assign buffering to a stream +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBvoid\fR \fBsetbuffer\fR(\fBFILE *\fR\fIiop\fR, \fBchar *\fR\fIabuf\fR, \fBsize_t\fR \fIasize\fR); +.fi + +.LP +.nf +\fBint\fR \fBsetlinebuf\fR(\fBFILE *\fR\fIiop\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsetbuffer()\fR and \fBsetlinebuf()\fR functions assign buffering to a +stream. The three types of buffering available are unbuffered, block buffered, +and line buffered. When an output stream is unbuffered, information appears on +the destination file or terminal as soon as written; when it is block buffered, +many characters are saved and written as a block; when it is line buffered, +characters are saved until either a \fBNEWLINE\fR is encountered or input is +read from \fBstdin\fR. The \fBfflush\fR(3C) function may be used to force the +block out early. Normally all files are block buffered. A buffer is obtained +from \fBmalloc\fR(3C) upon the first \fBgetc\fR(3C) or \fBputc\fR(3C) performed +on the file. If the standard stream \fBstdout\fR refers to a terminal, it is +line buffered. The standard stream \fBstderr\fR is unbuffered by default. +.sp +.LP +The \fBsetbuffer()\fR function can be used after a stream \fIiop\fR has been +opened but before it is read or written. It uses the character array \fIabuf\fR +whose size is determined by the \fIasize\fR argument instead of an +automatically allocated buffer. If \fIabuf\fR is the null pointer, +input/output will be completely unbuffered. A manifest constant \fBBUFSIZ\fR, +defined in the \fB<stdio.h>\fR header, tells how large an array is needed: +.sp +.LP +char buf[BUFSIZ]; +.sp +.LP +The \fBsetlinebuf()\fR function is used to change the buffering on a stream +from block buffered or unbuffered to line buffered. Unlike \fBsetbuffer()\fR, +it can be used at any time that the stream \fIiop\fR is active. +.sp +.LP +A stream can be changed from unbuffered or line buffered to block buffered by +using \fBfreopen\fR(3C). A stream can be changed from block buffered or line +buffered to unbuffered by using \fBfreopen\fR(3C) followed by \fBsetbuf\fR(3C) +with a buffer argument of \fINULL\fR. +.SH RETURN VALUES +.sp +.LP +The \fBsetlinebuf()\fR function returns no useful value. +.SH SEE ALSO +.sp +.LP +\fBmalloc\fR(3C), \fBfclose\fR(3C), \fBfopen\fR(3C), \fBfread\fR(3C), +\fBgetc\fR(3C), \fBprintf\fR(3C), \fBputc\fR(3C), \fBputs\fR(3C), +\fBsetbuf\fR(3C), \fBsetvbuf\fR(3C) +.SH NOTES +.sp +.LP +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. diff --git a/usr/src/man/man3c/setcat.3c b/usr/src/man/man3c/setcat.3c new file mode 100644 index 0000000000..f73bf35cb7 --- /dev/null +++ b/usr/src/man/man3c/setcat.3c @@ -0,0 +1,80 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH setcat 3C "29 Dec 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +setcat \- define default catalog +.SH SYNOPSIS +.LP +.nf +#include <pfmt.h> + +\fBchar *\fR\fBsetcat\fR(\fBconst char *\fR\fIcatalog\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsetcat()\fR function defines the default message catalog to be used by +subsequent calls to \fBgettxt\fR(3C), \fBlfmt\fR(3C), or \fBpfmt\fR(3C) that do +not explicitly specify a message catalog. +.sp +.LP +The \fIcatalog\fR argument must be limited to 14 characters. These characters +must be selected from a set of all characters values, excluding \fB\e0\fR +(null) and the ASCII codes for \fB/\fR (slash) and \fB:\fR (colon). +.sp +.LP +The \fBsetcat()\fR function assumes that the catalog exists. No checking is +done on the argument. +.sp +.LP +A null pointer passed as an argument will result in the return of a pointer to +the current default message catalog name. A pointer to an empty string passed +as an argument will cancel the default catalog. +.sp +.LP +If no default catalog is specified, or if \fIcatalog\fR is an invalid catalog +name, subsequent calls to \fBgettxt\fR(3C), \fBlfmt\fR(3C), or \fBpfmt\fR(3C) +that do not explicitely specify a catalog name will use \fBMessage not +found!!\en\fR as default string. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBsetcat()\fR returns a pointer to the catalog +name. Otherwise, it returns a null pointer. +.SH EXAMPLES +.LP +\fBExample 1 \fRExample of \fBsetcat()\fR function. +.sp +.in +2 +.nf + setcat("test"); + gettxt(":10", "hello world\en") +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgettxt\fR(3C), \fBlfmt\fR(3C), \fBpfmt\fR(3C), \fBsetlocale\fR(3C), +\fBattributes\fR(5), \fBenviron\fR(5) diff --git a/usr/src/man/man3c/setenv.3c b/usr/src/man/man3c/setenv.3c new file mode 100644 index 0000000000..2166176a71 --- /dev/null +++ b/usr/src/man/man3c/setenv.3c @@ -0,0 +1,100 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH setenv 3C "31 Mar 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +setenv \- add or change environment variable +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBint\fR \fBsetenv\fR(\fBconst char *\fR\fIenvname\fR, \fBconst char *\fR\fIenvval\fR, + \fBint\fR \fIoverwrite\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsetenv()\fR function updates or adds a variable in the environment of +the calling process. The \fIenvname\fR argument points to a string containing +the name of an environment variable to be added or altered. The environment +variable is set to the value to which \fIenvval\fR points. The function fails +if \fIenvname\fR points to a string which contains an '=' character. If the +environment variable named by \fIenvname\fR already exists and the value of +\fIoverwrite\fR is non-zero, the function returns successfully and the +environment is updated. If the environment variable named by \fIenvname\fR +already exists and the value of \fIoverwrite\fR is zero, the function returns +successfully and the environment remains unchanged. +.sp +.LP +If the application modifies \fIenviron\fR or the pointers to which it points, +the behavior of \fBsetenv()\fR is undefined. The \fBsetenv()\fR function +updates the list of pointers to which \fIenviron\fR points. +.sp +.LP +The strings described by \fIenvname\fR and \fIenvval\fR are copied by this +function. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, 0 is returned. Otherwise, -1 is returned, +\fBerrno\fR set to indicate the error, and the environment is left unchanged. +.SH ERRORS +.sp +.LP +The \fBsetenv()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIenvname\fR argument is a null pointer, points to an empty string, or +points to a string containing an '=' character. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient memory was available to add a variable or its value to the +environment. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgetenv\fR(3C), \fBunsetenv\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/setjmp.3c b/usr/src/man/man3c/setjmp.3c new file mode 100644 index 0000000000..493247611a --- /dev/null +++ b/usr/src/man/man3c/setjmp.3c @@ -0,0 +1,223 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1997, The Open Group. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH setjmp 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +setjmp, sigsetjmp, longjmp, siglongjmp \- non-local goto +.SH SYNOPSIS +.LP +.nf +#include <setjmp.h> + +\fBint\fR \fBsetjmp\fR(\fBjmp_buf\fR \fIenv\fR); +.fi + +.LP +.nf +\fBint\fR \fBsigsetjmp\fR(\fBsigjmp_buf\fR \fIenv\fR, \fBint\fR \fIsavemask\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBlongjmp\fR(\fBjmp_buf\fR \fIenv\fR, \fBint\fR \fIval\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBsiglongjmp\fR(\fBsigjmp_buf\fR \fIenv\fR, \fBint\fR \fIval\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions are useful for dealing with errors and interrupts encountered +in a low-level subroutine of a program. +.sp +.LP +The \fBsetjmp()\fR function saves its stack environment in \fIenv\fR for later +use by \fBlongjmp()\fR. +.sp +.LP +The \fBsigsetjmp()\fR function saves the calling process's registers and stack +environment (see \fBsigaltstack\fR(2)) in \fIenv\fR for later use by +\fBsiglongjmp()\fR. If \fIsavemask\fR is non-zero, the calling process's +signal mask (see \fBsigprocmask\fR(2)) and scheduling parameters (see +\fBpriocntl\fR(2)) are also saved. +.sp +.LP +The \fBlongjmp()\fR function restores the environment saved by the last call of +\fBsetjmp()\fR with the corresponding \fIenv\fR argument. After \fBlongjmp()\fR +completes, program execution continues as if the corresponding call to +\fBsetjmp()\fR had just returned the value \fIval\fR. The caller of +\fBsetjmp()\fR must not have returned in the interim. The \fBlongjmp()\fR +function cannot cause \fBsetjmp()\fR to return the value 0. If \fBlongjmp()\fR +is invoked with a second argument of 0, \fBsetjmp()\fR will return 1. At the +time of the second return from \fBsetjmp()\fR, all external and static +variables have values as of the time \fBlongjmp()\fR is called (see +\fBEXAMPLES\fR). +.sp +.LP +The \fBsiglongjmp()\fR function restores the environment saved by the last call +of \fBsigsetjmp()\fR with the corresponding \fIenv\fR argument. After +\fBsiglongjmp()\fR completes, program execution continues as if the +corresponding call to \fBsigsetjmp()\fR had just returned the value \fIval\fR. +The \fBsiglongjmp()\fR function cannot cause \fBsigsetjmp()\fR to return the +value 0. If \fBsiglongjmp()\fR is invoked with a second argument of 0, +\fBsigsetjmp()\fR will return 1. At the time of the second return from +\fBsigsetjmp()\fR, all external and static variables have values as of the time +\fBsiglongjmp()\fR was called. +.sp +.LP +If a signal-catching function interrupts \fBsleep\fR(3C) and calls +\fBsiglongjmp()\fR to restore an environment saved prior to the \fBsleep()\fR +call, the action associated with \fBSIGALRM\fR and time it is scheduled to be +generated are unspecified. It is also unspecified whether the \fBSIGALRM\fR +signal is blocked, unless the process's signal mask is restored as part of the +environment. +.sp +.LP +The \fBsiglongjmp()\fR function restores the saved signal mask if and only if +the \fIenv\fR argument was initialized by a call to the \fBsigsetjmp()\fR +function with a non-zero \fIsavemask\fR argument. +.sp +.LP +The values of register and automatic variables are undefined. Register or +automatic variables whose value must be relied upon must be declared as +volatile. +.SH RETURN VALUES +.sp +.LP +If the return is from a direct invocation, \fBsetjmp()\fR and \fBsigsetjmp()\fR +return \fB0\fR. If the return is from a call to \fBlongjmp()\fR, \fBsetjmp()\fR +returns a non-zero value. If the return is from a call to \fBsiglongjmp()\fR, +\fBsigsetjmp()\fR returns a non-zero value. +.sp +.LP +After \fBlongjmp()\fR is completed, program execution continues as if the +corresponding invocation of \fBsetjmp()\fR had just returned the value +specified by \fIval\fR. The \fBlongjmp()\fR function cannot cause +\fBsetjmp()\fR to return 0; if \fIval\fR is 0, \fBsetjmp()\fR returns 1. +.sp +.LP +After \fBsiglongjmp()\fR is completed, program execution continues as if the +corresponding invocation of \fBsigsetjmp()\fR had just returned the value +specified by \fIval\fR. The \fBsiglongjmp()\fR function cannot cause +\fBsigsetjmp()\fR to return 0; if \fIval\fR is 0, \fBsigsetjmp()\fR returns 1. +.SH EXAMPLES +.LP +\fBExample 1 \fRExample of \fBsetjmp()\fR and \fBlongjmp()\fR functions. +.sp +.LP +The following example uses both \fBsetjmp()\fR and \fBlongjmp()\fR to return +the flow of control to the appropriate instruction block: + +.sp +.in +2 +.nf +#include <stdio.h> +#include <setjmp.h> +#include <signal.h> +#include <unistd.h> +jmp_buf env; static void signal_handler(); + +main(\|) { + int returned_from_longjump, processing = 1; + unsigned int time_interval = 4; + if ((returned_from_longjump = setjmp(env)) != 0) + switch (returned_from_longjump) { + case SIGINT: + printf("longjumped from interrupt %d\en",SIGINT); + break; + case SIGALRM: + printf("longjumped from alarm %d\en",SIGALRM); + break; + } + (void) signal(SIGINT, signal_handler); + (void) signal(SIGALRM, signal_handler); + alarm(time_interval); + while (processing) { + printf(" waiting for you to INTERRUPT (cntrl-C) ...\en"); + sleep(1); + } /* end while forever loop */ +} + +static void signal_handler(sig) +int sig; { + switch (sig) { + case SIGINT: ... /* process for interrupt */ + longjmp(env,sig); + /* break never reached */ + case SIGALRM: ... /* process for alarm */ + longjmp(env,sig); + /* break never reached */ + default: exit(sig); + } +} +.fi +.in -2 + +.sp +.LP +When this example is compiled and executed, and the user sends an interrupt +signal, the output will be: + +.sp +.in +2 +.nf +longjumped from interrupt +.fi +.in -2 +.sp + +.sp +.LP +Additionally, every 4 seconds the alarm will expire, signalling this process, +and the output will be: + +.sp +.in +2 +.nf +longjumped from alarm +.fi +.in -2 +.sp + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgetcontext\fR(2), \fBpriocntl\fR(2), \fBsigaction\fR(2), +\fBsigaltstack\fR(2), \fBsigprocmask\fR(2), \fBsignal\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) +.SH WARNINGS +.sp +.LP +If \fBlongjmp()\fR or \fBsiglongjmp()\fR are called even though \fIenv\fR was +never primed by a call to \fBsetjmp()\fR or \fBsigsetjmp()\fR, or when the last +such call was in a function that has since returned, the results are undefined. diff --git a/usr/src/man/man3c/setkey.3c b/usr/src/man/man3c/setkey.3c new file mode 100644 index 0000000000..47c22680a9 --- /dev/null +++ b/usr/src/man/man3c/setkey.3c @@ -0,0 +1,86 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH setkey 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +setkey \- set encoding key +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBvoid\fR \fBsetkey\fR(\fBconst char *\fR\fIkey\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsetkey()\fR function provides (rather primitive) access to the hashing +algorithm employed by the \fBcrypt\fR(3C) function. The argument of +\fBsetkey()\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 will be used with the algorithm to +encode a string \fIblock\fR passed to \fBencrypt\fR(3C). +.SH RETURN VALUES +.sp +.LP +No values are returned. +.SH ERRORS +.sp +.LP +The \fBsetkey()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR\fR +.ad +.RS 10n +.rt +The functionality is not supported on this implementation. +.RE + +.SH USAGE +.sp +.LP +In some environments, decoding may not be implemented. This is related to U.S. +Government restrictions on encryption and decryption routines: the \fBDES\fR +decryption algorithm cannot be exported outside the U.S.A. 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 +\fBencrypt()\fR does encoding but not decoding. +.sp +.LP +Because \fBsetkey()\fR does not return a value, applications wishing to check +for errors should set \fBerrno\fR to 0, call \fBsetkey()\fR, then test +\fBerrno\fR and, if it is non-zero, assume an error has occurred. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBcrypt\fR(3C), \fBencrypt\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/setlabel.3c b/usr/src/man/man3c/setlabel.3c new file mode 100644 index 0000000000..8049a6ef78 --- /dev/null +++ b/usr/src/man/man3c/setlabel.3c @@ -0,0 +1,80 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH setlabel 3C "29 Dec 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +setlabel \- define the label for \fBpfmt()\fR and \fBlfmt()\fR +.SH SYNOPSIS +.LP +.nf +#include <pfmt..h> + +\fBint\fR \fBsetlabel\fR(\fBconst char *\fR\fIlabel\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsetlabel()\fR function defines the label for messages produced in +standard format by subsequent calls to \fBlfmt\fR(3C) and \fBpfmt\fR(3C). +.sp +.LP +The \fIlabel\fR argument is a character string no more than 25 characters in +length. +.sp +.LP +No label is defined before \fBsetlabel()\fR is called. The label should be set +once at the beginning of a utility and remain constant. A null pointer or an +empty string passed as argument will reset the definition of the label. +.SH RETURN VALUE +.sp +.LP +Upon successful completion, \fBsetlabel()\fR returns \fB0\fR; otherwise, it +returns a non-zero value. +.SH EXAMPLES +.sp +.LP +The following code (without previous call to \fBsetlabel()\fR): +.sp +.in +2 +.nf +pfmt(stderr, MM_ERROR, "test:2:Cannot open file\en"); +setlabel("UX:test"); +pfmt(stderr, MM_ERROR, "test:2:Cannot open file\en"); +.fi +.in -2 + +.sp +.LP +will produce the following output: +.sp +.in +2 +.nf +ERROR: Cannot open file +UX:test: ERROR: Cannot open file +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgetopt\fR(3C), \fBlfmt\fR(3C), \fBpfmt\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/setlocale.3c b/usr/src/man/man3c/setlocale.3c new file mode 100644 index 0000000000..78cbc5c877 --- /dev/null +++ b/usr/src/man/man3c/setlocale.3c @@ -0,0 +1,188 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH setlocale 3C "19 Sep 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +setlocale \- modify and query a program's locale +.SH SYNOPSIS +.LP +.nf +#include <locale.h> + +\fBchar *\fR\fBsetlocale\fR(\fBint\fR \fIcategory\fR, \fBconst char *\fR\fIlocale\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsetlocale()\fR function selects the appropriate piece of the program's +locale as specified by the \fIcategory\fR and \fIlocale\fR arguments. The +\fIcategory\fR argument may have the following values: \fBLC_CTYPE\fR, +\fBLC_NUMERIC\fR, \fBLC_TIME\fR, \fBLC_COLLATE\fR, \fBLC_MONETARY\fR, +\fBLC_MESSAGES\fR, and \fBLC_ALL\fR. These names are defined in the +<\fBlocale.h\fR> header. The \fBLC_ALL\fR variable names all of a program's +locale categories. +.sp +.LP +The \fBLC_CTYPE\fR variable affects the behavior of character handling +functions such as \fBisdigit\fR(3C) and \fBtolower\fR(3C), and multibyte +character functions such as \fBmbtowc\fR(3C) and \fBwctomb\fR(3C). +.sp +.LP +The \fBLC_NUMERIC\fR variable affects the decimal point character and thousands +separator character for the formatted input/output functions and string +conversion functions. +.sp +.LP +The \fBLC_TIME\fR variable affects the date and time format as delivered by +\fBascftime\fR(3C), \fBcftime\fR(3C), \fBgetdate\fR(3C), \fBstrftime\fR(3C), +and \fBstrptime\fR(3C). +.sp +.LP +The \fBLC_COLLATE\fR variable affects the sort order produced by collating +functions such as \fBstrcoll\fR(3C) and \fBstrxfrm\fR(3C). +.sp +.LP +The \fBLC_MONETARY\fR variable affects the monetary formatted information +returned by \fBlocaleconv\fR(3C). +.sp +.LP +The \fBLC_MESSAGES\fR variable affects the behavior of messaging functions such +as \fBdgettext\fR(3C), \fBgettext\fR(3C), and \fBgettxt\fR(3C). +.sp +.LP +A value of "C" for \fIlocale\fR specifies the traditional \fBUNIX\fR system +behavior. At program startup, the equivalent of +.sp +.LP +\fBsetlocale(LC_ALL, "C")\fR +.sp +.LP +is executed. This has the effect of initializing each category to the locale +described by the environment "C". +.sp +.LP +A value of "" for \fIlocale\fR specifies that the locale should be taken from +environment variables. The order in which the environment variables are checked +for the various categories is given below: +.sp + +.sp +.TS +tab() box; +cw(1.38i) |cw(1.38i) |cw(1.38i) |cw(1.38i) +lw(1.38i) |lw(1.38i) |lw(1.38i) |lw(1.38i) +. +Category1st Env Var2nd Env Var3rd Env Var +_ +LC_CTYPE:LC_ALLLC_CTYPELANG +_ +LC_COLLATE:LC_ALLLC_COLLATELANG +_ +LC_TIME:LC_ALLLC_TIMELANG +_ +LC_NUMERIC:LC_ALLLC_NUMERICLANG +_ +LC_MONETARY:LC_ALLLC_MONETARYLANG +_ +LC_MESSAGES:LC_ALLLC_MESSAGESLANG +.TE + +.sp +.LP +If a pointer to a string is given for \fIlocale\fR, \fBsetlocale()\fR attempts +to set the locale for the given category to \fIlocale\fR. If \fBsetlocale()\fR +succeeds, \fIlocale\fR is returned. If \fBsetlocale()\fR fails, a null pointer +is returned and the program's locale is not changed. +.sp +.LP +For category \fBLC_ALL\fR, the behavior is slightly different. If a pointer to +a string is given for \fIlocale\fR and \fBLC_ALL\fR is given for +\fIcategory\fR, \fBsetlocale()\fR attempts to set the locale for all the +categories to \fIlocale\fR. The \fIlocale\fR may be a simple locale, consisting +of a single locale, or a composite locale. If the locales for all the +categories are the same after all the attempted locale changes, +\fBsetlocale()\fR will return a pointer to the common simple locale. If there +is a mixture of locales among the categories, \fBsetlocale()\fR will return a +composite locale. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBsetlocale()\fR returns the string associated +with the specified category for the new locale. Otherwise, \fBsetlocale()\fR +returns a null pointer and the program's locale is not changed. +.sp +.LP +A null pointer for \fIlocale\fR causes \fBsetlocale()\fR to return a pointer to +the string associated with the \fIcategory\fR for the program's current locale. +The program's locale is not changed. +.sp +.LP +The string returned by \fBsetlocale()\fR is such that a subsequent call with +that string and its associated \fIcategory\fR will restore that part of the +program's locale. The string returned must not be modified by the program, but +may be overwritten by a subsequent call to \fBsetlocale()\fR. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/locale/\fIlocale\fR\fR\fR +.ad +.RS 26n +.rt +locale database directory for \fIlocale\fR +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +CSIEnabled +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBlocale\fR(1), \fBctype\fR(3C), \fBgetdate\fR(3C) \fBgettext\fR(3C), +\fBgettxt\fR(3C), \fBisdigit\fR(3C), \fBlibc\fR(3LIB), \fBlocaleconv\fR(3C), +\fBmbtowc\fR(3C), \fBstrcoll\fR(3C), \fBstrftime\fR(3C), \fBstrptime\fR(3C) +\fBstrxfrm\fR(3C) \fBtolower\fR(3C), \fBwctomb\fR(3C), \fBattributes\fR(5), +\fBenviron\fR(5), \fBlocale\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +It is unsafe for any thread to change locale (by calling \fBsetlocale()\fR with +a non-null locale argument) in a multithreaded application while any other +thread in the application is using any locale-sensitive routine. To change +locale in a multithreaded application, \fBsetlocale()\fR should be called prior +to using any locale-sensitive routine. Using \fBsetlocale()\fR to query the +current locale is safe and can be used anywhere in a multithreaded application +except when some other thread is changing locale. +.sp +.LP +It is the user's responsibility to ensure that mixed locale categories are +compatible. For example, setting \fBLC_CTYPE=C\fR and \fBLC_TIME=ja\fR (where +\fBja\fR indicates Japanese) will not work, because Japanese time cannot be +represented in the "C" locale's ASCII codeset. diff --git a/usr/src/man/man3c/shm_open.3c b/usr/src/man/man3c/shm_open.3c new file mode 100644 index 0000000000..d06a708f6b --- /dev/null +++ b/usr/src/man/man3c/shm_open.3c @@ -0,0 +1,296 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH shm_open 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +shm_open \- open a shared memory object +.SH SYNOPSIS +.LP +.nf +#include <sys/mman.h> + +\fBint\fR \fBshm_open\fR(\fBconst char *\fR\fIname\fR, \fBint\fR \fIoflag\fR, \fBmode_t\fR \fImode\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBshm_open()\fR function establishes a connection between a shared memory +object and a file descriptor. It creates 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 \fIname\fR 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 +\fIname\fR argument conforms to the construction rules for a pathname. The +first character of \fIname\fR must be a slash (/) character and the remaining +characters of \fIname\fR cannot include any slash characters. For maximum +portability, \fIname\fR should include no more than 14 characters, but this +limit is not enforced. +.sp +.LP +If successful, \fBshm_open()\fR returns 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 \fBFD_CLOEXEC\fR file descriptor flag associated with the +new file descriptor is set. +.sp +.LP +The file status flags and file access modes of the open file description are +according to the value of \fIoflag\fR. The \fIoflag\fR argument is the bitwise +inclusive OR of the following flags defined in the header <\fBfcntl.h\fR>. +Applications specify exactly one of the first two values (access modes) below +in the value of \fIoflag\fR: +.sp +.ne 2 +.mk +.na +\fB\fBO_RDONLY\fR \fR +.ad +.RS 13n +.rt +Open for read access only. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBO_RDWR\fR \fR +.ad +.RS 13n +.rt +Open for read or write access. +.RE + +.sp +.LP +Any combination of the remaining flags may be specified in the value of +\fIoflag\fR: +.sp +.ne 2 +.mk +.na +\fB\fBO_CREAT\fR \fR +.ad +.RS 12n +.rt +If the shared memory object exists, this flag has no effect, except as noted +under \fBO_EXCL\fR below. Otherwise the shared memory object is created; the +user \fBID\fR of the shared memory object will be set to the effective user +\fBID\fR of the process; the group \fBID\fR of the shared memory object will be +set to a system default group \fBID\fR or to the effective group \fBID\fR of +the process. The permission bits of the shared memory object will be set to the +value of the \fImode\fR argument except those set in the file mode creation +mask of the process. When bits in \fImode\fR other than the file permission +bits are set, the effect is unspecified. The \fImode\fR 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. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBO_EXCL\fR \fR +.ad +.RS 12n +.rt +If \fBO_EXCL\fR and \fBO_CREAT\fR are set, \fBshm_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 \fBshm_open()\fR naming the same shared memory object +with \fBO_EXCL\fR and \fBO_CREAT\fR set. If \fBO_EXCL\fR is set and +\fBO_CREAT\fR is not set, the result is undefined. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBO_TRUNC\fR \fR +.ad +.RS 12n +.rt +If the shared memory object exists, and it is successfully opened \fBO_RDWR\fR, +the object will be truncated to zero length and the mode and owner will be +unchanged by this function call. The result of using \fBO_TRUNC\fR with +\fBO_RDONLY\fR is undefined. +.RE + +.sp +.LP +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 VALUES +.sp +.LP +Upon successful completion, the \fBshm_open()\fR function returns a +non-negative integer representing the lowest numbered unused file descriptor. +Otherwise, it returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the error +condition. +.SH ERRORS +.sp +.LP +The \fBshm_open()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR \fR +.ad +.RS 17n +.rt +The shared memory object exists and the permissions specified by \fIoflag\fR +are denied, or the shared memory object does not exist and permission to create +the shared memory object is denied, or \fBO_TRUNC\fR is specified and write +permission is denied. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEEXIST\fR \fR +.ad +.RS 17n +.rt +\fBO_CREAT\fR and \fBO_EXCL\fR are set and the named shared memory object +already exists. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR \fR +.ad +.RS 17n +.rt +The \fBshm_open()\fR operation was interrupted by a signal. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR \fR +.ad +.RS 17n +.rt +The \fBshm_open()\fR operation is not supported for the given name. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR \fR +.ad +.RS 17n +.rt +Too many file descriptors are currently in use by this process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR \fR +.ad +.RS 17n +.rt +The length of the \fIname\fR string exceeds \fBPATH_MAX\fR, or a pathname +component is longer than \fINAME_MAX\fR while \fB_POSIX_NO_TRUNC\fR is in +effect. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENFILE\fR \fR +.ad +.RS 17n +.rt +Too many shared memory objects are currently open in the system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR \fR +.ad +.RS 17n +.rt +\fBO_CREAT\fR is not set and the named shared memory object does not exist. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSPC\fR \fR +.ad +.RS 17n +.rt +There is insufficient space for the creation of the new shared memory object. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR \fR +.ad +.RS 17n +.rt +The \fBshm_open()\fR function is not supported by the system. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBclose\fR(2), \fBdup\fR(2), \fBexec\fR(2), \fBfcntl\fR(2), \fBmmap\fR(2), +\fBumask\fR(2), \fBshm_unlink\fR(3C), \fBsysconf\fR(3C), \fBfcntl.h\fR(3HEAD), +\fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +Solaris 2.6 was the first release to support the Asynchronous Input and Output +option. Prior to this release, this function always returned \fB\(mi1\fR and +set \fBerrno\fR to \fBENOSYS\fR. diff --git a/usr/src/man/man3c/shm_unlink.3c b/usr/src/man/man3c/shm_unlink.3c new file mode 100644 index 0000000000..f331ca1348 --- /dev/null +++ b/usr/src/man/man3c/shm_unlink.3c @@ -0,0 +1,119 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH shm_unlink 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +shm_unlink \- remove a shared memory object +.SH SYNOPSIS +.LP +.nf +#include <sys/mman.h> + +\fBint\fR \fBshm_unlink\fR(\fBconst char *\fR\fIname\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBshm_unlink()\fR function removes the name of the shared memory object +named by the string pointed to by \fIname\fR. If one or more references to the +shared memory object exists when the object is unlinked, the name is removed +before \fBshm_unlink()\fR returns, but the removal of the memory object +contents will be postponed until all open and mapped references to the shared +memory object have been removed. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBshm_unlink()\fR returns \fB0\fR. Otherwise it +returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the error condition, and +the named shared memory object is not affected by this function call. +.SH ERRORS +.sp +.LP +The \fBshm_unlink()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR \fR +.ad +.RS 17n +.rt +Permission is denied to unlink the named shared memory object. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR \fR +.ad +.RS 17n +.rt +The length of the \fIname\fR string exceeds \fBPATH_MAX\fR, or a pathname +component is longer than \fINAME_MAX\fR while \fB_POSIX_NO_TRUNC\fR is in +effect. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR \fR +.ad +.RS 17n +.rt +The named shared memory object does not exist. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR \fR +.ad +.RS 17n +.rt +The \fBshm_unlink()\fR function is not supported by the system. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBclose\fR(2), \fBmmap\fR(2), \fBmlock\fR(3C), \fBshm_open\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +Solaris 2.6 was the first release to support the Asynchronous Input and Output +option. Prior to this release, this function always returned \fB\(mi1\fR and +set \fBerrno\fR to \fBENOSYS\fR. diff --git a/usr/src/man/man3c/sigfpe.3c b/usr/src/man/man3c/sigfpe.3c new file mode 100644 index 0000000000..f1c7187f86 --- /dev/null +++ b/usr/src/man/man3c/sigfpe.3c @@ -0,0 +1,191 @@ +'\" te +.\" Copyright (c) 1996, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH sigfpe 3C "4 May 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +sigfpe \- signal handling for specific SIGFPE codes +.SH SYNOPSIS +.LP +.nf +#include <floatingpoint.h> +#include <siginfo.h> + +\fBsigfpe_handler_type\fR \fBsigfpe\fR(\fBsigfpe_code_type\fR \fIcode\fR, + \fBsigfpe_handler_type\fR \fIhdl\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsigfpe()\fR function allows signal handling to be specified for +particular \fBSIGFPE\fR codes. A call to \fBsigfpe()\fR defines a new handler +\fIhdl\fR for a particular \fBSIGFPE\fR \fIcode\fR and returns the old handler +as the value of the function \fBsigfpe()\fR. Normally handlers are specified as +pointers to functions; the special cases \fBSIGFPE_IGNORE\fR, +\fBSIGFPE_ABORT\fR, and \fBSIGFPE_DEFAULT\fR allow ignoring, dumping core using +\fBabort\fR(3C), or default handling respectively. Default handling is to dump +core using \fBabort\fR(3C). +.sp +.LP +The \fIcode\fR argument is usually one of the five \fBIEEE\|754-related\fR +\fBSIGFPE\fR codes: +.sp +.in +2 +.nf +FPE_FLTRES fp_inexact \(mi floating-point inexact result +FPE_FLTDIV fp_division \(mi floating-point division by zero +FPE_FLTUND fp_underflow \(mi floating-point underflow +FPE_FLTOVF fp_overflow \(mi floating-point overflow +FPE_FLTINV fp_invalid \(mi floating-point invalid operation +.fi +.in -2 + +.sp +.LP +Three steps are required to intercept an \fBIEEE\|754-related\fR \fBSIGFPE\fR +code with \fBsigfpe()\fR: +.RS +4 +.TP +1. +Set up a handler with \fBsigfpe()\fR. +.RE +.RS +4 +.TP +2. +Enable the relevant \fBIEEE\|754\fR trapping capability in the hardware, +perhaps by using assembly-language instructions. +.RE +.RS +4 +.TP +3. +Perform a floating-point operation that generates the intended +\fBIEEE\|754\fR exception. +.RE +.sp +.LP +The \fBsigfpe()\fR function never changes floating-point hardware mode bits +affecting \fBIEEE\|754\fR trapping. No \fBIEEE\|754-related\fR \fBSIGFPE\fR +signals will be generated unless those hardware mode bits are enabled. +.sp +.LP +\fBSIGFPE\fR signals can be handled using \fBsigfpe()\fR, \fBsigaction\fR(2) or +\fBsignal\fR(3C). In a particular program, to avoid confusion, use only one of +these interfaces to handle \fBSIGFPE\fR signals. +.SH EXAMPLES +.LP +\fBExample 1 \fRExample Of A User-Specified Signal Handler +.sp +.LP +A user-specified signal handler might look like this: + +.sp +.in +2 +.nf +#include <floatingpoint.h> +#include <siginfo.h> +#include <ucontext.h> +/* +* The sample_handler prints out a message then commits suicide. +*/ +void +sample_handler(int sig, siginfo_t *sip, ucontext_t *uap) { + char *label; + switch (sip\(mi>si_code) { + case FPE_FLTINV: label = "invalid operand"; break; + case FPE_FLTRES: label = "inexact"; break; + case FPE_FLTDIV: label = "division-by-zero"; break; + case FPE_FLTUND: label = "underflow"; break; + case FPE_FLTOVF: label = "overflow"; break; + default: label = "???"; break; + } + fprintf(stderr, + "FP exception %s (0x%x) occurred at address %p.\en", + label, sip\(mi>si_code, (void *) sip\(mi>si_addr); + abort(); +} +.fi +.in -2 + +.sp +.LP +and it might be set up like this: + +.sp +.in +2 +.nf +#include <floatingpoint.h> +#include <siginfo.h> +#include <ucontext.h> +extern void sample_handler(int, siginfo_t *, ucontext_t *); +main(void) { + sigfpe_handler_type hdl, old_handler1, old_handler2; +/* + * save current fp_overflow and fp_invalid handlers; set the new +* fp_overflow handler to sample_handler(\|) and set the new +* fp_invalid handler to SIGFPE_ABORT (abort on invalid) +*/ + hdl = (sigfpe_handler_type) sample_handler; + old_handler1 = sigfpe(FPE_FLTOVF, hdl); + old_handler2 = sigfpe(FPE_FLTINV, SIGFPE_ABORT); + .\|.\|. +/* + * restore old fp_overflow and fp_invalid handlers + */ + sigfpe(FPE_FLTOVF, old_handler1); + sigfpe(FPE_FLTINV, old_handler2); +} +.fi +.in -2 + +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/usr/include/floatingpoint.h\fR\fR +.ad +.sp .6 +.RS 4n + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/include/siginfo.h\fR\fR +.ad +.sp .6 +.RS 4n + +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBsigaction\fR(2), \fBabort\fR(3C), \fBsignal\fR(3C), \fBattributes\fR(5), +\fBfloatingpoint.h\fR(3HEAD) +.SH DIAGNOSTICS +.sp +.LP +The \fBsigfpe()\fR function returns (void(*)())-1 if \fIcode\fR is not zero or +a defined \fBSIGFPE\fR code. diff --git a/usr/src/man/man3c/siginterrupt.3c b/usr/src/man/man3c/siginterrupt.3c new file mode 100644 index 0000000000..69fe20f644 --- /dev/null +++ b/usr/src/man/man3c/siginterrupt.3c @@ -0,0 +1,90 @@ +'\" te +.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH siginterrupt 3C "1 Sep 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +siginterrupt \- allow signals to interrupt functions +.SH SYNOPSIS +.LP +.nf +#include <signal.h> + +\fBint\fR \fBsiginterrupt\fR(\fBint\fR \fIsig\fR, \fBint\fR \fIflag\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsiginterrupt()\fR function changes the restart behavior when a function +is interrupted by the specified signal. The function +\fBsiginterrupt\fR(\fIsig\fR, \fIflag\fR) has an effect as if implemented as: +.sp +.in +2 +.nf +siginterrupt(int sig, int flag) { + int ret; + struct sigaction act; + (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 +.in -2 + +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBsiginterrupt()\fR returns 0. Otherwise, \(mi1 is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBsiginterrupt()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIsig\fR argument is not a valid signal number. +.RE + +.SH USAGE +.sp +.LP +The \fBsiginterrupt()\fR function supports programs written to historical +system interfaces. A standard-conforming application, when being written or +rewritten, should use \fBsigaction\fR(2) with the \fBSA_RESTART\fR flag instead +of \fBsiginterrupt()\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBsigaction\fR(2), \fBsignal.h\fR(3HEAD), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/signal.3c b/usr/src/man/man3c/signal.3c new file mode 100644 index 0000000000..790624ec5d --- /dev/null +++ b/usr/src/man/man3c/signal.3c @@ -0,0 +1,173 @@ +'\" te +.\" Copyright (c) 2007 Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH signal 3C "6 Sep 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +signal, sigset, sighold, sigrelse, sigignore, sigpause \- simplified signal +management for application processes +.SH SYNOPSIS +.LP +.nf +#include <signal.h> + +\fBvoid\fR \fB\fR(\fB*signal(int\fR \fIsig\fR, \fBvoid (*\fR\fIdisp\fR)(int)))(int); +.fi + +.LP +.nf +\fBvoid (*\fR\fBsigset\fR(\fBint\fR \fIsig\fR, \fBvoid (*\fR\fIdisp\fR)(int)))(int); +.fi + +.LP +.nf +\fBint\fR \fBsighold\fR(\fBint\fR \fIsig\fR); +.fi + +.LP +.nf +\fBint\fR \fBsigrelse\fR(\fBint\fR \fIsig\fR); +.fi + +.LP +.nf +\fBint\fR \fBsigignore\fR(\fBint\fR \fIsig\fR); +.fi + +.LP +.nf +\fBint\fR \fBsigpause\fR(\fBint\fR \fIsig\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions provide simplified signal management for application processes. +See \fBsignal.h\fR(3HEAD) for an explanation of general signal concepts. +.sp +.LP +The \fBsignal()\fR and \fBsigset()\fR functions modify signal dispositions. The +\fIsig\fR argument specifies the signal, which may be any signal except +\fBSIGKILL\fR and \fBSIGSTOP.\fR The \fIdisp\fR argument specifies the +signal's disposition, which may be \fBSIG_DFL,\fR \fBSIG_IGN,\fR or the address +of a signal handler. If \fBsignal()\fR is used, \fIdisp\fR is the address of a +signal handler, and \fIsig\fR is not \fBSIGILL,\fR \fBSIGTRAP\fR, or +\fBSIGPWR\fR, the system first sets the signal's disposition to \fBSIG_DFL\fR +before executing the signal handler. If \fBsigset()\fR is used and \fIdisp\fR +is the address of a signal handler, the system adds \fIsig\fR to the calling +process's signal mask before executing the signal handler; when the signal +handler returns, the system restores the calling process's signal mask to its +state prior to the delivery of the signal. In addition, if \fBsigset()\fR is +used and \fIdisp\fR is equal to \fBSIG_HOLD\fR, \fIsig\fR is added to the +calling process's signal mask and the signal's disposition remains unchanged. +.sp +.LP +The \fBsighold()\fR function adds \fIsig\fR to the calling process's signal +mask. +.sp +.LP +The \fBsigrelse()\fR function removes \fIsig\fR from the calling process's +signal mask. +.sp +.LP +The \fBsigignore()\fR function sets the disposition of \fIsig\fR to +\fBSIG_IGN.\fR +.sp +.LP +The \fBsigpause()\fR function removes \fIsig\fR from the calling process's +signal mask and suspends the calling process until a signal is received. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBsignal()\fR returns the signal's previous +disposition. Otherwise, it returns \fBSIG_ERR\fR and sets \fBerrno\fR to +indicate the error. +.sp +.LP +Upon successful completion, \fBsigset()\fR returns \fBSIG_HOLD\fR if the signal +had been blocked or the signal's previous disposition if it had not been +blocked. Otherwise, it returns \fBSIG_ERR\fR and sets \fBerrno\fR to indicate +the error. +.sp +.LP +Upon successful completion, \fBsighold()\fR, \fBsigrelse()\fR, +\fBsigignore()\fR, and \fBsigpause()\fR, return \fB0\fR. Otherwise, they +return \fB\(mi1\fR and set \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +These functions fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 10n +.rt +A signal was caught during the execution \fBsigpause()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of the \fIsig\fR argument is not a valid signal or is equal to +\fBSIGKILL\fR or \fBSIGSTOP\fR. +.RE + +.SH USAGE +.sp +.LP +The \fBsighold()\fR function used in conjunction with \fBsigrelse()\fR or +\fBsigpause()\fR may be used to establish critical regions of code that require +the delivery of a signal to be temporarily deferred. +.sp +.LP +If \fBsignal()\fR or \fBsigset()\fR is used to set \fBSIGCHLD\fR's disposition +to a signal handler, \fBSIGCHLD\fR will not be sent when the calling process's +children are stopped or continued. +.sp +.LP +If any of the above functions are used to set \fBSIGCHLD\fR's disposition to +\fBSIG_IGN,\fR the calling process's child processes will not create zombie +processes when they terminate (see \fBexit\fR(2)). If the calling process +subsequently waits for its children, it blocks until all of its children +terminate; it then returns \fB\(mi1\fR with \fBerrno\fR set to \fBECHILD\fR +(see \fBwait\fR(3C) and \fBwaitid\fR(2)). +.sp +.LP +The system guarantees that if more than one instance of the same signal is +generated to a process, at least one signal will be received. It does not +guarantee the reception of every generated signal. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBexit\fR(2), \fBkill\fR(2), \fBpause\fR(2), \fBsigaction\fR(2), +\fBsigsend\fR(2), \fBwaitid\fR(2), \fBsignal.h\fR(3HEAD), \fBwait\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/sigqueue.3c b/usr/src/man/man3c/sigqueue.3c new file mode 100644 index 0000000000..4010b45067 --- /dev/null +++ b/usr/src/man/man3c/sigqueue.3c @@ -0,0 +1,148 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH sigqueue 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +sigqueue \- queue a signal to a process +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <signal.h> + +\fBint\fR \fBsigqueue\fR(\fBpid_t\fR \fIpid\fR, \fBint\fR \fIsigno\fR, \fBconst union sigval\fR \fIvalue\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsigqueue()\fR function causes the signal specified by \fIsigno\fR to be +sent with the value specified by \fIvalue\fR to the process specified by +\fIpid\fR. If \fIsigno\fR 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 \fIpid\fR. +.sp +.LP +The conditions required for a process to have permission to queue a signal to +another process are the same as for the \fBkill\fR(2) function. +.sp +.LP +The \fBsigqueue()\fR function returns immediately. If \fBSA_SIGINFO\fR is set +for \fIsigno\fR and if the resources were available to queue the signal, the +signal is queued and sent to the receiving process. If \fBSA_SIGINFO\fR is not +set for \fIsigno\fR, then \fIsigno\fR is sent at least once to the receiving +process; it is unspecified whether \fIvalue\fR will be sent to the receiving +process as a result of this call. +.sp +.LP +If the value of \fIpid\fR causes \fIsigno\fR to be generated for the sending +process, and if \fIsigno\fR is not blocked for the calling thread and if no +other thread has \fIsigno\fR unblocked or is waiting in a \fBsigwait\fR(2) +function for \fIsigno\fR, either \fIsigno\fR or at least the pending, unblocked +signal will be delivered to the calling thread before the \fBsigqueue()\fR +function returns. Should any of multiple pending signals in the range +\fBSIGRTMIN\fR to \fBSIGRTMAX\fR be selected for delivery, it will be the +lowest numbered one. The selection order between realtime and non-realtime +signals, or between multiple pending non-realtime signals, is unspecified. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the specified signal will have been queued, and the +\fBsigqueue()\fR function returns \fB0\fR. Otherwise, the function returns +\fB\(mi1\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBsigqueue()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR \fR +.ad +.RS 11n +.rt +No resources are available to queue the signal. The process has already queued +\fBSIGQUEUE_MAX\fR signals that are still pending at the receiver(s), or a +system wide resource limit has been exceeded. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR \fR +.ad +.RS 11n +.rt +The value of \fIsigno\fR is an invalid or unsupported signal number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR \fR +.ad +.RS 11n +.rt +The \fBsigqueue()\fR function is not supported by the system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR \fR +.ad +.RS 11n +.rt +The process does not have the appropriate privilege to send the signal to the +receiving process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBESRCH\fR \fR +.ad +.RS 11n +.rt +The process \fIpid\fR does not exist. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityCommitted +_ +MT-LevelAsync-Signal-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBkill\fR(2), \fBsiginfo.h\fR(3HEAD), \fBsignal.h\fR(3HEAD), +\fBsigwaitinfo\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/sigsetops.3c b/usr/src/man/man3c/sigsetops.3c new file mode 100644 index 0000000000..6de51bbd91 --- /dev/null +++ b/usr/src/man/man3c/sigsetops.3c @@ -0,0 +1,130 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH sigsetops 3C "19 Dec 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +sigsetops, sigemptyset, sigfillset, sigaddset, sigdelset, sigismember \- +manipulate sets of signals +.SH SYNOPSIS +.LP +.nf +#include <signal.h> + +\fBint\fR \fBsigemptyset\fR(\fBsigset_t *\fR\fIset\fR); +.fi + +.LP +.nf +\fBint\fR \fBsigfillset\fR(\fBsigset_t *\fR\fIset\fR); +.fi + +.LP +.nf +\fBint\fR \fBsigaddset\fR(\fBsigset_t *\fR\fIset\fR, \fBint\fR \fIsigno\fR); +.fi + +.LP +.nf +\fBint\fR \fBsigdelset\fR(\fBsigset_t *\fR\fIset\fR, \fBint\fR \fIsigno\fR); +.fi + +.LP +.nf +\fBint\fR \fBsigismember\fR(\fBsigset_t *\fR\fIset\fR, \fBint\fR \fIsigno\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions manipulate \fBsigset_t\fR data types, representing the set of +signals supported by the implementation. +.sp +.LP +The \fBsigemptyset()\fR function initializes the set pointed to by \fIset\fR to +exclude all signals defined by the system. +.sp +.LP +The \fBsigfillset()\fR function initializes the set pointed to by \fIset\fR to +include all signals defined by the system. +.sp +.LP +The \fBsigaddset()\fR function adds the individual signal specified by the +value of \fIsigno\fR to the set pointed to by \fIset\fR. +.sp +.LP +The \fBsigdelset()\fR function deletes the individual signal specified by the +value of \fIsigno\fR from the set pointed to by \fIset\fR. +.sp +.LP +The \fBsigismember()\fR function checks whether the signal specified by the +value of \fIsigno\fR is a member of the set pointed to by \fIset\fR. +.sp +.LP +Any object of type \fIsigset_t\fR must be initialized by applying either +\fBsigemptyset()\fR or \fBsigfillset()\fR before applying any other operation. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBsigismember()\fR function returns \fB1\fR if +the specified signal is a member of the specified set, or \fB0\fR if it is not. +.sp +.LP +Upon successful completion, the other functions return \fB0\fR. Otherwise +\fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBsigaddset()\fR, \fBsigdelset()\fR, and \fBsigismember()\fR functions +will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of the \fIsigno\fR argument is not a valid signal number. +.RE + +.sp +.LP +The \fBsigfillset()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +.rt +The \fIset\fR argument specifies an invalid address. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelAsync-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBsigaction\fR(2), \fBsigpending\fR(2), \fBsigprocmask\fR(2), +\fBsigsuspend\fR(2), \fBsignal.h\fR(3HEAD), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/sigstack.3c b/usr/src/man/man3c/sigstack.3c new file mode 100644 index 0000000000..94fb210cee --- /dev/null +++ b/usr/src/man/man3c/sigstack.3c @@ -0,0 +1,124 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH sigstack 3C "28 Feb 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +sigstack \- set and/or get alternate signal stack context +.SH SYNOPSIS +.LP +.nf +#include <signal.h> + +\fBint\fR \fBsigstack\fR(\fBstruct sigstack *\fR\fIss\fR, \fBstruct sigstack *\fR\fIoss\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsigstack()\fR function allows the calling process to indicate to the +system an area of its address space to be used for processing signals received +by the process. +.sp +.LP +If the \fIss\fR argument is not a null pointer, it must point to a +\fBsigstack\fR structure. The length of the application-supplied stack must be +at least \fBSIGSTKSZ\fR bytes. If the alternate signal stack overflows, the +resulting behavior is undefined. (See \fBUSAGE\fR below.) +.RS +4 +.TP +.ie t \(bu +.el o +The value of the \fBss_onstack\fR member indicates whether the process wants +the system to use an alternate signal stack when delivering signals. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The value of the \fBss_sp\fR member indicates the desired location of the +alternate signal stack area in the process' address space. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If the \fIss\fR argument is a null pointer, the current alternate signal stack +context is not changed. +.RE +.sp +.LP +If the \fIoss\fR argument is not a null pointer, it points to a \fBsigstack\fR +structure in which the current alternate signal stack context is placed. The +value stored in the \fBss_onstack\fR member of \fIoss\fR will be non-zero if +the process is currently executing on the alternate signal stack. If the +\fIoss\fR argument is a null pointer, the current alternate signal stack +context is not returned. +.sp +.LP +When a signal's action indicates its handler should execute on the alternate +signal stack (specified by calling \fBsigaction\fR(2)), \fBsigstack()\fR checks +to see if the process is currently executing on that stack. If the process is +not currently executing on the alternate signal stack, the system arranges a +switch to the alternate signal stack for the duration of the signal handler's +execution. +.sp +.LP +After a successful call to one of the \fIexec\fR functions, there are no +alternate signal stacks in the new process image. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBsigstack()\fR returns \fB0\fR. Otherwise, it +returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBsigstack()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 9n +.rt +An attempt was made to modify an active stack. +.RE + +.SH USAGE +.sp +.LP +A portable application, when being written or rewritten, should use +\fBsigaltstack\fR(2) instead of \fBsigstack()\fR. +.sp +.LP +The direction of stack growth is not indicated in the historical definition of +\fBstruct sigstack\fR. The only way to portably establish a stack pointer is +for the application to determine stack growth direction, or to allocate a block +of storage and set the stack pointer to the middle. \fBsigstack()\fR may assume +that the size of the signal stack is \fBSIGSTKSZ\fR as found in +<\fBsignal.h\fR>. An application that would like to specify a signal stack size +other than \fBSIGSTKSZ\fR should use \fBsigaltstack\fR(2). +.sp +.LP +Applications should not use \fBlongjmp\fR(3C) to leave a signal handler that is +running on a stack established with \fBsigstack()\fR. Doing so may disable +future use of the signal stack. For abnormal exit from a signal handler, +\fBsiglongjmp\fR(3C), \fBsetcontext\fR(2), or \fBswapcontext\fR(3C) may be +used. These functions fully support switching from one stack to another. +.sp +.LP +The \fBsigstack()\fR function requires the application to have knowledge of the +underlying system's stack architecture. For this reason, \fBsigaltstack\fR(2) +is recommended over this function. +.SH SEE ALSO +.sp +.LP +\fBfork\fR(2), \fB_longjmp\fR(3C), \fBlongjmp\fR(3C), \fBsetjmp\fR(3C), +\fBsigaltstack\fR(2), \fBsiglongjmp\fR(3C), \fBsigsetjmp\fR(3C) diff --git a/usr/src/man/man3c/sigwaitinfo.3c b/usr/src/man/man3c/sigwaitinfo.3c new file mode 100644 index 0000000000..9eb60303c3 --- /dev/null +++ b/usr/src/man/man3c/sigwaitinfo.3c @@ -0,0 +1,180 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH sigwaitinfo 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +sigwaitinfo, sigtimedwait \- wait for queued signals +.SH SYNOPSIS +.LP +.nf +#include <signal.h> + +\fBint\fR \fBsigwaitinfo\fR(\fBconst sigset_t *restrict\fR \fIset\fR, + \fBsiginfo_t *restrict\fR \fIinfo\fR); +.fi + +.LP +.nf +\fBint\fR \fBsigtimedwait\fR(\fBconst sigset_t *restrict\fR \fIset\fR, + \fBsiginfo_t *restrict\fR \fIinfo\fR, + \fBconst struct timespec *restrict\fR \fItimeout\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsigwaitinfo()\fR function selects the pending signal from the set +specified by \fBset\fR. Should any of multiple pending signals in the range +\fBSIGRTMIN\fR to \fBSIGRTMAX\fR be selected, it will be the lowest numbered +one. The selection order between realtime and non-realtime signals, or between +multiple pending non-realtime signals, is unspecified. If no signal in +\fBset\fR is pending at the time of the call, the calling thread is suspended +until one or more signals in \fBset\fR become pending or until it is +interrupted by an unblocked, caught signal. +.sp +.LP +The \fBsigwaitinfo()\fR function behaves the same as the \fBsigwait\fR(2) +function if the \fIinfo\fR argument is \fINULL\fR. If the \fIinfo\fR argument +is non-\fINULL\fR, the \fBsigwaitinfo()\fR function behaves the same as +\fBsigwait\fR(2), except that the selected signal number is stored in the +\fIsi_signo\fR member, and the cause of the signal is stored in the +\fIsi_code\fR member. If any value is queued to the selected signal, the first +such queued value is dequeued and, if the \fIinfo\fR argument is +non-\fINULL\fR, the value is stored in the \fIsi_value\fR member of \fIinfo\fR. +The system resource used to queue the signal will be released and made +available to queue other signals. If no value is queued, the content of the +\fIsi_value\fR member is undefined. If no further signals are queued for the +selected signal, the pending indication for that signal will be reset. If the +value of the \fBsi_code\fR member is \fBSI_NOINFO\fR, only the \fBsi_signo\fR +member of \fBsiginfo_t\fR is meaningful, and the value of all other members is +unspecified. +.sp +.LP +The \fBsigtimedwait()\fR function behaves the same as \fBsigwaitinfo()\fR +except that if none of the signals specified by \fBset\fR are pending, +\fBsigtimedwait()\fR waits for the time interval specified in the +\fBtimespec\fR structure referenced by \fItimeout\fR. If the \fBtimespec\fR +structure pointed to by \fItimeout\fR is zero-valued and if none of the signals +specified by \fBset\fR are pending, then \fBsigtimedwait()\fR returns +immediately with an error. If \fItimeout\fR is the \fINULL\fR pointer, the +behavior is unspecified. +.sp +.LP +If, while \fBsigwaitinfo()\fR or \fBsigtimedwait()\fR is waiting, a signal +occurs which is eligible for delivery (that is, not blocked by the process +signal mask), that signal is handled asynchronously and the wait is +interrupted. +.SH RETURN VALUES +.sp +.LP +Upon successful completion (that is, one of the signals specified by \fIset\fR +is pending or is generated) \fBsigwaitinfo()\fR and \fBsigtimedwait()\fR will +return the selected signal number. Otherwise, the function returns \fB\(mi1\fR +and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBsigwaitinfo()\fR and \fBsigtimedwait()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 10n +.rt +The wait was interrupted by an unblocked, caught signal. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR\fR +.ad +.RS 10n +.rt +The \fBsigwaitinfo()\fR and \fBsigtimedwait()\fR functions are not supported. +.RE + +.sp +.LP +The \fBsigtimedwait()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +No signal specified by \fBset\fR was generated within the specified timeout +period. +.RE + +.sp +.LP +The \fBsigwaitinfo()\fR and \fBsigtimedwait()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +.rt +The \fIset\fR, \fIinfo\fR, or \fItimeout\fR argument points to an invalid +address. +.RE + +.sp +.LP +The \fBsigtimedwait()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fItimeout\fR argument specified a \fBtv_nsec\fR value less than zero or +greater than or equal to 1000 million. The system only checks for this error if +no signal is pending in \fIset\fR and it is necessary to wait. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityCommitted +_ +MT-LevelAsync-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBtime\fR(2), \fBsigqueue\fR(3C), \fBsiginfo.h\fR(3HEAD), +\fBsignal.h\fR(3HEAD), \fBtime.h\fR(3HEAD), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/sleep.3c b/usr/src/man/man3c/sleep.3c new file mode 100644 index 0000000000..b6ae2edef1 --- /dev/null +++ b/usr/src/man/man3c/sleep.3c @@ -0,0 +1,63 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH sleep 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +sleep \- suspend execution for an interval of time +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> + +\fBunsigned int\fR \fBsleep\fR(\fBunsigned int\fR \fIseconds\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The caller is suspended from execution for the number of \fIseconds\fR +specified by the argument. The actual suspension time may be less than that +requested because any caught signal will terminate the \fBsleep()\fR following +execution of that signal's catching routine. The suspension time may be longer +than requested by an arbitrary amount because of the scheduling of other +activity in the system. The value returned by \fBsleep()\fR will be the +``unslept'' amount (the requested time minus the time actually slept) if the +caller incurred premature arousal because of a caught signal. +.sp +.LP +The use of the \fBsleep()\fR function has no effect on the action or blockage +of any signal. In a multithreaded process, only the invoking thread is +suspended from execution. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelAsync-Signal-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBnanosleep\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/ssignal.3c b/usr/src/man/man3c/ssignal.3c new file mode 100644 index 0000000000..316cbc37d2 --- /dev/null +++ b/usr/src/man/man3c/ssignal.3c @@ -0,0 +1,87 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ssignal 3C "29 Dec 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +ssignal, gsignal \- software signals +.SH SYNOPSIS +.LP +.nf +#include <signal.h> + +\fBvoid\fR(\fB*ssignal\fR (\fBint\fR \fIsig\fR, \fBint\fR (*\fIaction\fR)(\fBint\fR)))(\fBint\fR); +.fi + +.LP +.nf +\fBint\fR \fBgsignal\fR(\fBint\fR \fIsig\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBssignal()\fR and \fBgsignal()\fR functions implement a software facility +similar to \fBsignal\fR(3C). This facility is made available to users for their +own purposes. +.SS "ssignal(\|)" +.sp +.LP +Software signals made available to users are associated with integers in the +inclusive range 1 through 17. A call to \fBssignal()\fR associates a procedure, +\fIaction\fR, with the software signal \fIsig\fR; the software signal, +\fIsig\fR, is raised by a call to \fBgsignal()\fR. Raising a software signal +causes the action established for that signal to be taken. +.sp +.LP +The first argument to \fBssignal()\fR is a number identifying the type of +signal for which an action is to be established. The second argument defines +the action; it is either the name of a (user-defined) \fIaction\fR +\fIfunction\fR or one of the manifest constants \fBSIG_DFL\fR (default) or +\fBSIG_IGN\fR (ignore). The \fBssignal()\fR function returns the action +previously established for that signal type; if no action has been established +or the signal number is illegal, \fBssignal()\fR returns \fBSIG_DFL\fR. +.SS "gsignal(\|)" +.sp +.LP +The \fBgsignal()\fR raises the signal identified by its argument, \fIsig\fR. +.sp +.LP +If an action function has been established for \fIsig\fR, then that action is +reset to \fBSIG_DFL\fR and the action function is entered with argument +\fIsig\fR. The \fBgsignal()\fR function returns the value returned to it by the +action function. +.sp +.LP +If the action for \fIsig\fR is \fBSIG_IGN\fR, \fBgsignal()\fR returns the value +1 and takes no other action. +.sp +.LP +If the action for \fIsig\fR is \fBSIG_DFL\fR, \fBgsignal()\fR returns the value +0 and takes no other action. +.sp +.LP +If \fIsig\fR has an illegal value or no action was ever specified for +\fIsig\fR, \fBgsignal()\fR returns the value 0 and takes no other action. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBraise\fR(3C), \fBsignal\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/stack_getbounds.3c b/usr/src/man/man3c/stack_getbounds.3c new file mode 100644 index 0000000000..af6053036f --- /dev/null +++ b/usr/src/man/man3c/stack_getbounds.3c @@ -0,0 +1,74 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH stack_getbounds 3C "18 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +stack_getbounds \- retrieve stack boundaries +.SH SYNOPSIS +.LP +.nf +#include <ucontext.h> + +\fBint\fR \fBstack_getbounds\fR(\fBstack_t *\fR\fIsp\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBstack_getbounds()\fR function retrieves the stack boundaries that the +calling thread is currently operating on. If the thread is currently operating +on the alternate signal stack, this function will retrieve the bounds of that +stack. +.sp +.LP +If successful, \fBstack_getbounds()\fR sets the \fBss_sp\fR member of the +\fBstack_t\fR structure pointed to by \fIsp\fR to the base of the stack region +and the \fBss_size\fR member to its size (maximum extent) in bytes. The +\fBss_flags\fR member is set to \fBSS_ONSTACK\fR if the calling thread is +executing on its alternate signal stack, and zero otherwise. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBstack_getbounds()\fR returns 0. Otherwise, \(mi1 +is returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBstack_getbounds()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +.rt +The \fIsp\fR argument does not refer to a valid address. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelAsync-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgetustack\fR(2), \fBsigaction\fR(2), \fBsigaltstack\fR(2), +\fBstack_setbounds\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/stack_inbounds.3c b/usr/src/man/man3c/stack_inbounds.3c new file mode 100644 index 0000000000..04782c638d --- /dev/null +++ b/usr/src/man/man3c/stack_inbounds.3c @@ -0,0 +1,56 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH stack_inbounds 3C "18 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +stack_inbounds \- determine if address is within stack boundaries +.SH SYNOPSIS +.LP +.nf +#include <ucontext.h> + +\fBint\fR \fBstack_inbounds\fR(\fBvoid *\fR\fIaddr\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBstack_inbounds()\fR function returns a boolean value indicating whether +the address specified by \fIaddr\fR is within the boundaries of the stack of +the calling thread. The address is compared to the stack boundary information +returned by a call to \fBstack_getbounds\fR(3C). +.SH RETURN VALUES +.sp +.LP +The \fBstack_inbounds()\fR function returns 0 to indicate that \fIaddr\fR is +not within the current stack bounds, or a non-zero value to indicate that +\fIaddr\fR is within the stack bounds. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelAsync-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBstack_getbounds\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/stack_setbounds.3c b/usr/src/man/man3c/stack_setbounds.3c new file mode 100644 index 0000000000..018ee00faa --- /dev/null +++ b/usr/src/man/man3c/stack_setbounds.3c @@ -0,0 +1,88 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH stack_setbounds 3C "18 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +stack_setbounds \- update stack boundaries +.SH SYNOPSIS +.LP +.nf +#include <ucontext.h> + +\fBint\fR \fBstack_setbounds\fR(\fBconst stack_t *\fR\fIsp\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBstack_setbounds()\fR function updates the current base and bounds of the +stack for the current thread to the bounds specified by the \fBstack_t\fR +structure pointed to by \fIsp\fR. The \fBss_sp\fR member refers to the virtual +address of the base of the stack memory. The \fBss_size\fR member refers to the +size of the stack in bytes. The \fBss_flags\fR member must be set to 0. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBstack_setbounds()\fR returns 0. Otherwise, \(mi1 +is returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBstack_setbounds()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +.rt +The \fIsp\fR argument does not refer to a valid address or the \fBss_sp\fR +member of the \fBstack_t\fR structure pointed to by \fIsp\fR points to an +illegal address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fBss_sp\fR member of the \fBstack_t\fR structure pointed to by sp is not +properly aligned, the \fBss_size\fR member is too small or is not properly +aligned, or the \fBss_flags\fR member is non-zero. +.RE + +.SH USAGE +.sp +.LP +The \fBstack_setbounds()\fR function is intended for use by applications that +are managing their own alternate stacks. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelAsync-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgetustack\fR(2), \fB_stack_grow\fR(3C), \fBstack_getbounds\fR(3C), +\fBstack_inbounds\fR(3C), \fBstack_violation\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/stack_violation.3c b/usr/src/man/man3c/stack_violation.3c new file mode 100644 index 0000000000..eff1a5c07d --- /dev/null +++ b/usr/src/man/man3c/stack_violation.3c @@ -0,0 +1,125 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH stack_violation 3C "18 Jul 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +stack_violation \- determine stack boundary violation event +.SH SYNOPSIS +.LP +.nf +#include <ucontext.h> + +\fBint\fR \fBstack_violation\fR(\fBint\fR \fIsig\fR, \fBconst siginfo_t *\fR\fIsip\fR, + \fBconst ucontext_t *\fR\fIucp\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBstack_violation()\fR function returns a boolean value indicating whether +the signal, \fIsig\fR, and accompanying signal information, \fIsip\fR, and +saved context, \fIucp\fR, represent a stack boundary violation event or a stack +overflow. +.SH RETURN VALUES +.sp +.LP +The \fBstack_violation()\fR function returns 0 if the signal does not represent +a stack boundary violation event and 1 if the signal does represent a stack +boundary violation event. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH EXAMPLES +.LP +\fBExample 1 \fRSet up a signal handler to run on an alternate stack. +.sp +.LP +The following example sets up a signal handler for \fBSIGSEGV\fR to run on an +alternate signal stack. For each signal it handles, the handler emits a message +to indicate if the signal was produced due to a stack boundary violation. + +.sp +.in +2 +.nf +#include <stdlib.h> +#include <unistd.h> +#include <ucontext.h> +#include <signal.h> + + +static void +handler(int sig, siginfo_t *sip, void *p) +{ + ucontext_t *ucp = p; + const char *str; + + if (stack_violation(sig, sip, ucp)) + str = "stack violation.\en"; + else + str = "no stack violation.\en"; + + (void) write(STDERR_FILENO, str, strlen(str)); + + exit(1); +} + +int +main(int argc, char **argv) +{ + struct sigaction sa; + stack_t altstack; + + altstack.ss_size = SIGSTKSZ; + altstack.ss_sp = malloc(SIGSTKSZ); + altstack.ss_flags = 0; + + (void) sigaltstack(&altstack, NULL); + + sa.sa_sigaction = handler; + (void) sigfillset(&sa.sa_mask); + sa.sa_flags = SA_ONSTACK | SA_SIGINFO; + (void) sigaction(SIGSEGV, &sa, NULL); + + /* + * The application is now set up to use stack_violation(3C). + */ + + return (0); +} +.fi +.in -2 + +.SH USAGE +.sp +.LP +An application typically uses \fBstack_violation()\fR in a signal handler that +has been installed for \fBSIGSEGV\fR using \fBsigaction\fR(2) with the +\fBSA_SIGINFO\fR flag set and is configured to run on an alternate signal +stack. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelAsync-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBsigaction\fR(2), \fBsigaltstack\fR(2), \fBstack_getbounds\fR(3C), +\fBstack_inbounds\fR(3C), \fBstack_setbounds\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/stdio.3c b/usr/src/man/man3c/stdio.3c new file mode 100644 index 0000000000..4c9b951627 --- /dev/null +++ b/usr/src/man/man3c/stdio.3c @@ -0,0 +1,354 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH stdio 3C "18 May 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +stdio \- standard buffered input/output package +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> +.fi + +.LP +.nf +\fBextern FILE *\fR\fIstdin\fR\fB;\fR +.fi + +.LP +.nf +\fBextern FILE *\fR\fIstdout\fR\fB;\fR +.fi + +.LP +.nf +\fBextern FILE *\fR\fIstderr\fR\fB;\fR +.fi + +.SH DESCRIPTION +.sp +.LP +The standard I/O functions described in section 3C of this manual constitute an +efficient, user-level \fBI/O\fR buffering scheme. The in-line macros +\fBgetc()\fR and \fBputc()\fR handle characters quickly. The macros +\fBgetchar\fR(3C) and \fBputchar\fR(3C), and the higher-level routines +\fBfgetc\fR(3C), \fBfgets\fR(3C), \fBfprintf\fR(3C), \fBfputc\fR(3C), +\fBfputs\fR(3C), \fBfread\fR(3C), \fBfscanf\fR(3C), \fBfwrite\fR(3C), +\fBgets\fR(3C), \fBgetw\fR(3C), \fBprintf\fR(3C), \fBputs\fR(3C), +\fBputw\fR(3C), and \fBscanf\fR(3C) all use or act as if they use \fBgetc()\fR +and \fBputc()\fR; they can be freely intermixed. +.sp +.LP +A file with associated buffering is called a \fIstream\fR (see \fBIntro\fR(3)) +and is declared to be a pointer to a defined type \fBFILE\fR. The +\fBfopen\fR(3C) function creates certain descriptive data for a stream and +returns a pointer to designate the stream in all further transactions. +Normally, there are three open streams with constant pointers declared in the +\fB<stdio.h>\fR header and associated with the standard open files: +.sp +.ne 2 +.mk +.na +\fB\fBstdin\fR\fR +.ad +.RS 10n +.rt +standard input file +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBstdout\fR\fR +.ad +.RS 10n +.rt +standard output file +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBstderr\fR\fR +.ad +.RS 10n +.rt +standard error file +.RE + +.sp +.LP +The following symbolic values in <\fBunistd.h\fR> define the file descriptors +that will be associated with the C-language \fBstdin\fR, \fBstdout\fR and +\fBstderr\fR when the application is started: +.sp + +.sp +.TS +tab(); +lw(1.38i) lw(1.65i) lw(.31i) lw(2.17i) +lw(1.38i) lw(1.65i) lw(.31i) lw(2.17i) +. +\fBSTDIN_FILENO\fRStandard input value0\fBstdin\fR +\fBSTDOUT_FILENO\fRStandard output value1\fBstdout\fR +\fBSTDERR_FILENO\fRStandard error value2\fBstderr\fR +.TE + +.sp +.LP +The constant \fINULL\fR designates a null pointer. +.sp +.LP +The integer-constant \fBEOF\fR is returned upon end-of-file or error by most +integer functions that deal with streams (see the individual descriptions for +details). +.sp +.LP +The integer constant \fBBUFSIZ\fR specifies the size of the buffers used by the +particular implementation. +.sp +.LP +The integer constant \fBFILENAME_MAX\fR specifies the number of bytes needed to +hold the longest pathname of a file allowed by the implementation. If the +system does not impose a maximum limit, this value is the recommended size for +a buffer intended to hold a file's pathname. +.sp +.LP +The integer constant \fBFOPEN_MAX\fR specifies the minimum number of files that +the implementation guarantees can be open simultaneously. Note that no more +than 255 files may be opened using \fBfopen()\fR, and only file descriptors 0 +through 255 can be used in a stream. +.sp +.LP +The functions and constants mentioned in the entries of section 3S of this +manual are declared in that header and need no further declaration. The +constants and the following "functions" are implemented as macros +(redeclaration of these names is perilous): \fBgetc()\fR, \fBgetchar()\fR, +\fBputc()\fR, \fBputchar()\fR, \fBferror\fR(3C), \fBfeof\fR(3C), +\fBclearerr\fR(3C), and \fBfileno\fR(3C). There are also function versions of +\fBgetc()\fR, \fBgetchar()\fR, \fBputc()\fR, \fBputchar()\fR, \fBferror()\fR, +\fBfeof()\fR, \fBclearerr()\fR, and \fBfileno()\fR. +.sp +.LP +Output streams, with the exception of the standard error stream \fBstderr\fR, +are by default buffered if the output refers to a file and line-buffered if the +output refers to a terminal. The standard error output stream \fBstderr\fR is +by default unbuffered, but use of \fBfreopen()\fR (see \fBfopen\fR(3C)) will +cause it to become buffered or line-buffered. When an output stream is +unbuffered, information is queued for writing on the destination file or +terminal as soon as written; when it is buffered, many characters are saved up +and written as a block. When it is line-buffered, each line of output is queued +for writing on the destination terminal as soon as the line is completed (that +is, as soon as a new-line character is written or terminal input is requested). +The \fBsetbuf()\fR or \fBsetvbuf()\fR functions (both described on the +\fBsetbuf\fR(3C) manual page) may be used to change the stream's buffering +strategy. +.SS "Interactions of Other FILE-Type C Functions" +.sp +.LP +A single open file description can be accessed both through streams and through +file descriptors. Either a file descriptor or a stream will be called a +\fIhandle\fR on the open file description to which it refers; an open file +description may have several handles. +.sp +.LP +Handles can be created or destroyed by user action without affecting the +underlying open file description. Some of the ways to create them include +\fBfcntl\fR(2), \fBdup\fR(2), \fBfdopen\fR(3C), \fBfileno\fR(3C) and +\fBfork\fR(2) (which duplicates existing ones into new processes). They can be +destroyed by at least \fBfclose\fR(3C) and \fBclose\fR(2), and by the +\fBexec\fR functions (see \fBexec\fR(2)), which close some file descriptors and +destroy streams. +.sp +.LP +A file descriptor that is never used in an operation and could affect the file +offset (for example \fBread\fR(2), \fBwrite\fR(2), or \fBlseek\fR(2)) is not +considered a handle in this discussion, but could give rise to one (as a +consequence of \fBfdopen()\fR, \fBdup()\fR, or \fBfork()\fR, for example). +This exception does include the file descriptor underlying a stream, whether +created with \fBfopen()\fR or \fBfdopen()\fR, as long as it is not used +directly by the application to affect the file offset. (The \fBread()\fR and +\fBwrite()\fR functions implicitly affect the file offset; \fBlseek()\fR +explicitly affects it.) +.sp +.LP +If two or more handles are used, and any one of them is a stream, their actions +shall be coordinated as described below. If this is not done, the result is +undefined. +.sp +.LP +A handle that is a stream is considered to be closed when either an +\fBfclose()\fR or \fBfreopen\fR(3C) is executed on it (the result of +\fBfreopen()\fR is a new stream for this discussion, which cannot be a handle +on the same open file description as its previous value) or when the process +owning that stream terminates the \fBexit\fR(2) or \fBabort\fR(3C). A file +descriptor is closed by \fBclose()\fR, \fB_exit()\fR (see \fBexit\fR(2)), or by +one of the \fBexec\fR functions when \fBFD_CLOEXEC\fR is set on that file +descriptor. +.sp +.LP +For a handle to become the active handle, the actions below must be performed +between the last other user of the first handle (the current active handle) and +the first other user of the second handle (the future active handle). The +second handle then becomes the active handle. All activity by the application +affecting the file offset on the first handle shall be suspended until it again +becomes the active handle. (If a stream function has as an underlying function +that affects the file offset, the stream function will be considered to affect +the file offset. The underlying functions are described below.) +.sp +.LP +The handles need not be in the same process for these rules to apply. Note that +after a \fBfork()\fR, two handles exist where one existed before. The +application shall assure that, if both handles will ever be accessed, that they +will both be in a state where the other could become the active handle first. +The application shall prepare for a \fBfork()\fR exactly as if it were a change +of active handle. (If the only action performed by one of the processes is one +of the \fBexec\fR functions or \fB_exit()\fR, the handle is never accessed in +that process.) +.RS +4 +.TP +1. +For the first handle, the first applicable condition below shall apply. +After the actions required below are taken, the handle may be closed if it is +still open. +.RS +4 +.TP +a. +If it is a file descriptor, no action is required. +.RE +.RS +4 +.TP +b. +If the only further action to be performed on any handle to this open file +description is to close it, no action need be taken. +.RE +.RS +4 +.TP +c. +If it is a stream that is unbuffered, no action need be taken. +.RE +.RS +4 +.TP +d. +If it is a stream that is line-buffered and the last character written to +the stream was a newline (that is, as if a \fBputc('\en')\fR was the most +recent operation on that stream), no action need be taken. +.RE +.RS +4 +.TP +e. +If it is a stream that is open for writing or append (but not also open for +reading), either an \fBfflush\fR(3C) shall occur or the stream shall be closed. +.RE +.RS +4 +.TP +f. +If the stream is open for reading and it is at the end of the file ( +\fBfeof\fR(3C) is true), no action need be taken. +.RE +.RS +4 +.TP +g. +If the stream is open with a mode that allows reading and the underlying +open file description refers to a device that is capable of seeking, either an +\fBfflush()\fR shall occur or the stream shall be closed. +.RE +.RS +4 +.TP +h. +Otherwise, the result is undefined. +.RE +.RE +.RS +4 +.TP +2. +For the second handle: if any previous active handle has called a function +that explicitly changed the file offset, except as required above for the first +handle, the application shall perform an \fBlseek()\fR or an \fBfseek\fR(3C) +(as appropriate to the type of the handle) to an appropriate location. +.RE +.RS +4 +.TP +3. +If the active handle ceases to be accessible before the requirements on the +first handle above have been met, the state of the open file description +becomes undefined. This might occur, for example, during a \fBfork()\fR or an +\fB_exit()\fR. +.RE +.RS +4 +.TP +4. +The \fBexec\fR functions shall be considered to make inaccessible all +streams that are open at the time they are called, independent of what streams +or file descriptors may be available to the new process image. +.RE +.RS +4 +.TP +5. +Implementation shall assure that an application, even one consisting of +several processes, shall yield correct results (no data is lost or duplicated +when writing, all data is written in order, except as requested by seeks) when +the rules above are followed, regardless of the sequence of handles used. If +the rules above are not followed, the result is unspecified. When these rules +are followed, it is implementation defined whether, and under what conditions, +all input is seen exactly once. +.RE +.SS "Use of stdio in Multithreaded Applications" +.sp +.LP +All the \fBstdio\fR functions are safe unless they have the \fB_unlocked\fR +suffix. Each \fBFILE\fR pointer has its own lock to guarantee that only one +thread can access it. In the case that output needs to be synchronized, the +lock for the \fBFILE\fR pointer can be acquired before performing a series of +\fBstdio\fR operations. For example: +.sp +.in +2 +.nf +FILE iop; +flockfile(iop); +fprintf(iop, "hello "); +fprintf(iop, "world); +fputc(iop, 'a'); +funlockfile(iop); +.fi +.in -2 + +.sp +.LP +will print everything out together, blocking other threads that might want to +write to the same file between calls to \fBfprintf()\fR. +.sp +.LP +An unlocked interface is available in case performace is an issue. For +example: +.sp +.in +2 +.nf +flockfile(iop); +while (!feof(iop)) { + *c++ = getc_unlocked(iop); +} +funlockfile(iop); +.fi +.in -2 + +.SH RETURN VALUES +.sp +.LP +Invalid stream pointers usually cause grave disorder, possibly including +program termination. Individual function descriptions describe the possible +error conditions. +.SH SEE ALSO +.sp +.LP +\fBclose\fR(2), \fBlseek\fR(2), \fBopen\fR(2), \fBpipe\fR(2), \fBread\fR(2), +\fBwrite\fR(2), \fBctermid\fR(3C), \fBcuserid\fR(3C), \fBfclose\fR(3C), +\fBferror\fR(3C), \fBfopen\fR(3C), \fBfread\fR(3C), \fBfseek\fR(3C), +\fBflockfile\fR(3C), \fBgetc\fR(3C), \fBgets\fR(3C), \fBpopen\fR(3C), +\fBprintf\fR(3C), \fBputc\fR(3C), \fBputs\fR(3C), \fBscanf\fR(3C), +\fBsetbuf\fR(3C), \fBsystem\fR(3C), \fBtmpfile\fR(3C), \fBtmpnam\fR(3C), +\fBungetc\fR(3C) diff --git a/usr/src/man/man3c/str2sig.3c b/usr/src/man/man3c/str2sig.3c new file mode 100644 index 0000000000..45d18a5916 --- /dev/null +++ b/usr/src/man/man3c/str2sig.3c @@ -0,0 +1,71 @@ +'\" te +.\" Copyright (c) 1999, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH str2sig 3C "7 Oct 1999" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +str2sig, sig2str \- translation between signal name and signal number +.SH SYNOPSIS +.LP +.nf +#include <signal.h> + +\fBint\fR \fBstr2sig\fR(\fBconst char *\fR\fIstr\fR, \fBint\fR \fI*signum\fR); +.fi + +.LP +.nf +\fBint\fR \fBsig2str\fR(\fBint\fR \fIsignum\fR, \fBchar *\fR\fIstr\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBstr2sig()\fR function translates the signal name \fIstr\fR to a signal +number, and stores that result in the location referenced by \fIsignum\fR. The +name in \fIstr\fR can be either the symbol for that signal, without the "SIG" +prefix, or a decimal number. All the signal symbols defined in +<\fBsys/signal.h\fR> are recognized. This means that both "CLD" and "CHLD" are +recognized and return the same signal number, as do both "POLL" and "IO". For +access to the signals in the range \fBSIGRTMIN\fR to \fBSIGRTMAX\fR, the first +four signals match the strings "RTMIN", "RTMIN+1", "RTMIN+2", and "RTMIN+3" and +the last four match the strings "RTMAX-3", "RTMAX-2", "RTMAX-1", and "RTMAX". +.sp +.LP +The \fBsig2str()\fR function translates the signal number \fIsignum\fR to the +symbol for that signal, without the "SIG" prefix, and stores that symbol at the +location specified by \fIstr\fR. The storage referenced by \fIstr\fR should be +large enough to hold the symbol and a terminating null byte. The symbol +\fBSIG2STR_MAX\fR defined by \fB<signal.h>\fR gives the maximum size in bytes +required. +.SH RETURN VALUES +.sp +.LP +The \fBstr2sig()\fR function returns \fB0\fR if it recognizes the signal name +specified in \fIstr\fR; otherwise, it returns \fB\(mi1\fR\&. +.sp +.LP +The \fBsig2str()\fR function returns \fB0\fR if the value \fIsignum\fR +corresponds to a valid signal number; otherwise, it returns \fB\(mi1\fR\&. +.SH EXAMPLES +.LP +\fBExample 1 \fRA sample program using the \fBstr2sig()\fR function. +.sp +.in +2 +.nf +int i; +char buf[SIG2STR_MAX]; /*storage for symbol */ + +str2sig("KILL",&i); /*stores 9 in i */ +str2sig("9", &i); /* stores 9 in i */ +sig2str(SIGKILL,buf); /* stores "KILL" in buf */ +sig2str(9,buf); /* stores "KILL" in buf */ +.fi +.in -2 +.sp + +.SH SEE ALSO +.sp +.LP +\fBkill\fR(1), \fBstrsignal\fR(3C) diff --git a/usr/src/man/man3c/strcoll.3c b/usr/src/man/man3c/strcoll.3c new file mode 100644 index 0000000000..348e39bf32 --- /dev/null +++ b/usr/src/man/man3c/strcoll.3c @@ -0,0 +1,109 @@ +'\" te +.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH strcoll 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +strcoll \- string collation +.SH SYNOPSIS +.LP +.nf +#include <string.h> + +\fBint\fR \fBstrcoll\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +Both \fBstrcoll()\fR and \fBstrxfrm\fR(3C) provide for locale-specific string +sorting. \fBstrcoll()\fR is intended for applications in which the number of +comparisons per string is small. When strings are to be compared a number of +times, \fBstrxfrm\fR(3C) is a more appropriate function because the +transformation process occurs only once. +.sp +.LP +The \fBstrcoll()\fR function does not change the setting of \fBerrno\fR if +successful. +.sp +.LP +Since no return value is reserved to indicate an error, an application wishing +to check for error situations should set \fBerrno\fR to 0, then call +\fBstrcoll()\fR, then check \fBerrno\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBstrcoll()\fR returns an integer greater than, +equal to, or less than zero in direct correlation to whether string \fIs1\fR is +greater than, equal to, or less than the string \fIs2\fR. The comparison is +based on strings interpreted as appropriate to the program's locale for +category \fBLC_COLLATE\fR (see \fBsetlocale\fR(3C)). +.sp +.LP +On error, \fBstrcoll()\fR may set \fBerrno\fR, but no return value is reserved +to indicate an error. +.SH ERRORS +.sp +.LP +The \fBstrcoll()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIs1\fR or \fIs2\fR arguments contain characters outside the domain of the +collating sequence. +.RE + +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/locale/\fIlocale\fR/\fIlocale\fR.so.*\fR\fR +.ad +.sp .6 +.RS 4n +\fBLC_COLLATE\fR database for \fIlocale\fR +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +CSIEnabled +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe with exceptions +.TE + +.sp +.LP +The \fBstrcoll()\fR function can be used safely in multithreaded applications, +as long as \fBsetlocale\fR(3C) is not being called to change the locale. +.SH SEE ALSO +.sp +.LP +\fBlocaledef\fR(1), \fBsetlocale\fR(3C), \fBstring\fR(3C), \fBstrxfrm\fR(3C), +\fBwsxfrm\fR(3C), \fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/strerror.3c b/usr/src/man/man3c/strerror.3c new file mode 100644 index 0000000000..3aaa27bb6f --- /dev/null +++ b/usr/src/man/man3c/strerror.3c @@ -0,0 +1,111 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH strerror 3C "31 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +strerror, strerror_r \- get error message string +.SH SYNOPSIS +.LP +.nf +#include <string.h> + +\fBchar *\fR\fBstrerror\fR(\fBint\fR \fIerrnum\fR); +.fi + +.LP +.nf +\fBint\fR \fBstrerror_r\fR(\fBint\fR \fIerrnum\fR, \fBchar *\fR\fIstrerrbuf\fR, \fBsize_t\fR \fIbuflen\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBstrerror()\fR function maps the error number in \fIerrnum\fR to an error +message string, and returns a pointer to that string. It uses the same set of +error messages as \fBperror\fR(3C). The returned string should not be +overwritten. +.sp +.LP +The \fBstrerror_r()\fR function maps the error number in \fIerrnum\fR to +anerror message string and returns the string in the buffer pointed to by +\fIstrerrbuf\fR with length \fIbuflen\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBstrerror()\fR returns a pointer to the generated +message string. Otherwise, it sets \fBerrno\fR and returns a pointer to an +error message string. It returns the string "Unknown error" if \fIerrnum\fR is +not a valid error number. +.sp +.LP +Upon successful completion, \fBstrerror_r()\fR returns 0. Otherwise it sets +\fBerrno\fR and returns the value of \fBerrno\fR to indicate the error. It +returns the string "Unknown error" in the buffer pointed to by \fIstrerrbuf\fR +if \fIerrnum\fR is not a valid error number. +.SH ERRORS +.sp +.LP +These functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of \fIerrnum\fR is not a valid error number. +.RE + +.sp +.LP +The \fBstrerror_r()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBERANGE\fR\fR +.ad +.RS 10n +.rt +The \fIbuflen\fR argument specifies insufficient storage to contain the +generated message string. +.RE + +.SH USAGE +.sp +.LP +Messages returned from these functions are in the native language specified by +the \fBLC_MESSAGES\fR locale category. See \fBsetlocale\fR(3C). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgettext\fR(3C), \fBperror\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/strftime.3c b/usr/src/man/man3c/strftime.3c new file mode 100644 index 0000000000..e1e161aa98 --- /dev/null +++ b/usr/src/man/man3c/strftime.3c @@ -0,0 +1,915 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH strftime 3C "5 Sep 2006" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +strftime, cftime, ascftime \- convert date and time to string +.SH SYNOPSIS +.LP +.nf +#include <time.h> + +\fBsize_t\fR \fBstrftime\fR(\fBchar *restrict\fR \fIs\fR, \fBsize_t\fR \fImaxsize\fR, + \fBconst char *restrict\fR \fIformat\fR, + \fBconst struct tm *restrict\fR \fItimeptr\fR); +.fi + +.LP +.nf +\fBint\fR \fBcftime\fR(\fBchar *\fR\fIs\fR, \fBchar *\fR\fIformat\fR, \fBconst time_t *\fR\fIclock\fR); +.fi + +.LP +.nf +\fBint\fR \fBascftime\fR(\fBchar *\fR\fIs\fR, \fBconst char *\fR\fIformat\fR, + \fBconst struct tm *\fR\fItimeptr\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBstrftime()\fR, \fBascftime()\fR, and \fBcftime()\fR functions place +bytes into the array pointed to by \fIs\fR as controlled by the string pointed +to by \fIformat\fR. The \fIformat\fR string consists of zero or more conversion +specifications and ordinary characters. A conversion specification consists of +a '\fB%\fR' (percent) character and one or two terminating conversion +characters that determine the conversion specification's behavior. All +ordinary characters (including the terminating null byte) are copied unchanged +into the array pointed to by \fIs\fR. If copying takes place between objects +that overlap, the behavior is undefined. For \fBstrftime()\fR, no more than +\fImaxsize\fR bytes are placed into the array. +.sp +.LP +If \fIformat\fR is \fB(char *)0\fR, then the locale's default format is used. +For \fBstrftime()\fR the default format is the same as \fB%c\fR; for +\fBcftime()\fR and \fBascftime()\fR the default format is the same as \fB%C\fR. +\fBcftime()\fR and \fBascftime()\fR first try to use the value of the +environment variable \fBCFTIME\fR, and if that is undefined or empty, the +default format is used. +.sp +.LP +Each conversion specification is replaced by appropriate characters as +described in the following list. The appropriate characters are determined by +the \fBLC_TIME\fR category of the program's locale and by the values contained +in the structure pointed to by \fItimeptr\fR for \fBstrftime()\fR and +\fBascftime()\fR, and by the time represented by \fIclock\fR for +\fBcftime()\fR. +.sp +.ne 2 +.mk +.na +\fB\fB%%\fR\fR +.ad +.RS 6n +.rt +Same as \fB%\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%a\fR\fR +.ad +.RS 6n +.rt +Locale's abbreviated weekday name. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%A\fR\fR +.ad +.RS 6n +.rt +Locale's full weekday name. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%b\fR\fR +.ad +.RS 6n +.rt +Locale's abbreviated month name. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%B\fR\fR +.ad +.RS 6n +.rt +Locale's full month name. +.RE + +.SS "Default" +.sp +.ne 2 +.mk +.na +\fB\fB%c\fR\fR +.ad +.RS 6n +.rt +Locale's appropriate date and time represented as: +.sp +.in +2 +.nf +%a %b %d %H:%M:%S %Y +.fi +.in -2 + +This is the default behavior as well as standard-conforming behavior for +standards first supported by releases prior to Solaris 2.4. See +\fBstandards\fR(5). +.RE + +.SS "Standard conforming" +.sp +.ne 2 +.mk +.na +\fB\fB%c\fR\fR +.ad +.RS 6n +.rt +Locale's appropriate date and time represented as: +.sp +.in +2 +.nf +%a %b %e %H:%M:%S %Y +.fi +.in -2 + +This is standard-conforming behavior for standards first supported by Solaris +2.4 through Solaris 10. +.RE + +.SS "Default" +.sp +.ne 2 +.mk +.na +\fB\fB%C\fR\fR +.ad +.RS 6n +.rt +Locale's date and time representation as produced by \fBdate\fR(1). +.sp +This is the default behavior as well as standard-conforming behavior for +standards first supported by releases prior to Solaris 2.4. +.RE + +.SS "Standard conforming" +.sp +.ne 2 +.mk +.na +\fB\fB%C\fR\fR +.ad +.RS 6n +.rt +Century number (the year divided by 100 and truncated to an integer as a +decimal number [01,99]). +.sp +This is standard-conforming behavior for standards first supported by Solaris +2.4 through Solaris 10. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%d\fR\fR +.ad +.RS 6n +.rt +Day of month [01,31]. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%D\fR\fR +.ad +.RS 6n +.rt +Date as \fB%m\fR/\fB%d\fR/\fB%y\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%e\fR\fR +.ad +.RS 6n +.rt +Day of month [1,31]; single digits are preceded by a space. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%F\fR\fR +.ad +.RS 6n +.rt +Equivalent to \fB%Y\fR-\fB%m\fR-\fB%d\fR (the ISO 8601:2000 standard date +format). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%g\fR\fR +.ad +.RS 6n +.rt +Week-based year within century [00,99]. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%G\fR\fR +.ad +.RS 6n +.rt +Week-based year, including the century [0000,9999]. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%h\fR\fR +.ad +.RS 6n +.rt +Locale's abbreviated month name. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%H\fR\fR +.ad +.RS 6n +.rt +Hour (24-hour clock) [00,23]. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%I\fR\fR +.ad +.RS 6n +.rt +Hour (12-hour clock) [01,12]. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%j\fR\fR +.ad +.RS 6n +.rt +Day number of year [001,366]. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%k\fR\fR +.ad +.RS 6n +.rt +Hour (24-hour clock) [0,23]; single digits are preceded by a space. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%l\fR\fR +.ad +.RS 6n +.rt +Hour (12-hour clock) [1,12]; single digits are preceded by a space. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%m\fR\fR +.ad +.RS 6n +.rt +Month number [01,12]. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%M\fR\fR +.ad +.RS 6n +.rt +Minute [00,59]. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%n\fR\fR +.ad +.RS 6n +.rt +Insert a NEWLINE. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%p\fR\fR +.ad +.RS 6n +.rt +Locale's equivalent of either a.m. or p.m. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%r\fR\fR +.ad +.RS 6n +.rt +Appropriate time representation in 12-hour clock format with \fB%p\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%R\fR\fR +.ad +.RS 6n +.rt +Time as \fB%H\fR:\fB%M\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%S\fR\fR +.ad +.RS 6n +.rt +Seconds [00,60]; the range of values is [00,60] rather than [00,59] to allow +for the occasional leap second. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%t\fR\fR +.ad +.RS 6n +.rt +Insert a TAB. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%T\fR\fR +.ad +.RS 6n +.rt +Time as \fB%H\fR:\fB%M\fR:\fB%S\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%u\fR\fR +.ad +.RS 6n +.rt +Weekday as a decimal number [1,7], with 1 representing Monday. See \fBNOTES\fR +below. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%U\fR\fR +.ad +.RS 6n +.rt +Week number of year as a decimal number [00,53], with Sunday as the first day +of week 1. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%V\fR\fR +.ad +.RS 6n +.rt +The ISO 8601 week number as a decimal number [01,53]. In the ISO 8601 +week-based system, weeks begin on a Monday and week 1 of the year is the week +that includes both January 4th and the first Thursday of 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. See \fBNOTES\fR below. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%w\fR\fR +.ad +.RS 6n +.rt +Weekday as a decimal number [0,6], with 0 representing Sunday. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%W\fR\fR +.ad +.RS 6n +.rt +Week number of year as a decimal number [00,53], with Monday as the first day +of week 1. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%x\fR\fR +.ad +.RS 6n +.rt +Locale's appropriate date representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%X\fR\fR +.ad +.RS 6n +.rt +Locale's appropriate time representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%y\fR\fR +.ad +.RS 6n +.rt +Year within century [00,99]. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Y\fR\fR +.ad +.RS 6n +.rt +Year, including the century (for example 1993). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%z\fR\fR +.ad +.RS 6n +.rt +Replaced by offset from UTC in ISO 8601:2000 standard format (\fB+hhmm\fR or +\fB-hhmm\fR), or by no characters if no time zone is determinable. For example, +"-0430" means 4 hours 30 minutes behind UTC (west of Greenwich). If +\fBtm_isdst\fR is zero, the standard time offset is used. If \fBtm_isdst\fR is +greater than zero, the daylight savings time offset if used. If \fBtm_isdst\fR +is negative, no characters are returned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Z\fR\fR +.ad +.RS 6n +.rt +Time zone name or abbreviation, or no bytes if no time zone information exists. +.RE + +.sp +.LP +If a conversion specification does not correspond to any of the above or to any +of the modified conversion specifications listed below, the behavior is +undefined and \fB0\fR is returned. +.sp +.LP +The difference between \fB%U\fR and \fB%W\fR (and also between modified +conversion specifications \fB%OU\fR and \fB%OW\fR) lies in which day is counted +as the first of the week. Week number 1 is the first week in January starting +with a Sunday for \fB%U\fR or a Monday for \fB%W\fR. Week number 0 contains +those days before the first Sunday or Monday in January for \fB%U\fR and +\fB%W\fR, respectively. +.SS "Modified Conversion Specifications" +.sp +.LP +Some conversion specifications can be modified by the \fBE\fR and \fBO\fR +modifiers to indicate that an alternate format or specification should be used +rather than the one normally used by the unmodified conversion specification. +If the alternate format or specification does not exist in the current locale, +the behavior will be as if the unmodified specification were used. +.sp +.ne 2 +.mk +.na +\fB\fB%Ec\fR\fR +.ad +.RS 7n +.rt +Locale's alternate appropriate date and time representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%EC\fR\fR +.ad +.RS 7n +.rt +Name of the base year (period) in the locale's alternate representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Eg\fR\fR +.ad +.RS 7n +.rt +Offset from \fB%EC\fR of the week-based year in the locale's alternative +representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%EG\fR\fR +.ad +.RS 7n +.rt +Full alternative representation of the week-based year. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Ex\fR\fR +.ad +.RS 7n +.rt +Locale's alternate date representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%EX\fR\fR +.ad +.RS 7n +.rt +Locale's alternate time representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Ey\fR\fR +.ad +.RS 7n +.rt +Offset from \fB%EC\fR (year only) in the locale's alternate representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%EY\fR\fR +.ad +.RS 7n +.rt +Full alternate year representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Od\fR\fR +.ad +.RS 7n +.rt +Day of the month using the locale's alternate numeric symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Oe\fR\fR +.ad +.RS 7n +.rt +Same as \fB%Od\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Og\fR\fR +.ad +.RS 7n +.rt +Week-based year (offset from \fB%C\fR) in the locale's alternate representation +and using the locale's alternate numeric symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%OH\fR\fR +.ad +.RS 7n +.rt +Hour (24-hour clock) using the locale's alternate numeric symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%OI\fR\fR +.ad +.RS 7n +.rt +Hour (12-hour clock) using the locale's alternate numeric symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Om\fR\fR +.ad +.RS 7n +.rt +Month using the locale's alternate numeric symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%OM\fR\fR +.ad +.RS 7n +.rt +Minutes using the locale's alternate numeric symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%OS\fR\fR +.ad +.RS 7n +.rt +Seconds using the locale's alternate numeric symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Ou\fR\fR +.ad +.RS 7n +.rt +Weekday as a number in the locale's alternate numeric symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%OU\fR\fR +.ad +.RS 7n +.rt +Week number of the year (Sunday as the first day of the week) using the +locale's alternate numeric symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Ow\fR\fR +.ad +.RS 7n +.rt +Number of the weekday (Sunday=0) using the locale's alternate numeric symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%OW\fR\fR +.ad +.RS 7n +.rt +Week number of the year (Monday as the first day of the week) using the +locale's alternate numeric symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Oy\fR\fR +.ad +.RS 7n +.rt +Year (offset from \fB%C\fR) in the locale's alternate representation and using +the locale's alternate numeric symbols. +.RE + +.SS "Selecting the Output Language" +.sp +.LP +By default, the output of \fBstrftime()\fR, \fBcftime()\fR, and +\fBascftime()\fR appear in U.S. English. The user can request that the output +of \fBstrftime()\fR, \fBcftime()\fR, or \fBascftime()\fR be in a specific +language by setting the \fBLC_TIME\fR category using \fBsetlocale()\fR. +.SS "Time Zone" +.sp +.LP +Local time zone information is used as though \fBtzset\fR(3C) were called. +.SH RETURN VALUES +.sp +.LP +The \fBstrftime()\fR, \fBcftime()\fR, and \fBascftime()\fR functions return the +number of characters placed into the array pointed to by \fIs\fR, not including +the terminating null character. If the total number of resulting characters +including the terminating null character is more than \fImaxsize\fR, +\fBstrftime()\fR returns \fB0\fR and the contents of the array are +indeterminate. +.SH EXAMPLES +.LP +\fBExample 1 \fRAn example of the \fBstrftime()\fR function. +.sp +.LP +The following example illustrates the use of \fBstrftime()\fR for the +\fBPOSIX\fR locale. It shows what the string in \fIstr\fR would look like if +the structure pointed to by \fItmptr\fR contains the values corresponding to +Thursday, August 28, 1986 at 12:44:36. + +.sp +.in +2 +.nf +\fBstrftime (str, strsize, "%A %b %d %j", tmptr)\fR +.fi +.in -2 + +.sp +.LP +This results in \fIstr\fR containing "Thursday Aug 28 240". + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +CSIEnabled +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee below. +.TE + +.sp +.LP +For \fBstrftime()\fR, see \fBstandards\fR(5). +.SH SEE ALSO +.sp +.LP +\fBdate\fR(1), \fBctime\fR(3C), \fBmktime\fR(3C), \fBsetlocale\fR(3C), +\fBstrptime\fR(3C), \fBtzset\fR(3C), \fBTIMEZONE\fR(4), \fBzoneinfo\fR(4), +\fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +The conversion specification for \fB%V\fR was changed in the Solaris 7 release. +This change was based on the public review draft of the ISO C9x standard at +that time. Previously, the specification stated that if the week containing 1 +January had fewer than four days in the new year, it became week 53 of the +previous year. The ISO C9x standard committee subsequently recognized that that +specification had been incorrect. +.sp +.LP +The conversion specifications for \fB%g\fR, \fB%G\fR, \fB%Eg\fR, \fB%EG\fR, and +\fB%Og\fR were added in the Solaris 7 release. This change was based on the +public review draft of the ISO C9x standard at that time. These specifications +are evolving. If the ISO C9x standard is finalized with a different +conclusion, these specifications will change to conform to the ISO C9x standard +decision. +.sp +.LP +The conversion specification for \fB%u\fR was changed in the Solaris 8 release. +This change was based on the XPG4 specification. +.sp +.LP +If using the \fB%Z\fR specifier and \fBzoneinfo\fR timezones and if the input +date is outside the range 20:45:52 UTC, December 13, 1901 to 03:14:07 UTC, +January 19, 2038, the timezone name may not be correct. diff --git a/usr/src/man/man3c/string.3c b/usr/src/man/man3c/string.3c new file mode 100644 index 0000000000..f8717aa694 --- /dev/null +++ b/usr/src/man/man3c/string.3c @@ -0,0 +1,570 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1994 Man-cgi 1.15, Panagiotis Christias (christia@softlab.ntua.gr) +.\" Portions Copyright (c) 1996-2008 Modified for NetBSD by Kimmo Suominen (kimmo@suominen.com) +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH string 3C "1 Aug 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +string, strcasecmp, strncasecmp, strcat, strncat, strlcat, strchr, strrchr, +strcmp, strncmp, strcpy, strncpy, strlcpy, strcspn, strspn, strdup, strlen, +strnlen, strpbrk, strsep, strstr, strtok, strtok_r \- string operations +.SH SYNOPSIS +.LP +.nf +#include <strings.h> + +\fBint\fR \fBstrcasecmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR); +.fi + +.LP +.nf +\fBint\fR \fBstrncasecmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +#include <string.h> + +\fBchar *\fR\fBstrcat\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBstrncat\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR, \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +\fBsize_t\fR \fBstrlcat\fR(\fBchar *\fR\fIdst\fR, \fBconst char *\fR\fIsrc\fR, \fBsize_t\fR \fIdstsize\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBstrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBstrrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR); +.fi + +.LP +.nf +\fBint\fR \fBstrcmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR); +.fi + +.LP +.nf +\fBint\fR \fBstrncmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBstrcpy\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBstrncpy\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR, \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +\fBsize_t\fR \fBstrlcpy\fR(\fBchar *\fR\fIdst\fR, \fBconst char *\fR\fIsrc\fR, \fBsize_t\fR \fIdstsize\fR); +.fi + +.LP +.nf +\fBsize_t\fR \fBstrcspn\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR); +.fi + +.LP +.nf +\fBsize_t\fR \fBstrspn\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBstrdup\fR(\fBconst char *\fR\fIs1\fR); +.fi + +.LP +.nf +\fBsize_t\fR \fBstrlen\fR(\fBconst char *\fR\fIs\fR); +.fi + +.LP +.nf +\fBsize_t\fR \fBstrnlen\fR(\fBconst char *\fR\fIs\fR, \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBstrpbrk\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBstrsep\fR(\fBchar **\fR\fIstringp\fR, \fBconst char *\fR\fIdelim\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBstrstr\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBstrtok\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBstrtok_r\fR(\fBchar *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBchar **\fR\fIlasts\fR); +.fi + +.SS "ISO C++" +.LP +.nf +#include <string.h> + +\fBconst char *\fR\fBstrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR); +.fi + +.LP +.nf +\fBconst char *\fR\fBstrpbrk\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR); +.fi + +.LP +.nf +\fBconst char *\fR\fBstrrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR); +.fi + +.LP +.nf +\fBconst char *\fR\fBstrstr\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR); +.fi + +.LP +.nf +#include <cstring> + +\fBchar *std::\fR\fBstrchr\fR(\fBchar *\fR\fIs\fR, \fBint\fR \fIc\fR); +.fi + +.LP +.nf +\fBchar *std::\fR\fBstrpbrk\fR(\fBchar *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR); +.fi + +.LP +.nf +\fBchar *std::\fR\fBstrrchr\fR(\fBchar *\fR\fIs\fR, \fBint\fR \fIc\fR); +.fi + +.LP +.nf +\fBchar *std::\fR\fBstrstr\fR(\fBchar *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The arguments \fIs\fR, \fIs1\fR, and \fIs2\fR point to strings (arrays of +characters terminated by a null character). The \fBstrcat()\fR, +\fBstrncat()\fR, \fBstrlcat()\fR, \fBstrcpy()\fR, \fBstrncpy()\fR, +\fBstrlcpy()\fR, \fBstrsep()\fR, \fBstrtok()\fR, and \fBstrtok_r()\fR functions +all alter their first argument. Additionally, the \fBstrcat()\fR and +\fBstrcpy()\fR functions do not check for overflow of the array. +.SS "\fBstrcasecmp()\fR, \fBstrncasecmp()\fR" +.sp +.LP +The \fBstrcasecmp()\fR and \fBstrncasecmp()\fR functions are case-insensitive +versions of \fBstrcmp()\fR and \fBstrncmp()\fR respectively, described below. +They assume the \fBASCII\fR character set and ignore differences in case when +comparing lower and upper case characters. +.SS "\fBstrcat()\fR, \fBstrncat()\fR, \fBstrlcat()\fR" +.sp +.LP +The \fBstrcat()\fR function appends a copy of string \fIs2\fR, including the +terminating null character, to the end of string \fIs1\fR. The \fBstrncat()\fR +function appends at most \fIn\fR characters. Each returns a pointer to the +null-terminated result. The initial character of \fIs2\fR overrides the null +character at the end of \fIs1\fR. If copying takes place between objects that +overlap, the behavior of \fBstrcat()\fR, \fBstrncat()\fR, and \fBstrlcat()\fR +is undefined. +.sp +.LP +The \fBstrlcat()\fR function appends at most +(\fIdstsize\fR-\fBstrlen\fR(\fIdst\fR)-1) characters of \fIsrc\fR to \fIdst\fR +(\fIdstsize\fR being the size of the string buffer \fIdst\fR). If the string +pointed to by \fIdst\fR contains a null-terminated string that fits into +\fIdstsize\fR bytes when \fBstrlcat()\fR is called, the string pointed to by +\fIdst\fR will be a null-terminated string that fits in \fIdstsize\fR bytes +(including the terminating null character) when it completes, and the initial +character of \fIsrc\fR will override the null character at the end of +\fIdst\fR. If the string pointed to by \fIdst\fR is longer than \fIdstsize\fR +bytes when \fBstrlcat()\fR is called, the string pointed to by \fIdst\fR will +not be changed. The function returns +\fBmin\fR{\fIdstsize\fR,\fBstrlen\fR(\fIdst\fR)}+\fBstrlen\fR(\fIsrc\fR). +Buffer overflow can be checked as follows: +.sp +.in +2 +.nf +if (strlcat(dst, src, dstsize) >= dstsize) + return \(mi1; +.fi +.in -2 + +.SS "\fBstrchr()\fR, \fBstrrchr()\fR" +.sp +.LP +The \fBstrchr()\fR function returns a pointer to the first occurrence of +\fIc\fR (converted to a \fBchar\fR) in string \fIs\fR, or a null pointer if +\fIc\fR does not occur in the string. The \fBstrrchr()\fR function returns a +pointer to the last occurrence of \fIc\fR. The null character terminating a +string is considered to be part of the string. +.SS "\fBstrcmp()\fR, \fBstrncmp()\fR" +.sp +.LP +The \fBstrcmp()\fR function compares two strings byte-by-byte, according to the +ordering of your machine's character set. The function returns an integer +greater than, equal to, or less than 0, if the string pointed to by \fIs1\fR +is greater than, equal to, or less than the string pointed to by \fIs2\fR +respectively. 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 that differ in the +strings being compared. The \fBstrncmp()\fR function makes the same comparison +but looks at a maximum of \fIn\fR bytes. Bytes following a null byte are not +compared. +.SS "\fBstrcpy()\fR, \fBstrncpy()\fR, \fBstrlcpy()\fR" +.sp +.LP +The \fBstrcpy()\fR function copies string \fIs2\fR to \fIs1\fR, including the +terminating null character, stopping after the null character has been copied. +The \fBstrncpy()\fR function copies exactly \fIn\fR bytes, truncating \fIs2\fR +or adding null characters to \fIs1\fR if necessary. The result will not be +null-terminated if the length of \fIs2\fR is \fIn\fR or more. Each function +returns \fIs1\fR. If copying takes place between objects that overlap, the +behavior of \fBstrcpy()\fR, \fBstrncpy()\fR, and \fBstrlcpy()\fR is undefined. +.sp +.LP +The \fBstrlcpy()\fR function copies at most \fIdstsize\fR\(mi1 characters +(\fIdstsize\fR being the size of the string buffer \fIdst\fR) from \fIsrc\fR +to \fIdst\fR, truncating \fIsrc\fR if necessary. The result is always +null-terminated. The function returns \fBstrlen\fR(\fIsrc\fR). Buffer overflow +can be checked as follows: +.sp +.in +2 +.nf +if (strlcpy(dst, src, dstsize) >= dstsize) + return \(mi1; +.fi +.in -2 + +.SS "\fBstrcspn()\fR, \fBstrspn()\fR" +.sp +.LP +The \fBstrcspn()\fR function returns the length of the initial segment of +string \fIs1\fR that consists entirely of characters not from string \fIs2\fR. +The \fBstrspn()\fR function returns the length of the initial segment of string +\fIs1\fR that consists entirely of characters from string \fIs2\fR. +.SS "\fBstrdup()\fR" +.sp +.LP +The \fBstrdup()\fR function returns a pointer to a new string that is a +duplicate of the string pointed to by \fIs1\fR. The returned pointer can be +passed to \fBfree()\fR. The space for the new string is obtained using +\fBmalloc\fR(3C). If the new string cannot be created, a null pointer is +returned and \fBerrno\fR may be set to \fBENOMEM\fR to indicate that the +storage space available is insufficient. +.SS "\fBstrlen()\fR, \fBstrnlen()\fR" +.sp +.LP +The \fBstrlen()\fR function returns the number of bytes in \fIs\fR, not +including the terminating null character. +.sp +.LP +The \fBstrnlen()\fR function returns the smaller of \fIn\fR or the number of +bytes in \fIs\fR, not including the terminating null character. The +\fBstrnlen()\fR function never examines more than \fIn\fR bytes of the string +pointed to by \fIs\fR. +.SS "\fBstrpbrk()\fR" +.sp +.LP +The \fBstrpbrk()\fR function returns a pointer to the first occurrence in +string \fIs1\fR of any character from string \fIs2\fR, or a null pointer if no +character from \fIs2\fR exists in \fIs1\fR. +.SS "\fBstrsep()\fR" +.sp +.LP +The \fBstrsep()\fR function locates, in the null-terminated string referenced +by *\fIstringp\fR, the first occurrence of any character in the string +\fIdelim\fR (or the terminating `\e0' character) and replaces it with a `\e0'. +The location of the next character after the delimiter character (or +\fINULL\fR, if the end of the string was reached) is stored in *\fIstringp\fR. +The original value of *\fIstringp\fR is returned. +.sp +.LP +An ``empty'' field (one caused by two adjacent delimiter characters) can be +detected by comparing the location referenced by the pointer returned by +\fBstrsep()\fR to `\e0'. +.sp +.LP +If *\fIstringp\fR is initially \fINULL\fR, \fBstrsep()\fR returns \fINULL\fR. +.SS "\fBstrstr()\fR" +.sp +.LP +The \fBstrstr()\fR function locates the first occurrence of the string \fIs2\fR +(excluding the terminating null character) in string \fIs1\fR and returns a +pointer to the located string, or a null pointer if the string is not found. If +\fIs2\fR points to a string with zero length (that is, the string \fB""\fR), +the function returns \fIs1\fR. +.SS "\fBstrtok()\fR" +.sp +.LP +A sequence of calls to \fBstrtok()\fR breaks the string pointed to by \fIs1\fR +into a sequence of tokens, each of which is delimited by a byte from the string +pointed to by \fIs2\fR. The first call in the sequence has \fIs1\fR as its +first argument, and is followed by calls with a null pointer as their first +argument. The separator string pointed to by \fIs2\fR can be different from +call to call. +.sp +.LP +The first call in the sequence searches the string pointed to by \fIs1\fR for +the first byte that is not contained in the current separator string pointed to +by \fIs2\fR. If no such byte is found, then there are no tokens in the string +pointed to by \fIs1\fR and \fBstrtok()\fR returns a null pointer. If such a +byte is found, it is the start of the first token. +.sp +.LP +The \fBstrtok()\fR function then searches from there for a byte that 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 \fIs1\fR, and +subsequent searches for a token return a null pointer. If such a byte is found, +it is overwritten by a null byte that terminates the current token. The +\fBstrtok()\fR function saves a pointer to the following byte in +thread-specific data, from which the next search for a token starts. +.sp +.LP +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. +.sp +.LP +See Example 1, 2, and 3 in the \fBEXAMPLES\fR section for examples of +\fBstrtok()\fR usage and the explanation in \fBNOTES\fR. +.SS "\fBstrtok_r()\fR" +.sp +.LP +The \fBstrtok_r()\fR function considers the null-terminated string \fIs1\fR as +a sequence of zero or more text tokens separated by spans of one or more +characters from the separator string \fIs2\fR. The argument \fIlasts\fR points +to a user-provided pointer which points to stored information necessary for +\fBstrtok_r()\fR to continue scanning the same string. +.sp +.LP +In the first call to \fBstrtok_r()\fR, \fIs1\fR points to a null-terminated +string, \fIs2\fR to a null-terminated string of separator characters, and the +value pointed to by \fIlasts\fR is ignored. The \fBstrtok_r()\fR function +returns a pointer to the first character of the first token, writes a null +character into \fIs1\fR immediately following the returned token, and updates +the pointer to which \fIlasts\fR points. +.sp +.LP +In subsequent calls, \fIs1\fR is a null pointer and \fIlasts\fR is unchanged +from the previous call so that subsequent calls move through the string +\fIs1\fR, returning successive tokens until no tokens remain. The separator +string \fIs2\fR can be different from call to call. When no token remains in +\fIs1\fR, a null pointer is returned. +.sp +.LP +See Example 3 in the \fBEXAMPLES\fR section for an example of \fBstrtok_r()\fR +usage and the explanation in \fBNOTES\fR. +.SH EXAMPLES +.LP +\fBExample 1 \fRSearch for word separators. +.sp +.LP +The following example searches for tokens separated by space characters. + +.sp +.in +2 +.nf +#include <string.h> +\&... +char *token; +char line[] = "LINE TO BE SEPARATED"; +char *search = " "; + +/* Token will point to "LINE". */ +token = strtok(line, search); + +/* Token will point to "TO". */ +token = strtok(NULL, search); +.fi +.in -2 + +.LP +\fBExample 2 \fRBreak a Line. +.sp +.LP +The following example uses strtok to break a line into two character strings +separated by any combination of SPACEs, TABs, or NEWLINEs. + +.sp +.in +2 +.nf +#include <string.h> +\&... +struct element { + char *key; + char *data; +}; +\&... +char line[LINE_MAX]; +char *key, *data; +\&... +key = strtok(line, " \en"); +data = strtok(NULL, " \en"); +.fi +.in -2 + +.LP +\fBExample 3 \fRSearch for tokens. +.sp +.LP +The following example uses both \fBstrtok()\fR and \fBstrtok_r()\fR to search +for tokens separated by one or more characters from the string pointed to by +the second argument, "/". + +.sp +.in +2 +.nf +#define __EXTENSIONS__ +#include <stdio.h> +#include <string.h> + +int +main() { + char *buf="5/90/45"; + char *token; + char *lasts; + + printf("tokenizing \e"%s\e" with strtok():\en", buf); + if ((token = strtok(buf, "/")) != NULL) { + printf("token = "%s\e"\en", token); + while ((token = strtok(NULL, "/")) != NULL) { + printf("token = \e"%s\e"\en", token); + } + } + + buf = "//5//90//45//"; + printf("\entokenizing \e"%s\e" with strtok_r():\en", buf); + if ((token = strtok_r(buf, "/", &lasts)) != NULL) { + printf("token = \e"%s\e"\en", token); + while ((token = strtok_r(NULL, "/", &lasts)) != NULL) { + printf("token = \e"%s\e"\en", token); + } + } +} +.fi +.in -2 + +.sp +.LP +When compiled and run, this example produces the following output: + +.sp +.in +2 +.nf +tokenizing "5/90/45" with \fBstrtok()\fR: +token = "5" +token = "90" +token = "45" + +tokenizing "//5//90//45//" with \fBstrtok_r()\fR: +token = "5" +token = "90" +token = "45" +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelSee below. +_ +StandardSee below. +.TE + +.sp +.LP +The \fBstrtok()\fR and \fBstrdup()\fR functions are MT-Safe. The remaining +functions are Async-Signal-Safe. +.sp +.LP +For all except \fBstrlcat()\fR, \fBstrlcpy()\fR, and \fBstrsep()\fR, see +\fBstandards\fR(5). +.SH SEE ALSO +.sp +.LP +\fBmalloc\fR(3C), \fBsetlocale\fR(3C), \fBstrxfrm\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) +.SH NOTES +.sp +.LP +When compiling multithreaded applications, the \fB_REENTRANT\fR flag must be +defined on the compile line. This flag should only be used in multithreaded +applications. +.sp +.LP +A single-threaded application can gain access to \fBstrtok_r()\fR only by +defining \fB__EXTENSIONS__\fR or by defining \fB_POSIX_C_SOURCE\fR to a value +greater than or equal to 199506L. +.sp +.LP +All of these functions assume the default locale ``C.'' For some locales, +\fBstrxfrm\fR(3C) should be applied to the strings before they are passed to +the functions. +.sp +.LP +The \fBstrtok()\fR function is safe to use in multithreaded applications +because it saves its internal state in a thread-specific data area. However, +its use is discouraged, even for single-threaded applications. The +\fBstrtok_r()\fR function should be used instead. +.sp +.LP +Do not pass the address of a character string literal as the argument \fIs1\fR +to either \fBstrtok()\fR or \fBstrtok_r()\fR. Similarly, do not pass a pointer +to the address of a character string literal as the argument \fIstringp\fR to +\fBstrsep()\fR. These functions can modify the storage pointed to by \fIs1\fR +in the case of \fBstrtok()\fR and \fBstrtok_r()\fR or *\fIstringp\fR in the +case of \fBstrsep()\fR. The C99 standard specifies that attempting to modify +the storage occupied by a string literal results in undefined behavior. This +allows compilers (including \fBgcc\fR and the Sun Studio compilers when the +\fB-xstrconst\fR flag is used) to place string literals in read-only memory. +Note that in Example 1 above, this problem is avoided because the variable +\fIline\fR is declared as a writable array of type \fBchar\fR that is +initialized by a string literal rather than a pointer to \fBchar\fR that points +to a string literal. diff --git a/usr/src/man/man3c/string_to_decimal.3c b/usr/src/man/man3c/string_to_decimal.3c new file mode 100644 index 0000000000..75b606823d --- /dev/null +++ b/usr/src/man/man3c/string_to_decimal.3c @@ -0,0 +1,291 @@ +'\" te +.\" Copyright (c) 2003. Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH string_to_decimal 3C "1 Oct 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +string_to_decimal, file_to_decimal, func_to_decimal \- parse characters into +decimal record +.SH SYNOPSIS +.LP +.nf +#include <floatingpoint.h> + +\fBvoid\fR \fBstring_to_decimal\fR(\fBchar **\fR\fIpc\fR, \fBint\fR \fInmax\fR, + \fBint\fR \fIfortran_conventions\fR, \fBdecimal_record *\fR\fIpd\fR, + \fBenum decimal_string_form *\fR\fIpform\fR, \fBchar **\fR\fIpechar\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBfunc_to_decimal\fR(\fBchar **\fR\fIpc\fR, \fBint\fR \fInmax\fR, + \fBint\fR \fIfortran_conventions\fR, \fBdecimal_record *\fR\fIpd\fR, + \fBenum decimal_string_form *\fR\fIpform\fR, \fBchar **\fR\fIpechar\fR, + \fBint (*\fR\fIpget\fR)(void), \fBint *\fR\fIpnread\fR, \fBint (*\fR\fIpunget\fR)(int \fIc\fR)); +.fi + +.LP +.nf +#include <stdio.h> + +\fBvoid\fR \fBfile_to_decimal\fR(\fBchar **\fR\fIpc\fR, \fBint\fR \fInmax\fR, + \fBint\fR \fIfortran_conventions\fR, \fBdecimal_record *\fR\fIpd\fR, + \fBenum decimal_string_form *\fR\fIpform\fR, \fBchar **\fR\fIpechar\fR, + \fBFILE *\fR\fIpf\fR, \fBint *\fR\fIpnread\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions attempt to parse a numeric token from at most \fInmax\fR +characters read from a string **\fIpc\fR, a file *\fIpf\fR, or function +(*\fIpget\fR). They set the decimal record *\fIpd\fR to reflect the value of +the numeric token recognized and set *\fIpform\fR and *\fIpechar\fR to indicate +its form. +.sp +.LP +The accepted forms for the numeric token consist of an initial, possibly empty, +sequence of white-space characters, as defined by \fBisspace\fR(3C), followed +by a subject sequence representing a numeric value, infinity, or NaN. The +subject sequence consists of an optional plus or minus sign followed by one of +the following: +.RS +4 +.TP +.ie t \(bu +.el o +a non-empty sequence of decimal digits optionally containing a decimal point +character, then an optional exponent part +.RE +.RS +4 +.TP +.ie t \(bu +.el o +one of INF or INFINITY, ignoring case +.RE +.RS +4 +.TP +.ie t \(bu +.el o +one of NAN or NAN(\fIstring\fR), ignoring case in the NAN part; \fIstring\fR +can be any sequence of characters not containing ')' (right parenthesis) +or '\e0' (null). +.RE +.sp +.LP +The \fIfortran_conventions\fR argument provides additional control over the set +of accepted forms. It must be one of the following values: +.sp +.ne 2 +.mk +.na +\fB0\fR +.ad +.RS 5n +.rt +no Fortran conventions +.RE + +.sp +.ne 2 +.mk +.na +\fB1\fR +.ad +.RS 5n +.rt +Fortran list-directed input conventions +.RE + +.sp +.ne 2 +.mk +.na +\fB2\fR +.ad +.RS 5n +.rt +Fortran formatted input conventions, blanks are ignored +.RE + +.sp +.ne 2 +.mk +.na +\fB3\fR +.ad +.RS 5n +.rt +Fortran formatted input conventions, blanks are interpreted as zeroes +.RE + +.sp +.LP +When \fIfortran_conventions\fR is zero, the decimal point character is the +current locale's decimal point character, and the exponent part consists of the +letter \fBE\fR or \fBe\fR followed by an optional sign and a non-empty string +of decimal digits. +.sp +.LP +When \fIfortran_conventions\fR is non-zero, the decimal point character is "." +(period), and the exponent part consists of either a sign or one of the letters +\fBE\fR, \fBe\fR, \fBD\fR, \fBd\fR, \fBQ\fR, or \fBq\fR followed by an optional +sign, then a non-empty string of decimal digits. +.sp +.LP +When \fIfortran_conventions\fR is \fB2\fR or \fB3\fR, blanks can appear in the +digit strings for the integer, fraction, and exponent parts, between the +exponent delimiter and optional exponent sign, and after an INF, INFINITY, NAN, +or NAN(\fIstring\fR). When \fIfortran_conventions\fR is \fB2\fR, all blanks +are ignored. When \fIfortran_conventions\fR is \fB3\fR, blanks in digit +strings are interpreted as zeros and other blanks are ignored. +.sp +.LP +The following table summarizes the accepted forms and shows the corresponding +values to which *\fIpform\fR and \fIpd\fR->\fBfpclass\fR are set. Here +\fIdigits\fR represents any string of decimal digits, "." (period) stands for +the decimal point character, and \fIexponent\fR represents the exponent part as +defined above. Numbers in brackets refer to the notes following the table. +.sp + +.sp +.TS +tab(); +cw(1.63i) cw(2.02i) cw(1.85i) +lw(1.63i) lw(2.02i) lw(1.85i) +. +form*\fIpform\fRpd->\fBfpclass\fR +_ +all white space [1]\fBwhitespace_form\fR\fBfp_zero\fR +\fIdigits\fR\fBfixed_int_form\fR\fBfp_normal\fR [2] +\fIdigits\fR.\fBfixed_intdot_form\fR\fBfp_normal\fR [2] +\&.\fIdigits\fR\fBfixed_dotfrac_form\fR\fBfp_normal\fR [2] +\fIdigits\fR.\fIdigits\fR\fBfixed_intdotfrac_form\fR\fBfp_normal\fR [2] +\fIdigits\fR \fIexponent\fR\fBfloating_int_form\fR\fBfp_normal\fR [2] +\fIdigits\fR. \fIexponent\fR\fBfloating_intdot_form\fR\fBfp_normal\fR [2] +\&.digits \fIexponent\fR\fBfloating_dotfrac_form\fR\fBfp_normal\fR [2] +\fIdigits\fR.\fIdigits\fR \fIexponent\fR\fBfloating_intdotfrac_form\fR\fBfp_normal\fR [2] +INF\fBinf_form\fR\fBfp_infinity\fR +INFINITY\fBinfinity_form\fR\fBfp_infinity\fR +NAN\fBnan_form\fR\fBfp_quiet\fR +NAN(\fIstring\fR)\fBnanstring_form\fR\fBfp_quiet\fR +none of the above\fBinvalid_form\fR\fBfp_signaling\fR +.TE + +.sp +.LP +Notes: +.RS +4 +.TP +1. +The \fBwhitespace_form\fR is accepted only when \fIfortran_conventions\fR is +2 or 3 and is interpreted as zero. +.RE +.RS +4 +.TP +2. +For all numeric forms, \fIpd\fR->\fBfpclass\fR is set to \fBfp_normal\fR if +any non-zero digits appear in the integer or fraction parts, and otherwise +\fIpd\fR->\fBfpclass\fR is set to \fBfp_zero\fR. +.RE +.sp +.LP +If the accepted token has one of the numeric forms and represents a non-zero +number \fIx\fR, its significant digits are stored in \fIpd\fR->\fBds\fR. +Leading and trailing zeroes and the radix point are omitted. +\fIpd\fR->\fBsign\fR and \fIpd\fR->\fBexponent\fR are set so that if \fIm\fR is +the integer represented by pd->\fBds\fR, +.sp +.in +2 +.nf +\(mi1**(pd->sign) * m * 10**(pd->exponent) +.fi +.in -2 + +.sp +.LP +approximates \fIx\fR to at least 511 significant digits. \fIpd\fR->\fBmore\fR +is set to 1 if this approximation is not exact (that is, the accepted token +contains additional non-zero digits beyond those copied to \fIpd\fR->\fBds\fR) +and to 0 otherwise. +.sp +.LP +If the accepted token has the NAN(\fIstring\fR) form, up to 511 characters from +the string part are copied to \fIpd\fR->\fBds\fR. +.sp +.LP +\fIpd\fR->\fBds\fR is always terminated by a null byte, and +\fIpd\fR->\fBndigits\fR is set to the length of the string stored in +\fIpd\fR->\fBds\fR. +.sp +.LP +On entry, *\fIpc\fR points to the beginning of a character string buffer. The +\fBstring_to_decimal()\fR function reads characters from this buffer until +either enough characters are read to delimit the accepted token (for example, a +null character marking the end of the string is found) or the limit of +\fInmax\fR characters is reached. The \fBfile_to_decimal()\fR function reads +characters from the file *\fIpf\fR and stores them in the buffer. The +\fBfunc_to_decimal()\fR function reads characters one at a time by calling the +function (*\fIpget\fR)() and stores them in the buffer; (*\fIpget\fR)() must +return integer values in the range \(mi1 to 255, where \(mi1 is interpreted as +EOF and 0, ..., 255 are interpreted as \fBunsigned char\fR values. Both +\fBfile_to_decimal()\fR and \fBfunc_to_decimal()\fR read characters until +either enough characters are read to delimit the accepted token, EOF is +encountered, or the limit of \fInmax\fR characters is reached. These functions, +therefore, typically read one or more additional characters beyond the end of +the accepted token and attempt to push back any excess characters read. +Provided that the \fIpunget\fR argument is not \fINULL\fR, +\fBfunc_to_decimal()\fR pushes back characters one at a time by calling +(*\fIpunget\fR)(\fIc\fR), where \fIc\fR is an integer in the range 0 to 255 +corresponding to a value previously read via (*\fIpget\fR)(). After pushing +back as many excess characters as possible, \fBfile_to_decimal()\fR and +\fBfunc_to_decimal()\fR store a null byte in the buffer following the last +character read and not pushed back and set *\fIpnread\fR to the number of +characters stored in the buffer prior to this null byte. Since these functions +can read up to \fInmax\fR characters, the buffer must be large enough to hold +\fInmax\fR + 1. +.sp +.LP +On exit, *\fIpc\fR points to the next character in the buffer past the last one +that was accepted as part of the numeric token. If no valid token is found, +*\fIpc\fR is unchanged. If \fBfile_to_decimal()\fR and \fBfunc_to_decimal()\fR +successfully push back all unused characters, *\fIpc\fR points to the null byte +stored in the buffer following the last character read and not pushed back. +.sp +.LP +If the accepted token contains an exponent part, *\fIpechar\fR is set to point +to the position in the buffer where the first character of the exponent field +is stored. If the accepted token does not contain an exponent part, +*\fIpechar\fR is set to \fINULL\fR. +.SH USAGE +.sp +.LP +If the \fB_IOWRT\fR flag is set in *\fIpf\fR, \fBfile_to_decimal()\fR reads +characters directly from the file buffer until a null character is found. (The +\fB_IOWRT\fR flag should only be set when \fBfile_to_decimal()\fR is called +from \fBsscanf\fR(3C).) Otherwise, \fBfile_to_decimal()\fR uses +\fBgetc_unlocked\fR(3C), so it is not MT-safe unless the caller holds the +stream lock. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBctype\fR(3C), \fBdecimal_to_floating\fR(3C), \fBgetc_unlocked\fR(3C), +\fBisspace\fR(3C), \fBlocaleconv\fR(3C), \fBscanf\fR(3C), \fBsetlocale\fR(3C), +\fBstrtod\fR(3C), \fBungetc\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/strptime.3c b/usr/src/man/man3c/strptime.3c new file mode 100644 index 0000000000..5b7c68d777 --- /dev/null +++ b/usr/src/man/man3c/strptime.3c @@ -0,0 +1,803 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH strptime 3C "27 Aug 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +strptime \- date and time conversion +.SH SYNOPSIS +.LP +.nf +#include <time.h> + +\fBchar *\fR\fBstrptime\fR(\fBconst char *restrict\fR \fIbuf\fR, + \fBconst char *restrict\fR \fIformat\fR, \fBstruct tm *restrict\fR \fItm\fR); +.fi + +.SS "Non-zeroing Behavior" +.LP +.nf +\fBcc\fR [\fIflag\fR...] \fIfile\fR... \fB-D_STRPTIME_DONTZERO\fR [\fIlibrary\fR...] +#include <time.h> + +\fBchar *\fR\fBstrptime\fR(\fBconst char *restrict\fR \fIbuf\fR, + \fBconst char *restrict\fR \fIformat\fR, \fBstruct tm *restrict\fR \fItm\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBstrptime()\fR function converts the character string pointed to by +\fIbuf\fR to values which are stored in the \fBtm\fR structure pointed to by +\fItm\fR, using the format specified by \fIformat\fR. +.sp +.LP +The \fIformat\fR argument is composed of zero or more conversion +specifications. Each conversion specification is composed of a "%" (percent) +character followed by one or two conversion characters which specify the +replacement required. One or more white space characters (as specified by +\fBisspace\fR(3C)) may precede or follow a conversion specification. There must +be white-space or other non-alphanumeric characters between any two conversion +specifications. +.sp +.LP +A non-zeroing version of \fBstrptime()\fR, described below under \fBNon-zeroing +Behavior\fR, is provided if \fB_STRPTIME_DONTZERO\fR is defined. +.SS "Conversion Specifications" +.sp +.LP +The following conversion specifications are supported: +.sp +.ne 2 +.mk +.na +\fB\fB%%\fR\fR +.ad +.RS 6n +.rt +Same as \fB%\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%a\fR\fR +.ad +.RS 6n +.rt +Day of week, using the locale's weekday names; either the abbreviated or full +name may be specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%A\fR\fR +.ad +.RS 6n +.rt +Same as \fB%a\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%b\fR\fR +.ad +.RS 6n +.rt +Month, using the locale's month names; either the abbreviated or full name may +be specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%B\fR\fR +.ad +.RS 6n +.rt +Same as \fB%b\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%c\fR\fR +.ad +.RS 6n +.rt +Locale's appropriate date and time representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%C\fR\fR +.ad +.RS 6n +.rt +Century number (the year divided by 100 and truncated to an integer as a +decimal number [1,99]); single digits are preceded by 0. If \fB%C\fR is used +without the \fB%y\fR specifier, \fBstrptime()\fR assumes the year offset is +zero in whichever century is specified. Note the behavior of \fB%C\fR in the +absence of \fB%y\fR is not specified by any of the standards or specifications +described on the \fBstandards\fR(5) manual page, so portable applications +should not depend on it. This behavior may change in a future release. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%d\fR\fR +.ad +.RS 6n +.rt +Day of month [1,31]; leading zero is permitted but not required. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%D\fR\fR +.ad +.RS 6n +.rt +Date as \fB%m\fR/\fB%d\fR/\fB%y\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%e\fR\fR +.ad +.RS 6n +.rt +Same as \fB%d\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%h\fR\fR +.ad +.RS 6n +.rt +Same as \fB%b\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%H\fR\fR +.ad +.RS 6n +.rt +Hour (24-hour clock) [0,23]; leading zero is permitted but not required. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%I\fR\fR +.ad +.RS 6n +.rt +Hour (12-hour clock) [1,12]; leading zero is permitted but not required. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%j\fR\fR +.ad +.RS 6n +.rt +Day number of the year [1,366]; leading zeros are permitted but not required. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%m\fR\fR +.ad +.RS 6n +.rt +Month number [1,12]; leading zero is permitted but not required. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%M\fR\fR +.ad +.RS 6n +.rt +Minute [0-59]; leading zero is permitted but not required. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%n\fR\fR +.ad +.RS 6n +.rt +Any white space. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%p\fR\fR +.ad +.RS 6n +.rt +Locale's equivalent of either a.m. or p.m. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%r\fR\fR +.ad +.RS 6n +.rt +Appropriate time representation in the 12-hour clock format with \fB%p\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%R\fR\fR +.ad +.RS 6n +.rt +Time as \fB%H\fR:\fB%M\fR. +.RE + +.SS "SUSv3" +.sp +.ne 2 +.mk +.na +\fB\fB%S\fR\fR +.ad +.RS 6n +.rt +Seconds [0,60]; leading zero is permitted but not required. The range of values +is [00,60] rather than [00,59] to allow for the occasional leap second. +.RE + +.SS "Default and other standards" +.sp +.ne 2 +.mk +.na +\fB\fB%S\fR\fR +.ad +.RS 6n +.rt +Seconds [0,61]; leading zero is permitted but not required. The range of values +is [00,61] rather than [00,59] to allow for the occasional leap second and even +more occasional double leap second. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%t\fR\fR +.ad +.RS 6n +.rt +Any white space. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%T\fR\fR +.ad +.RS 6n +.rt +Time as \fB%H\fR:\fB%M\fR:\fB%S\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%U\fR\fR +.ad +.RS 6n +.rt +Week number of the year as a decimal number [0,53], with Sunday as the first +day of the week; leading zero is permitted but not required. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%w\fR\fR +.ad +.RS 6n +.rt +Weekday as a decimal number [0,6], with 0 representing Sunday. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%W\fR\fR +.ad +.RS 6n +.rt +Week number of the year as a decimal number [0,53], with Monday as the first +day of the week; leading zero is permitted but not required. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%x\fR\fR +.ad +.RS 6n +.rt +Locale's appropriate date representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%X\fR\fR +.ad +.RS 6n +.rt +Locale's appropriate time representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%y\fR\fR +.ad +.RS 6n +.rt +Year within century. When a century is not otherwise specified, values in the +range 69-99 refer to years in the twentieth century (1969 to 1999 inclusive); +values in the range 00-68 refer to years in the twenty-first century (2000 to +2068 inclusive). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Y\fR\fR +.ad +.RS 6n +.rt +Year, including the century (for example, 1993). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Z\fR\fR +.ad +.RS 6n +.rt +Time zone name or no characters if no time zone exists. +.RE + +.SS "Modified Conversion Specifications" +.sp +.LP +Some conversion specifications can be modified by the \fBE\fR and \fBO\fR +modifier characters to indicate that an alternate format or specification +should be used rather than the one normally used by the unmodified +specification. If the alternate format or specification does not exist in the +current locale, the behavior will be as if the unmodified conversion +specification were used. +.sp +.ne 2 +.mk +.na +\fB\fB%Ec\fR\fR +.ad +.RS 7n +.rt +Locale's alternate appropriate date and time representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%EC\fR\fR +.ad +.RS 7n +.rt +Name of the base year (era) in the locale's alternate representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Ex\fR\fR +.ad +.RS 7n +.rt +Locale's alternate date representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%EX\fR\fR +.ad +.RS 7n +.rt +Locale's alternate time representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Ey\fR\fR +.ad +.RS 7n +.rt +Offset from \fB%EC\fR (year only) in the locale's alternate representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%EY\fR\fR +.ad +.RS 7n +.rt +Full alternate year representation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Od\fR\fR +.ad +.RS 7n +.rt +Day of the month using the locale's alternate numeric symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Oe\fR\fR +.ad +.RS 7n +.rt +Same as \fB%Od\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%OH\fR\fR +.ad +.RS 7n +.rt +Hour (24-hour clock) using the locale's alternate numeric symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%OI\fR\fR +.ad +.RS 7n +.rt +Hour (12-hour clock) using the locale's alternate numeric symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Om\fR\fR +.ad +.RS 7n +.rt +Month using the locale's alternate numeric symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%OM\fR\fR +.ad +.RS 7n +.rt +Minutes using the locale's alternate numeric symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%OS\fR\fR +.ad +.RS 7n +.rt +Seconds using the locale's alternate numeric symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%OU\fR\fR +.ad +.RS 7n +.rt +Week number of the year (Sunday as the first day of the week) using the +locale's alternate numeric symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Ow\fR\fR +.ad +.RS 7n +.rt +Number of the weekday (Sunday=0) using the locale's alternate numeric symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%OW\fR\fR +.ad +.RS 7n +.rt +Week number of the year (Monday as the first day of the week) using the +locale's alternate numeric symbols. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%Oy\fR\fR +.ad +.RS 7n +.rt +Year (offset from \fB%C\fR) in the locale's alternate representation and using +the locale's alternate numeric symbols. +.RE + +.SS "General Specifications" +.sp +.LP +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 specification, the specification +fails, and the differing and subsequent characters remain unscanned. +.sp +.LP +A series of specifications composed of \fB%n\fR, \fB%t\fR, 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. White space is defined by \fBisspace\fR(3C). +.sp +.LP +Any other conversion specification is executed by scanning characters until a +character matching the next specification is scanned, or until no more +characters can be scanned. These characters, except the one matching the next +specification, are then compared to the locale values associated with the +conversion specifier. If a match is found, values for the appropriate +\fItm\fR structure members are set to values corresponding to the locale +information. If no match is found, \fBstrptime()\fR fails and no more +characters are scanned. +.sp +.LP +The month names, weekday names, era names, and alternate numeric symbols can +consist of any combination of upper and lower case letters. The user can +request that the input date or time specification be in a specific language by +setting the \fBLC_TIME\fR category using \fBsetlocale\fR(3C). +.SS "Non-zeroing Behavior" +.sp +.LP +In addition to the behavior described above by various standards, the Solaris +implementation of \fBstrptime()\fR provides the following extensions. These may +change at any time in the future. Portable applications should not depend on +these extended features: +.RS +4 +.TP +.ie t \(bu +.el o +If \fB_STRPTIME_DONTZERO\fR is not defined, the \fBtm struct\fR is zeroed on +entry and \fBstrptime()\fR updates the fields of the \fBtm struct\fR associated +with the specifiers in the format string. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If \fB_STRPTIME_DONTZERO\fR is defined, \fBstrptime()\fR does not zero the +\fBtm struct\fR on entry. Additionally, for some specifiers, \fBstrptime()\fR +will use some values in the input \fBtm struct\fR to recalculate the date and +re-assign the appropriate members of the \fBtm struct\fR. +.RE +.sp +.LP +The following describes extended features regardless of whether +\fB_STRPTIME_DONTZERO\fR is defined or not defined: +.RS +4 +.TP +.ie t \(bu +.el o +If \fB%j\fR is specified, \fBtm_yday\fR is set; if year is given, and if month +and day are not given, \fBstrptime()\fR calculates and sets \fBtm_mon\fR, +\fBtm_mday\fR, and \fBtm_year\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If \fB%U\fR or \fB%W\fR is specified and if weekday and year are given and +month and day of month are not given, \fBstrptime()\fR calculates and sets +\fBtm_mon\fR, \fBtm_mday\fR, \fBtm_wday\fR, and \fBtm_year\fR. +.RE +.sp +.LP +The following describes extended features when \fB_STRPTIME_DONTZERO\fR is not +defined: +.RS +4 +.TP +.ie t \(bu +.el o +If \fB%C\fR is specified and \fB%y\fR is not specified, \fBstrptime()\fRassumes +0 as the year offset, then calculates the year, and assigns \fBtm_year\fR. +.RE +.sp +.LP +The following describes extended features when \fB_STRPTIME_DONTZERO\fR is +defined: +.RS +4 +.TP +.ie t \(bu +.el o +If \fB%C\fR is specified and \fB%y\fR is not specified, \fBstrptime()\fR +assumes the year offset of the year value of the \fBtm_year\fR member of the +input \fBtm struct\fR, then calculates the year and assigns \fBtm_year\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If \fB%j\fR is specified and neither \fB%y\fR, \fB%Y\fR, nor \fB%C\fR are +specified, and neither month nor day of month are specified, \fBstrptime()\fR +assumes the year value given by the value of the \fBtm_year\fR field of the +input \fBtm struct\fR. Then, in addition to setting \fBtm_yday\fR, +\fBstrptime()\fR uses day-of-year and year values to calculate the month and +day-of-month, and assigns \fBtm_month\fR and \fBtm_mday\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If \fB%U\fR or \fB%W\fR is specified, and if weekday and/or year are not given, +and month and day of month are not given, \fBstrptime()\fR will assume the +weekday value and/or the year value as the value of the \fBtm_wday\fR field +and/or \fBtm_year\fR field of the input \fBtm struct\fR. Then, +\fBstrptime()\fR will calculate the month and day-of-month and assign +\fBtm_month\fR, \fBtm_mday\fR, and/or \fBtm_year\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If \fB%p\fR is specified and if hour is not specified, \fBstrptime()\fR will +reference, and if needed, update the \fBtm_hour\fR member. If the \fBam_pm\fR +input is p.m. and the input \fBtm_hour\fR value is between 0 - 11, +\fBstrptime()\fR will add 12 hours and update \fBtm_hour\fR. If the +\fBam_pm\fR input is a.m. and input \fBtm_hour\fR value is between 12 - 23, +\fBstrptime()\fR will subtract 12 hours and update \fBtm_hour\fR. +.RE +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBstrptime()\fR returns a pointer to the character +following the last character parsed. Otherwise, a null pointer is returned. +.SH USAGE +.sp +.LP +Several "same as" formats, and the special processing of white-space characters +are provided in order to ease the use of identical \fIformat\fR strings for +\fBstrftime\fR(3C) and \fBstrptime()\fR. +.sp +.LP +The \fBstrptime()\fR function tries to calculate \fBtm_year\fR, \fBtm_mon\fR, +and \fBtm_mday\fR when given incomplete input. This allows the \fBstruct tm\fR +created by \fBstrptime()\fR to be passed to \fBmktime\fR(3C) to produce a +\fBtime_t\fR value for dates and times that are representable by a +\fBtime_t\fR. As an example, since \fBmktime()\fR ignores \fBtm_yday\fR, +\fBstrptime()\fR calculates \fBtm_mon\fR and \fBtm_mday\fR as well as filling +in \fBtm_yday\fR when \fB%j\fR is specified without otherwise specifying a +month and day within month. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +CSIEnabled +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBctime\fR(3C), \fBgetdate\fR(3C), \fBisspace\fR(3C), \fBmktime\fR(3C), +\fBsetlocale\fR(3C), \fBstrftime\fR(3C), \fBattributes\fR(5), \fBenviron\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/strsignal.3c b/usr/src/man/man3c/strsignal.3c new file mode 100644 index 0000000000..f15af0e7ca --- /dev/null +++ b/usr/src/man/man3c/strsignal.3c @@ -0,0 +1,55 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH strsignal 3C "31 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +strsignal \- get name of signal +.SH SYNOPSIS +.LP +.nf +#include <string.h> + +\fBchar *\fR\fBstrsignal\fR(\fBint\fR \fIsig\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBstrsignal()\fR function maps the signal number in \fIsig\fR to a string +describing the signal and returns a pointer to that string. It uses the same +set of the messages as \fBpsignal\fR(3C). The returned string should not be +overwritten. +.SH RETURN VALUES +.sp +.LP +The \fBstrsignal()\fR function returns \fINULL\fR if \fIsig\fR is not a valid +signal number. +.SH USAGE +.sp +.LP +Messages returned from this function are in the native language specified by +the \fBLC_MESSAGES\fR locale category. See \fBsetlocale\fR(3C). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgettext\fR(3C), \fBpsignal\fR(3C), \fBsetlocale\fR(3C), \fBstr2sig\fR(3C), +\fBattributes\fR(5) diff --git a/usr/src/man/man3c/strtod.3c b/usr/src/man/man3c/strtod.3c new file mode 100644 index 0000000000..33d1199193 --- /dev/null +++ b/usr/src/man/man3c/strtod.3c @@ -0,0 +1,407 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH strtod 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +strtod, strtof, strtold, atof \- convert string to floating-point number +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBdouble\fR \fBstrtod\fR(\fBconst char *restrict\fR \fInptr\fR, \fBchar **restrict\fR \fIendptr\fR); +.fi + +.LP +.nf +\fBfloat\fR \fBstrtof\fR(\fBconst char *restrict\fR \fInptr\fR, \fBchar **restrict\fR \fIendptr\fR); +.fi + +.LP +.nf +\fBlong double\fR \fBstrtold\fR(\fBconst char *restrict\fR \fInptr\fR, \fBchar **restrict\fR \fIendptr\fR); +.fi + +.LP +.nf +\fBdouble\fR \fBatof\fR(\fBconst char *\fR\fIstr\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBstrtod()\fR, \fBstrtof()\fR, and \fBstrtold()\fR functions convert the +initial portion of the string pointed to by \fInptr\fR to \fBdouble\fR, +\fBfloat\fR, and \fBlong double\fR representation, respectively. First they +decompose the input string into three parts: +.RS +4 +.TP +1. +An initial, possibly empty, sequence of white-space characters (as specified +by \fBisspace\fR(3C)) +.RE +.RS +4 +.TP +2. +A subject sequence interpreted as a floating-point constant or representing +infinity or NaN +.RE +.RS +4 +.TP +3. +A final string of one or more unrecognized characters, including the +terminating null byte of the input string. +.RE +.sp +.LP +Then they attempt to convert the subject sequence to a floating-point number, +and return the result. +.sp +.LP +The expected form of the subject sequence is an optional plus or minus sign, +then one of the following: +.RS +4 +.TP +.ie t \(bu +.el o +A non-empty sequence of digits optionally containing a radix character, then an +optional exponent part +.RE +.RS +4 +.TP +.ie t \(bu +.el o +A 0x or 0X, then a non-empty sequence of hexadecimal digits optionally +containing a radix character, then an optional binary exponent part +.RE +.RS +4 +.TP +.ie t \(bu +.el o +One of INF or INFINITY, ignoring case +.RE +.RS +4 +.TP +.ie t \(bu +.el o +One of NAN or NAN(\fIn-char-sequence\fR(\fIopt\fR)), ignoring case in the NAN +part, where: +.sp +.in +2 +.nf +n-char-sequence: + digit + nondigit + n-char-sequence digit + n-char-sequence nondigit +.fi +.in -2 + +.RE +.sp +.LP +In default mode for \fBstrtod()\fR, only decimal, INF/INFINITY, and +NAN/NAN(\fIn-char-sequence\fR) forms are recognized. In C99/SUSv3 mode, +hexadecimal strings are also recognized. +.sp +.LP +In default mode for \fBstrtod()\fR, the \fIn-char-sequence\fR in the +NAN(\fIn-char-equence\fR) form can contain any character except ')' (right +parenthesis) or '\e0' (null). In C99/SUSv3 mode, the \fIn-char-sequence\fR can +contain only upper and lower case letters, digits, and '_' (underscore). +.sp +.LP +The \fBstrtof()\fR and \fBstrtold()\fR functions always function in +C99/SUSv3-conformant mode. +.sp +.LP +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. +.sp +.LP +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) is interpreted as a floating constant of the +C language, except that the radix character is 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 is interpreted as +negated. A character sequence INF or INFINITY is interpreted as an infinity. A +character sequence NAN or NAN(\fIn-char-sequence\fR(\fIopt\fR)) is interpreted +as a quiet NaN. A pointer to the final string is stored in the object pointed +to by \fIendptr\fR, provided that \fIendptr\fR is not a null pointer. +.sp +.LP +If the subject sequence has either the decimal or hexadecimal form, the value +resulting from the conversion is rounded correctly according to the prevailing +floating point rounding direction mode. The conversion also raises floating +point inexact, underflow, or overflow exceptions as appropriate. +.sp +.LP +The radix character is defined in the program's locale (category +\fBLC_NUMERIC\fR). In the POSIX locale, or in a locale where the radix +character is not defined, the radix character defaults to a period ('.'). +.sp +.LP +If the subject sequence is empty or does not have the expected form, no +conversion is performed; the value of \fInptr\fR is stored in the object +pointed to by \fIendptr\fR, provided that \fIendptr\fR is not a null pointer. +.sp +.LP +The \fBstrtod()\fR function does not change the setting of \fBerrno\fR if +successful. +.sp +.LP +The \fBatof(\fR\fIstr\fR\fB)\fR function call is equivalent to +\fBstrtod(\fR\fInptr\fR\fB, (char **)NULL)\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, these functions return the converted value. If no +conversion could be performed, \fB0\fR is returned. +.sp +.LP +If the correct value is outside the range of representable values, +\fB\(+-HUGE_VAL\fR, \fB\(+-HUGE_VALF\fR, or \fB\(+-HUGE_VALL\fR is returned +(according to the sign of the value), a floating point overflow exception is +raised, and \fBerrno\fR is set to \fBERANGE\fR. +.sp +.LP +If the correct value would cause an underflow, the correctly rounded result +(which may be normal, subnormal, or zero) is returned, a floating point +underflow exception is raised, and \fBerrno\fR is set to \fBERANGE\fR. +.SH ERRORS +.sp +.LP +These functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBERANGE\fR\fR +.ad +.RS 10n +.rt +The value to be returned would cause overflow or underflow +.RE + +.sp +.LP +These functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +No conversion could be performed. +.RE + +.SH USAGE +.sp +.LP +Since 0 is returned on error and is also a valid return on success, an +application wishing to check for error situations should set \fBerrno\fR to 0, +then call \fBstrtod()\fR, \fBstrtof()\fR, or \fBstrtold()\fR, then check +\fBerrno\fR. +.sp +.LP +The changes to \fBstrtod()\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 IEEE Std 1003.1-200x. One such +example would be: +.sp +.in +2 +.nf +int +what_kind_of_number (char *s) +{ + char *endp; + double d; + long l; + d = strtod(s, &endp); + if (s != endp && *endp == `\0') + 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 +.in -2 + +.sp +.LP +If the function is called with: +.sp +.in +2 +.nf +what_kind_of_number ("0x10") +.fi +.in -2 + +.sp +.LP +an ISO/IEC 9899: 1990 standard-compliant library will result in the function +printing: +.sp +.in +2 +.nf +It's an integer with value 16 +.fi +.in -2 + +.sp +.LP +With the ISO/IEC 9899: 1999 standard, the result is: +.sp +.in +2 +.nf +It's a float with value 16 +.fi +.in -2 + +.sp +.LP +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 ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +CSIEnabled +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBisspace\fR(3C), \fBlocaleconv\fR(3C), \fBscanf\fR(3C), \fBsetlocale\fR(3C), +\fBstrtol\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +The \fBstrtod()\fR and \fBatof()\fR functions can be used safely in +multithreaded applications, as long as \fBsetlocale\fR(3C) is not called to +change the locale. +.sp +.LP +The DESCRIPTION and RETURN VALUES sections above are very similar to the +wording used by the Single UNIX Specification version 2 (SUSv2) and the 1989 C +Standard to describe the behavior of the \fBstrtod()\fR function. Since some +users have reported that they find the description confusing, the following +notes might be helpful. +.RS +4 +.TP +1. +The \fBstrtod()\fR function does not modify the string pointed to by +\fIstr\fR and does not \fBmalloc()\fR space to hold the decomposed portions of +the input string. +.RE +.RS +4 +.TP +2. +If \fIendptr\fR is not \fB(char **)NULL\fR, \fBstrtod()\fR will set the +pointer pointed to by \fIendptr\fR to the first byte of the "final string of +unrecognized characters". (If all input characters were processed, the pointer +pointed to by \fIendptr\fR will be set to point to the null character at the +end of the input string.) +.RE +.RS +4 +.TP +3. +If \fBstrtod()\fR returns 0.0, one of the following occurred: +.RS +4 +.TP +a. +The "subject sequence" was not an empty string, but evaluated to 0.0. (In +this case, \fBerrno\fR will be left unchanged.) +.RE +.RS +4 +.TP +b. +The "subject sequence" was an empty string . In this case, \fBerrno\fR will +be left unchanged. (The Single UNIX Specification version 2 allows \fBerrno\fR +to be set to \fBEINVAL\fR or to be left unchanged. The C Standard does not +specify any specific behavior in this case.) +.RE +.RS +4 +.TP +c. +The "subject sequence" specified a numeric value whose conversion resulted +in a floating point underflow. In this case, an underflow exception is raised +and \fBerrno\fR is set to \fBERANGE\fR. +.RE +Note that the standards do not require that implementations distinguish between +these three cases. An application can determine case (b) by making sure that +there are no leading white-space characters in the string pointed to by +\fIstr\fR and giving \fBstrtod()\fR an \fIendptr\fR that is not \fB(char +**)NULL\fR. If \fIendptr\fR points to the first character of \fIstr\fR when +\fBstrtod()\fR returns, you have detected case (b). Case (c) can be detected +by examining the underflow flag or by looking for a non-zero digit before the +exponent part of the "subject sequence". Note, however, that the decimal-point +character is locale-dependent. +.RE +.RS +4 +.TP +4. +If \fBstrtod()\fR returns \fB+HUGE_VAL\fR or \fB\(miHUGE_VAL\fR, one of the +following occurred: +.RS +4 +.TP +a. +If \fB+HUGE_VAL\fR is returned and \fBerrno\fR is set to \fBERANGE\fR, a +floating point overflow occurred while processing a positive value, causing a +floating point overflow exception to be raised. +.RE +.RS +4 +.TP +b. +If \fB\(miHUGE_VAL\fR is returned and \fBerrno\fR is set to \fBERANGE\fR, a +floating point overflow occurred while processing a negative value, causing a +floating point overflow exception to be raised. +.RE +.RS +4 +.TP +c. +If \fBstrtod()\fR does not set \fBerrno\fR to \fBERANGE\fR, the value +specified by the "subject string" converted to \fB+HUGE_VAL\fR or +\fB\(miHUGE_VAL\fR, respectively. +.RE +Note that if \fBerrno\fR is set to \fBERANGE\fR when \fBstrtod()\fR is called, +case (c) can be distinguished from cases (a) and (b) by examining either +\fBERANGE\fR or the overflow flag. +.RE diff --git a/usr/src/man/man3c/strtoimax.3c b/usr/src/man/man3c/strtoimax.3c new file mode 100644 index 0000000000..6bac7d2bec --- /dev/null +++ b/usr/src/man/man3c/strtoimax.3c @@ -0,0 +1,99 @@ +'\" te +.\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved. Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH strtoimax 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +strtoimax, strtoumax \- convert string to integer type +.SH SYNOPSIS +.LP +.nf +#include <inttypes.h> + +\fBintmax_t\fR \fBstrtoimax\fR(\fBconst char *restrict\fR \fInptr\fR, + \fBchar **restrict\fR \fIendptr\fR, \fBint\fR \fIbase\fR); +.fi + +.LP +.nf +\fBuintmax_t\fR \fBstrtoumax\fR(\fBconst char *restrict\fR \fInptr\fR, + \fBchar **restrict\fR \fIendptr\fR, \fBint\fR \fIbase\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions are equivalent to the \fBstrtol()\fR, \fBstrtoll()\fR, +\fBstrtoul()\fR, and \fBstrtoull()\fR functions, except that the initial +portion of the string is converted to \fBintmax_t\fR and \fBuintmax_t\fR +representation, respectively. +.SH RETURN VALUES +.sp +.LP +These functions return the converted value, if any. +.sp +.LP +If no conversion could be performed, 0 is returned. +.sp +.LP +If the correct value is outside the range of representable values, +{\fBINTMAX_MAX\fR}, {\fBINTMAX_MIN\fR}, or {\fBUINTMAX_MAX\fR} is returned +(according to the return type and sign of the value, if any), and \fBerrno\fR +is set to \fBERANGE\fR. +.SH ERRORS +.sp +.LP +These functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBERANGE\fR\fR +.ad +.RS 10n +.rt +The value to be returned is not representable. +.RE + +.sp +.LP +These functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of \fIbase\fR is not supported. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBstrtol\fR(3C), \fBstrtoul\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/strtol.3c b/usr/src/man/man3c/strtol.3c new file mode 100644 index 0000000000..a6b21a5c85 --- /dev/null +++ b/usr/src/man/man3c/strtol.3c @@ -0,0 +1,244 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH strtol 3C "6 May 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +strtol, strtoll, atol, atoll, atoi, lltostr, ulltostr \- string conversion +routines +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBlong\fR \fBstrtol\fR(\fBconst char *restrict\fR \fIstr\fR, \fBchar **restrict\fR \fIendptr\fR, \fBint\fR \fIbase\fR); +.fi + +.LP +.nf +\fBlong long\fR \fBstrtoll\fR(\fBconst char *restrict\fR \fIstr\fR, \fBchar **restrict\fR \fIendptr\fR, + \fBint\fR \fIbase\fR); +.fi + +.LP +.nf +\fBlong\fR \fBatol\fR(\fBconst char *\fR\fIstr\fR); +.fi + +.LP +.nf +\fBlong long\fR \fBatoll\fR(\fBconst char *\fR\fIstr\fR); +.fi + +.LP +.nf +\fBint\fR \fBatoi\fR(\fBconst char *\fR\fIstr\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBlltostr\fR(\fBlong long\fR \fIvalue\fR, \fBchar *\fR\fIendptr\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBulltostr\fR(\fBunsigned long long\fR \fIvalue\fR, \fBchar *\fR\fIendptr\fR); +.fi + +.SH DESCRIPTION +.SS "\fBstrtol()\fR and \fBstrtoll()\fR" +.sp +.LP +The \fBstrtol()\fR function converts the initial portion of the string pointed +to by \fIstr\fR to a type \fBlong int\fR representation. +.sp +.LP +The \fBstrtoll()\fR function converts the initial portion of the string pointed +to by \fIstr\fR to a type \fBlong long\fR representation. +.sp +.LP +Both functions first decompose the input string into three parts: an initial, +possibly empty, sequence of white-space characters (as specified by +\fBisspace\fR(3C)); a subject sequence interpreted as an integer represented in +some radix determined by the value of \fIbase\fR; and a final string of one or +more unrecognized characters, including the terminating null byte of the input +string. They then attempt to convert the subject sequence to an integer and +return the result. +.sp +.LP +If the value of \fIbase\fR 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 + or \(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 0 optionally followed by a sequence of the digits 0 to 7 +only. A hexadecimal constant consists of the prefix 0x or 0X followed by a +sequence of the decimal digits and letters a (or A) to f (or F) with values 10 +to 15 respectively. +.sp +.LP +If the value of \fIbase\fR 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 \fIbase\fR, optionally preceded by a + or \(mi +sign. The letters from a (or A) to z (or Z) inclusive are ascribed the values +10 to 35; only letters whose ascribed values are less than that of \fIbase\fR +are permitted. If the value of \fIbase\fR is 16, the characters 0x or 0X may +optionally precede the sequence of letters and digits, following the sign if +present. +.sp +.LP +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 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. +.sp +.LP +If the subject sequence has the expected form and the value of \fIbase\fR is 0, +the sequence of characters starting with the first digit is interpreted as an +integer constant. If the subject sequence has the expected form and the value +of \fIbase\fR is between 2 and 36, it is 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 is negated. A +pointer to the final string is stored in the object pointed to by \fIendptr\fR, +provided that \fIendptr\fR is not a null pointer. +.sp +.LP +In other than the POSIX locale, additional implementation-dependent subject +sequence forms may be accepted. +.sp +.LP +If the subject sequence is empty or does not have the expected form, no +conversion is performed; the value of \fIstr\fR is stored in the object pointed +to by \fIendptr\fR, provided that \fIendptr\fR is not a null pointer. +.SS "\fBatol()\fR, \fBatoll()\fR and \fBatoi()\fR" +.sp +.LP +Except for behavior on error, \fBatol()\fR is equivalent to: \fBstrtol(str, +(char **)NULL, 10)\fR. +.sp +.LP +Except for behavior on error, \fBatoll()\fR is equivalent to: \fBstrtoll(str, +(char **)NULL, 10)\fR. +.sp +.LP +Except for behavior on error, \fBatoi()\fR is equivalent to: \fB(int) +strtol(str, (char **)NULL, 10)\fR. +.sp +.LP +If the value cannot be represented, the behavior is undefined. +.SS "\fBlltostr()\fR and \fBulltostr()\fR" +.sp +.LP +The \fBlltostr()\fR function returns a pointer to the string represented by the +\fBlong\fR \fBlong\fR \fIvalue\fR. The \fIendptr\fR argument is assumed to +point to the byte following a storage area into which the decimal +representation of \fIvalue\fR is to be placed as a string. The \fBlltostr()\fR +function converts \fIvalue\fR to decimal and produces the string, and returns +a pointer to the beginning of the string. No leading zeros are produced, and no +terminating null is produced. The low-order digit of the result always occupies +memory position \fIendptr\fR\(mi1. The behavior of \fBlltostr()\fR is +undefined if \fIvalue\fR is negative. A single zero digit is produced if +\fIvalue\fR is 0. +.sp +.LP +The \fBulltostr()\fR function is similar to \fBlltostr()\fR except that +\fIvalue\fR is an \fBunsigned long long\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBstrtol()\fR, \fBstrtoll()\fR, \fBatol()\fR, +\fBatoll()\fR, and \fBatoi()\fR return the converted value, if any. If no +conversion could be performed, \fBstrtol()\fR and \fBstrtoll()\fR return +\fB0\fR and \fBerrno\fR may be set to \fBEINVAL\fR. +.sp +.LP +If the correct value is outside the range of representable values, +\fBstrtol()\fR returns \fBLONG_MAX\fR or \fBLONG_MIN\fR and \fBstrtoll()\fR +returns \fBLLONG_MAX\fR or \fBLLONG_MIN\fR (according to the sign of the +value), and \fBerrno\fR is set to \fBERANGE\fR. +.sp +.LP +Upon successful completion, \fBlltostr()\fR and \fBulltostr()\fR return a +pointer to the converted string. +.SH ERRORS +.sp +.LP +The \fBstrtol()\fR and \fBstrtoll()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBERANGE\fR\fR +.ad +.RS 10n +.rt +The value to be returned is not representable. The \fBstrtol()\fR and +\fBstrtoll()\fR functions may fail if: +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of \fIbase\fR is not supported. +.RE + +.SH USAGE +.sp +.LP +Because 0, \fBLONG_MIN\fR, \fBLONG_MAX\fR, \fBLLONG_MIN\fR, and \fBLLONG_MAX\fR +are returned on error and are also valid returns on success, an application +wishing to check for error situations should set \fBerrno\fR to 0, call the +function, then check \fBerrno\fR and if it is non-zero, assume an error has +occurred. +.sp +.LP +The \fBstrtol()\fR function no longer accepts values greater than +\fBLONG_MAX\fR or \fBLLONG_MAX\fR as valid input. Use \fBstrtoul\fR(3C) +instead. +.sp +.LP +Calls to \fBatoi()\fR and \fBatol()\fR might be faster than corresponding calls +to \fBstrtol()\fR, and calls to \fBatoll()\fR might be faster than +corresponding calls to \fBstrtoll()\fR. However, applications should not use +the \fBatoi()\fR, \fBatol()\fR, or \fBatoll()\fR functions unless they know the +value represented by the argument will be in range for the corresponding result +type. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilitySee below. +_ +MT-LevelMT-Safe +.TE + +.sp +.LP +The \fBstrtol()\fR, \fBstrtoll()\fR, \fBatol()\fR, \fBatoll()\fR, and +\fBatoi()\fR functions are Standard. +.SH SEE ALSO +.sp +.LP +\fBisalpha\fR(3C), \fBisspace\fR(3C), \fBscanf\fR(3C), \fBstrtod\fR(3C), +\fBstrtoul\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/strtoul.3c b/usr/src/man/man3c/strtoul.3c new file mode 100644 index 0000000000..e558e4c36d --- /dev/null +++ b/usr/src/man/man3c/strtoul.3c @@ -0,0 +1,174 @@ +'\" te +.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH strtoul 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +strtoul, strtoull \- convert string to unsigned long +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBunsigned long\fR \fBstrtoul\fR(\fBconst char *restrict\fR \fIstr\fR, + \fBchar **restrict\fR \fIendptr\fR, \fBint\fR \fIbase\fR); +.fi + +.LP +.nf +\fBunsigned long long\fR \fBstrtoull\fR(\fBconst char *restrict\fR \fIstr\fR, + \fBchar **restrict\fR \fIendptr\fR, \fBint\fR \fIbase\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBstrtoul()\fR function converts the initial portion of the string pointed +to by \fIstr\fR to a type \fBunsigned long int\fR representation. First it +decomposes the input string into three parts: an initial, possibly empty, +sequence of white-space characters (as specified by \fBisspace\fR(3C)); a +subject sequence interpreted as an integer represented in some radix determined +by the value of \fIbase\fR; and a final string of one or more unrecognised +characters, including the terminating null byte of the input string. Then it +attempts to convert the subject sequence to an unsigned integer, and returns +the result. +.sp +.LP +If the value of \fIbase\fR 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 + or \(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 0 optionally followed by a sequence of the digits 0 to 7 +only. A hexadecimal constant consists of the prefix 0x or 0X followed by a +sequence of the decimal digits and letters a (or A) to f (or F) with values 10 +to 15 respectively. +.sp +.LP +If the value of \fIbase\fR 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 \fIbase\fR, optionally preceded by a + or \(mi +sign. The letters from a (or A) to z (or Z) inclusive are ascribed the values +10 to 35; only letters whose ascribed values are less than that of \fIbase\fR +are permitted. If the value of \fIbase\fR is 16, the characters 0x or 0X may +optionally precede the sequence of letters and digits, following the sign if +present. +.sp +.LP +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 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. +.sp +.LP +If the subject sequence has the expected form and the value of \fIbase\fR is 0, +the sequence of characters starting with the first digit is interpreted as an +integer constant. If the subject sequence has the expected form and the value +of \fIbase\fR is between 2 and 36, it is 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 is negated. A +pointer to the final string is stored in the object pointed to by \fIendptr\fR, +provided that \fIendptr\fR is not a null pointer. +.sp +.LP +In other than the POSIX locale, additional implementation-dependent subject +sequence forms may be accepted. +.sp +.LP +If the subject sequence is empty or does not have the expected form, no +conversion is performed; the value of \fIstr\fR is stored in the object pointed +to by \fIendptr\fR, provided that \fIendptr\fR is not a null pointer. +.sp +.LP +The \fBstrtoull()\fR function is identical to \fBstrtoul()\fR except that it +returns the value represented by \fIstr\fR as an \fBunsigned long long\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion \fBstrtoul()\fR returns the converted value, if any. +If no conversion could be performed, \fB0\fR is returned and \fBerrno\fR may be +set to \fBEINVAL\fR. If the correct value is outside the range of representable +values, \fBULONG_MAX\fR is returned and \fBerrno\fR is set to \fBERANGE\fR. +.SH ERRORS +.sp +.LP +The \fBstrtoul()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of \fIbase\fR is not supported. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBERANGE\fR\fR +.ad +.RS 10n +.rt +The value to be returned is not representable. +.RE + +.sp +.LP +The \fBstrtoul()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +No conversion could be performed. +.RE + +.SH USAGE +.sp +.LP +Because 0 and \fBULONG_MAX\fR are returned on error and are also valid returns +on success, an application wishing to check for error situations should set +\fBerrno\fR to 0, then call \fBstrtoul()\fR, then check \fBerrno\fR and if it +is non-zero, assume an error has occurred. +.sp +.LP +Unlike \fBstrtod\fR(3C) and \fBstrtol\fR(3C), \fBstrtoul()\fR must always +return a non-negative number; so, using the return value of \fBstrtoul()\fR for +out-of-range numbers with \fBstrtoul()\fR could cause more severe problems than +just loss of precision if those numbers can ever be negative. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBisalpha\fR(3C), \fBisspace\fR(3C), \fBscanf\fR(3C), \fBstrtod\fR(3C), +\fBstrtol\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/strtows.3c b/usr/src/man/man3c/strtows.3c new file mode 100644 index 0000000000..e42a34ebcb --- /dev/null +++ b/usr/src/man/man3c/strtows.3c @@ -0,0 +1,51 @@ +'\" te +.\" Portions Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH strtows 3C "20 Dec 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +strtows, wstostr \- code conversion for Process Code and File Code +.SH SYNOPSIS +.LP +.nf +#include <widec.h> + +\fBwchar_t *\fR\fBstrtows\fR(\fBwchar_t *\fR\fIdst\fR, \fBchar *\fR\fIsrc\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBwstostr\fR(\fBchar *\fR\fIdst\fR, \fBwchar_t *\fR\fIsrc\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBstrtows()\fR and \fBwstostr()\fR functions convert strings back and +forth between File Code representation and Process Code. +.sp +.LP +The \fBstrtows()\fR function takes a character string \fIsrc\fR, converts it to +a Process Code string, terminated by a Process Code null, and places the result +into \fIdst\fR. +.sp +.LP +The \fBwstostr()\fR function takes the Process Code string pointed to by +\fIsrc\fR, converts it to a character string, and places the result into +\fIdst\fR. +.SH RETURN VALUES +.sp +.LP +The \fBstrtows()\fR function returns the Process Code string if it completes +successfully. Otherwise, a null pointer will be returned and \fBerrno\fR will +be set to \fBEILSEQ\fR. +.sp +.LP +The \fBwstostr()\fR function returns the File Code string if it completes +successfully. Otherwise, a null pointer will be returned and \fBerrno\fR will +be set to \fBEILSEQ\fR. +.SH SEE ALSO +.sp +.LP +\fBwstring\fR(3C) diff --git a/usr/src/man/man3c/strxfrm.3c b/usr/src/man/man3c/strxfrm.3c new file mode 100644 index 0000000000..e0217dd882 --- /dev/null +++ b/usr/src/man/man3c/strxfrm.3c @@ -0,0 +1,120 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH strxfrm 3C "10 Dec 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +strxfrm \- string transformation +.SH SYNOPSIS +.LP +.nf +#include <string.h> + +\fBsize_t\fR \fBstrxfrm\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR, \fBsize_t\fR \fIn\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBstrxfrm()\fR function transforms the string pointed to by \fIs2\fR and +places the resulting string into the array pointed to by \fIs1\fR. The +transformation is such that if \fBstrcmp\fR(3C) is applied to two transformed +strings, it returns a value greater than, equal to or less than \fB0\fR, +corresponding to the result of \fBstrcoll\fR(3C) applied to the same two +original strings. No more than \fIn\fR bytes are placed into the resulting +array pointed to by \fIs1\fR, including the terminating null byte. If \fIn\fR +is \fB0\fR, \fIs1\fR is permitted to be a null pointer. If copying takes place +between objects that overlap, the behavior is undefined. +.sp +.LP +The \fBstrxfrm()\fR function does not change the setting of \fBerrno\fR if +successful. +.sp +.LP +Since no return value is reserved to indicate an error, an application wishing +to check for error situations should set \fBerrno\fR to 0, then call +\fBstrxfrm()\fR, then check \fBerrno\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBstrxfrm()\fR returns the length of the +transformed string (not including the terminating null byte). If the value +returned is \fIn\fR or more, the contents of the array pointed to by \fIs1\fR +are indeterminate. +.sp +.LP +On error, \fBstrxfrm()\fR may set \fBerrno\fR but no return value is reserved +to indicate the error. +.SH USAGE +.sp +.LP +The transformation function is such that two transformed strings can be ordered +by \fBstrcmp\fR(3C) as appropriate to collating sequence information in the +program's locale (category \fBLC_COLLATE\fR). +.sp +.LP +The fact that when \fIn\fR is \fB0\fR, \fIs1\fR is permitted to be a null +pointer, is useful to determine the size of the \fIs1\fR array prior to making +the transformation. +.SH EXAMPLES +.LP +\fBExample 1 \fRA sample of using the \fBstrxfm()\fR function. +.sp +.LP +The value of the following expression is the size of the array needed to hold +the transformation of the string pointed to by \fIs\fR. + +.sp +.in +2 +.nf +1 + strxfrm(NULL, s, 0); +.fi +.in -2 + +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/usr/lib/locale/\fIlocale\fR/\fIlocale\fR.so.*\fR\fR +.ad +.sp .6 +.RS 4n +\fBLC_COLLATE\fR database for \fIlocale\fR +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +CSIEnabled +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe with exceptions +.TE + +.sp +.LP +The \fBstrxfrm()\fR function can be used safely in a multithreaded application, +as long as \fBsetlocale\fR(3C) is not being called to change the locale. +.SH SEE ALSO +.sp +.LP +\fBlocaledef\fR(1), \fBsetlocale\fR(3C), \fBstrcmp\fR(3C), \fBstrcoll\fR(3C), +\fBwscoll\fR(3C), \fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/swab.3c b/usr/src/man/man3c/swab.3c new file mode 100644 index 0000000000..7381217292 --- /dev/null +++ b/usr/src/man/man3c/swab.3c @@ -0,0 +1,64 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH swab 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +swab \- swap bytes +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBvoid\fR \fBswab\fR(\fBconst char *\fR\fIsrc\fR, \fBchar *\fR\fIdest\fR, \fBssize_t\fR \fInbytes\fR); +.fi + +.SS "XPG4, SUS, SUSv2, SUSv3" +.LP +.nf +#include <unistd.h> + +\fBvoid\fR \fBswab\fR(\fBconst void *restrict\fR \fIsrc\fR, \fBvoid *restrict\fR \fIdest\fR, \fBssize_t\fR \fInbytes\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBswab()\fR function copies \fInbytes\fR bytes, which are pointed to by +\fIsrc\fR, to the object pointed to by \fIdest\fR, exchanging adjacent bytes. +The \fInbytes\fR argument should be even. If \fInbytes\fR is odd \fBswab()\fR +copies and exchanges \fInbytes\fR\(mi1 bytes and the disposition of the last +byte is unspecified. If copying takes place between objects that overlap, the +behavior is undefined. If \fInbytes\fR is negative, \fBswab()\fR does nothing. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/sync_instruction_memory.3c b/usr/src/man/man3c/sync_instruction_memory.3c new file mode 100644 index 0000000000..907af97dff --- /dev/null +++ b/usr/src/man/man3c/sync_instruction_memory.3c @@ -0,0 +1,75 @@ +'\" te +.\" Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH sync_instruction_memory 3C "12 Feb 1997" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +sync_instruction_memory \- make modified instructions executable +.SH SYNOPSIS +.LP +.nf +\fBvoid\fR \fBsync_instruction_memory\fR(\fBcaddr_t\fR \fIaddr\fR, \fBint\fR \fIlen\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsync_instruction_memory()\fR function performs whatever steps are +required to make instructions modified by a program executable. +.sp +.LP +Some processor architectures, including some SPARC processors, have separate +and independent instruction and data caches which are not kept consistent by +hardware. For example, if the instruction cache contains an instruction from +some address and the program then stores a new instruction at that address, the +new instruction may not be immediately visible to the instruction fetch +mechanism. Software must explicitly invalidate the instruction cache entries +for new or changed mappings of pages that might contain executable +instructions. The \fBsync_instruction_memory()\fR function performs this +function, and/or any other functions needed to make modified instructions +between \fIaddr\fR and \fIaddr\fR+\fIlen\fR visible. A program should call +\fBsync_instruction_memory()\fR after modifying instructions and before +executing them. +.sp +.LP +On processors with unified caches (one cache for both instructions and data) +and pipelines which are flushed by a branch instruction, such as the x86 +architecture, the function may do nothing and just return. +.sp +.LP +The changes are immediately visible to the thread calling +\fBsync_instruction_memory()\fR when the call returns, even if the thread +should migrate to another processor during or after the call. The changes +become visible to other threads in the same manner that stores do; that is, +they eventually become visible, but the latency is implementation-dependent. +.sp +.LP +The result of executing \fBsync_instruction_memory()\fR are unpredictable if +\fIaddr\fR through \fIaddr\fR+\fIlen\fR-1 are not valid for the address space +of the program making the call. +.SH RETURN VALUES +.sp +.LP +No values are returned. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5) diff --git a/usr/src/man/man3c/sysconf.3c b/usr/src/man/man3c/sysconf.3c new file mode 100644 index 0000000000..a7ae5242bb --- /dev/null +++ b/usr/src/man/man3c/sysconf.3c @@ -0,0 +1,504 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH sysconf 3C "26 Mar 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +sysconf \- get configurable system variables +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> + +\fBlong\fR \fBsysconf\fR(\fBint\fR \fIname\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsysconf()\fR function provides a method for an application to determine +the current value of a configurable system limit or option (variable). +.sp +.LP +The \fIname\fR argument represents the system variable to be queried. The +following table lists the minimal set of system variables from \fB<limits.h>\fR +and \fB<unistd.h>\fR that can be returned by \fBsysconf()\fR and the symbolic +constants defined in \fB<unistd.h>\fR that are the corresponding values used +for \fIname\fR on the SPARC and x86 platforms. +.sp +.in +2 +.nf + Name Return Value Meaning +_______________________________________________________________________ +_SC_2_C_BIND _POSIX2_C_BIND Supports the C lang- + uage binding option +_SC_2_C_DEV _POSIX2_C_DEV Supports the C lang- + uage development + utilities option +_SC_2_C_VERSION _POSIX2_C_VERSION Integer value + indicates version + of ISO POSIX-2 + standard (Commands) +_SC_2_CHAR_TERM _POSIX2_CHAR_TERM Supports at least + one terminal +_SC_2_FORT_DEV _POSIX2_FORT_DEV Supports FORTRAN + Development + Utilities Option +_SC_2_FORT_RUN _POSIX2_FORT_RUN Supports FORTRAN + Run-time Utilities + Option +_SC_2_LOCALEDEF _POSIX2_LOCALEDEF Supports creation + of locales by the + localedef utility +_SC_2_SW_DEV _POSIX2_SW_DEV Supports Software + Development Utility + Option +_SC_2_UPE _POSIX2_UPE Supports User + Portability + Utilities Option +_SC_2_VERSION _POSIX2_VERSION Integer value + indicates version + of ISO POSIX-2 + standard (C language + binding) +_SC_AIO_LISTIO_MAX AIO_LISTIO_MAX Max number of I/O + operations in a + single list I/O call + supported +_SC_AIO_MAX AIO_MAX Max number of + outstanding + asynchronous I/O + operations supported +_SC_AIO_PRIO_DELTA_MAX AIO_PRIO_DELTA_MAX Max amount by which + process can decrease + its asynchronous + I/O priority level + from its own + scheduling priority +_SC_ARG_MAX ARG_MAX Max size of argv[] + plus envp[] +_SC_ASYNCHRONOUS_IO _POSIX_ASYNCHRONOUS_IO Supports + Asynchronous I/O +_SC_ATEXIT_MAX ATEXIT_MAX Max number of + functions that can + be registered with + atexit() +_SC_AVPHYS_PAGES Number of physical + memory pages not + currently in use by + system +_SC_BARRIERS _POSIX_BARRIERS Supports Barriers + option +_SC_BC_BASE_MAX BC_BASE_MAX Maximum obase values + allowed by bc +_SC_BC_DIM_MAX BC_DIM_MAX Max number of + elements permitted + in array by bc +_SC_BC_SCALE_MAX BC_SCALE_MAX Max scale value + allowed by bc +_SC_BC_STRING_MAX BC_STRING_MAX Max length of string + constant allowed by + bc +_SC_CHILD_MAX CHILD_MAX Max processes + allowed to a UID +_SC_CLK_TCK CLK_TCK Ticks per second + (clock_t) +_SC_CLOCK_SELECTION _POSIX_CLOCK_SELECTION Supports Clock + Selection option +_SC_COLL_WEIGHTS_MAX COLL_WEIGHTS_MAX Max number of + weights that can be + assigned to entry of + the LC_COLLATE order + keyword in locale + definition file +_SC_CPUID_MAX Max possible + processor ID +_SC_DELAYTIMER_MAX DELAYTIMER_MAX Max number of timer + expiration overruns +_SC_EXPR_NEST_MAX EXPR_NEST_MAX Max number of + parentheses by expr +_SC_FSYNC _POSIX_FSYNC Supports File + Synchronization +_SC_GETGR_R_SIZE_MAX Max size of group + entry buffer +_SC_GETPW_R_SIZE_MAX Max size of password + entry buffer +_SC_HOST_NAME_MAX _POSIX_HOST_NAME_MAX Maximum length of a + host name (excluding + terminating null) +_SC_IOV_MAX IOV_MAX Max number of iovec + structures available + to one process for + use with readv() + and writev() +_SC_JOB_CONTROL _POSIX_JOB_CONTROL Job control + supported? +_SC_LINE_MAX LINE_MAX Max length of input + line +_SC_LOGIN_NAME_MAX LOGNAME_MAX + 1 Max length of login + name +_SC_LOGNAME_MAX LOGNAME_MAX +_SC_MAPPED_FILES _POSIX_MAPPED_FILES Supports Memory + Mapped Files +_SC_MAXPID Max pid value +_SC_MEMLOCK _POSIX_MEMLOCK Supports Process + Memory Locking +_SC_MEMLOCK_RANGE _POSIX_MEMLOCK_RANGE Supports Range + Memory Locking +_SC_MEMORY_PROTECTION _POSIX_MEMORY_PROTECTION Supports Memory + Protection +_SC_MESSAGE_PASSING _POSIX_MESSAGE_PASSING Supports Message + Passing +_SC_MONOTONIC_CLOCK _POSIX_MONOTONIC_CLOCK Supports Monotonic + Clock option +_SC_MQ_OPEN_MAX MQ_OPEN_MAX Max number of open + message queues a + process can hold +_SC_MQ_PRIO_MAX MQ_PRIO_MAX Max number of + message priorities + supported +_SC_NGROUPS_MAX NGROUPS_MAX Max simultaneous + groups to which + one can belong +_SC_NPROCESSORS_CONF Number of processors + configured +_SC_NPROCESSORS_MAX Max number of + processors supported + by platform +_SC_NPROCESSORS_ONLN Number of processors + online +_SC_OPEN_MAX OPEN_MAX Max open files per + process +_SC_PAGESIZE PAGESIZE System memory page + size +_SC_PAGE_SIZE PAGESIZE Same as _SC_PAGESIZE +_SC_PASS_MAX PASS_MAX Max number of + significant bytes + in a password +_SC_PHYS_PAGES Total number of + pages of physical + memory in system +_SC_PRIORITIZED_IO _POSIX_PRIORITIZED_IO Supports Prioritized + I/O +_SC_PRIORITY_SCHEDULING _POSIX_PRIORITY_SCHEDULING Supports Process + Scheduling +_SC_RAW_SOCKETS _POSIX_RAW_SOCKETS Supports Raw Sockets + option +_SC_RE_DUP_MAX RE_DUP_MAX Max number of + repeated occurrences + of a regular + expression permitted + when using interval + notation \e{m,n\e} +_SC_READER_WRITER_LOCKS _POSIX_READER_WRITER_LOCKS Supports IPV6 option +_SC_REALTIME_SIGNALS _POSIX_REALTIME_SIGNALS Supports Realtime + Signals +_SC_REGEXP _POSIX_REGEXP Supports Regular + Expression Handling + option +_SC_RTSIG_MAX RTSIG_MAX Max number of + realtime signals + reserved for + application use +_SC_SAVED_IDS _POSIX_SAVED_IDS Saved IDs + (seteuid()) + supported? +_SC_SEM_NSEMS_MAX SEM_NSEMS_MAX Max number of POSIX + semaphores a process + can have +_SC_SEM_VALUE_MAX SEM_VALUE_MAX Max value a POSIX + semaphore can have +_SC_SEMAPHORES _POSIX_SEMAPHORES Supports Semaphores +_SC_SHARED_MEMORY_ _POSIX_SHARED_MEMORY_ Supports Shared + OBJECTS OBJECTS Memory Objects +_SC_SHELL _POSIX_SHELL Supports POSIX shell +_SC_SIGQUEUE_MAX SIGQUEUE_MAX Max number of queued + signals that a + process can send and + have pending at + receiver(s) at a + time +_SC_SPAWN _POSIX_SPAWN Supports Spawn option +_SC_SPIN_LOCKS _POSIX_SPIN_LOCKS Supports Spin Locks + option +_SC_STACK_PROT Default stack + protection +_SC_STREAM_MAX STREAM_MAX Number of streams + one process can + have open at a time +_SC_SYMLOOP_MAX _POSIX_SYMLOOP_MAX Max number of symbolic + links that can be + reliably traversed in + the resolution of a + pathname in the absence + of a loop +_SC_SYNCHRONIZED_IO _POSIX_SYNCHRONIZED_IO Supports + Synchronized I/O +_SC_THREAD_ATTR_ _POSIX_THREAD_ATTR_ Supports Thread + STACKADDR STACKADDR Stack Address + Attribute option +_SC_THREAD_ATTR_ _POSIX_THREAD_ATTR_ Supports Thread + STACKSIZE STACKSIZE Stack Size + Attribute option +_SC_THREAD_DESTRUCTOR_ PTHREAD_DESTRUCTOR_ Number attempts made + ITERATIONS ITERATIONS to destroy thread- + specific data on + thread exit +_SC_THREAD_KEYS_MAX PTHREAD_KEYS_MAX Max number of data + keys per process +_SC_THREAD_PRIO_ _POSIX_THREAD_PRIO_ Supports Priority + INHERIT INHERIT Inheritance option +_SC_THREAD_PRIO_ _POSIX_THREAD_PRIO_ Supports Priority + PROTECT PROTECT Protection option +_SC_THREAD_PRIORITY_ _POSIX_THREAD_PRIORITY_ Supports Thread + SCHEDULING SCHEDULING Execution + Scheduling option +_SC_THREAD_PROCESS_ _POSIX_THREAD_PROCESS_ Supports + SHARED SHARED Process-Shared + Synchronization + option +_SC_THREAD_SAFE_ _POSIX_THREAD_SAFE_ Supports Thread-Safe + FUNCTIONS FUNCTIONS Functions option +_SC_THREAD_STACK_MIN PTHREAD_STACK_MIN Min byte size of + thread stack storage +_SC_THREAD_THREADS_MAX PTHREAD_THREADS_MAX Max number of + threads per process +_SC_THREADS _POSIX_THREADS Supports Threads + option +_SC_TIMEOUTS _POSIX_TIMEOUTS Supports Timeouts + option +_SC_TIMER_MAX TIMER_MAX Max number of timer + per process + supported +_SC_TIMERS _POSIX_TIMERS Supports Timers +_SC_TTY_NAME_MAX TTYNAME_MAX Max length of tty + device name +_SC_TZNAME_MAX TZNAME_MAX Max number of bytes + supported for name + of a time zone +_SC_V6_ILP32_OFF32 _POSIX_V6_ILP32_OFF32 Supports X/Open + ILP32 w/32-bit + offset build + environment +_SC_V6_ILP32_OFFBIG _POSIX_V6_ILP32_OFFBIG Supports X/Open + ILP32 w/64-bit + offset build + environment +_SC_V6_LP64_OFF64 _POSIX_V6_LP64_OFF64 Supports X/Open + LP64 w/64-bit + offset build + environment +_SC_V6_LPBIG_OFFBIG _POSIX_V6_LPBIG_OFFBIG Same as + _SC_V6_LP64_OFF64 +_SC_VERSION _POSIX_VERSION POSIX.1 version + supported +_SC_XBS5_ILP32_OFF32 _XBS_ILP32_OFF32 Indicates support + for X/Open ILP32 + w/32-bit offset + build environment +_SC_XBS5_ILP32_OFFBIG _XBS5_ILP32_OFFBIG Indicates support + for X/Open ILP32 + w/64-bit offset + build environment +_SC_XBS5_LP64_OFF64 _XBS5_LP64_OFF64 Indicates support of + X/Open LP64, + 64-bit offset + build environment +_SC_XBS5_LPBIG_OFFBIG _XBS5_LP64_OFF64 Same as + _SC_XBS5_LP64_OFF64 +_SC_XOPEN_CRYPT _XOPEN_CRYPT Supports X/Open + Encryption Feature + Group +_SC_XOPEN_ENH_I18N _XOPEN_ENH_I18N Supports X/Open + Enhanced + Internationalization + Feature Group +_SC_XOPEN_LEGACY _XOPEN_LEGACY Supports X/Open + Legacy Feature Group +_SC_XOPEN_REALTIME _XOPEN_REALTIME Supports X/Open + POSIX Realtime + Feature Group +_SC_XOPEN_REALTIME_ _XOPEN_REALTIME_THREADS Supports X/Open + THREADS POSIX Reatime + Threads Feature + Group +_SC_XOPEN_SHM _XOPEN_SHM Supports X/Open + Shared Memory + Feature Group +_SC_XOPEN_STREAMS _POSIX_XOPEN_STREAMS Supports XSI Streams + option group +_SC_XOPEN_UNIX _XOPEN_UNIX Supports X/Open CAE + Specification, + August 1994, System + Interfaces and + Headers, Issue 4, + Version 2 +_SC_XOPEN_VERSION _XOPEN_VERSION Integer value + indicates version of + X/Open Portability + Guide to which + implementation + conforms +_SC_XOPEN_XCU_VERSION _XOPEN_XCU_VERSION Integer value + indicates version of + XCU specification to + which implementation + conforms +.fi +.in -2 +.sp + +.sp +.LP +The following options are not supported and return \(mi1: +.sp + +.sp +.TS +tab(); +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fB_SC_2_PBS\fR\fB_POSIX2_PBS\fR +\fB_SC_2_PBS_ACCOUNTING\fR\fB_POSIX2_PBS_ACCOUNTING\fR +\fB_SC_2_PBS_CHECKPOINT\fR\fB_POSIX2_PBS_CHECKPOINT\fR +\fB_SC_2_PBS_LOCATE\fR\fB_POSIX2_PBS_LOCATE\fR +\fB_SC_2_PBS_MESSAGE\fR\fB_POSIX2_PBS_MESSAGE\fR +\fB_SC_2_PBS_TRACK\fR\fB_POSIX2_PBS_TRACK\fR +\fB_SC_ADVISORY_INFO\fR\fB_POSIX_ADVISORY_INFO\fR +\fB_SC_CPUTIME\fR\fB_POSIX_CPUTIME\fR +\fB_SC_SPORADIC_SERVER\fR\fB_POSIX_SPORADIC_SERVER\fR +\fB_SC_SS_REPL_MAX\fR\fB_POSIX_SS_REPL_MAX\fR +\fB_SC_THREAD_CPUTIME\fR\fB_POSIX_THREAD_CPUTIME\fR +\fB_SC_THREAD_SPORADIC_SERVER\fR\fB_POSIX_THREAD_SPORADIC_SERVER\fR +\fB_SC_TRACE\fR\fB_POSIX_TRACE\fR +\fB_SC_TRACE_EVENT_FILTER\fR\fB_POSIX_TRACE_EVENT_FILTER\fR +\fB_SC_TRACE_EVENT_NAME_MAX\fR\fB_POSIX_TRACE_EVENT_NAME_MAX\fR +\fB_SC_TRACE_INHERIT\fR\fB_POSIX_TRACE_INHERIT\fR +\fB_SC_TRACE_LOG\fR\fB_POSIX_TRACE_LOG\fR +\fB_SC_TRACE_NAME_MAX\fR\fB_POSIX_TRACE_NAME_MAX\fR +\fB_SC_TRACE_SYS_MAX\fR\fB_POSIX_TRACE_SYS_MAX\fR +\fB_SC_TRACE_USER_EVENT_MAX\fR\fB_POSIX_TRACE_USER_EVENT_MAX\fR +\fB_SC_TYPED_MEMORY_OBJECTS\fR\fB_POSIX_TYPED_MEMORY_OBJECTS\fR +.TE + +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBsysconf()\fR returns the current variable value +on the system. The value returned will not be more restrictive than the +corresponding value described to the application when it was compiled with the +implementation's <\fBlimits.h\fR>, <\fBunistd.h\fR> or <\fBtime.h\fR>. With +only a few obvious exceptions such as \fB_SC_AVPHYS_PAGES\fR and +\fB_SC_NPROCESSORS_ONLN\fR, the value will not change during the lifetime of +the calling process. +.sp +.LP +If \fIname\fR is an invalid value, \fBsysconf()\fR returns \fB\(mi1\fR and sets +\fBerrno\fR to indicate the error. If the variable corresponding to \fIname\fR +is associated with functionality that is not supported by the system, +\fBsysconf()\fR returns \fB\(mi1\fR without changing the value of \fIerrno\fR. +.sp +.LP +Calling \fBsysconf()\fR with the following returns \fB\(mi1\fR without setting +\fBerrno\fR, because no maximum limit can be determined. The system supports at +least the minimum values and can support higher values depending upon system +resources. +.sp +.in +2 +.nf +Variable Minimum supported value +_SC_AIO_MAX _POSIX_AIO_MAX +_SC_ATEXIT_MAX 32 +_SC_MQ_OPEN_MAX 32 +_SC_THREAD_THREADS_MAX _POSIX_THREAD_THREADS_MAX +_SC_THREAD_KEYS_MAX _POSIX_THREAD_KEYS_MAX +_SC_THREAD_DESTRUCTOR_ITERATIONS _POSIX_THREAD_DESTRUCTOR_ITERATIONS +.fi +.in -2 + +.sp +.LP +The following SPARC and x86 platform variables return \fBEINVAL\fR: +.sp +.in +2 +.nf +_SC_COHER_BLKSZ _SC_DCACHE_ASSOC +_SC_DCACHE_BLKSZ _SC_DCACHE_LINESZ +_SC_DCACHE_SZ _SC_DCACHE_TBLKSZ +_SC_ICACHE_ASSOC _SC_ICACHE_BLKSZ +_SC_ICACHE_LINESZ _SC_ICACHE_SZ +_SC_SPLIT_CACHE +.fi +.in -2 + +.SH ERRORS +.sp +.LP +The \fBsysconf()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of the \fIname\fR argument is invalid. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitectureSPARC and x86 +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe, Async-Signal-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBpooladm\fR(1M), \fBzoneadm\fR(1M), \fBfpathconf\fR(2), \fBseteuid\fR(2), +\fBsetrlimit\fR(2), \fBconfstr\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +A call to \fBsetrlimit()\fR can cause the value of \fBOPEN_MAX\fR to change. +.sp +.LP +Multiplying \fBsysconf\fR(\fB_SC_PHYS_PAGES\fR) or +\fBsysconf\fR(\fB_SC_AVPHYS_PAGES\fR) by \fBsysconf\fR(\fB_SC_PAGESIZE\fR) to +determine memory amount in bytes can exceed the maximum values representable in +a 32-bit signed or unsigned integer. +.sp +.LP +The value of \fBCLK_TCK\fR can be variable and it should not be assumed that +\fBCLK_TCK\fR is a compile-time constant. +.sp +.LP +If the caller is in a non-global zone and the pools facility is active, +\fBsysconf\fR(\fB_SC_NPROCESSORS_CONF\fR) and +\fBsysconf\fR(\fB_SC_NPROCESSORS_ONLN\fR) return the number of processors in +the processor set of the pool to which the zone is bound. diff --git a/usr/src/man/man3c/syslog.3c b/usr/src/man/man3c/syslog.3c new file mode 100644 index 0000000000..68f30fb011 --- /dev/null +++ b/usr/src/man/man3c/syslog.3c @@ -0,0 +1,566 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 1983 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical +.\" and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.TH syslog 3C "16 Mar 2009" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +syslog, openlog, closelog, setlogmask \- control system log +.SH SYNOPSIS +.LP +.nf +#include <syslog.h> + +\fBvoid\fR \fBopenlog\fR(\fBconst char *\fR\fIident\fR, \fBint\fR \fIlogopt\fR, \fBint\fR \fIfacility\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBsyslog\fR(\fBint\fR \fIpriority\fR, \fBconst char *\fR\fImessage\fR, \fB\&.../*\fR \fIarguments\fR */); +.fi + +.LP +.nf +\fBvoid\fR \fBcloselog\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBint\fR \fBsetlogmask\fR(\fBint\fR \fImaskpri\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsyslog()\fR function sends a message to \fBsyslogd\fR(1M), which, +depending on the configuration of \fB/etc/syslog.conf\fR, logs it in an +appropriate system log, writes it to the system console, forwards it to a list +of users, or forwards it to \fBsyslogd\fR on another host over the network. +The logged message includes a message header and a message body. The message +header consists of a facility indicator, a severity level indicator, a +timestamp, a tag string, and optionally the process ID. +.sp +.LP +The message body is generated from the \fImessage\fR and following arguments in +the same manner as if these were arguments to \fBprintf\fR(3UCB), except that +occurrences of \fB%m\fR in the format string pointed to by the \fImessage\fR +argument are replaced by the error message string associated with the current +value of \fBerrno\fR. A trailing \fBNEWLINE\fR character is added if needed. +.sp +.LP +Symbolic constants for use as values of the \fIlogopt\fR, \fIfacility\fR, +\fIpriority\fR, and \fImaskpri\fR arguments are defined in the <\fBsyslog.h\fR> +header. +.sp +.LP +Values of the \fIpriority\fR argument are formed by ORing together a +\fIseverity level\fR value and an optional \fIfacility\fR value. If no +facility value is specified, the current default facility value is used. +.sp +.LP +Possible values of severity level include, in decreasing order: +.sp +.ne 2 +.mk +.na +\fB\fBLOG_EMERG\fR\fR +.ad +.RS 15n +.rt +A panic condition. This is normally broadcast to all users. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOG_ALERT\fR\fR +.ad +.RS 15n +.rt +A condition that should be corrected immediately, such as a corrupted system +database. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOG_CRIT\fR\fR +.ad +.RS 15n +.rt +Critical conditions, such as hard device errors. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOG_ERR\fR\fR +.ad +.RS 15n +.rt +Errors. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOG_WARNING\fR\fR +.ad +.RS 15n +.rt +Warning messages. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOG_NOTICE\fR\fR +.ad +.RS 15n +.rt +Conditions that are not error conditions, but that may require special +handling. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOG_INFO\fR\fR +.ad +.RS 15n +.rt +Informational messages. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOG_DEBUG\fR\fR +.ad +.RS 15n +.rt +Messages that contain information normally of use only when debugging a +program. +.RE + +.sp +.LP +The facility indicates the application or system component generating the +message. Possible facility values include: +.sp +.ne 2 +.mk +.na +\fB\fBLOG_KERN\fR\fR +.ad +.RS 14n +.rt +Messages generated by the kernel. These cannot be generated by any user +processes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOG_USER\fR\fR +.ad +.RS 14n +.rt +Messages generated by random user processes. This is the default facility +identifier if none is specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOG_MAIL\fR\fR +.ad +.RS 14n +.rt +The mail system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOG_DAEMON\fR\fR +.ad +.RS 14n +.rt +System daemons, such as \fBin.ftpd\fR(1M). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOG_AUTH\fR\fR +.ad +.RS 14n +.rt +The authentication / security / authorization system: \fBlogin\fR(1), +\fBsu\fR(1M), \fBgetty\fR(1M). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOG_LPR\fR\fR +.ad +.RS 14n +.rt +The line printer spooling system: \fBlpr\fR(1B), \fBlpc\fR(1B). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOG_NEWS\fR\fR +.ad +.RS 14n +.rt +Designated for the \fBUSENET\fR network news system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOG_UUCP\fR\fR +.ad +.RS 14n +.rt +Designated for the \fBUUCP\fR system; it does not currently use \fBsyslog()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOG_CRON\fR\fR +.ad +.RS 14n +.rt +The \fBcron\fR/\fBat\fR facility; \fBcrontab\fR(1), \fBat\fR(1), +\fBcron\fR(1M). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOG_AUDIT\fR\fR +.ad +.RS 14n +.rt +The audit facility, for example, \fBauditd\fR(1M). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOG_LOCAL0\fR\fR +.ad +.RS 14n +.rt +Designated for local use. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOG_LOCAL1\fR\fR +.ad +.RS 14n +.rt +Designated for local use. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOG_LOCAL2\fR\fR +.ad +.RS 14n +.rt +Designated for local use. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOG_LOCAL3\fR\fR +.ad +.RS 14n +.rt +Designated for local use. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOG_LOCAL4\fR\fR +.ad +.RS 14n +.rt +Designated for local use. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOG_LOCAL5\fR\fR +.ad +.RS 14n +.rt +Designated for local use. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOG_LOCAL6\fR\fR +.ad +.RS 14n +.rt +Designated for local use. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOG_LOCAL7\fR\fR +.ad +.RS 14n +.rt +Designated for local use. +.RE + +.sp +.LP +The \fBopenlog()\fR function sets process attributes that affect subsequent +calls to \fBsyslog()\fR. The \fIident\fR argument is a string that is prepended +to every message. The \fBopenlog()\fR function uses the passed-in \fIident\fR +argument directly, rather than making a private copy of it. The \fIlogopt\fR +argument indicates logging options. Values for \fIlogopt\fR are constructed by +a bitwise-inclusive OR of zero or more of the following: +.sp +.ne 2 +.mk +.na +\fB\fBLOG_PID\fR\fR +.ad +.RS 14n +.rt +Log the process \fBID\fR with each message. This is useful for identifying +specific daemon processes (for daemons that fork). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOG_CONS\fR\fR +.ad +.RS 14n +.rt +Write messages to the system console if they cannot be sent to +\fBsyslogd\fR(1M). This option is safe to use in daemon processes that have no +controlling terminal, since \fBsyslog()\fR forks before opening the console. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOG_NDELAY\fR\fR +.ad +.RS 14n +.rt +Open the connection to \fBsyslogd\fR(1M) 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. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOG_ODELAY\fR\fR +.ad +.RS 14n +.rt +Delay open until \fBsyslog()\fR is called. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLOG_NOWAIT\fR\fR +.ad +.RS 14n +.rt +Do not wait for child processes that have been forked to log messages onto the +console. This option should be used by processes that enable notification of +child termination using \fBSIGCHLD\fR, since \fBsyslog()\fR may otherwise block +waiting for a child whose exit status has already been collected. +.RE + +.sp +.LP +The \fIfacility\fR 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 \fBLOG_USER\fR. +.sp +.LP +The \fBopenlog()\fR and \fBsyslog()\fR functions may allocate a file +descriptor. It is not necessary to call \fBopenlog()\fR prior to calling +\fBsyslog()\fR. +.sp +.LP +The \fBcloselog()\fR function closes any open file descriptors allocated by +previous calls to \fBopenlog()\fR or \fBsyslog()\fR. +.sp +.LP +The \fBsetlogmask()\fR function sets the log priority mask for the current +process to \fImaskpri\fR and returns the previous mask. If the \fImaskpri\fR +argument is 0, the current log mask is not modified. Calls by the current +process to \fBsyslog()\fR with a priority not set in \fImaskpri\fR are +rejected. The mask for an individual priority \fIpri\fR is calculated by the +macro \fBLOG_MASK(\fIpri\fR)\fR; the mask for all priorities up to and +including \fItoppri\fR is given by the macro \fBLOG_UPTO(\fItoppri\fR)\fR. The +default log mask allows all priorities to be logged. +.SH RETURN VALUES +.sp +.LP +The \fBsetlogmask()\fR function returns the previous log priority mask. The +\fBcloselog()\fR, \fBopenlog()\fR and \fBsyslog()\fR functions return no value. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH EXAMPLES +.LP +\fBExample 1 \fRExample of \fBLOG_ALERT\fR message. +.sp +.LP +This call logs a message at priority \fBLOG_ALERT\fR: + +.sp +.in +2 +.nf +\fBsyslog(LOG_ALERT, "who: internal error 23")\fR; +.fi +.in -2 +.sp + +.sp +.LP +The \fBFTP\fR daemon \fBftpd\fR would make this call to \fBopenlog()\fR to +indicate that all messages it logs should have an identifying string of +\fBftpd\fR, should be treated by \fBsyslogd\fR(1M) as other messages from +system daemons are, should include the process \fBID\fR of the process logging +the message: + +.sp +.in +2 +.nf +\fBopenlog("ftpd", LOG_PID, LOG_DAEMON)\fR; +.fi +.in -2 +.sp + +.sp +.LP +Then it would make the following call to \fBsetlogmask()\fR to indicate that +messages at priorities from \fBLOG_EMERG\fR through \fBLOG_ERR\fR should be +logged, but that no messages at any other priority should be logged: + +.sp +.in +2 +.nf +\fBsetlogmask(LOG_UPTO(LOG_ERR))\fR; +.fi +.in -2 +.sp + +.sp +.LP +Then, to log a message at priority \fBLOG_INFO\fR, it would make the following +call to \fBsyslog\fR: + +.sp +.in +2 +.nf +\fBsyslog(LOG_INFO, "Connection from host %d", CallingHost)\fR; +.fi +.in -2 +.sp + +.sp +.LP +A locally-written utility could use the following call to \fBsyslog()\fR to log +a message at priority \fBLOG_INFO\fR to be treated by \fBsyslogd\fR(1M) as +other messages to the facility \fBLOG_LOCAL2\fR are: + +.sp +.in +2 +.nf +\fBsyslog(LOG_INFO|LOG_LOCAL2, "error: %m")\fR; +.fi +.in -2 +.sp + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelSafe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBat\fR(1), \fBcrontab\fR(1), \fBlogger\fR(1), \fBlogin\fR(1), \fBlpc\fR(1B), +\fBlpr\fR(1B), \fBauditd\fR(1M), \fBcron\fR(1M), \fBgetty\fR(1M), +\fBin.ftpd\fR(1M), \fBsu\fR(1M), \fBsyslogd\fR(1M), \fBprintf\fR(3UCB), +\fBsyslog.conf\fR(4), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/system.3c b/usr/src/man/man3c/system.3c new file mode 100644 index 0000000000..11812da3f8 --- /dev/null +++ b/usr/src/man/man3c/system.3c @@ -0,0 +1,134 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH system 3C "14 Dec 2006" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +system \- issue a shell command +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBint\fR \fBsystem\fR(\fBconst char *\fR\fIstring\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsystem()\fR function causes \fIstring\fR to be given to the shell as +input, as if \fIstring\fR had been typed as a command at a terminal. The +invoker waits until the shell has completed, then returns the exit status of +the shell in the format specified by \fBwaitpid\fR(3C). +.sp +.LP +If \fIstring\fR is a null pointer, \fBsystem()\fR checks if the shell exists +and is executable. If the shell is available, \fBsystem()\fR returns a +non-zero value; otherwise, it returns \fB0\fR. The standard to which the +caller conforms determines which shell is used. See \fBstandards\fR(5). +.sp +.LP +The \fBsystem()\fR function sets the \fBSIGINT\fR and \fBSIGQUIT\fR signals to +be ignored, and blocks the \fBSIGCHLD\fR signal for the calling thread, while +waiting for the command to terminate. The \fBsystem()\fR function does not +affect the termination status of any child of the calling processes other than +the process it creates. +.sp +.LP +The termination status of the process created by the \fBsystem()\fR function is +not affected by the actions of other threads in the calling process (it is +invisible to \fBwait\fR(3C)) or by the disposition of the \fBSIGCHLD\fR signal +in the calling process, even if it is set to be ignored. No \fBSIGCHLD\fR +signal is sent to the process containing the calling thread when the command +terminates. +.SH RETURN VALUES +.sp +.LP +The \fBsystem()\fR function executes \fBposix_spawn\fR(3C) to create a child +process running the shell that in turn executes the commands in \fIstring\fR. +If \fBposix_spawn()\fR fails, \fBsystem()\fR returns \fB\(mi1\fR and sets +\fBerrno\fR to indicate the error; otherwise the exit status of the shell is +returned. +.SH ERRORS +.sp +.LP +The \fBsystem()\fR function may set \fBerrno\fR values as described by +\fBfork\fR(2), in particular: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +A resource control or limit on the total number of processes, tasks or LWPs +under execution by a single user, task, project, or zone has been exceeded, +or the total amount of system memory available is temporarily insufficient to +duplicate this process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +There is not enough swap space. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 10n +.rt +The {\fBPRIV_PROC_FORK\fR} privilege is not asserted in the effective set of +the calling process. +.RE + +.SH USAGE +.sp +.LP +The \fBsystem()\fR function manipulates the signal handlers for \fBSIGINT\fR +and \fBSIGQUIT\fR. It is therefore not safe to call \fBsystem()\fR in a +multithreaded process, since some other thread that manipulates these signal +handlers and a thread that concurrently calls \fBsystem()\fR can interfere with +each other in a destructive manner. If, however, no such other thread is +active, \fBsystem()\fR can safely be called concurrently from multiple threads. +See \fBpopen\fR(3C) for an alternative to \fBsystem()\fR that is thread-safe. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBksh\fR(1), \fBsh\fR(1), \fBpopen\fR(3C), \fBposix_spawn\fR(3C), +\fBwait\fR(3C), \fBwaitpid\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/tcdrain.3c b/usr/src/man/man3c/tcdrain.3c new file mode 100644 index 0000000000..c5a5a3db6f --- /dev/null +++ b/usr/src/man/man3c/tcdrain.3c @@ -0,0 +1,113 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH tcdrain 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +tcdrain \- wait for transmission of output +.SH SYNOPSIS +.LP +.nf +#include <termios.h> + +\fBint\fR \fBtcdrain\fR(\fBint\fR \fIfildes\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBtcdrain()\fR function waits until all output written to the object +referred to by \fIfildes\fR is transmitted. The \fIfildes\fR argument is an +open file descriptor associated with a terminal. +.sp +.LP +Any attempts to use \fBtcdrain()\fR from a process which is a member of a +background process group on a \fIfildes\fR associated with its controlling +terminal, will cause the process group to be sent a \fBSIGTTOU\fR signal. If +the calling process is blocking or ignoring \fBSIGTTOU\fR signals, the process +is allowed to perform the operation, and no signal is sent. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBtcdrain()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIfildes\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 10n +.rt +A signal interrupted \fBtcdrain()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTTY\fR\fR +.ad +.RS 10n +.rt +The file associated with \fIfildes\fR is not a terminal. +.RE + +.sp +.LP +The \fBtcdrain()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 7n +.rt +The process group of the writing process is orphaned, and the writing process +is not ignoring or blocking \fBSIGTTOU\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe, and Async-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBtcflush\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5), \fBtermio\fR(7I) diff --git a/usr/src/man/man3c/tcflow.3c b/usr/src/man/man3c/tcflow.3c new file mode 100644 index 0000000000..abe585febf --- /dev/null +++ b/usr/src/man/man3c/tcflow.3c @@ -0,0 +1,146 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH tcflow 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +tcflow \- suspend or restart the transmission or reception of data +.SH SYNOPSIS +.LP +.nf +#include <termios.h> + +\fBint\fR \fBtcflow\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIaction\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBtcflow()\fR function suspends transmission or reception of data on the +object referred to by \fIfildes\fR, depending on the value of \fIaction\fR. The +\fIfildes\fR argument is an open file descriptor associated with a terminal. +.RS +4 +.TP +.ie t \(bu +.el o +If \fIaction\fR is \fBTCOOFF\fR, output is suspended. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If \fIaction\fR is \fBTCOON\fR, suspended output is restarted. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If \fIaction\fR is \fBTCIOFF\fR, the system transmits a \fBSTOP\fR character, +which is intended to cause the terminal device to stop transmitting data to the +system. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If \fIaction\fR is \fBTCION\fR, the system transmits a \fBSTART\fR character, +which is intended to cause the terminal device to start transmitting data to +the system. +.RE +.sp +.LP +The default on the opening of a terminal file is that neither its input nor its +output are suspended. +.sp +.LP +Attempts to use \fBtcflow()\fR from a process which is a member of a background +process group on a \fIfildes\fR associated with its controlling terminal, will +cause the process group to be sent a \fBSIGTTOU\fR signal. If the calling +process is blocking or ignoring \fBSIGTTOU\fR signals, the process is allowed +to perform the operation, and no signal is sent. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBtcflow()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIfildes\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIaction\fR argument is not a supported value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTTY\fR\fR +.ad +.RS 10n +.rt +The file associated with \fIfildes\fR is not a terminal. +.RE + +.sp +.LP +The \fBtcflow()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 7n +.rt +The process group of the writing process is orphaned, and the writing process +is not ignoring or blocking \fBSIGTTOU\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe, and Async-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBtcsendbreak\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5), +\fBtermio\fR(7I) diff --git a/usr/src/man/man3c/tcflush.3c b/usr/src/man/man3c/tcflush.3c new file mode 100644 index 0000000000..6c506853c0 --- /dev/null +++ b/usr/src/man/man3c/tcflush.3c @@ -0,0 +1,135 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH tcflush 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +tcflush \- flush non-transmitted output data, non-read input data or both +.SH SYNOPSIS +.LP +.nf +#include <termios.h> + +\fBint\fR \fBtcflush\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIqueue_selector\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +Upon successful completion, \fBtcflush()\fR discards data written to the object +referred to by \fIfildes\fR (an open file descriptor associated with a +terminal) but not transmitted, or data received but not read, depending on the +value of \fIqueue_selector\fR: +.RS +4 +.TP +.ie t \(bu +.el o +If \fIqueue_selector\fR is \fBTCIFLUSH\fR it flushes data received but not +read. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If \fIqueue_selector\fR is \fBTCOFLUSH\fR it flushes data written but not +transmitted. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If \fIqueue_selector\fR is \fBTCIOFLUSH\fR it flushes both data received but +not read and data written but not transmitted. +.RE +.sp +.LP +Attempts to use \fBtcflush()\fR from a process which is a member of a +background process group on a \fIfildes\fR associated with its controlling +terminal, will cause the process group to be sent a \fBSIGTTOU\fR signal. If +the calling process is blocking or ignoring \fBSIGTTOU\fR signals, the process +is allowed to perform the operation, and no signal is sent. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBtcflush()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIfildes\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIqueue_selector\fR argument is not a supported value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTTY\fR\fR +.ad +.RS 10n +.rt +The file associated with \fIfildes\fR is not a terminal. +.RE + +.sp +.LP +The \fBtcflush()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 7n +.rt +The process group of the writing process is orphaned, and the writing process +is not ignoring or blocking \fBSIGTTOU\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe, and Async-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBtcdrain\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5), \fBtermio\fR(7I) diff --git a/usr/src/man/man3c/tcgetattr.3c b/usr/src/man/man3c/tcgetattr.3c new file mode 100644 index 0000000000..5e383ac5eb --- /dev/null +++ b/usr/src/man/man3c/tcgetattr.3c @@ -0,0 +1,95 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH tcgetattr 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +tcgetattr \- get the parameters associated with the terminal +.SH SYNOPSIS +.LP +.nf +#include <termios.h> + +\fBint\fR \fBtcgetattr\fR(\fBint\fR \fIfildes\fR, \fBstruct termios *\fR\fItermios_p\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBtcgetattr()\fR function gets the parameters associated with the terminal +referred to by \fIfildes\fR and stores them in the \fBtermios\fR structure (see +\fBtermio\fR(7I)) referenced by \fItermios_p\fR. The \fIfildes\fR argument is +an open file descriptor associated with a terminal. +.sp +.LP +The \fItermios_p\fR argument is a pointer to a \fBtermios\fR structure. +.sp +.LP +The \fBtcgetattr()\fR operation is allowed from any process. +.sp +.LP +If the terminal device supports different input and output baud rates, the baud +rates stored in the \fBtermios\fR structure returned by \fBtcgetattr()\fR +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 is the actual baud +rate. If the terminal device does not support split baud rates, the input baud +rate stored in the \fBtermios\fR structure will be 0. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBtcgetattr()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIfildes\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTTY\fR\fR +.ad +.RS 10n +.rt +The file associated with \fIfildes\fR is not a terminal. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe, and Async-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBtcsetattr\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5), \fBtermio\fR(7I) diff --git a/usr/src/man/man3c/tcgetpgrp.3c b/usr/src/man/man3c/tcgetpgrp.3c new file mode 100644 index 0000000000..c4ec04d722 --- /dev/null +++ b/usr/src/man/man3c/tcgetpgrp.3c @@ -0,0 +1,94 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH tcgetpgrp 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +tcgetpgrp \- get foreground process group ID +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <unistd.h> + +\fBpid_t\fR \fBtcgetpgrp\fR(\fBint\fR \fIfildes\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBtcgetpgrp()\fR function will return the value of the process group +\fBID\fR of the foreground process group associated with the terminal. +.sp +.LP +If there is no foreground process group, \fBtcgetpgrp()\fR returns a value +greater than 1 that does not match the process group \fBID\fR of any existing +process group. +.sp +.LP +The \fBtcgetpgrp()\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 VALUES +.sp +.LP +Upon successful completion, \fBtcgetpgrp()\fR returns the value of the process +group \fBID\fR of the foreground process associated with the terminal. +Otherwise, \fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the +error. +.SH ERRORS +.sp +.LP +The \fBtcgetpgrp()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIfildes\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTTY\fR\fR +.ad +.RS 10n +.rt +The calling process does not have a controlling terminal, or the file is not +the controlling terminal. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe, and Async-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBsetpgid\fR(2), \fBsetsid\fR(2), \fBtcsetpgrp\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5), \fBtermio\fR(7I) diff --git a/usr/src/man/man3c/tcgetsid.3c b/usr/src/man/man3c/tcgetsid.3c new file mode 100644 index 0000000000..8d965b9a48 --- /dev/null +++ b/usr/src/man/man3c/tcgetsid.3c @@ -0,0 +1,91 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH tcgetsid 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +tcgetsid \- get process group ID for session leader for controlling terminal +.SH SYNOPSIS +.LP +.nf +#include <termios.h> + +\fBpid_t\fR \fBtcgetsid\fR(\fBint\fR \fIfildes\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBtcgetsid()\fR function obtains the process group \fBID\fR of the session +for which the terminal specified by \fIfildes\fR is the controlling terminal. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBtcgetsid()\fR returns the process group \fBID\fR +associated with the terminal. Otherwise, a value of \fB(pid_t)\(mi1\fR is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBtcgetsid()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 10n +.rt +The \fIfildes\fR argument is not associated with a controlling terminal. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIfildes\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTTY\fR\fR +.ad +.RS 10n +.rt +The file associated with \fIfildes\fR is not a terminal. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBstandards\fR(5), \fBtermio\fR(7I) diff --git a/usr/src/man/man3c/tcsendbreak.3c b/usr/src/man/man3c/tcsendbreak.3c new file mode 100644 index 0000000000..c3f688aff3 --- /dev/null +++ b/usr/src/man/man3c/tcsendbreak.3c @@ -0,0 +1,113 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH tcsendbreak 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +tcsendbreak \- send a ``break'' for a specific duration +.SH SYNOPSIS +.LP +.nf +#include <termios.h> + +\fBint\fR \fBtcsendbreak\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIduration\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fIfildes\fR argument is an open file descriptor associated with a +terminal. +.sp +.LP +If the terminal is using asynchronous serial data transmission, +\fBtcsendbreak()\fR will cause transmission of a continuous stream of +zero-valued bits for a specific duration. If \fIduration\fR is 0, it will +cause transmission of zero-valued bits for at least 0.25 seconds, and not more +than 0.5 seconds. If \fIduration\fR is not 0, it behaves in a way similar to +\fBtcdrain\fR(3C). +.sp +.LP +If the terminal is not using asynchronous serial data transmission, it sends +data to generate a break condition or returns without taking any action. +.sp +.LP +Attempts to use \fBtcsendbreak()\fR from a process which is a member of a +background process group on a \fIfildes\fR associated with its controlling +terminal will cause the process group to be sent a \fBSIGTTOU\fR signal. If the +calling process is blocking or ignoring \fBSIGTTOU\fR signals, the process is +allowed to perform the operation, and no signal is sent. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBtcsendbreak()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIfildes\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTTY\fR\fR +.ad +.RS 10n +.rt +The file associated with \fIfildes\fR is not a terminal. +.RE + +.sp +.LP +The \fBtcsendbreak()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 7n +.rt +The process group of the writing process is orphaned, and the writing process +is not ignoring or blocking \fBSIGTTOU\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe, and Async-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBtcdrain\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5), \fBtermio\fR(7I) diff --git a/usr/src/man/man3c/tcsetattr.3c b/usr/src/man/man3c/tcsetattr.3c new file mode 100644 index 0000000000..ba0866ed53 --- /dev/null +++ b/usr/src/man/man3c/tcsetattr.3c @@ -0,0 +1,195 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH tcsetattr 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +tcsetattr \- set the parameters associated with the terminal +.SH SYNOPSIS +.LP +.nf +#include <termios.h> + +\fBint\fR \fBtcsetattr\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIoptional_actions\fR, + \fBconst struct termios *\fR\fItermios_p\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBtcsetattr()\fR function sets the parameters associated with the terminal +referred to by the open file descriptor \fIfildes\fR (an open file descriptor +associated with a terminal) from the \fBtermios\fR structure (see +\fBtermio\fR(7I)) referenced by \fItermios_p\fR as follows: +.RS +4 +.TP +.ie t \(bu +.el o +If \fIoptional_actions\fR is \fBTCSANOW\fR, the change will occur immediately. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If \fIoptional_actions\fR is \fBTCSADRAIN\fR, the change will occur after all +output written to \fIfildes\fR is transmitted. This function should be used +when changing parameters that affect output. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If \fIoptional_actions\fR is \fBTCSAFLUSH\fR, the change will occur after all +output written to \fIfildes\fR is transmitted, and all input so far received +but not read will be discarded before the change is made. +.RE +.sp +.LP +If the output baud rate stored in the \fBtermios\fR structure pointed to by +\fItermios_p\fR is the zero baud rate, B0, the modem control lines will no +longer be asserted. Normally, this will disconnect the line. +.sp +.LP +If the input baud rate stored in the \fBtermios\fR structure pointed to by +\fItermios_p\fR is 0, the input baud rate given to the hardware will be the +same as the output baud rate stored in the \fBtermios\fR structure. +.sp +.LP +The \fBtcsetattr()\fR function will 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 will set all the attributes that implementation +supports as requested and leave all the attributes not supported by the +implementation unchanged. If no part of the request can be honoured, it will +return \fB\(mi1\fR and set \fBerrno\fR to \fBEINVAL\fR. If the input and output +baud rates differ and are a combination that is not supported, neither baud +rate is changed. A subsequent call to \fBtcgetattr\fR(3C) will return the +actual state of the terminal device (reflecting both the changes made and not +made in the previous \fBtcsetattr()\fR call). The \fBtcsetattr()\fR function +will not change the values in the \fBtermios\fR structure whether or not it +actually accepts them. +.sp +.LP +The effect of \fBtcsetattr()\fR is undefined if the value of the \fBtermios\fR +structure pointed to by \fItermios_p\fR was not derived from the result of a +call to \fBtcgetattr\fR(3C) on \fIfildes\fR; an application should modify only +fields and flags defined by this document between the call to +\fBtcgetattr\fR(3C) and \fBtcsetattr()\fR, leaving all other fields and flags +unmodified. +.sp +.LP +No actions defined by this document, other than a call to \fBtcsetattr()\fR or +a close of the last file descriptor in the system associated with this terminal +device, will cause any of the terminal attributes defined by this document to +change. +.sp +.LP +Attempts to use \fBtcsetattr()\fR from a process which is a member of a +background process group on a \fIfildes\fR associated with its controlling +terminal, will cause the process group to be sent a \fBSIGTTOU\fR signal. If +the calling process is blocking or ignoring \fBSIGTTOU\fR signals, the process +is allowed to perform the operation, and no signal is sent. +.SH USAGE +.sp +.LP +If trying to change baud rates, applications should call \fBtcsetattr()\fR then +call \fBtcgetattr\fR(3C) in order to determine what baud rates were actually +selected. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBtcsetattr()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIfildes\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 10n +.rt +A signal interrupted \fBtcsettattr()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIoptional_actions\fR argument is not a supported value, or an attempt was +made to change an attribute represented in the \fBtermios\fR structure to an +unsupported value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTTY\fR\fR +.ad +.RS 10n +.rt +The file associated with \fIfildes\fR is not a terminal. +.RE + +.sp +.LP +The \fBtcsetattr()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 7n +.rt +The process group of the writing process is orphaned, and the writing process +is not ignoring or blocking \fBSIGTTOU\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe, and Async-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBcfgetispeed\fR(3C), \fBtcgetattr\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5), \fBtermio\fR(7I) diff --git a/usr/src/man/man3c/tcsetpgrp.3c b/usr/src/man/man3c/tcsetpgrp.3c new file mode 100644 index 0000000000..bb4161b0f8 --- /dev/null +++ b/usr/src/man/man3c/tcsetpgrp.3c @@ -0,0 +1,124 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH tcsetpgrp 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +tcsetpgrp \- set foreground process group ID +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <unistd.h> + +\fBint\fR \fBtcsetpgrp\fR(\fBint\fR \fIfildes\fR, \fBpid_t\fR \fIpgid_id\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +If the process has a controlling terminal, \fBtcsetpgrp()\fR will set the +foreground process group \fBID\fR associated with the terminal to +\fIpgid_id\fR. The file associated with \fIfildes\fR must be the controlling +terminal of the calling process and the controlling terminal must be currently +associated with the session of the calling process. The value of \fIpgid_id\fR +must match a process group \fBID\fR of a process in the same session as the +calling process. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBtcsetpgrp()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIfildes\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +This implementation does not support the value in the \fIpgid_id\fR argument. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTTY\fR\fR +.ad +.RS 10n +.rt +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. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 10n +.rt +The process is not ignoring or holding \fBSIGTTOU\fR and is a member of an +orphaned process group. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 10n +.rt +The value of \fIpgid_id\fR does not match the process group \fBID\fR of a +process in the same session as the calling process. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe, and Async-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBtcgetpgrp\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5), \fBtermio\fR(7I) diff --git a/usr/src/man/man3c/tell.3c b/usr/src/man/man3c/tell.3c new file mode 100644 index 0000000000..e577b1d510 --- /dev/null +++ b/usr/src/man/man3c/tell.3c @@ -0,0 +1,94 @@ +'\" te +.\" Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH tell 3C "28 Jan 1998" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +tell \- return a file offset for a file descriptor +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> + +\fBoff_t\fR \fBtell\fR(\fBint\fR \fIfd\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBtell()\fR function obtains the current value of the file-position +indicator for the file descriptor \fIfd\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBtell()\fR returns the current value of the +file-position indicator for \fIfd\fR measured in bytes from the beginning of +the file. +.sp +.LP +Otherwise, it returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBtell()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 13n +.rt +The file descriptor \fIfd\fR is not an open file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOVERFLOW\fR\fR +.ad +.RS 13n +.rt +The current file offset cannot be represented correctly in an object of type +\fBoff_t\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBESPIPE\fR\fR +.ad +.RS 13n +.rt +The file descriptor \fIfd\fR is associated with a pipe or FIFO. +.RE + +.SH USAGE +.sp +.LP +The \fBtell()\fR function is equivalent to \fBlseek(\fR\fIfd\fR\fB, 0, +SEEK_CUR)\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlseek\fR(2), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/telldir.3c b/usr/src/man/man3c/telldir.3c new file mode 100644 index 0000000000..8ac5e2ec40 --- /dev/null +++ b/usr/src/man/man3c/telldir.3c @@ -0,0 +1,75 @@ +'\" te +.\" Copyright (c) 1999, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH telldir 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +telldir \- current location of a named directory stream +.SH SYNOPSIS +.LP +.nf +#include <dirent.h> + +\fBlong int\fR \fBtelldir\fR(\fBDIR *\fR\fIdirp\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBtelldir()\fR function obtains the current location associated with the +directory stream specified by \fIdirp\fR. +.sp +.LP +If the most recent operation on the directory stream was a \fBseekdir\fR(3C), +the directory position returned from the \fBtelldir()\fR is the same as that +supplied as a \fIloc\fR argument for \fBseekdir()\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBtelldir()\fR returns the current location of the +specified directory stream. +.SH ERRORS +.sp +.LP +The \fBtelldir()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEOVERFLOW\fR\fR +.ad +.RS 13n +.rt +The current location of the directory cannot be stored in an object of type +\fBlong\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBopendir\fR(3C), \fBreaddir\fR(3C), \fBseekdir\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/termios.3c b/usr/src/man/man3c/termios.3c new file mode 100644 index 0000000000..f1481b26e3 --- /dev/null +++ b/usr/src/man/man3c/termios.3c @@ -0,0 +1,100 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH termios 3C "5 Apr 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +termios \- general terminal interface +.SH SYNOPSIS +.LP +.nf +#include <termios.h> + +\fBint\fR \fBtcgetattr\fR(\fBint\fR \fIfildes\fR, \fBstruct termios *\fR\fItermios_p\fR); +.fi + +.LP +.nf +\fBint\fR \fBtcsetattr\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIoptional_actions\fR, + \fBconst struct termios *\fR\fItermios_p\fR); +.fi + +.LP +.nf +\fBint\fR \fBtcsendbreak\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIduration\fR); +.fi + +.LP +.nf +\fBint\fR \fBtcdrain\fR(\fBint\fR \fIfildes\fR); +.fi + +.LP +.nf +\fBint\fR \fBtcflush\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIqueue_selector\fR); +.fi + +.LP +.nf +\fBint\fR \fBtcflow\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIaction\fR); +.fi + +.LP +.nf +\fBspeed_t\fR \fBcfgetospeed\fR(\fBconst struct termios *\fR\fItermios_p\fR); +.fi + +.LP +.nf +\fBint\fR \fBcfsetospeed\fR(\fBstruct termios *\fR\fItermios_p\fR, \fBspeed_t\fR \fIspeed\fR); +.fi + +.LP +.nf +\fBspeed_t\fR \fBcfgetispeed\fR(\fBconst struct termios *\fR\fItermios_p\fR); +.fi + +.LP +.nf +\fBint\fR \fBcfsetispeed\fR(\fBstruct termios *\fR\fItermios_p\fR, \fBspeed_t\fR \fIspeed\fR); +.fi + +.LP +.nf +#include <sys/types.h> +#include <termios.h> + +\fBpid_t\fR \fBtcgetpgrp\fR(\fBint\fR \fIfildes\fR); +.fi + +.LP +.nf +\fBint\fR \fBtcsetpgrp\fR(\fBint\fR \fIfildes\fR, \fBpid_t\fR \fIpgid\fR); +.fi + +.LP +.nf +\fBpid_t\fR \fBtcgetsid\fR(\fBint\fR \fIfildes\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions describe a general terminal interface for controlling +asynchronous communications ports. A more detailed overview of the terminal +interface can be found in \fBtermio\fR(7I), which also describes an +\fBioctl\fR(2) interface that provides the same functionality. However, the +function interface described by these functions is the preferred user +interface. +.sp +.LP +Each of these functions is now described on a separate manual page. +.SH SEE ALSO +.sp +.LP +\fBioctl\fR(2), \fBcfgetispeed\fR(3C), \fBcfgetospeed\fR(3C), +\fBcfsetispeed\fR(3C), \fBcfsetospeed\fR(3C), \fBtcdrain\fR(3C), +\fBtcflow\fR(3C), \fBtcflush\fR(3C), \fBtcgetattr\fR(3C), \fBtcgetpgrp\fR(3C), +\fBtcgetsid\fR(3C), \fBtcsendbreak\fR(3C), \fBtcsetattr\fR(3C), +\fBtcgetpgrp\fR(3C), \fBtcsendbreak\fR(3C), \fBtermio\fR(7I) diff --git a/usr/src/man/man3c/thr_create.3c b/usr/src/man/man3c/thr_create.3c new file mode 100644 index 0000000000..428646027a --- /dev/null +++ b/usr/src/man/man3c/thr_create.3c @@ -0,0 +1,463 @@ +'\" te +.\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved. +.\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 1995 IEEE. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical +.\" and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH thr_create 3C "16 Mar 2009" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +thr_create \- create a thread +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR...[ \fIlibrary\fR... ] +#include <thread.h> + +\fBint\fR \fBthr_create\fR(\fBvoid *\fR\fIstack_base\fR, \fBsize_t\fR \fIstack_size\fR, + \fBvoid *(*\fR\fIstart_func\fR) (void*), \fBvoid *\fR\fIarg\fR, \fBlong\fR \fIflags\fR, + \fBthread_t *\fR\fInew_thread_ID\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +Thread creation adds a new thread of control to the current process. The +procedure \fBmain()\fR is a single thread of control. Each thread executes +concurrently with all other threads within the calling process and with other +threads from other active processes. +.sp +.LP +Although a newly created thread shares all of the calling process's global data +with the other threads in the process, it has its own set of attributes and +private execution stack. The new thread inherits the calling thread's signal +mask and scheduling priority. Pending signals for a new thread are not +inherited and will be empty. +.sp +.LP +The call to create a thread takes the address of a user-defined function, +specified by \fIstart_func\fR, as one of its arguments. This function is the +complete execution routine for the new thread. +.sp +.LP +The lifetime of a thread begins with the successful return from +\fBthr_create()\fR, which calls \fIstart_func\fR(\|) and ends with one of the +following: +.RS +4 +.TP +.ie t \(bu +.el o +the normal completion of \fIstart_func\fR(\|), +.RE +.RS +4 +.TP +.ie t \(bu +.el o +an explicit call to \fBthr_exit\fR(3C), or +.RE +.RS +4 +.TP +.ie t \(bu +.el o +the conclusion of the calling process (see \fBexit\fR(2)). +.RE +.sp +.LP +The new thread performs by calling the function defined by \fIstart_func\fR +with only one argument, \fIarg\fR. If more than one argument needs to be passed +to \fIstart_func\fR, the arguments can be packed into a structure, the address +of which can be passed to \fIarg\fR. +.sp +.LP +If \fIstart_func\fR returns, the thread terminates with the exit status set to +the \fIstart_func\fR return value (see \fBthr_exit\fR(3C)). +.sp +.LP +When the thread from which \fBmain()\fR originated returns, the effect is the +same as if an implicit call to \fBexit()\fR were made using the return value of +\fBmain()\fR as the exit status. This behavior differs from a \fIstart_func\fR +return. If \fBmain()\fR calls \fBthr_exit\fR(3C), only the \fBmain\fR thread +exits, not the entire process. +.sp +.LP +If the thread creation fails, a new thread is not created and the contents of +the location referenced by the pointer to the new thread are undefined. +.sp +.LP +The \fIflags\fR argument specifies which attributes are modifiable for the +created thread. The value in \fIflags\fR is determined by the bitwise +inclusive-OR of the following: +.sp +.ne 2 +.mk +.na +\fB\fBTHR_BOUND\fR \fR +.ad +.RS 18n +.rt +This flag is obsolete and is maintained for compatibility. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTHR_DETACHED\fR \fR +.ad +.RS 18n +.rt +This flag affects the detachstate attribute of the thread. The new thread is +created detached. The exit status of a detached thread is not accessible to +other threads. Its thread ID and other resources may be re-used as soon as the +thread terminates. \fBthr_join\fR(3C) will not wait for a detached thread. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTHR_NEW_LWP\fR \fR +.ad +.RS 18n +.rt +This flag is obsolete and is maintained for compatibility. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTHR_SUSPENDED\fR \fR +.ad +.RS 18n +.rt +This flag affects the suspended attribute of the thread. The new thread is +created suspended and will not execute \fIstart_func\fR until it is started by +\fBthr_continue()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTHR_DAEMON\fR \fR +.ad +.RS 18n +.rt +This flag affects the daemon attribute of the thread. In addition to being +created detached (\fBTHR_DAEMON\fR implies \fBTHR_DETACHED\fR), the thread is +marked as a daemon. Daemon threads do not interfere with the exit conditions +for a process. A process will terminate when the last non-daemon thread exits +or the process calls \fBexit\fR(2). Also, a thread that is waiting in +\fBthr_join\fR(3C) for any thread to terminate will return \fBEDEADLK\fR when +all remaining threads in the process are either daemon threads or other threads +waiting in \fBthr_join()\fR. Daemon threads are most useful in libraries that +want to use threads. +.RE + +.sp +.LP +Default thread creation: +.sp +.in +2 +.nf +thread_t tid; +void *start_func(void *), *arg; +thr_create(NULL, 0, start_func, arg, 0, &tid); +.fi +.in -2 + +.sp +.LP +Create a detached thread whose thread ID we do not care about: +.sp +.in +2 +.nf +thr_create(NULL, 0, start_func, arg, THR_DETACHED, NULL); +.fi +.in -2 + +.sp +.LP +If \fIstack_base\fR is not \fINULL\fR, the new thread uses the stack beginning +at the address specified by \fIstack_base\fR and continuing for +\fIstack_size\fR bytes, where \fIstack_size\fR must be greater than or equal to +\fBTHR_MIN_STACK\fR. If \fIstack_base\fR is \fINULL\fR, \fBthr_create()\fR +allocates a stack for the new thread with at least \fIstack_size\fR bytes. If +\fIstack_size\fR is 0, a default size is used. If \fIstack_size\fR is not 0, it +must be greater than or equal to \fBTHR_MIN_STACK\fR. See \fBNOTES\fR. +.sp +.LP +When \fInew_thread_ID\fR is not \fINULL\fR, it points to a location where the +\fBID\fR of the new thread is stored if \fBthr_create()\fR is successful. The +\fBID\fR is only valid within the calling process. +.SH RETURN VALUES +.sp +.LP +If successful, the \fBthr_create()\fR function returns \fB0\fR. Otherwise, an +error value is returned to indicate the error. +.SH ERRORS +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR \fR +.ad +.RS 11n +.rt +A resource control limit on the total number of threads in a process, task, +project, or zone has been exceeded or some system resource has been exceeded. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR \fR +.ad +.RS 11n +.rt +The \fIstack_base\fR argument is not \fINULL\fR and \fIstack_size\fR is less +than \fBTHR_MIN_STACK\fR, or the \fIstack_base\fR argument is \fINULL\fR and +\fIstack_size\fR is not \fB0\fR and is less than \fBTHR_MIN_STACK\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 11n +.rt +The system cannot allocate stack for the thread. +.RE + +.sp +.LP +The \fBthr_create()\fR function may use \fBmmap()\fR to allocate thread stacks +from \fBMAP_PRIVATE\fR, \fBMAP_NORESERVE\fR, and \fBMAP_ANON\fR memory mappings +if \fIstack_base\fR is \fINULL\fR, and consequently may return upon failure the +relevant error values returned by \fBmmap()\fR. See the \fBmmap\fR(2) manual +page for these error values. +.SH EXAMPLES +.sp +.LP +The following is an example of concurrency with multithreading. Since POSIX +threads and Solaris threads are fully compatible even within the same process, +this example uses \fBpthread_create()\fR if you execute \fBa.out 0\fR, or +\fBthr_create()\fR if you execute \fBa.out 1\fR. +.sp +.LP +Five threads are created that simultaneously perform a time-consuming function, +\fBsleep(\fR10\fB)\fR. If the execution of this process is timed, the results +will show that all five individual calls to sleep for ten-seconds completed +in about ten seconds, even on a uniprocessor. If a single-threaded process +calls \fBsleep(\fR10\fB)\fR five times, the execution time will be about +50-seconds. +.sp +.LP +The command-line to time this process is: +.sp +.LP +\fB/usr/bin/time\fR \fBa.out\fR \fB0\fR \fB(for\fR \fBPOSIX\fR \fBthreading)\fR +.sp +.LP +or +.sp +.LP +\fB/usr/bin/time\fR \fBa.out\fR \fB1\fR \fB(for\fR \fBSolaris\fR +\fBthreading)\fR +.LP +\fBExample 1 \fRAn example of concurrency with multithreading. +.sp +.in +2 +.nf +#define _REENTRANT /* basic 3-lines for threads */ +#include <pthread.h> +#include <thread.h> +#define NUM_THREADS 5 +#define SLEEP_TIME 10 + +void *sleeping(void *); /* thread routine */ +int i; +thread_t tid[NUM_THREADS]; /* array of thread IDs */ + +int +main(int argc, char *argv[]) +{ + if (argc == 1) { + printf("use 0 as arg1 to use pthread_create(\|)\en"); + printf("or use 1 as arg1 to use thr_create(\|)\en"); + return (1); + } + + switch (*argv[1]) { + case '0': /* POSIX */ + for ( i = 0; i < NUM_THREADS; i++) + pthread_create(&tid[i], NULL, sleeping, + (void *)SLEEP_TIME); + for ( i = 0; i < NUM_THREADS; i++) + pthread_join(tid[i], NULL); + break; + + case '1': /* Solaris */ + for ( i = 0; i < NUM_THREADS; i++) + thr_create(NULL, 0, sleeping, (void *)SLEEP_TIME, 0, + &tid[i]); + while (thr_join(0, NULL, NULL) == 0) + continue; + break; + } /* switch */ + printf("main(\|) reporting that all %d threads have + terminated\en", i); + return (0); +} /* main */ + +void * +sleeping(void *arg) +{ + int sleep_time = (int)arg; + printf("thread %d sleeping %d seconds ...\en", thr_self(\|), + sleep_time); + sleep(sleep_time); + printf("\enthread %d awakening\en", thr_self(\|)); + return (NULL); +} +.fi +.in -2 + +.sp +.LP +Had \fBmain()\fR not waited for the completion of the other threads (using +\fBpthread_join\fR(3C) or \fBthr_join\fR(3C)), it would have continued to +process concurrently until it reached the end of its routine and the entire +process would have exited prematurely (see \fBexit\fR(2)). + +.LP +\fBExample 2 \fRCreating a default thread with a new signal mask. +.sp +.LP +The following example demonstrates how to create a default thread with a new +signal mask. The \fInew_mask\fR argument is assumed to have a value different +from the creator's signal mask (\fIorig_mask\fR). The \fInew_mask\fR argument +is set to block all signals except for \fBSIGINT\fR. The creator's signal mask +is changed so that the new thread inherits a different mask, and is restored to +its original value after \fBthr_create()\fR returns. + +.sp +.LP +This example assumes that \fBSIGINT\fR is also unmasked in the creator. If it +is masked by the creator, then unmasking the signal opens the creator to this +signal. The other alternative is to have the new thread set its own signal +mask in its start routine. + +.sp +.in +2 +.nf +thread_t tid; +sigset_t new_mask, orig_mask; +int error; + +(void)sigfillset(&new_mask); +(void)sigdelset(&new_mask, SIGINT); +(void)thr_sigsetmask(SIG_SETMASK, &new_mask, &orig_mask); +error = thr_create(NULL, 0, do_func, NULL, 0, &tid); +(void)thr_sigsetmask(SIG_SETMASK, &orig_mask, NULL); +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBexit\fR(2), \fBgetrlimit\fR(2), \fBmmap\fR(2), \fBexit\fR(3C), +\fBsleep\fR(3C), \fBthr_exit\fR(3C), \fBthr_join\fR(3C), +\fBthr_min_stack\fR(3C), \fBthr_setconcurrency\fR(3C), \fBthr_suspend\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5), \fBthreads\fR(5) +.SH NOTES +.sp +.LP +Since multithreaded-application threads execute independently of each other, +their relative behavior is unpredictable. It is therefore possible for the +thread executing \fBmain()\fR to finish before all other user-application +threads. +.sp +.LP +Using \fBthr_join\fR(3C) in the following syntax, +.sp +.in +2 +.nf +while (thr_join(0, NULL, NULL) == 0) + continue; +.fi +.in -2 + +.sp +.LP +will cause the invoking thread (which may be \fBmain()\fR) to wait for the +termination of all non-daemon threads, excluding threads that are themselves +waiting in \fBthr_join()\fR; however, the second and third arguments to +\fBthr_join()\fR need not necessarily be \fINULL\fR. +.sp +.LP +A thread has not terminated until \fBthr_exit()\fR has finished. The only way +to determine this is by \fBthr_join()\fR. When \fBthr_join()\fR returns a +departed thread, it means that this thread has terminated and its resources are +reclaimable. For instance, if a user specified a stack to \fBthr_create()\fR, +this stack can only be reclaimed after \fBthr_join()\fR has reported this +thread as a departed thread. It is not possible to determine when a +\fIdetached\fR thread has terminated. A detached thread disappears without +leaving a trace. +.sp +.LP +Typically, thread stacks allocated by \fBthr_create()\fR begin on page +boundaries and any specified (a red-zone) size is rounded up to the next page +boundary. A page with no access permission is appended to the top of the stack +so that most stack overflows will result in a \fBSIGSEGV\fR signal being sent +to the offending thread. Thread stacks allocated by the caller are used as is. +.sp +.LP +Using a default stack size for the new thread, instead of passing a +user-specified stack size, results in much better \fBthr_create()\fR +performance. The default stack size for a user-thread is 1 megabyte in a +32-bit process and 2 megabyte in a 64-bit process. +.sp +.LP +A user-specified stack size must be greater than or equal to +\fBTHR_MIN_STACK\fR. A minimum stack size may not accommodate the stack frame +for the user thread function \fIstart_func\fR. If a stack size is specified, +it must accommodate \fIstart_func\fR requirements and the functions that it may +call in turn, in addition to the minimum requirement. +.sp +.LP +It is usually very difficult to determine the runtime stack requirements for a +thread. \fBTHR_MIN_STACK\fR specifies how much stack storage is required to +execute a trivial \fIstart_func\fR. The total runtime requirements for stack +storage are dependent on the storage required to do runtime linking, the amount +of storage required by library runtimes (like \fBprintf()\fR) that your thread +calls. Since these storage parameters are not known before the program runs, it +is best to use default stacks. If you know your runtime requirements or decide +to use stacks that are larger than the default, then it makes sense to specify +your own stacks. diff --git a/usr/src/man/man3c/thr_exit.3c b/usr/src/man/man3c/thr_exit.3c new file mode 100644 index 0000000000..ffed2a2ed9 --- /dev/null +++ b/usr/src/man/man3c/thr_exit.3c @@ -0,0 +1,117 @@ +'\" te +.\" Copyright (c) 2007 Sun Microsystems, Inc. All Rights Reserved +.\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 1995 IEEE All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH thr_exit 3C "2 Nov 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +thr_exit \- terminate the calling thread +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR...[ \fIlibrary\fR... ] +#include <thread.h> + +\fBvoid\fR \fBthr_exit\fR(\fBvoid *\fR\fIstatus\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBthr_exit()\fR function terminates the calling thread, in a similar way +that \fBexit\fR(3C) terminates the calling process. If the calling thread is +not detached, then the thread's \fBID\fR and the exit status specified by +\fIstatus\fR are retained. The value \fIstatus\fR is then made available to any +successful join with the terminating thread (see \fBthr_join\fR(3C)); +otherwise, \fIstatus\fR is disregarded allowing the thread's ID to be reclaimed +immediately. +.sp +.LP +Any cancellation cleanup handlers that have been pushed and not yet popped are +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 will 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 \fBatexit()\fR routines that might exist. +.sp +.LP +An exiting thread runs with all signals blocked. All thread termination +functions, including cancellation cleanup handlers and thread-specific data +destructor functions, are called with all signals blocked. +.sp +.LP +If any thread, including the \fBmain()\fR thread, calls \fBthr_exit()\fR, only +that thread will exit. +.sp +.LP +If \fBmain()\fR returns or exits (either implicitly or explicitly), or any +thread explicitly calls \fBexit()\fR, the entire process will exit. +.sp +.LP +The behavior of \fBthr_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 \fBthr_exit()\fR. +.sp +.LP +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 \fBthr_exit()\fR \fIstatus\fR parameter +value. +.sp +.LP +If any thread (except the \fBmain()\fR thread) implicitly or explicitly +returns, the result is the same as if the thread called \fBthr_exit()\fR and it +will return the value of \fIstatus\fR as the exit code. +.sp +.LP +The process will terminate with an exit status of \fB0\fR after the last +non-daemon thread has terminated (including the \fBmain()\fR thread). This +behavior is the same as if the application had called \fBexit()\fR with a +\fB0\fR argument at thread termination time. +.SH RETURN VALUES +.sp +.LP +The \fBthr_exit()\fR function cannot return to its caller. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBexit\fR(3C), \fBthr_create\fR(3C), \fBthr_join\fR(3C), +\fBthr_keycreate\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +Although only POSIX implements cancellation, cancellation can be used with +Solaris threads, due to their interoperability. +.sp +.LP +The \fIstatus\fR argument should not reference any variables local to the +calling thread. diff --git a/usr/src/man/man3c/thr_getconcurrency.3c b/usr/src/man/man3c/thr_getconcurrency.3c new file mode 100644 index 0000000000..51a557e4b3 --- /dev/null +++ b/usr/src/man/man3c/thr_getconcurrency.3c @@ -0,0 +1,89 @@ +'\" te +.\" Copyright (c) 1998 Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH thr_getconcurrency 3C "11 May 1998" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +thr_getconcurrency, thr_setconcurrency \- get or set thread concurrency level +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR...[ \fIlibrary\fR... ] +#include <thread.h> + +\fBint\fR \fBthr_setconcurrency\fR(\fBint\fR \fInew_level\fR); +.fi + +.LP +.nf +\fBint\fR \fBthr_getconcurrency\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions are obsolete and maintained for compatibility only. The +\fBthr_setconcurrency()\fR function updates the desired concurrency level that +\fBlibthread\fR maintains for the calling process. This value does not affect +the behavior of the calling process. +.sp +.LP +The \fBthr_getconcurrency()\fR function returns the current value for the +desired concurrency level. +.SH RETURN VALUES +.sp +.LP +The \fBthr_getconcurrency()\fR function always returns the current value for +the desired concurrency level. +.sp +.LP +If successful, the \fBthr_setconcurrency()\fR function returns \fB0\fR. +Otherwise, a non-zero value is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBthr_setconcurrency()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR \fR +.ad +.RS 11n +.rt +The specified concurrency level would cause a system resource to be exceeded. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR \fR +.ad +.RS 11n +.rt +The value for \fInew_level\fR is negative. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBthr_create\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/thr_getprio.3c b/usr/src/man/man3c/thr_getprio.3c new file mode 100644 index 0000000000..132722eee6 --- /dev/null +++ b/usr/src/man/man3c/thr_getprio.3c @@ -0,0 +1,117 @@ +'\" te +.\" Copyright (c) 1995 IEEE All Rights Reserved. +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2001 Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH thr_getprio 3C "1 Apr 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +thr_getprio, thr_setprio \- access dynamic thread scheduling +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR...[ \fIlibrary\fR... ] +#include <thread.h> + +\fBint\fR \fBthr_setprio\fR(\fBthread_t\fR \fItarget_thread\fR, \fBint\fR \fIpriority\fR); +.fi + +.LP +.nf +\fBint\fR \fBthr_getprio\fR(\fBthread_t\fR \fItarget_thread\fR, \fBint *\fR\fIpriority\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBthr_setprio()\fR function sets the scheduling priority for the thread +specified by target_thread within the current process to the value given by +priority. +.sp +.LP +The \fBthr_getprio()\fR function stores the current priority for the thread +specified by \fItarget_thread\fR in the location pointed to by \fIpriority\fR. +.sp +.LP +If the \fBthr_setprio()\fR function fails, the scheduling priority of the +target thread is not changed. +.sp +.LP +See \fBpriocntl\fR(2), \fBpthread_setschedprio\fR(3C), and +\fBsched_setparam\fR(3C). +.SH RETURN VALUES +.sp +.LP +If successful, the \fBthr_getprio()\fR and \fBthr_setprio()\fR functions return +\fB0\fR. Otherwise, an error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBthr_getprio()\fR and \fBthr_setprio()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBESRCH\fR\fR +.ad +.RS 9n +.rt +The value specified by \fItarget_thread\fR does not refer to an existing +thread. +.RE + +.sp +.LP +The \fBthr_setprio()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of \fIpriority\fR is invalid for the scheduling policy of the +specified thread. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 10n +.rt +The caller does not have the appropriate permission to set the priority to the +value specified. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpriocntl\fR(2), \fBpthread_setschedprio\fR(3C), \fBsched_setparam\fR(3C), +\fBthr_create\fR(3C), \fBthr_suspend\fR(3C), \fBthr_yield\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/thr_join.3c b/usr/src/man/man3c/thr_join.3c new file mode 100644 index 0000000000..59cd1809d7 --- /dev/null +++ b/usr/src/man/man3c/thr_join.3c @@ -0,0 +1,122 @@ +'\" te +.\" Copyright (c) 2000 Sun Microsystems, Inc. All Rights Reserved. +.\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 1995 IEEE All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH thr_join 3C "27 Mar 2000" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +thr_join \- wait for thread termination +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR...[ \fIlibrary\fR... ] +#include <thread.h> + +\fBint\fR \fBthr_join\fR(\fBthread_t\fR \fIthread\fR, \fBthread_t *\fR\fIdeparted\fR, \fBvoid **\fR\fIstatus\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBthr_join()\fR function suspends processing of the calling thread until +the target \fIthread\fR completes. The \fIthread\fR argument must be a member +of the current process and cannot be a detached thread. See +\fBthr_create\fR(3C). +.sp +.LP +If two or more threads wait for the same thread to complete, all will suspend +processing until the thread has terminated, and then one thread will return +successfully and the others will return with an error of \fBESRCH\fR. The +\fBthr_join()\fR function will not block processing of the calling thread if +the target \fIthread\fR has already terminated. +.sp +.LP +If a \fBthr_join()\fR call returns successfully with a non-null \fIstatus\fR +argument, the value passed to \fBthr_exit\fR(3C) by the terminating thread will +be placed in the location referenced by \fIstatus\fR. +.sp +.LP +If the target \fIthread\fR \fBID\fR is \fB0\fR, \fBthr_join()\fR finds and +returns the status of a terminated undetached thread in the process. If no such +thread exists, it suspends processing of the calling thread until a thread for +which no other thread is waiting enters that state, at which time it returns +successfully, or until all other threads in the process are either daemon +threads or threads waiting in \fBthr_join()\fR, in which case it returns +\fBEDEADLK\fR. See \fBNOTES\fR. +.sp +.LP +If \fIdeparted\fR is not \fINULL\fR, it points to a location that is set to the +ID of the terminated thread if \fBthr_join()\fR returns successfully. +.SH RETURN VALUES +.sp +.LP +If successful, \fBthr_join()\fR returns \fB0\fR. Otherwise, an error number is +returned to indicate the error. +.SH ERRORS +.sp +.ne 2 +.mk +.na +\fB\fBEDEADLK\fR \fR +.ad +.RS 12n +.rt +A joining deadlock would occur, such as when a thread attempts to wait for +itself, or the calling thread is waiting for any thread to exit and only daemon +threads or waiting threads exist in the process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBESRCH\fR \fR +.ad +.RS 12n +.rt +No undetached thread could be found corresponding to the given thread ID. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBthr_create\fR(3C), \fBthr_exit\fR(3C), \fBwait\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) +.SH NOTES +.sp +.LP +Using thr_join(3C) in the following syntax, +.sp +.in +2 +.nf +while (thr_join(0, NULL, NULL) == 0); +.fi +.in -2 + +.sp +.LP +will wait for the termination of all non-daemon threads, excluding threads that +are themselves waiting in \fBthr_join()\fR. diff --git a/usr/src/man/man3c/thr_keycreate.3c b/usr/src/man/man3c/thr_keycreate.3c new file mode 100644 index 0000000000..a28bd63bde --- /dev/null +++ b/usr/src/man/man3c/thr_keycreate.3c @@ -0,0 +1,262 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 1995 IEEE. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH thr_keycreate 3C "2 Nov 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +thr_keycreate, thr_keycreate_once, thr_setspecific, thr_getspecific \- +thread-specific data functions +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <thread.h> + +\fBint\fR \fBthr_keycreate\fR(\fBthread_key_t *\fR\fIkeyp\fR, + \fBvoid (*\fR\fIdestructor\fR)(void *)); +.fi + +.LP +.nf +\fBint\fR \fBthr_keycreate_once\fR(\fBthread_key_t *\fR\fIkeyp\fR, + \fBvoid (*\fR\fIdestructor\fR)(void *)); +.fi + +.LP +.nf +\fBint\fR \fBthr_setspecific\fR(\fBthread_key_t\fR \fIkey\fR, \fBvoid *\fR\fIvalue\fR); +.fi + +.LP +.nf +\fBint\fR \fBthr_getspecific\fR(\fBthread_key_t\fR \fIkey\fR, \fBvoid **\fR\fIvaluep\fR); +.fi + +.SH DESCRIPTION +.SS "Create Key" +.sp +.LP +In general, thread key creation allocates a key that locates data specific to +each thread in the process. The key is global to all threads in the process, +which allows each thread to bind a value to the key once the key has been +created. The key independently maintains specific values for each binding +thread. The \fBthr_keycreate()\fR function allocates a global \fIkey\fR +namespace, pointed to by \fIkeyp\fR, that is visible to all threads in the +process. Each thread is initially bound to a private element of this \fIkey\fR, +which allows access to its thread-specific data. +.sp +.LP +Upon key creation, a new key is assigned the value \fINULL\fR for all active +threads. Additionally, upon thread creation, all previously created keys in the +new thread are assigned the value \fINULL.\fR +.sp +.LP +Optionally, a destructor function \fIdestructor\fR can be associated with each +\fIkey\fR. Upon thread exit, if a \fIkey\fR has a non-null \fIdestructor\fR +function and the thread has a non-null \fIvalue\fR associated with that +\fIkey\fR, the \fIdestructor\fR function is called with the current associated +\fIvalue\fR. If more than one \fIdestructor\fR exists for a thread when it +exits, the order of destructor calls is unspecified. +.sp +.LP +An exiting thread runs with all signals blocked. All thread termination +functions, including thread-specific data destructor functions, are called with +all signals blocked. +.sp +.LP +The \fBthr_keycreate_once()\fR function is identical to the +\fBthr_keycreate()\fR function except that the key pointed to by \fIkeyp\fR +must be statically initialized with the value \fBTHR_ONCE_KEY\fR before calling +\fBthr_keycreate_once()\fR and the key will be created exactly once. This is +equivalent to using \fBpthread_once()\fR to call a onetime initialization +function that calls \fBthr_keycreate()\fR to create the data key. +.SS "Set Value" +.sp +.LP +Once a key has been created, each thread can bind a new \fIvalue\fR to the key +using \fBthr_setspecific()\fR. The values are unique to the binding thread and +are individually maintained. These values continue for the life of the +calling thread. +.sp +.LP +Proper synchronization of \fIkey\fR storage and access must be ensured by the +caller. The \fIvalue\fR argument to \fBthr_setspecific()\fR is generally a +pointer to a block of dynamically allocated memory reserved by the calling +thread for its own use. See \fBEXAMPLES\fR below. +.sp +.LP +At thread exit, the \fIdestructor\fR function, which is associated at time of +creation, is called and it uses the specific key value as its sole argument. +.SS "Get Value" +.sp +.LP +\fBthr_getspecific()\fR stores the current value bound to \fIkey\fR for the +calling thread into the location pointed to by \fIvaluep\fR. +.SH RETURN VALUES +.sp +.LP +If successful, \fBthr_keycreate()\fR, \fBthr_keycreate_once()\fR, +\fBthr_setspecific()\fR and \fBthr_getspecific()\fR return 0. Otherwise, an +error number is returned to indicate the error. +.SH ERRORS +.sp +.LP +If the following conditions occur, \fBthr_keycreate()\fR and +\fBthr_keycreate_once()\fR return the corresponding error number: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +The system lacked the necessary resources to create another thread-specific +data key. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient memory exists to create the key. +.RE + +.sp +.LP +If the following conditions occur, \fBthr_setspecific()\fR returns the +corresponding error number: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient memory exists to associate the value with the key. +.RE + +.sp +.LP +The \fBthr_setspecific()\fR function returns the corresponding error number: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIkey\fR value is invalid. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRCall the thread-specific data from more than one thread without +special initialization. +.sp +.LP +In this example, the thread-specific data in this function can be called from +more than one thread without special initialization. For each argument passed +to the executable, a thread is created and privately bound to the string-value +of that argument. + +.sp +.in +2 +.nf +/* cc -mt thisfile.c */ + +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <thread.h> + +void *thread_specific_data(void *); +void cleanup(void*); +#define MAX_ARGC 20 +thread_t tid[MAX_ARGC]; +int num_threads; + +int +main(int argc, char *argv[]) { + int i; + num_threads = argc - 1; + for (i = 0; i < num_threads; i++) + thr_create(NULL, 0, thread_specific_data, argv[i+1], 0, &tid[i]); + for (i = 0; i < num_threads; i++) + thr_join(tid[i], NULL, NULL); + return (0); +} /* end main */ + +void * +thread_specific_data(void *arg) { + static thread_key_t key = THR_ONCE_KEY; + char *private_data = arg; + void *tsd = NULL; + void *data; + + thr_keycreate_once(&key, cleanup); + thr_getspecific(key, &tsd); + if (tsd == NULL) { + data = malloc(strlen(private_data) + 1); + strcpy(data, private_data); + thr_setspecific(key, data); + thr_getspecific(key, &tsd); + } + printf("tsd for %d = %s\en", thr_self(), (char *)tsd); + thr_getspecific(key, &tsd); + printf("tsd for %d remains %s\en", thr_self(), (char *)tsd); + return (NULL); +} /* end thread_specific_data */ + +void +cleanup(void *v) { + /* application-specific clean-up function */ + free(v); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpthread_once\fR(3C), \fBthr_exit\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) +.SH WARNINGS +.sp +.LP +The \fBthr_getspecific()\fR and \fBthr_setspecific()\fR functions can be +called either explicitly or implicitly from a thread-specific data destructor +function. Calling \fBthr_setspecific()\fR from a destructor can result in lost +storage or infinite loops. diff --git a/usr/src/man/man3c/thr_kill.3c b/usr/src/man/man3c/thr_kill.3c new file mode 100644 index 0000000000..991347ede2 --- /dev/null +++ b/usr/src/man/man3c/thr_kill.3c @@ -0,0 +1,89 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 1995 IEEE. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH thr_kill 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +thr_kill \- send a signal to a thread +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <signal.h> +#include <thread.h> + +\fBint\fR \fBthr_kill\fR(\fBthread_t\fR \fIthread\fR, \fBint\fR \fIsig\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBthr_kill()\fR function sends the \fIsig\fR signal to the thread +designated by \fIthread\fR. The \fIthread\fR argument must be a member of the +same process as the calling thread. The \fIsig\fR argument must be one of the +signals listed in \fBsignal.h\fR(3HEAD), with the exception of \fBSIGCANCEL\fR +being reserved and off limits to \fBthr_kill()\fR. If \fIsig\fR is \fB0\fR, a +validity check is done for the existence of the target thread; no signal is +sent. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBthr_kill()\fR returns \fB0\fR. Otherwise, an +error number is returned. In the event of failure, no signal is sent. +.SH ERRORS +.sp +.LP +The \fBthr_kill()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIsig\fR argument value is not zero and is an invalid or an unsupported +signal number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBESRCH\fR\fR +.ad +.RS 10n +.rt +No thread was found that corresponded to the thread designated by \fIthread\fR +ID. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelAsync-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBkill\fR(2), \fBsigaction\fR(2), \fBraise\fR(3C), \fBsignal.h\fR(3HEAD), +\fBthr_self\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/thr_main.3c b/usr/src/man/man3c/thr_main.3c new file mode 100644 index 0000000000..9e9eeb1e0b --- /dev/null +++ b/usr/src/man/man3c/thr_main.3c @@ -0,0 +1,87 @@ +'\" te +.\" Copyright (c) 1998 Sun Microsystems, Inc. - All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH thr_main 3C "11 May 1998" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +thr_main \- identify the main thread +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <thread.h> + +\fBint\fR \fBthr_main\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBthr_main()\fR function returns one of the following: +.sp +.ne 2 +.mk +.na +\fB\fB1\fR \fR +.ad +.RS 7n +.rt +if the calling thread is the main thread +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB0\fR \fR +.ad +.RS 7n +.rt +if the calling thread is not the main thread +.RE + +.sp +.ne 2 +.mk +.na +\fB-\fB1\fR \fR +.ad +.RS 7n +.rt +if \fBlibthread\fR is not linked in or thread initialization has not completed +.RE + +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/lib/libthread\fR \fR +.ad +.RS 19n +.rt + +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBthr_self\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/thr_min_stack.3c b/usr/src/man/man3c/thr_min_stack.3c new file mode 100644 index 0000000000..0e799bcd44 --- /dev/null +++ b/usr/src/man/man3c/thr_min_stack.3c @@ -0,0 +1,89 @@ +'\" te +.\" Copyright (c) 1997 Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH thr_min_stack 3C "12 May 1998" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +thr_min_stack \- return the minimum-allowable size for a thread's stack +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR...[ \fIlibrary\fR... ] +#include <thread.h> + +\fBsize_t\fR \fBthr_min_stack\fR(\fB\fR\fIvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +When a thread is created with a user-supplied stack, the user must reserve +enough space to run this thread. In a dynamically linked execution environment, +it is very hard to know what the minimum stack requirments are for a thread. +The function \fBthr_min_stack()\fR returns the amount of space needed to +execute a null thread. This is a thread that was created to execute a null +procedure. A thread that does something useful should have a stack size that is +\fBthr_min_stack()\fR + \fI<some increment>\fR\&. +.sp +.LP +Most users should not be creating threads with user-supplied stacks. This +functionality was provided to support applications that wanted complete control +over their execution environment. +.sp +.LP +Typically, users should let the threads library manage stack allocation. The +threads library provides default stacks which should meet the requirements of +any created thread. +.sp +.LP +\fBthr_min_stack()\fR will return the unsigned int \fBTHR_MIN_STACK,\fR which +is the minimum-allowable size for a thread's stack. +.sp +.LP +In this implementation the default size for a user-thread's stack is one +mega-byte. If the second argument to \fBthr_create\fR(3C) is \fBNULL,\fR then +the default stack size for the newly-created thread will be used. Otherwise, +you may specify a stack-size that is at least \fBTHR_MIN_STACK,\fR yet less +than the size of your machine's virtual memory. +.sp +.LP +It is recommended that the default stack size be used. +.sp +.LP +To determine the smallest-allowable size for a thread's stack, execute the +following: +.sp +.in +2 +.nf +/* cc thisfile.c -lthread */ +#define _REENTRANT +#include <thread.h> +#include <stdio.h> +main(\|) { + printf("thr_min_stack(\|) returns %u\en",thr_min_stack(\|)); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/thr_self.3c b/usr/src/man/man3c/thr_self.3c new file mode 100644 index 0000000000..94e660caf8 --- /dev/null +++ b/usr/src/man/man3c/thr_self.3c @@ -0,0 +1,57 @@ +'\" te +.\" Copyright (c) 1995 IEEE All Rights Reserved +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 1998 Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH thr_self 3C "9 May 1998" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +thr_self \- get calling thread's ID +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR...[ \fIlibrary\fR... ] +#include <thread.h> + +\fBthread_t\fR \fBthr_self\fR(\fBvoid);\fR +.fi + +.LP +.nf +\fBtypedef\fR(\fBunsigned int thread_t\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +\fBthr_self()\fR returns the thread \fBID\fR of the calling thread. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBthr_create\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/thr_sigsetmask.3c b/usr/src/man/man3c/thr_sigsetmask.3c new file mode 100644 index 0000000000..db4cd303b7 --- /dev/null +++ b/usr/src/man/man3c/thr_sigsetmask.3c @@ -0,0 +1,360 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 1995 IEEE. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH thr_sigsetmask 3C "23 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +thr_sigsetmask \- change or examine calling thread's signal mask +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +#include <thread.h> +#include <signal.h> + +\fBint\fR \fBthr_sigsetmask\fR(\fBint\fR \fIhow\fR, \fBconst sigset_t *\fR\fIset\fR, \fBsigset_t *\fR\fIoset\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBthr_sigsetmask()\fR function changes or examines a calling thread's +signal mask. Each thread has its own signal mask. A new thread inherits the +calling thread's signal mask and priority; however, pending signals are not +inherited. Signals pending for a new thread will be empty. +.sp +.LP +If the value of the argument \fIset\fR is not \fINULL,\fR \fBset\fR points to +a set of signals that can modify the currently blocked set. If the value of +\fIset\fR is \fINULL\fR, the value of \fIhow\fR is insignificant and the +thread's signal mask is unmodified; thus, \fBthr_sigsetmask()\fR can be used to +inquire about the currently blocked signals. +.sp +.LP +The value of the argument \fIhow\fR specifies the method in which the set is +changed and takes one of the following values: +.sp +.ne 2 +.mk +.na +\fB\fBSIG_BLOCK\fR\fR +.ad +.RS 15n +.rt +\fIset\fR corresponds to a set of signals to block. They are added to the +current signal mask. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIG_UNBLOCK\fR\fR +.ad +.RS 15n +.rt +\fIset\fR corresponds to a set of signals to unblock. These signals are deleted +from the current signal mask. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIG_SETMASK\fR\fR +.ad +.RS 15n +.rt +\fIset\fR corresponds to the new signal mask. The current signal mask is +replaced by \fBset\fR. +.RE + +.sp +.LP +If the value of \fIoset\fR is not \fINULL\fR, it points to the location where +the previous signal mask is stored. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBthr_sigsetmask()\fR function returns +\fB0\fR. Otherwise, it returns a non-zero value. +.SH ERRORS +.sp +.LP +The \fBthr_sigsetmask()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of \fIhow\fR is not defined and \fIoset\fR is \fINULL.\fR +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRCreate a default thread that can serve as a signal +catcher/handler with its own signal mask. +.sp +.LP +The following example shows how to create a default thread that can serve as a +signal catcher/handler with its own signal mask. \fBnew\fR will have a +different value from the creator's signal mask. + +.sp +.LP +As POSIX threads and Solaris threads are fully compatible even within the same +process, this example uses \fBpthread_create\fR(3C) if you execute \fBa.out +0\fR, or \fBthr_create\fR(3C) if you execute \fBa.out 1\fR. + +.sp +.LP +In this example: + +.RS +4 +.TP +.ie t \(bu +.el o +The \fBsigemptyset\fR(3C) function initializes a null signal set, \fBnew\fR. +The \fBsigaddset\fR(3C) function packs the signal, \fBSIGINT\fR, into that new +set. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Either \fBpthread_sigmask()\fR or \fBthr_sigsetmask()\fR is used to mask the +signal, \fBSIGINT\fR (CTRL-C), from the calling thread, which is \fBmain()\fR. +The signal is masked to guarantee that only the new thread will receive this +signal. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBpthread_create()\fR or \fBthr_create()\fR creates the signal-handling +thread. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Using \fBpthread_join\fR(3C) or \fBthr_join\fR(3C), \fBmain()\fR then waits for +the termination of that signal-handling thread, whose \fBID\fR number is +\fBuser_threadID\fR. Then \fBmain()\fR will \fBsleep\fR(3C) for 2 seconds, +after which the program terminates. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The signal-handling thread, \fBhandler\fR: +.RS +4 +.TP +.ie t \(bu +.el o +Assigns the handler \fBinterrupt()\fR to handle the signal \fBSIGINT\fR by the +call to \fBsigaction\fR(2). +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Resets its own signal set to \fInot block\fR the signal, \fBSIGINT\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Sleeps for 8 seconds to allow time for the user to deliver the signal +\fBSIGINT\fR by pressing the \fBCTRL-C.\fR +.RE +.RE +.sp +.in +2 +.nf +/* cc thisfile.c -lthread -lpthread */ +#define _REENTRANT /* basic first 3-lines for threads */ +#include <pthread.h> +#include <thread.h> + +thread_t user_threadID; +sigset_t new; +void *handler(\|), interrupt(\|); + +int +main( int argc, char *argv[\|] ){ + test_argv(argv[1]); + + sigemptyset(&new); + sigaddset(&new, SIGINT); + switch(*argv[1]) { + + case '0': /* POSIX */ + pthread_sigmask(SIG_BLOCK, &new, NULL); + pthread_create(&user_threadID, NULL, handler, argv[1]); + pthread_join(user_threadID, NULL); + break; + + case '1': /* Solaris */ + thr_sigsetmask(SIG_BLOCK, &new, NULL); + thr_create(NULL, 0, handler, argv[1], 0, &user_threadID); + thr_join(user_threadID, NULL, NULL); + break; +} /* switch */ + + printf("thread handler, # %d, has exited\en",user_threadID); + sleep(2); + printf("main thread, # %d is done\en", thr_self(\|)); + return (0) +} /* end main */ + +struct sigaction act; + +void * +handler(char *argv1) + { + act.sa_handler = interrupt; + sigaction(SIGINT, &act, NULL); + switch(*argv1){ + case '0': /* POSIX */ + pthread_sigmask(SIG_UNBLOCK, &new, NULL); + break; + case '1': /* Solaris */ + thr_sigsetmask(SIG_UNBLOCK, &new, NULL); + break; + } + printf("\en Press CTRL-C to deliver SIGINT signal to the process\en"); + sleep(8); /* give user time to hit CTRL-C */ + return (NULL) +} + +void +interrupt(int sig) +{ +printf("thread %d caught signal %d\en", thr_self(\|), sig); +} + +void test_argv(char argv1[\|]) { + if(argv1 == NULL) { + printf("use 0 as arg1 to use thr_create(\|);\en \e + or use 1 as arg1 to use pthread_create(\|)\en"); + exit(NULL); + } +} +.fi +.in -2 + +.sp +.LP +In the last example, the \fBhandler\fR thread served as a signal-handler while +also taking care of activity of its own (in this case, sleeping, although it +could have been some other activity). A thread could be completely dedicated to +signal-handling simply by waiting for the delivery of a selected signal by +blocking with \fBsigwait\fR(2). The two subroutines in the previous example, +\fBhandler()\fR and \fBinterrupt()\fR, could have been replaced with the +following routine: + +.sp +.in +2 +.nf +void * +handler(void *ignore) +{ int signal; + printf("thread %d waiting for you to press the CTRL-C keys\en", + thr_self(\|)); + sigwait(&new, &signal); + printf("thread %d has received the signal %d \en", thr_self(\|), signal); +} +/*pthread_create(\|) and thr_create(\|) would use NULL instead of + argv[1] for the arg passed to handler(\|) */ +.fi +.in -2 + +.sp +.LP +In this routine, one thread is dedicated to catching and handling the signal +specified by the set \fBnew\fR, which allows \fBmain()\fR and all of its other +sub-threads, created \fIafter\fR \fBpthread_sigmask()\fR or +\fBthr_sigsetmask()\fR masked that signal, to continue uninterrupted. Any use +of \fBsigwait\fR(2) should be such that all threads block the signals passed +to \fBsigwait\fR(2) at all times. Only the thread that calls \fBsigwait()\fR +will get the signals. The call to \fBsigwait\fR(2) takes two arguments. + +.sp +.LP +For this type of background dedicated signal-handling routine, a Solaris daemon +thread can be used by passing the argument \fBTHR_DAEMON\fR to +\fBthr_create()\fR. + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe and Async-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBsigaction\fR(2), \fBsigprocmask\fR(2), \fBsigwait\fR(2), +\fBcond_wait\fR(3C), \fBpthread_cancel\fR(3C), \fBpthread_create\fR(3C), +\fBpthread_join\fR(3C), \fBpthread_self\fR(3C), \fBsigaddset\fR(3C), +\fBsigemptyset\fR(3C), \fBsigsetops\fR(3C), \fBsleep\fR(3C), +\fBattributes\fR(5), \fBcancellation\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +It is not possible to block signals that cannot be caught or ignored (see +\fBsigaction\fR(2)). It is also not possible to block or unblock +\fBSIGCANCEL\fR, as \fBSIGCANCEL\fR is reserved for the implementation of POSIX +thread cancellation (see \fBpthread_cancel\fR(3C) and \fBcancellation\fR(5)). +This restriction is quietly enforced by the standard C library. +.sp +.LP +Using \fBsigwait\fR(2) in a dedicated thread allows asynchronously generated +signals to be managed synchronously; however, \fBsigwait\fR(2) should never be +used to manage synchronously generated signals. +.sp +.LP +Synchronously generated signals are exceptions that are generated by a thread +and are directed at the thread causing the exception. Since \fBsigwait()\fR +blocks waiting for signals, the blocking thread cannot receive a synchronously +generated signal. +.sp +.LP +Calling the\fBsigprocmask\fR(2) function will be the same as if +\fBthr_sigsetmask()\fR or \fBpthread_sigmask()\fR has been called. POSIX leaves +the semantics of the call to \fBsigprocmask\fR(2) unspecified in a +multi-threaded process, so programs that care about POSIX portability should +not depend on this semantic. +.sp +.LP +If a signal is delivered while a thread is waiting on a condition variable, +the \fBcond_wait\fR(3C) function will be interrupted and the handler will be +executed. The state of the lock protecting the condition variable is undefined +while the thread is executing the signal handler. +.sp +.LP +Signals that are generated synchronously should not be masked. If such a signal +is blocked and delivered, the receiving process is killed. diff --git a/usr/src/man/man3c/thr_stksegment.3c b/usr/src/man/man3c/thr_stksegment.3c new file mode 100644 index 0000000000..84b45b6c0e --- /dev/null +++ b/usr/src/man/man3c/thr_stksegment.3c @@ -0,0 +1,90 @@ +'\" te +.\" Copyright (c) 2000 Sun Microsystems, Inc. - All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH thr_stksegment 3C "15 Jun 2000" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +thr_stksegment \- get thread stack address and size +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR...[ \fIlibrary\fR... ] +#include <thread.h> +#include <signal.h> + +\fBint\fR \fBthr_stksegment\fR(\fBstack_t *\fR\fIss\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBthr_stksegment()\fR function returns, in its \fBstack_t\fR argument, the +address and size of the calling thread's stack. +.sp +.LP +The \fBstack_t\fR structure includes the following members: +.sp +.in +2 +.nf +void *ss_sp +size_t ss_size +int ss_flags +.fi +.in -2 + +.sp +.LP +On successful return from \fBthr_stksegment()\fR, \fBss_sp\fR contains the high +address of the caller's stack and \fBss_size\fR contains the size of the stack +in bytes. The \fBss_flags\fR member is always 0. Note that the meaning of +\fBss_sp\fR is reversed from other uses of \fBstack_t\fR such as +\fBsigaltstack\fR(2) where \fBss_sp\fR is the low address. +.sp +.LP +The stack information provided by \fBthr_stksegment()\fR is typically used by +debuggers, garbage collectors, and similar applications. Most applications +should not require such information. +.SH RETURN VALUES +.sp +.LP +The \fBthr_stksegment()\fR function returns \fB0\fR if the thread stack +address and size were successfully retrieved. Otherwise, it returns a non-zero +error value. +.SH ERRORS +.sp +.LP +The \fBthr_stksegment()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR \fR +.ad +.RS 11n +.rt +The stack information for the thread is not available because the thread's +initialization is not yet complete, or the thread is an internal thread. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBsigaltstack\fR(2), \fBthr_create\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/thr_suspend.3c b/usr/src/man/man3c/thr_suspend.3c new file mode 100644 index 0000000000..bf1fd9f160 --- /dev/null +++ b/usr/src/man/man3c/thr_suspend.3c @@ -0,0 +1,99 @@ +'\" te +.\" Copyright (c) 2001 Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH thr_suspend 3C "22 Mar 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +thr_suspend, thr_continue \- suspend or continue thread execution +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR...[ \fIlibrary\fR... ] +#include <thread.h> + +\fBint\fR \fBthr_suspend\fR(\fBthread_t\fR \fItarget_thread\fR); +.fi + +.LP +.nf +\fBint\fR \fBthr_continue\fR(\fBthread_t\fR \fItarget_thread\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBthr_suspend()\fR function immediately suspends the execution of the +thread specified by \fItarget_thread\fR. On successful return from +\fBthr_suspend()\fR, the suspended thread is no longer executing. Once a thread +is suspended, subsequent calls to \fBthr_suspend()\fR have no effect. +.sp +.LP +The \fBthr_continue()\fR function resumes the execution of a suspended thread. +Once a suspended thread is continued, subsequent calls to \fBthr_continue()\fR +have no effect. +.sp +.LP +A suspended thread will not be awakened by any mechanism other than a call to +\fBthr_continue()\fR. Signals and the effect of calls +to\fBmutex_unlock\fR(3C), \fBrw_unlock\fR(3C), \fBsema_post\fR(3C), +\fBcond_signal\fR(3C), and \fBcond_broadcast\fR(3C) remain pending until the +execution of the thread is resumed by \fBthr_continue()\fR. +.SH RETURN VALUES +.sp +.LP +If successful, the \fBthr_suspend()\fR and \fBthr_continue()\fR functions +return \fB0\fR. Otherwise, a non-zero value is returned to indicate the error. +.SH ERRORS +.sp +.LP +The \fBthr_suspend()\fR and \fBthr_continue()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBESRCH\fR \fR +.ad +.RS 10n +.rt +The \fItarget_thread\fR cannot be found in the current process. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBthr_create\fR(3C), \fBthr_join\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) +.SH WARNINGS +.sp +.LP +The \fBthr_suspend()\fR function is extremely difficult to use safely because +it suspends the target thread with no concern for the target thread's state. +The target thread could be holding locks, waiting for a lock, or waiting on a +condition variable when it is unconditionally suspended. The thread will not +run until \fBthr_continue()\fR is applied, regardless of any calls to +\fBmutex_unlock()\fR, \fBcond_signal()\fR, or \fBcond_broadcast()\fR by other +threads. Its existence on a sleep queue can interfere with the waking up of +other threads that are on the same sleep queue. +.sp +.LP +The \fBthr_suspend()\fR and \fBthr_continue()\fR functions should be avoided. +Mechanisms that involve the cooperation of the targeted thread, such as mutex +locks and condition variables, should be employed instead. diff --git a/usr/src/man/man3c/thr_yield.3c b/usr/src/man/man3c/thr_yield.3c new file mode 100644 index 0000000000..5e56792945 --- /dev/null +++ b/usr/src/man/man3c/thr_yield.3c @@ -0,0 +1,47 @@ +'\" te +.\" Copyright (c) 1998 Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH thr_yield 3C "12 May 1998" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +thr_yield \- yield to another thread +.SH SYNOPSIS +.LP +.nf +cc -mt [ \fIflag\fR... ] \fIfile\fR...[ \fIlibrary\fR... ] +#include <thread.h> + +\fBvoid\fR \fBthr_yield\fR(\fBvoid\fR\fI\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBthr_yield()\fR function causes the current thread to yield its execution +in favor of another thread with the same or greater priority. +.SH RETURN VALUES +.sp +.LP +The \fBthr_yield()\fR function returns nothing and does not set \fBerrno\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBthr_setprio\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/timer_create.3c b/usr/src/man/man3c/timer_create.3c new file mode 100644 index 0000000000..ae033ccfe8 --- /dev/null +++ b/usr/src/man/man3c/timer_create.3c @@ -0,0 +1,186 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH timer_create 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +timer_create \- create a timer +.SH SYNOPSIS +.LP +.nf +#include <signal.h> +#include <time.h> + +\fBint\fR \fBtimer_create\fR(\fBclockid_t\fR \fIclock_id\fR, + \fBstruct sigevent *restrict\fR \fIevp\fR, \fBtimer_t *restrict\fR \fItimerid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBtimer_create()\fR function creates a timer using the specified clock, +\fIclock_id\fR, as the timing base. The \fBtimer_create()\fR function returns, +in the location referenced by \fItimerid\fR, a timer \fBID\fR of type +\fBtimer_t\fR used to identify the timer in timer requests. This timer \fBID\fR +will be unique within the calling process until the timer is deleted. The +particular clock, \fIclock_id\fR, is defined in <\fBtime.h\fR>. The timer whose +\fBID\fR is returned will be in a disarmed state upon return from +\fBtimer_create()\fR. +.sp +.LP +The \fIevp\fR argument, if non-null, points to a \fBsigevent\fR structure. This +structure, allocated by the application, defines the asynchronous notification +that will occur when the timer expires (see \fBsignal.h\fR(3HEAD) for event +notification details). If the \fIevp\fR argument is \fINULL\fR, the effect is +as if the \fIevp\fR argument pointed to a \fBsigevent\fR structure with the +\fBsigev_notify\fR member having the value \fBSIGEV_SIGNAL\fR, the +\fBsigev_signo\fR having the value \fBSIGALARM\fR, and the \fBsigev_value\fR +member having the value of the timer \fBID\fR. +.sp +.LP +The system defines a set of clocks that can be used as timing bases for +per-process timers. The following values for \fIclock_id\fR are supported: +.sp +.ne 2 +.mk +.na +\fB\fBCLOCK_REALTIME\fR\fR +.ad +.RS 18n +.rt +wall clock +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCLOCK_VIRTUAL\fR\fR +.ad +.RS 18n +.rt +user CPU usage clock +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCLOCK_PROF\fR\fR +.ad +.RS 18n +.rt +user and system CPU usage clock +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCLOCK_HIGHRES\fR\fR +.ad +.RS 18n +.rt +non-adjustable, high-resolution clock +.RE + +.sp +.LP +For timers created with a \fIclock_id\fR of \fBCLOCK_HIGHRES\fR, the system +will attempt to use an optimal hardware source. This may include, but is not +limited to, per-CPU timer sources. The actual hardware source used is +transparent to the user and may change over the lifetime of the timer. For +example, if the caller that created the timer were to change its processor +binding or its processor set, the system may elect to drive the timer with a +hardware source that better reflects the new binding. Timers based on a +\fIclock_id\fR of \fBCLOCK_HIGHRES\fR are ideally suited for interval timers +that have minimal jitter tolerence. +.sp +.LP +Timers are not inherited by a child process across a \fBfork\fR(2) and are +disarmed and deleted by a call to one of the \fBexec\fR functions (see +\fBexec\fR(2)). +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBtimer_create()\fR returns \fB0\fR and updates +the location referenced by \fItimerid\fR to a \fBtimer_t\fR, which can be +passed to the per-process timer calls. If an error occurs, the function returns +\fB\(mi1\fR and sets \fBerrno\fR to indicate the error. The value of +\fItimerid\fR is undefined if an error occurs. +.SH ERRORS +.sp +.LP +The \fBtimer_create()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +The system lacks sufficient signal queuing resources to honor the request, or +the calling process has already created all of the timers it is allowed by the +system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The specified clock \fBID\fR, \fIclock_id\fR, is not defined. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 10n +.rt +The specified clock \fBID\fR, \fIclock_id\fR, is \fBCLOCK_HIGHRES\fR and the +{\fBPRIV_PROC_CLOCK_HIGHRES\fR} is not asserted in the effective set of the +calling process. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe with exceptions +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBexec\fR(2), \fBfork\fR(2), \fBtime\fR(2), \fBclock_settime\fR(3C), +\fBsignal\fR(3C), \fBsignal.h\fR(3HEAD), \fBtimer_delete\fR(3C), +\fBtimer_settime\fR(3C), \fBattributes\fR(5), \fBprivileges\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/timer_delete.3c b/usr/src/man/man3c/timer_delete.3c new file mode 100644 index 0000000000..a79a1df69f --- /dev/null +++ b/usr/src/man/man3c/timer_delete.3c @@ -0,0 +1,86 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH timer_delete 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +timer_delete \- delete a timer +.SH SYNOPSIS +.LP +.nf +#include <time.h> + +\fBint\fR \fBtimer_delete\fR(\fBtimer_t\fR \fItimerid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBtimer_delete()\fR function deletes the specified timer, \fItimerid\fR, +previously created by the \fBtimer_create\fR(3C) function. If the timer is +armed when \fBtimer_delete()\fR is called, the behavior will be as if the timer +is automatically disarmed before removal. The disposition of pending signals +for the deleted timer is unspecified. +.SH RETURN VALUES +.sp +.LP +If successful, the function returns \fB0\fR. Otherwise, the function returns +\fB\(mi1\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBtimer_delete()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The timer \fBID\fR specified by \fItimerid\fR is not a valid timer \fBID\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR\fR +.ad +.RS 10n +.rt +The \fBtimer_delete()\fR function is not supported by the system. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe with exceptions +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBtimer_create\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/timer_settime.3c b/usr/src/man/man3c/timer_settime.3c new file mode 100644 index 0000000000..cd2ccbb980 --- /dev/null +++ b/usr/src/man/man3c/timer_settime.3c @@ -0,0 +1,181 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH timer_settime 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +timer_settime, timer_gettime, timer_getoverrun \- per-process timers +.SH SYNOPSIS +.LP +.nf +#include <time.h> + +\fBint\fR \fBtimer_settime\fR(\fBtimer_t\fR \fItimerid\fR, \fBint\fR \fIflags\fR, + \fBconst struct itimerspec *restrict\fR \fIvalue\fR, + \fBstruct itimerspec *restrict\fR \fIovalue\fR); +.fi + +.LP +.nf +\fBint\fR \fBtimer_gettime\fR(\fBtimer_t\fR \fItimerid\fR, \fBstruct itimerspec *\fR\fIvalue\fR); +.fi + +.LP +.nf +\fBint\fR \fBtimer_getoverrun\fR(\fBtimer_t\fR \fItimerid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBtimer_settime()\fR function sets the time until the next expiration of +the timer specified by \fItimerid\fR from the \fBit_value\fR member of the +\fIvalue\fR argument and arm the timer if the \fBit_value\fR member of +\fIvalue\fR is non-zero. If the specified timer was already armed when +\fBtimer_settime()\fR is called, this call resets the time until next +expiration to the \fIvalue\fR specified. If the \fBit_value\fR member of +\fIvalue\fR is 0, the timer is disarmed. The effect of disarming or resetting a +timer on pending expiration notifications is unspecified. +.sp +.LP +If the flag \fBTIMER_ABSTIME\fR is not set in the argument \fIflags\fR, +\fBtimer_settime()\fR behaves as if the time until next expiration is set to be +equal to the interval specified by the \fBit_value\fR member of \fIvalue\fR. +That is, the timer expires in \fBit_value\fR nanoseconds from when the call is +made. If the flag \fBTIMER_ABSTIME\fR is set in the argument \fIflags\fR, +\fBtimer_settime()\fR behaves as if the time until next expiration is set to be +equal to the difference between the absolute time specified by the +\fBit_value\fR member of \fIvalue\fR and the current value of the clock +associated with \fItimerid\fR. That is, the timer expires when the clock +reaches the value specified by the \fBit_value\fR member of \fIvalue\fR. If the +specified time has already passed, the function succeeds and the expiration +notification is made. +.sp +.LP +The reload value of the timer is set to the value specified by the +\fBit_interval\fR member of \fIvalue\fR. When a timer is armed with a non-zero +\fBit_interval\fR, a periodic (or repetitive) timer is specified. +.sp +.LP +Time values that are between two consecutive non-negative integer multiples of +the resolution of the specified timer will be rounded up to the larger multiple +of the resolution. Quantization error will not cause the timer to expire +earlier than the rounded time value. +.sp +.LP +If the argument \fIovalue\fR is not \fINULL\fR, the function +\fBtimer_settime()\fR stores, in the location referenced by \fIovalue\fR, a +value representing the previous amount of time before the timer would have +expired or 0 if the timer was disarmed, together with the previous timer reload +value. The members of \fIovalue\fR are subject to the resolution of the timer, +and they are the same values that would be returned by a \fBtimer_gettime()\fR +call at that point in time. +.sp +.LP +The \fBtimer_gettime()\fR function stores the amount of time until the +specified timer, \fItimerid\fR, expires and the reload value of the timer into +the space pointed to by the \fIvalue\fR argument. The \fBit_value\fR member of +this structure contains the amount of time before the timer expires, or 0 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 +\fBit_interval\fR member of \fIvalue\fR contains the reload value last set by +\fBtimer_settime()\fR. +.sp +.LP +Only a single signal will 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 will be queued, and a timer overrun occurs. When a timer expiration +signal is delivered to or accepted by a process, the \fBtimer_getoverrun()\fR +function returns the timer expiration overrun count for the specified timer. +The overrun count returned contains the number of extra timer expirations that +occurred between the time the signal was generated (queued) and when it was +delivered or accepted, up to but not including an implementation-dependent +maximum of \fBDELAYTIMER_MAX\fR. If the number of such extra expirations is +greater than or equal to \fBDELAYTIMER_MAX\fR, then the overrun count will be +set to \fBDELAYTIMER_MAX\fR. The value returned by \fBtimer_getoverrun()\fR +applies to the most recent expiration signal delivery or acceptance for the +timer. If no expiration signal has been delivered for the timer, the meaning of +the overrun count returned is undefined. +.SH RETURN VALUES +.sp +.LP +If the \fBtimer_settime()\fR or \fBtimer_gettime()\fR functions succeed, +\fB0\fR is returned. If an error occurs for either of these functions, +\fB\(mi1\fR is returned, and \fBerrno\fR is set to indicate the error. If the +\fBtimer_getoverrun()\fR function succeeds, it returns the timer expiration +overrun count as explained above. +.SH ERRORS +.sp +.LP +The \fBtimer_settime()\fR, \fBtimer_gettime()\fR and \fBtimer_getoverrun()\fR +functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR \fR +.ad +.RS 11n +.rt +The \fItimerid\fR argument does not correspond to a timer returned by +\fBtimer_create\fR(3C) but not yet deleted by \fBtimer_delete\fR(3C). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR \fR +.ad +.RS 11n +.rt +The \fBtimer_settime()\fR, \fBtimer_gettime()\fR, and \fBtimer_getoverrun()\fR +functions are not supported by the system. The \fBtimer_settime()\fR function +will fail if: +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 11n +.rt +A \fIvalue\fR structure specified a nanosecond value less than zero or greater +than or equal to 1000 million. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelAsync-Signal-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBtime.h\fR(3HEAD), \fBclock_settime\fR(3C), \fBtimer_create\fR(3C), +\fBtimer_delete\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/timeradd.3c b/usr/src/man/man3c/timeradd.3c new file mode 100644 index 0000000000..cb7a213099 --- /dev/null +++ b/usr/src/man/man3c/timeradd.3c @@ -0,0 +1,106 @@ +'\" te +.\" Copyright 1994-2008 The FreeBSD Project. All Rights Reserved. +.\" Copyright (c) 1982, 1986, 1993 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. +.\" Portions Copyright (c) 2008, Sun Microsystems Inc. All Rights Reserved. +.TH timeradd 3C "12 Jun 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +timeradd, timersub, timerclear, timerisset, timercmp \- operations on timeval +structures +.SH SYNOPSIS +.LP +.nf +#include <sys/time.h> + +\fBvoid\fR \fBtimeradd\fR(\fBstruct timeval *\fR\fIa\fR, \fBstruct timeval *\fR\fIb\fR, + \fBstruct timeval *\fR\fIres\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBtimerclear\fR(\fBstruct timeval *\fR\fItvp\fR); +.fi + +.LP +.nf +\fBint\fR \fBtimercmp\fR(\fBstruct timeval *\fR\fIa\fR, \fBstruct timeval *\fR\fIb\fR, \fICMP\fR); +.fi + +.LP +.nf +\fBint\fR \fBtimerisset\fR(\fBstruct timeval *\fR\fItvp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBtimersub\fR(\fBstruct timeval *\fR\fIa\fR, \fBstruct timeval *\fR\fIb\fR, + \fBstruct timeval *\fR\fIres\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These macros are provided for manipulating \fBtimeval\fR structures for use +with \fBgettimeofday\fR(3C) and \fBsettimeofday\fR(3C) operands. The structure +is defined in \fB<sys/time.h>\fR as: +.sp +.in +2 +.nf +struct timeval { + long tv_sec; /* seconds since Jan. 1, 1970 */ + long tv_usec; /* and microseconds */ +}; +.fi +.in -2 + +.sp +.LP +The \fBtimeradd()\fR macro adds the time information stored in \fIa\fR to +\fIb\fR and stores the resulting \fBtimeval\fR in \fIres\fR. The results are +simplified such that the value of \fIres\fR\(->\fItv_usec\fR is always less +than 1,000,000 (1 second). +.sp +.LP +The \fBtimersub()\fR macro subtracts the time information stored in \fIb\fR +from \fIa\fR and stores the resulting \fBtimeval\fR in \fIres\fR. +.sp +.LP +The \fBtimerclear()\fR macro initializes \fItvp\fR to midnight (0 hour) January +1st, 1970 (the Epoch). +.sp +.LP +The \fBtimerisset()\fR macro returns true if \fItvp\fR is set to any time value +other than the Epoch. +.sp +.LP +The \fBtimercmp()\fR macro compares \fIa\fR to \fIb\fR using the form a +\fICMP\fR \fIb\fR, where \fICMP\fR is one of \fB<,\fR \fB<=\fR, \fB==\fR, +\fB!=\fR, \fB>=\fR, or \fB>\fR. +.SH USAGE +.sp +.LP +These macros are not available in function form. All of these macros evaluate +their arguments more than once. If parameters passed to these macros are +expressions with side effects, the results are undefined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe with Exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBgettimeofday\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/tmpfile.3c b/usr/src/man/man3c/tmpfile.3c new file mode 100644 index 0000000000..6c54806499 --- /dev/null +++ b/usr/src/man/man3c/tmpfile.3c @@ -0,0 +1,144 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH tmpfile 3C "4 Aug 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +tmpfile \- create a temporary file +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBFILE *\fR\fBtmpfile\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBtmpfile()\fR function creates a temporary file and opens a corresponding +stream. The file will automatically be deleted when all references to the file +are closed. The file is opened as in \fBfopen\fR(3C) for update (\fBw+\fR). +.sp +.LP +The largest value that can be represented correctly in an object of type +\fBoff_t\fR will be established as the offset maximum in the open file +description. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBtmpfile()\fR returns a pointer to the stream of +the file that is created. Otherwise, it returns a null pointer and sets +\fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBtmpfile()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 10n +.rt +A signal was caught during the execution of \fBtmpfile()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 10n +.rt +There are \fBOPEN_MAX\fR file descriptors currently open in the calling +process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENFILE\fR\fR +.ad +.RS 10n +.rt +The maximum allowable number of files is currently open in the system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSPC\fR\fR +.ad +.RS 10n +.rt +The directory or file system which would contain the new file cannot be +expanded. +.RE + +.sp +.LP +The \fBtmpfile()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 10n +.rt +There are \fBFOPEN_MAX\fR streams currently open in the calling process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient storage space is available. +.RE + +.SH USAGE +.sp +.LP +The stream refers to a file which is unlinked. If the process is killed in the +period between file creation and unlinking, a permanent file may be left +behind. +.sp +.LP +The \fBtmpfile()\fR function has a transitional interface for 64-bit file +offsets. See \fBlf64\fR(5). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +.TE + +.SH SEE ALSO +.sp +.LP +\fBunlink\fR(2), \fBfopen\fR(3C), \fBmkstemp\fR(3C), \fBmktemp\fR(3C), +\fBtmpnam\fR(3C), \fBlf64\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/tmpnam.3c b/usr/src/man/man3c/tmpnam.3c new file mode 100644 index 0000000000..f56aa3d766 --- /dev/null +++ b/usr/src/man/man3c/tmpnam.3c @@ -0,0 +1,146 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH tmpnam 3C "18 May 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +tmpnam, tmpnam_r, tempnam \- create a name for a temporary file +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBchar *\fR\fBtmpnam\fR(\fBchar *\fR\fIs\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBtmpnam_r\fR(\fBchar *\fR\fIs\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBtempnam\fR(\fBconst char *\fR\fIdir\fR, \fBconst char *\fR\fIpfx\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions generate file names that can be used safely for a temporary +file. +.SS "\fBtmpnam()\fR" +.sp +.LP +The \fBtmpnam()\fR function always generates a file name using the path prefix +defined as \fBP_tmpdir\fR in the <\fBstdio.h\fR> header. On Solaris systems, +the default value for \fBP_tmpdir\fR is \fB/var/tmp\fR. If \fIs\fR is +\fINULL\fR, \fBtmpnam()\fR leaves its result in a thread-specific data area and +returns a pointer to that area. The next call to \fBtmpnam()\fR by the same +thread will destroy the contents of the area. If \fIs\fR is not \fINULL\fR, it +is assumed to be the address of an array of at least \fBL_tmpnam\fR bytes, +where \fBL_tmpnam\fR is a constant defined through inclusion of +<\fBstdio.h\fR>. The \fB tmpnam()\fR function places its result in that array +and returns \fIs\fR. +.SS "\fBtmpnam_r()\fR" +.sp +.LP +The \fBtmpnam_r()\fR function has the same functionality as \fBtmpnam()\fR +except that if \fIs\fR is a null pointer, the function returns \fINULL\fR. +.SS "\fBtempnam()\fR" +.sp +.LP +The \fBtempnam()\fR function allows the user to control the choice of a +directory. The argument \fIdir\fR points to the name of the directory in which +the file is to be created. If \fIdir\fR is \fINULL\fR or points to a string +that is not a name for an appropriate directory, the path prefix defined as +\fBP_tmpdir\fR in the <\fBstdio.h\fR> header is used. If that directory is not +accessible, \fB/tmp\fR is used. If, however, the \fBTMPDIR\fR environment +variable is set in the user's environment, its value is used as the +temporary-file directory. +.sp +.LP +Many applications prefer that temporary files have certain initial character +sequences in their names. The \fIpfx\fR argument may be \fINULL\fR or point to +a string of up to five characters to be used as the initial characters of the +temporary-file name. +.sp +.LP +Upon successful completion, \fBtempnam()\fR uses \fBmalloc\fR(3C) to allocate +space for a string, puts the generated pathname in that space, and returns a +pointer to it. The pointer is suitable for use in a subsequent call to +\fBfree()\fR. If \fBtempnam()\fR cannot return the expected result for any +reason (for example, \fBmalloc()\fR failed), or if none of the above-mentioned +attempts to find an appropriate directory was successful, a null pointer is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBtempnam()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Insufficient storage space is available. +.RE + +.SH USAGE +.sp +.LP +These functions generate a different file name each time they are called. +.sp +.LP +Files created using these functions and either \fBfopen\fR(3C) or +\fBcreat\fR(2) are temporary only in the sense that they reside in a directory +intended for temporary use, and their names are unique. It is the user's +responsibility to remove the file when its use is ended. +.sp +.LP +If called more than \fBTMP_MAX\fR (defined in <\fBstdio.h\fR>) times in a +single process, these functions start recycling previously used names. +.sp +.LP +Between the time a file name is created and the file is opened, it is possible +for some other process to create a file with the same name. This can never +happen if that other process is using these functions or \fBmktemp\fR(3C) and +the file names are chosen to render duplication by other means unlikely. +.sp +.LP +The \fBtmpnam()\fR function is safe to use in multithreaded applications +because it employs thread-specific data if it is passed a NULL pointer. +However, its use is discouraged. The \fBtempnam()\fR function is safe in +multithreaded applications and should be used instead. +.sp +.LP +When compiling multithreaded applications, the \fB_REENTRANT\fR flag must be +defined on the compile line. This flag should be used only with multithreaded +applications. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface Stability\fBtmpnam()\fR and \fBtempnam()\fR are Standard. +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBcreat\fR(2), \fBunlink\fR(2), \fBfopen\fR(3C), \fBfree\fR(3C), +\fBmalloc\fR(3C), \fBmktemp\fR(3C), \fBmkstemp\fR(3C), \fBtmpfile\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/toascii.3c b/usr/src/man/man3c/toascii.3c new file mode 100644 index 0000000000..0e7f6065ad --- /dev/null +++ b/usr/src/man/man3c/toascii.3c @@ -0,0 +1,54 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH toascii 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +toascii \- translate integer to a 7-bit ASCII character +.SH SYNOPSIS +.LP +.nf +#include <ctype.h> + +\fBint\fR \fBtoascii\fR(\fBint\fR \fIc\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBtoascii()\fR function converts its argument into a 7-bit \fBASCII\fR +character. +.SH RETURN VALUES +.sp +.LP +The \fBtoascii()\fR function returns the value \fB(\fR\fIc\fR\fB & 0x7f)\fR. +.SH ERRORS +.sp +.LP +No errors are returned. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +CSIEnabled +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBisascii\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/tolower.3c b/usr/src/man/man3c/tolower.3c new file mode 100644 index 0000000000..6669ba0aa7 --- /dev/null +++ b/usr/src/man/man3c/tolower.3c @@ -0,0 +1,63 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH tolower 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +tolower \- transliterate upper-case characters to lower-case +.SH SYNOPSIS +.LP +.nf +#include <ctype.h> + +\fBint\fR \fBtolower\fR(\fBint\fR \fIc\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBtolower()\fR function has as a domain a type \fBint\fR, the value of +which is representable as an \fBunsigned char\fR or the value of \fBEOF\fR. If +the argument has any other value, the argument is returned unchanged. If the +argument of \fBtolower()\fR represents an upper-case letter, and there exists a +corresponding lower-case letter (as defined by character type information in +the program locale category \fB\fR\fBLC_CTYPE\fR\fB), \fR the result is the +corresponding lower-case letter. All other arguments in the domain are returned +unchanged. +.SH RETURN VALUES +.sp +.LP +On successful completion, \fBtolower()\fR returns the lower-case letter +corresponding to the argument passed. Otherwise, it returns the argument +unchanged. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +CSIEnabled +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fB_tolower\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/toupper.3c b/usr/src/man/man3c/toupper.3c new file mode 100644 index 0000000000..ca353074dd --- /dev/null +++ b/usr/src/man/man3c/toupper.3c @@ -0,0 +1,61 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH toupper 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +toupper \- transliterate lower-case characters to upper-case +.SH SYNOPSIS +.LP +.nf +#include <ctype.h> + +\fBint\fR \fBtoupper\fR(\fBint\fR \fIc\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBtoupper()\fR function has as a domain a type \fBint\fR, the value of +which is representable as an \fBunsigned char\fR or the value of \fBEOF\fR. If +the argument has any other value, the argument is returned unchanged. If the +argument of \fBtoupper()\fR represents a lower-case letter, and there exists a +corresponding upper-case letter (as defined by character type information in +the program locale category \fBLC_CTYPE\fR), the result is the corresponding +upper-case letter. All other arguments in the domain are returned unchanged. +.SH RETURN VALUES +.sp +.LP +On successful completion, \fBtoupper()\fR returns the upper-case letter +corresponding to the argument passed. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +CSIEnabled +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fB_toupper\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/truncate.3c b/usr/src/man/man3c/truncate.3c new file mode 100644 index 0000000000..4120e6632d --- /dev/null +++ b/usr/src/man/man3c/truncate.3c @@ -0,0 +1,391 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH truncate 3C "5 Apr 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +truncate, ftruncate \- set a file to a specified length +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> + +\fBint\fR \fBtruncate\fR(\fBconst char *\fR\fIpath\fR, \fBoff_t\fR \fIlength\fR); +.fi + +.LP +.nf +\fBint\fR \fBftruncate\fR(\fBint\fR \fIfildes\fR, \fBoff_t\fR \fIlength\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBtruncate()\fR function causes the regular file named by \fIpath\fR to +have a size equal to \fIlength\fR bytes. +.sp +.LP +If the file previously was larger than \fIlength\fR, the extra data is +discarded. If the file was previously shorter than length, its size is +increased, and the extended area appears as if it were zero-filled. +.sp +.LP +The application must ensure that the process has write permission for the file. +.sp +.LP +This function does not modify the file offset for any open file descriptions +associated with the file. +.sp +.LP +The \fBftruncate()\fR function causes the regular file referenced by +\fIfildes\fR to be truncated to \fIlength\fR. If the size of the file +previously exceeded \fIlength\fR, the extra data is no longer available to +reads on the file. If the file previously was smaller than this size, +\fBftruncate()\fR increases the size of the file with the extended area +appearing as if it were zero-filled. The value of the seek pointer is not +modified by a call to \fBftruncate()\fR. +.sp +.LP +The \fBftruncate()\fR function works only with regular files and shared memory. +If \fIfildes\fR refers to a shared memory object, \fBftruncate()\fR sets the +size of the shared memory object to \fIlength\fR. If \fIfildes\fR refers to a +directory or is not a valid file descriptor open for writing, \fBftruncate()\fR +fails. +.sp +.LP +If the effect of \fBftruncate()\fR is to decrease the size of a shared memory +object or memory mapped file and whole pages beyond the new end were previously +mapped, then the whole pages beyond the new end shall be discarded. +.sp +.LP +If the effect of \fBftruncate()\fR is to increase the size of a shared memory +object, it is unspecified if the contents of any mapped pages between the old +end-of-file and the new are flushed to the underlying object. +.sp +.LP +These functions do not modify the file offset for any open file descriptions +associated with the file. On successful completion, if the file size is +changed, these functions will mark for update the \fBst_ctime\fR and +\fBst_mtime\fR fields of the file, and if the file is a regular file, the +\fBS_ISUID\fR and \fBS_ISGID\fR bits of the file mode are left unchanged. +.sp +.LP +If the request would cause the file size to exceed the soft file size limit for +the process, the request will fail and a \fBSIGXFSZ\fR signal will be generated +for the process. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBftruncate()\fR and \fBtruncate()\fR return +\fB0\fR. Otherwise, \fB\(mi1\fR is returned and \fBerrno\fR is set to indicate +the error. +.SH ERRORS +.sp +.LP +The \fBftruncate()\fR and \fBtruncate()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 19n +.rt +A signal was caught during execution. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 19n +.rt +The \fIlength\fR argument was less than 0. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFBIG\fR or \fBEINVAL\fR\fR +.ad +.RS 19n +.rt +The \fIlength\fR argument was greater than the maximum file size. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 19n +.rt +An I/O error occurred while reading from or writing to a file system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEROFS\fR\fR +.ad +.RS 19n +.rt +The named file resides on a read-only file system. +.RE + +.sp +.LP +The \fBtruncate()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 16n +.rt +A component of the path prefix denies search permission, or write permission is +denied on the file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 16n +.rt +The \fIpath\fR argument points outside the process' allocated address space. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 16n +.rt +The \fIpath\fR argument is not an ordinary file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEISDIR\fR\fR +.ad +.RS 16n +.rt +The named file is a directory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBELOOP\fR\fR +.ad +.RS 16n +.rt +Too many symbolic links were encountered in resolving \fIpath\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 16n +.rt +The maximum number of file descriptors available to the process has been +reached. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +The length of the specified pathname exceeds {\fBPATH_MAX\fR} bytes, or the +length of a component of the pathname exceeds {\fBNAME_MAX\fR} bytes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 16n +.rt +A component of \fIpath\fR does not name an existing file or \fIpath\fR is an +empty string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENFILE\fR\fR +.ad +.RS 16n +.rt +Additional space could not be allocated for the system file table. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTDIR\fR\fR +.ad +.RS 16n +.rt +A component of the path prefix of \fIpath\fR is not a directory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOLINK\fR\fR +.ad +.RS 16n +.rt +The \fIpath\fR argument points to a remote machine and the link to that machine +is no longer active. +.RE + +.sp +.LP +The \fBftruncate()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 19n +.rt +The file exists, mandatory file/record locking is set, and there are +outstanding record locks on the file (see \fBchmod\fR(2)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR or \fBEINVAL\fR\fR +.ad +.RS 19n +.rt +The \fIfildes\fR argument is not a file descriptor open for writing. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFBIG\fR\fR +.ad +.RS 19n +.rt +The file is a regular file and \fIlength\fR is greater than the offset maximum +established in the open file description associated with \fIfildes\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 19n +.rt +The \fIfildes\fR argument references a file that was opened without write +permission. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 19n +.rt +The \fIfildes\fR argument does not correspond to an ordinary file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOLINK\fR\fR +.ad +.RS 19n +.rt +The \fIfildes\fR argument points to a remote machine and the link to that +machine is no longer active. +.RE + +.sp +.LP +The \fBtruncate()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +Pathname resolution of a symbolic link produced an intermediate result whose +length exceeds {\fBPATH_MAX\fR}. +.RE + +.SH USAGE +.sp +.LP +The \fBtruncate()\fR and \fBftruncate()\fR functions have transitional +interfaces for 64-bit file offsets. See \fBlf64\fR(5). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBchmod\fR(2), \fBfcntl\fR(2), \fBopen\fR(2), \fBattributes\fR(5), +\fBlf64\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/tsearch.3c b/usr/src/man/man3c/tsearch.3c new file mode 100644 index 0000000000..eae068bd57 --- /dev/null +++ b/usr/src/man/man3c/tsearch.3c @@ -0,0 +1,227 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH tsearch 3C "6 Dec 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +tsearch, tfind, tdelete, twalk \- manage binary search trees +.SH SYNOPSIS +.LP +.nf +#include <search.h> + +\fBvoid *\fR\fBtsearch\fR(\fBconst void *\fR\fIkey\fR, \fBvoid **\fR\fIrootp\fR, + \fBint (*\fR\fIcompar\fR)(const void *, const void *)); +.fi + +.LP +.nf +\fBvoid *\fR\fBtfind\fR(\fBconst void *\fR\fIkey\fR, \fBvoid * const *\fR\fIrootp\fR, + \fBint (*\fR\fIcompar\fR)(const void *, const void *)); +.fi + +.LP +.nf +\fBvoid *\fR\fBtdelete\fR(\fBconst void *restrict\fR \fIkey\fR, \fBvoid **restrict\fR \fIrootp\fR, + \fBint (*\fR\fIcompar\fR)(const void *, const void *)); +.fi + +.LP +.nf +\fBvoid\fR \fBtwalk\fR(\fBconst void *\fR\fIroot\fR, \fBvoid(*\fR\fIaction\fR) (void *, VISIT, int)); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBtsearch()\fR, \fBtfind()\fR, \fBtdelete()\fR, and \fBtwalk()\fR +functions are routines for manipulating binary search trees. They are +generalized from \fIKnuth\fR \fI(6.2.2)\fR \fIAlgorithms\fR \fIT\fR \fIand\fR +\fID.\fR All comparisons are done with a user-supplied routine. This routine is +called with two arguments, the pointers to the elements being compared. It +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. +.sp +.LP +The \fBtsearch()\fR function is used to build and access the tree. The +\fIkey\fR argument is a pointer to a datum to be accessed or stored. If there +is a datum in the tree equal to \fI*key\fR (the value pointed to by \fIkey\fR), +a pointer to this found datum is returned. Otherwise, \fI*key\fR is inserted, +and a pointer to it returned. Only pointers are copied, so the calling routine +must store the data. The \fIrootp\fR argument points to a variable that points +to the root of the tree. A null value for the variable pointed to by +\fIrootp\fR denotes an empty tree; in this case, the variable will be set to +point to the datum which will be at the root of the new tree. +.sp +.LP +Like \fBtsearch()\fR, \fBtfind()\fR will search for a datum in the tree, +returning a pointer to it if found. However, if it is not found, \fBtfind()\fR +will return a null pointer. The arguments for \fBtfind()\fR are the same as for +\fBtsearch()\fR. +.sp +.LP +The \fBtdelete()\fR function deletes a node from a binary search tree. The +arguments are the same as for \fBtsearch()\fR. The variable pointed to by +\fIrootp\fR will be changed if the deleted node was the root of the tree. +\fBtdelete()\fR returns a pointer to the parent of the deleted node, or a null +pointer if the node is not found. +.sp +.LP +The \fBtwalk()\fR function traverses a binary search tree. The \fIroot\fR +argument is the root of the tree to be traversed. (Any node in a tree may be +used as the root for a walk below that node.) \fIaction\fR is the name of a +routine to be invoked at each node. This routine is, in turn, called with three +arguments. The first argument is the address of the node being visited. The +second argument is a value from an enumeration data type +.sp +.in +2 +.nf +typedef enum { preorder, postorder, endorder, leaf } VISIT; +.fi +.in -2 + +.sp +.LP +(defined in <\fBsearch.h\fR>), depending on whether this is the first, second +or third time that the node has been visited (during a depth-first, +left-to-right traversal of the tree), or whether the node is a leaf. The third +argument is the level of the node in the tree, with the root being level zero. +.sp +.LP +The pointers to the key and the root of the tree should be of type +pointer-to-element, and cast to type pointer-to-character. Similarly, although +declared as type pointer-to-character, the value returned should be cast into +type pointer-to-element. +.SH RETURN VALUES +.sp +.LP +If the node is found, both \fBtsearch()\fR and \fBtfind()\fR return a pointer +to it. If not, \fBtfind()\fR returns a null pointer, and \fBtsearch()\fR +returns a pointer to the inserted item. +.sp +.LP +A null pointer is returned by \fBtsearch()\fR if there is not enough space +available to create a new node. +.sp +.LP +A null pointer is returned by \fBtsearch()\fR, \fBtfind()\fR and +\fBtdelete()\fR if \fIrootp\fR is a null pointer on entry. +.sp +.LP +The \fBtdelete()\fR function returns a pointer to the parent of the deleted +node, or a null pointer if the node is not found. +.sp +.LP +The \fBtwalk()\fR function returns no value. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH USAGE +.sp +.LP +The \fIroot\fR argument to \fBtwalk()\fR is one level of indirection less than +the \fIrootp\fR arguments to \fBtsearch()\fR and \fBtdelete()\fR. +.sp +.LP +There are two nomenclatures used to refer to the order in which tree nodes are +visited. \fBtsearch()\fR uses preorder, postorder and endorder 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 alternate +nomenclature uses preorder, inorder and postorder to refer to the same visits, +which could result in some confusion over the meaning of postorder. +.sp +.LP +If the calling function alters the pointer to the root, the results are +unpredictable. +.sp +.LP +These functions safely allows concurrent access by multiple threads to disjoint +data, such as overlapping subtrees or tables. +.SH EXAMPLES +.LP +\fBExample 1 \fRA sample program of using \fBtsearch()\fR function. +.sp +.LP +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 +.in +2 +.nf +#include <string.h> +#include <stdio.h> +#include <search.h> +struct node { + char *string; + int length; +}; +char string_space[10000]; +struct node nodes[500]; +void *root = NULL; + +int node_compare(const void *node1, const void *node2) { + return strcmp(((const struct node *) node1)->string, + ((const struct node *) node2)->string); +} + +void print_node(const void *node, VISIT order, int level) { + if (order == preorder || order == leaf) { + printf("length=%d, string=%20s\en", + (*(struct node **)node)->length, + (*(struct node **)node)->string); + } +} + +main() +{ + char *strptr = string_space; + struct node *nodeptr = nodes; + int i = 0; + + while (gets(strptr) != NULL && i++ < 500) { + nodeptr->string = strptr; + nodeptr->length = strlen(strptr); + (void) tsearch((void *)nodeptr, + &root, node_compare); + strptr += nodeptr->length + 1; + nodeptr++; + } + twalk(root, print_node); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBbsearch\fR(3C), \fBhsearch\fR(3C), \fBlsearch\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/ttyname.3c b/usr/src/man/man3c/ttyname.3c new file mode 100644 index 0000000000..c4bfcc1462 --- /dev/null +++ b/usr/src/man/man3c/ttyname.3c @@ -0,0 +1,149 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ttyname 3C "31 Mar 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +ttyname, ttyname_r \- find pathname of a terminal +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> + +\fBchar *\fR\fBttyname\fR(\fBint\fR \fIfildes\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBttyname_r\fR(\fBint\fR \fIfildes\fR, \fBchar *\fR\fIname\fR, \fBint\fR \fInamelen\fR); +.fi + +.SS "Standard conforming" +.LP +.nf +cc [ \fIflag\fR...] \fIfile\fR ... \fB-D_POSIX_PTHREAD_SEMANTICS\fR [ \fIlibrary\fR ... ] + +\fBint\fR \fBttyname_r\fR(\fBint\fR \fIfildes\fR, \fBchar *\fR\fIname\fR, \fBsize_t\fR \fInamesize\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBttyname()\fR function returns a pointer to a string containing the +null-terminated path name of the terminal device associated with file +descriptor \fIfildes\fR. The return value points to thread-specific data whose +content is overwritten by each call from the same thread. +.sp +.LP +The \fBttyname_r()\fR function has the same functionality as \fBttyname()\fR +except that the caller must supply a buffer \fIname\fR with length +\fInamelen\fR to store the result; this buffer must be at least +\fB_POSIX_PATH_MAX\fR in size (defined in <\fBlimits.h\fR>). The +standard-conforming version (see \fBstandards\fR(5)) of \fBttyname_r()\fR takes +a \fInamesize\fR parameter of type \fBsize_t\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBttyname()\fR and \fBttyname_r()\fR return a +pointer to a string. Otherwise, a null pointer is returned and \fBerrno\fR is +set to indicate the error. +.sp +.LP +The standard-conforming \fBttyname_r()\fR returns 0 if successful or the error +number upon failure. +.SH ERRORS +.sp +.LP +The \fBttyname()\fR and \fBttyname_r()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIfildes\fR argument is not a valid file descriptor. This condition is +reported. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTTY\fR\fR +.ad +.RS 10n +.rt +The \fIfildes\fR argument does not refer to a terminal device. This condition +is reported. +.RE + +.sp +.LP +The \fBttyname_r()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBERANGE\fR\fR +.ad +.RS 10n +.rt +The value of \fInamesize\fR is smaller than the length of the string to be +returned including the terminating null character. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(3), \fBgettext\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) +.SH NOTES +.sp +.LP +When compiling multithreaded applications, see \fBIntro\fR(3), \fINotes On +Multithreaded Applications\fR. +.sp +.LP +Messages printed from this function are in the native language specified by the +\fBLC_MESSAGES\fR locale category. See \fBsetlocale\fR(3C). +.sp +.LP +The return value of \fBttyname()\fR points to thread-specific data whose +content is overwritten by each call from the same thread. This function is safe +to use in multithreaded applications, but its use is discouraged. The +\fBttyname_r()\fR function should used instead. +.sp +.LP +Solaris 2.4 and earlier releases provided definitions of the \fBttyname_r()\fR +interface as specified in POSIX.1c Draft 6. The final POSIX.1c standard changed +the interface as described above. Support for the Draft 6 interface is provided +for compatibility only and might not be supported in future releases. New +applications and libraries should use the standard-conforming interface. diff --git a/usr/src/man/man3c/ttyslot.3c b/usr/src/man/man3c/ttyslot.3c new file mode 100644 index 0000000000..a1ce5d4df0 --- /dev/null +++ b/usr/src/man/man3c/ttyslot.3c @@ -0,0 +1,66 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ttyslot 3C "27 Oct 1998" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +ttyslot \- find the slot of the current user in the user accounting database +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBint\fR \fBttyslot\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBttyslot()\fR function returns the index of the current user's entry in +the user accounting database, \fB/var/adm/utmpx\fR. The current user's entry is +an entry for which the \fButline\fR member matches the name of a terminal +device associated with any of the process's file descriptors 0, 1 or 2. The +index is an ordinal number representing the record number in the database of +the current user's entry. The first entry in the database is represented by +the return value 0. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBttyslot()\fR returns the index of the current +user's entry in the user accounting database. If an error was encountered while +searching for the terminal name or if none of the above file descriptors are +associated with a terminal device, \fB\(mi1\fR is returned. +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/var/adm/utmpx\fR\fR +.ad +.RS 18n +.rt +user access and accounting information +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgetutent\fR(3C), \fBttyname\fR(3C), \fButmpx\fR(4), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/u8_strcmp.3c b/usr/src/man/man3c/u8_strcmp.3c new file mode 100644 index 0000000000..e11bdd404f --- /dev/null +++ b/usr/src/man/man3c/u8_strcmp.3c @@ -0,0 +1,378 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH u8_strcmp 3C "12 Sep 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +u8_strcmp \- UTF-8 string comparison function +.SH SYNOPSIS +.LP +.nf +#include <sys/u8_textprep.h> + +\fBint\fR \fBu8_strcmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR, + \fBint\fR \fIflag\fR, \fBsize_t\fR \fIversion\fR, \fBint *\fR\fIerrnum\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIs1\fR, \fIs2\fR\fR +.ad +.RS 13n +.rt +Pointers to null-terminated UTF-8 strings +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIn\fR\fR +.ad +.RS 13n +.rt +The maximum number of bytes to be compared. If 0, the comparison is performed +until either or both of the strings are examined to the string terminating null +byte. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflag\fR\fR +.ad +.RS 13n +.rt +The possible comparison options constructed by a bit-wise-inclusive-OR of the +following values: +.sp +.ne 2 +.mk +.na +\fB\fBU8_STRCMP_CS\fR\fR +.ad +.sp .6 +.RS 4n +Perform case-sensitive string comparison. This is the default. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_STRCMP_CI_UPPER\fR\fR +.ad +.sp .6 +.RS 4n +Perform case-insensitive string comparison based on Unicode upper case +converted results of \fIs1\fR and \fIs2\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_STRCMP_CI_LOWER\fR\fR +.ad +.sp .6 +.RS 4n +Perform case-insensitive string comparison based on Unicode lower case +converted results of \fIs1\fR and \fIs2\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_STRCMP_NFD\fR\fR +.ad +.sp .6 +.RS 4n +Perform string comparison after \fIs1\fR and \fIs2\fR have been normalized by +using Unicode Normalization Form D. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_STRCMP_NFC\fR\fR +.ad +.sp .6 +.RS 4n +Perform string comparison after \fIs1\fR and \fIs2\fR have been normalized by +using Unicode Normalization Form C. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_STRCMP_NFKD\fR\fR +.ad +.sp .6 +.RS 4n +Perform string comparison after \fIs1\fR and \fIs2\fR have been normalized by +using Unicode Normalization Form KD. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_STRCMP_NFKC\fR\fR +.ad +.sp .6 +.RS 4n +Perform string comparison after \fIs1\fR and \fIs2\fR have been normalized by +using Unicode Normalization Form KC. +.RE + +Only one case-sensitive or case-insensitive option is allowed. Only one Unicode +Normalization option is allowed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIversion\fR\fR +.ad +.RS 13n +.rt +The version of Unicode data that should be used during comparison. The +following values are supported: +.sp +.ne 2 +.mk +.na +\fB\fBU8_UNICODE_320\fR\fR +.ad +.sp .6 +.RS 4n +Use Unicode 3.2.0 data during comparison. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_UNICODE_500\fR\fR +.ad +.sp .6 +.RS 4n +Use Unicode 5.0.0 data during comparison. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_UNICODE_LATEST\fR\fR +.ad +.sp .6 +.RS 4n +Use the latest Unicode version data available, which is Unicode 5.0.0. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIerrnum\fR\fR +.ad +.RS 13n +.rt +A non-zero value indicates that an error has occurred during comparison. The +following values are supported: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The specified option values are conflicting and cannot be supported. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEILSEQ\fR\fR +.ad +.RS 10n +.rt +There was an illegal character at \fIs1\fR, \fIs2\fR, or both. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +There was an incomplete character at \fIs1\fR, \fIs2\fR, or both. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBERANGE\fR\fR +.ad +.RS 10n +.rt +The specified Unicode version value is not supported. +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBu8_stcmp()\fR function internally processes UTF-8 strings pointed to by +\fIs1\fR and \fIs2\fR based on the corresponding version of the Unicode +Standard and other input arguments and compares the result strings in +byte-by-byte, machine ordering. +.sp +.LP +When multiple comparison options are specified, Unicode Normalization is +performed after case-sensitive or case-insensitive processing is performed. +.SH RETURN VALUES +.sp +.LP +The \fBu8_strcmp()\fR function returns an integer greater than, equal to, or +less than 0 if the string pointed to by \fIs1\fR is greater than, equal to, or +less than the string pointed to by \fIs2\fR, respectively. +.sp +.LP +When \fBu8_strcmp()\fR detects an illegal or incomplete character, such +character causes the function to set \fIerrnum\fR to indicate the error. +Afterward, the comparison is still performed on the resultant strings and a +value based on byte-by-byte comparison is always returned. +.SH EXAMPLES +.LP +\fBExample 1 \fRPerform simple default string comparison. +.sp +.in +2 +.nf +#include <sys/u8_textprep.h> + +int +docmp_default(const char *u1, const char *u2) { + int result; + int errnum; + + result = u8_strcmp(u1, u2, 0, 0, U8_UNICODE_LATEST, &errnum); + if (errnum == EILSEQ) + return (-1); + if (errnum == EINVAL) + return (-2); + if (errnum == EBADF) + return (-3); + if (errnum == ERANGE) + return (-4); +.fi +.in -2 + +.LP +\fBExample 2 \fRPerform upper case based case-insensitive comparison with +Unicode 3.2.0 date. +.sp +.in +2 +.nf +#include <sys/u8_textprep.h> + +int +docmp_caseinsensitive_u320(const char *u1, const char *u2) { + int result; + int errnum; + + result = u8_strcmp(u1, u2, 0, U8_STRCMP_CI_UPPER, + U8_UNICODE_320, &errnum); + if (errnum == EILSEQ) + return (-1); + if (errnum == EINVAL) + return (-2); + if (errnum == EBADF) + return (-3); + if (errnum == ERANGE) + return (-4); + + return (result); +} +.fi +.in -2 + +.LP +\fBExample 3 \fRPerform Unicode Normalization Form D. +.sp +.LP +Perform Unicode Normalization Form D and upper case based case-insensitive +comparison with Unicode 3.2.0 date. + +.sp +.in +2 +.nf +#include <sys/u8_textprep.h> + +int +docmp_nfd_caseinsensitive_u320(const char *u1, const char *u2) { + int result; + int errnum; + + result = u8_strcmp(u1, u2, 0, + (U8_STRCMP_NFD|U8_STRCMP_CI_UPPER), U8_UNICODE_320, + &errnum); + if (errnum == EILSEQ) + return (-1); + if (errnum == EINVAL) + return (-2); + if (errnum == EBADF) + return (-3); + if (errnum == ERANGE) + return (-4); + + return (result); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBu8_textprep_str\fR(3C), \fBu8_validate\fR(3C), \fBattributes\fR(5), +\fBu8_strcmp\fR(9F), \fBu8_textprep_str\fR(9F), \fBu8_validate\fR(9F) +.sp +.LP +The Unicode Standard (http://www.unicode.org) diff --git a/usr/src/man/man3c/u8_textprep_str.3c b/usr/src/man/man3c/u8_textprep_str.3c new file mode 100644 index 0000000000..86fb3149ea --- /dev/null +++ b/usr/src/man/man3c/u8_textprep_str.3c @@ -0,0 +1,424 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH u8_textprep_str 3C "18 Sep 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +u8_textprep_str \- string-based UTF-8 text preparation function +.SH SYNOPSIS +.LP +.nf +#include <sys/u8_textprep.h> + +\fBsize_t\fR \fBu8_textprep_str\fR(\fBchar *\fR\fIinarray\fR, \fBsize_t *\fR\fIinlen\fR, + \fBchar *\fR\fIoutarray\fR, \fBsize_t *\fR\fIoutlen\fR, \fBint\fR \fIflag\fR, + \fBsize_t\fR \fIunicode_version\fR, \fBint *\fR\fIerrnum\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIinarray\fR\fR +.ad +.RS 20n +.rt +A pointer to a byte array containing a sequence of UTF-8 character bytes to be +prepared. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIinlen\fR\fR +.ad +.RS 20n +.rt +As input argument, the number of bytes to be prepared in \fIinarray\fR. As +output argument, the number of bytes in \fIinarray\fR still not consumed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoutarray\fR\fR +.ad +.RS 20n +.rt +A pointer to a byte array where prepared UTF-8 character bytes can be saved. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoutlen\fR\fR +.ad +.RS 20n +.rt +As input argument, the number of available bytes at \fIoutarray\fR where +prepared character bytes can be saved. As output argument, after the +conversion, the number of bytes still available at \fIoutarray\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflag\fR\fR +.ad +.RS 20n +.rt +The possible preparation options constructed by a bitwise-inclusive-OR of the +following values: +.sp +.ne 2 +.mk +.na +\fB\fBU8_TEXTPREP_IGNORE_NULL\fR\fR +.ad +.sp .6 +.RS 4n +Normally \fBu8_textprep_str()\fR stops the preparation if it encounters null +byte even if the current \fIinlen\fR is pointing to a value bigger than zero. +.sp +With this option, null byte does not stop the preparation and the preparation +continues until \fIinlen\fR specified amount of \fIinarray\fR bytes are all +consumed for preparation or an error happened. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_TEXTPREP_IGNORE_INVALID\fR\fR +.ad +.sp .6 +.RS 4n +Normally \fBu8_textprep_str()\fR stops the preparation if it encounters illegal +or incomplete characters with corresponding \fIerrnum\fR values. +.sp +When this option is set, \fBu8_textprep_str()\fR does not stop the preparation +and instead treats such characters as no need to do any preparation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_TEXTPREP_TOUPPER\fR\fR +.ad +.sp .6 +.RS 4n +Map lowercase characters to uppercase characters if applicable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_TEXTPREP_TOLOWER\fR\fR +.ad +.sp .6 +.RS 4n +Map uppercase characters to lowercase characters if applicable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_TEXTPREP_NFD\fR\fR +.ad +.sp .6 +.RS 4n +Apply Unicode Normalization Form D. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_TEXTPREP_NFC\fR\fR +.ad +.sp .6 +.RS 4n +Apply Unicode Normalization Form C. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_TEXTPREP_NFKD\fR\fR +.ad +.sp .6 +.RS 4n +Apply Unicode Normalization Form KD. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_TEXTPREP_NFKC\fR\fR +.ad +.sp .6 +.RS 4n +Apply Unicode Normalization Form KC. +.RE + +Only one case folding option is allowed. Only one Unicode Normalization option +is allowed. +.sp +When a case folding option and a Unicode Normalization option are specified +together, UTF-8 text preparation is done by doing case folding first and then +Unicode Normalization. +.sp +If no option is specified, no processing occurs except the simple copying of +bytes from input to output. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIunicode_version\fR\fR +.ad +.RS 20n +.rt +The version of Unicode data that should be used during UTF-8 text preparation. +The following values are supported: +.sp +.ne 2 +.mk +.na +\fB\fBU8_UNICODE_320\fR\fR +.ad +.sp .6 +.RS 4n +Use Unicode 3.2.0 data during comparison. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_UNICODE_500\fR\fR +.ad +.sp .6 +.RS 4n +Use Unicode 5.0.0 data during comparison. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_UNICODE_LATEST\fR\fR +.ad +.sp .6 +.RS 4n +Use the latest Unicode version data available which is Unicode 5.0.0 currently. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIerrnum\fR\fR +.ad +.RS 20n +.rt +The error value when preparation is not completed or fails. The following +values are supported: +.sp +.ne 2 +.mk +.na +\fB\fBE2BIG\fR\fR +.ad +.RS 10n +.rt +Text preparation stopped due to lack of space in the output array. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +Specified option values are conflicting and cannot be supported. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEILSEQ\fR\fR +.ad +.RS 10n +.rt +Text preparation stopped due to an input byte that does not belong to UTF-8. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +Text preparation stopped due to an incomplete UTF-8 character at the end of the +input array. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBERANGE\fR\fR +.ad +.RS 10n +.rt +The specified Unicode version value is not a supported version. +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBu8_textprep_str()\fR function prepares the sequence of UTF-8 characters +in the array specified by \fIinarray\fR into a sequence of corresponding UTF-8 +characters prepared in the array specified by \fIoutarray\fR. The \fIinarray\fR +argument points to a character byte array to the first character in the input +array and \fIinlen\fR indicates the number of bytes to the end of the array to +be converted. The \fIoutarray\fR argument points to a character byte array to +the first available byte in the output array and \fIoutlen\fR indicates the +number of the available bytes to the end of the array. Unless \fIflag\fR is +\fBU8_TEXTPREP_IGNORE_NULL\fR, \fBu8_textprep_str()\fR normally stops when it +encounters a null byte from the input array regardless of the current +\fIinlen\fR value. +.sp +.LP +If \fIflag\fR is \fBU8_TEXTPREP_IGNORE_INVALID\fR and a sequence of input bytes +does not form a valid UTF-8 character, preparation stops after the previous +successfully prepared character. If \fIflag\fR is +\fBU8_TEXTPREP_IGNORE_INVALID\fR and the input array ends with an incomplete +UTF-8 character, preparation stops after the previous successfully prepared +bytes. If the output array is not large enough to hold the entire prepared +text, preparation stops just prior to the input bytes that would cause the +output array to overflow. The value pointed to by \fIinlen\fR is decremented to +reflect the number of bytes still not prepared in the input array. The value +pointed to by \fIoutlen\fR is decremented to reflect the number of bytes still +available in the output array. +.SH RETURN VALUES +.sp +.LP +The \fBu8_textprep_str()\fR function updates the values pointed to by +\fIinlen\fR and \fIoutlen\fR arguments to reflect the extent of the +preparation. When \fBU8_TEXTPREP_IGNORE_INVALID\fR is specified, +\fBu8_textprep_str()\fR returns the number of illegal or incomplete characters +found during the text preparation. When \fBU8_TEXTPREP_IGNORE_INVALID\fR is not +specified and the text preparation is entirely successful, the function returns +0. If the entire string in the input array is prepared, the value pointed to by +\fIinlen\fR will be 0. If the text preparation is stopped due to any conditions +mentioned above, the value pointed to by \fIinlen\fR will be non-zero and +\fIerrnum\fR is set to indicate the error. If such and any other error occurs, +\fBu8_textprep_str()\fR returns (\fBsize_t\fR)-1 and sets \fIerrnum\fR to +indicate the error. +.SH EXAMPLES +.LP +\fBExample 1 \fRSimple UTF-8 text preparation +.sp +.in +2 +.nf +#include <sys/u8_textprep.h> +\&. +\&. +\&. +size_t ret; +char ib[MAXPATHLEN]; +char ob[MAXPATHLEN]; +size_t il, ol; +int err; +\&. +\&. +\&. +/* + * We got a UTF-8 pathname from somewhere. + * + * Calculate the length of input string including the terminating + * NULL byte and prepare other arguments. + */ +(void) strlcpy(ib, pathname, MAXPATHLEN); +il = strlen(ib) + 1; +ol = MAXPATHLEN; + +/* + * Do toupper case folding, apply Unicode Normalization Form D, + * ignore NULL byte, and ignore any illegal/incomplete characters. + */ +ret = u8_textprep_str(ib, &il, ob, &ol, + (U8_TEXTPREP_IGNORE_NULL|U8_TEXTPREP_IGNORE_INVALID| + U8_TEXTPREP_TOUPPER|U8_TEXTPREP_NFD), U8_UNICODE_LATEST, &err); +if (ret == (size_t)-1) { + if (err == E2BIG) + return (-1); + if (err == EBADF) + return (-2); + if (err == ERANGE) + return (-3); + return (-4); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBu8_strcmp\fR(3C), \fBu8_validate\fR(3C), \fBattributes\fR(5), +\fBu8_strcmp\fR(9F), \fBu8_textprep_str\fR(9F), \fBu8_validate\fR(9F) +.sp +.LP +The Unicode Standard (http://www.unicode.org) +.SH NOTES +.sp +.LP +After the text preparation, the number of prepared UTF-8 characters and the +total number bytes may decrease or increase when you compare the numbers with +the input buffer. +.sp +.LP +Case conversions are performed using Unicode data of the corresponding version. +There are no locale-specific case conversions that can be performed. diff --git a/usr/src/man/man3c/u8_validate.3c b/usr/src/man/man3c/u8_validate.3c new file mode 100644 index 0000000000..cbe4ed41ea --- /dev/null +++ b/usr/src/man/man3c/u8_validate.3c @@ -0,0 +1,309 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH u8_validate 3C "18 Sep 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +u8_validate \- validate UTF-8 characters and calculate the byte length +.SH SYNOPSIS +.LP +.nf +#include <sys/u8_textprep.h> + +\fBint\fR u8_validate(\fBchar *\fR\fIu8str\fR, \fBsize_t\fR \fIn\fR, \fBchar **\fR\fIlist\fR, \fBint\fR \fIflag\fR, + \fBint *\fR\fIerrnum\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIu8str\fR\fR +.ad +.RS 10n +.rt +The UTF-8 string to be validated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIn\fR\fR +.ad +.RS 10n +.rt +The maximum number of bytes in \fIu8str\fR that can be examined and validated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlist\fR\fR +.ad +.RS 10n +.rt +A list of null-terminated character strings in UTF-8 that must be additionally +checked against as invalid characters. The last string in \fIlist\fR must be +null to indicate there is no further string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflag\fR\fR +.ad +.RS 10n +.rt +Possible validation options constructed by a bitwise-inclusive-OR of the +following values: +.sp +.ne 2 +.mk +.na +\fB\fBU8_VALIDATE_ENTIRE\fR\fR +.ad +.sp .6 +.RS 4n +By default, \fBu8_validate()\fR looks at the first character or up to \fIn\fR +bytes, whichever is smaller in terms of the number of bytes to be consumed, and +returns with the result. +.sp +When this option is used, \fBu8_validate()\fR will check up to \fIn\fR bytes +from \fIu8str\fR and possibly more than a character before returning the +result. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_VALIDATE_CHECK_ADDITIONAL\fR\fR +.ad +.sp .6 +.RS 4n +By default, \fBu8_validate()\fR does not use list supplied. +.sp +When this option is supplied with a list of character strings, +\fBu8_validate()\fR additionally validates \fIu8str\fR against the character +strings supplied with \fIlist\fR and returns EBADF in \fIerrnum\fR if +\fIu8str\fR has any one of the character strings in \fIlist\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_VALIDATE_UCS2_RANGE\fR\fR +.ad +.sp .6 +.RS 4n +By default, \fBu8_validate()\fR uses the entire Unicode coding space of U+0000 +to U+10FFFF. +.sp +When this option is specified, the valid Unicode coding space is smaller to +U+0000 to U+FFFF. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIerrnum\fR\fR +.ad +.RS 10n +.rt +An error occurred during validation. The following values are supported: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +Validation failed because list-specified characters were found in the string +pointed to by \fIu8str\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEILSEQ\fR\fR +.ad +.RS 10n +.rt +Validation failed because an illegal byte was found in the string pointed to by +\fIu8str\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +Validation failed because an incomplete byte was found in the string pointed to +by \fIu8str\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBERANGE\fR\fR +.ad +.RS 10n +.rt +Validation failed because character bytes were encountered that are outside the +range of the Unicode coding space. +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBu8_validate()\fR function validates \fIu8str\fR in UTF-8 and determines +the number of bytes constituting the character(s) pointed to by \fIu8str\fR. +.SH RETURN VALUES +.sp +.LP +If \fIu8str\fR is a null pointer, \fBu8_validate()\fR returns 0. Otherwise, +\fBu8_validate()\fR returns either the number of bytes that constitute the +characters if the next \fIn\fR or fewer bytes form valid characters, or -1 if +there is an validation failure, in which case it may set \fIerrnum\fR to +indicate the error. +.SH EXAMPLES +.LP +\fBExample 1 \fRDetermine the length of the first UTF-8 character. +.sp +.in +2 +.nf +#include <sys/u8_textprep.h> + +char u8[MAXPATHLEN]; +int errnum; +\&. +\&. +\&. +len = u8_validate(u8, 4, (char **)NULL, 0, &errnum); +if (len == -1) { + switch (errnum) { + case EILSEQ: + case EINVAL: + return (MYFS4_ERR_INVAL); + case EBADF: + return (MYFS4_ERR_BADNAME); + case ERANGE: + return (MYFS4_ERR_BADCHAR); + default: + return (-10); + } +} +.fi +.in -2 + +.LP +\fBExample 2 \fRCheck if there are any invalid characters in the entire string. +.sp +.in +2 +.nf +#include <sys/u8_textprep.h> + +char u8[MAXPATHLEN]; +int n; +int errnum; +\&. +\&. +\&. +n = strlen(u8); +len = u8_validate(u8, n, (char **)NULL, U8_VALIDATE_ENTIRE, &errnum); +if (len == -1) { + switch (errnum) { + case EILSEQ: + case EINVAL: + return (MYFS4_ERR_INVAL); + case EBADF: + return (MYFS4_ERR_BADNAME); + case ERANGE: + return (MYFS4_ERR_BADCHAR); + default: + return (-10); + } +} +.fi +.in -2 + +.LP +\fBExample 3 \fRCheck if there is any invalid character, including prohibited +characters, in the entire string. +.sp +.in +2 +.nf +#include <sys/u8_textprep.h> + +char u8[MAXPATHLEN]; +int n; +int errnum; +char *prohibited[4] = { + ".", "..", "\e\e", NULL +}; +\&. +\&. +\&. +n = strlen(u8); +len = u8_validate(u8, n, prohibited, + (U8_VALIDATE_ENTIRE|U8_VALIDATE_CHECK_ADDITIONAL), &errnum); +if (len == -1) { + switch (errnum) { + case EILSEQ: + case EINVAL: + return (MYFS4_ERR_INVAL); + case EBADF: + return (MYFS4_ERR_BADNAME); + case ERANGE: + return (MYFS4_ERR_BADCHAR); + default: + return (-10); + } +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBu8_strcmp\fR(3C), \fBu8_textprep_str\fR(3C), \fBattributes\fR(5), +\fBu8_strcmp\fR(9F), \fBu8_textprep_str\fR(9F), \fBu8_validate\fR(9F) +.sp +.LP +The Unicode Standard (http://www.unicode.org) diff --git a/usr/src/man/man3c/ualarm.3c b/usr/src/man/man3c/ualarm.3c new file mode 100644 index 0000000000..5e5ead8f11 --- /dev/null +++ b/usr/src/man/man3c/ualarm.3c @@ -0,0 +1,72 @@ +'\" te +.\" Copyright (c) 1980 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, +.\" X/Open Company Limited All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.TH ualarm 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +ualarm \- schedule signal after interval in microseconds +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> + +\fBuseconds_t\fR \fBualarm\fR(\fBuseconds_t\fR \fIuseconds\fR, \fBuseconds_t\fR \fIinterval\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBualarm()\fR function causes the \fBSIGALRM\fR signal to be generated for +the calling process after the number of real-time microseconds specified by the +\fIuseconds\fR argument has elapsed. When the \fIinterval\fR argument is +non-zero, repeated timeout notification occurs with a period in microseconds +specified by the \fIinterval\fR argument. If the notification signal, +\fBSIGALRM\fR, is not caught or ignored, the calling process is terminated. +.sp +.LP +Because of scheduling delays, resumption of execution when the signal is caught +may be delayed an arbitrary amount of time. +.sp +.LP +Interactions between \fBualarm()\fR and either \fBalarm\fR(2) or +\fBsleep\fR(3C) are unspecified. +.SH RETURN VALUES +.sp +.LP +The \fBualarm()\fR function returns the number of microseconds remaining from +the previous \fBualarm()\fR call. If no timeouts are pending or if +\fBualarm()\fR has not previously been called, \fBualarm()\fR returns \fB0\fR. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH USAGE +.sp +.LP +The \fBualarm()\fR function is a simplified interface to \fBsetitimer\fR(2), +and uses the \fBITIMER_REAL\fR interval timer. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +.TE + +.SH SEE ALSO +.sp +.LP +\fBalarm\fR(2), \fBsetitimer\fR(2), \fBsighold\fR(3C), \fBsignal\fR(3C), +\fBsleep\fR(3C), \fBusleep\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/uconv_u16tou32.3c b/usr/src/man/man3c/uconv_u16tou32.3c new file mode 100644 index 0000000000..c94cf32c07 --- /dev/null +++ b/usr/src/man/man3c/uconv_u16tou32.3c @@ -0,0 +1,532 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH uconv_u16tou32 3C "18 Sep 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +uconv_u16tou32, uconv_u16tou8, uconv_u32tou16, uconv_u32tou8, uconv_u8tou16, +uconv_u8tou32 \- Unicode encoding conversion functions +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/errno.h> +#include <sys/u8_textprep.h> + +\fBint\fR \fBuconv_u16tou32\fR(const \fBuint16_t *\fR\fIutf16str\fR, \fBsize_t *\fR\fIutf16len\fR, + \fBuint32_t *\fR\fIutf32str\fR, \fBsize_t *\fR\fIutf32len\fR, \fBint\fR \fIflag\fR); +.fi + +.LP +.nf +\fBint\fR \fBuconv_u16tou8\fR(const \fBuint16_t *\fR\fIutf16str\fR, \fBsize_t *\fR\fIutf16len\fR, + \fBuchar_t *\fR\fIutf8str\fR, \fBsize_t *\fR\fIutf8len\fR, \fBint\fR \fIflag\fR); +.fi + +.LP +.nf +\fBint\fR \fBuconv_u32tou16\fR(const \fBuint32_t *\fR\fIutf32str\fR, \fBsize_t *\fR\fIutf32len\fR, + \fBuint16_t *\fR\fIutf16str\fR, \fBsize_t *\fR\fIutf16len\fR, \fBint\fR \fIflag\fR); +.fi + +.LP +.nf +\fBint\fR \fBuconv_u32tou8\fR(const \fBuint32_t *\fR\fIutf32str\fR, \fBsize_t *\fR\fIutf32len\fR, + \fBuchar_t *\fR\fIutf8str\fR, \fBsize_t *\fR\fIutf8len\fR, \fBint\fR \fIflag\fR); +.fi + +.LP +.nf +\fBint\fR \fBuconv_u8tou16\fR(const \fBuchar_t *\fR\fIutf8str\fR, \fBsize_t *\fR\fIutf8len\fR, + \fBuint16_t *\fR\fIutf16str\fR, \fBsize_t *\fR\fIutf16len\fR, \fBint\fR \fIflag\fR); +.fi + +.LP +.nf +\fBint\fR \fBuconv_u8tou32\fR(const \fBuchar_t *\fR\fIutf8str\fR, \fBsize_t *\fR\fIutf8len\fR, + \fBuint32_t *\fR\fIutf32str\fR, \fBsize_t *\fR\fIutf32len\fR, \fBint\fR \fIflag\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIutf16str\fR\fR +.ad +.RS 12n +.rt +A pointer to a \fBUTF-16\fR character string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIutf16len\fR\fR +.ad +.RS 12n +.rt +As an input parameter, the number of 16-bit unsigned integers in \fIutf16str\fR +as \fBUTF-16\fR characters to be converted or saved. +.sp +As an output parameter, the number of 16-bit unsigned integers in +\fIutf16str\fR consumed or saved during conversion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIutf32str\fR\fR +.ad +.RS 12n +.rt +A pointer to a \fBUTF-32\fR character string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIutf32len\fR\fR +.ad +.RS 12n +.rt +As an input parameter, the number of 32-bit unsigned integers in \fIutf32str\fR +as \fBUTF-32\fR characters to be converted or saved. +.sp +As an output parameter, the number of 32-bit unsigned integers in +\fIutf32str\fR consumed or saved during conversion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIutf8str\fR\fR +.ad +.RS 12n +.rt +A pointer to a \fBUTF-8\fR character string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIutf8len\fR\fR +.ad +.RS 12n +.rt +As an input parameter, the number of bytes in \fIutf8str\fR as \fBUTF-8\fR +characters to be converted or saved. +.sp +As an output parameter, the number of bytes in \fIutf8str\fR consumed or saved +during conversion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflag\fR\fR +.ad +.RS 12n +.rt +The possible conversion options that are constructed by a bitwise-inclusive-OR +of the following values: +.sp +.ne 2 +.mk +.na +\fB\fBUCONV_IN_BIG_ENDIAN\fR\fR +.ad +.sp .6 +.RS 4n +The input parameter is in big endian byte ordering. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUCONV_OUT_BIG_ENDIAN\fR\fR +.ad +.sp .6 +.RS 4n +The output parameter should be in big endian byte ordering. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUCONV_IN_SYSTEM_ENDIAN\fR\fR +.ad +.sp .6 +.RS 4n +The input parameter is in the default byte ordering of the current system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUCONV_OUT_SYSTEM_ENDIAN\fR\fR +.ad +.sp .6 +.RS 4n +The output parameter should be in the default byte ordering of the current +system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUCONV_IN_LITTLE_ENDIAN\fR\fR +.ad +.sp .6 +.RS 4n +The input parameter is in little endian byte ordering. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUCONV_OUT_LITTLE_ENDIAN\fR\fR +.ad +.sp .6 +.RS 4n +The output parameter should be in little endian byte ordering. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUCONV_IGNORE_NULL\fR\fR +.ad +.sp .6 +.RS 4n +The null or \fBU+0000\fR character should not stop the conversion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUCONV_IN_ACCEPT_BOM\fR\fR +.ad +.sp .6 +.RS 4n +If the Byte Order Mark (\fBBOM\fR, \fBU+FEFF\fR) character exists as the first +character of the input parameter, interpret it as the \fBBOM\fR character. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUCONV_OUT_EMIT_BOM\fR\fR +.ad +.sp .6 +.RS 4n +Start the output parameter with Byte Order Mark (\fBBOM\fR, \fBU+FEFF\fR) +character to indicate the byte ordering if the output parameter is in +\fBUTF-16\fR or \fBUTF-32\fR. +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBuconv_u16tou32()\fR function reads the given \fIutf16str\fR in +\fBUTF-16\fR until \fBU+0000\fR (zero) in \fIutf16str\fR is encountered as a +character or until the number of 16-bit unsigned integers specified in +\fIutf16len\fR is read. The \fBUTF-16\fR characters that are read are converted +into \fBUTF-32\fR and the result is saved at \fIutf32str\fR. After the +successful conversion, \fIutf32len\fR contains the number of 32-bit unsigned +integers saved at \fIutf32str\fR as \fBUTF-32\fR characters. +.sp +.LP +The \fBuconv_u16tou8()\fR function reads the given \fIutf16str\fR in +\fBUTF-16\fR until \fBU+0000\fR (zero) in \fIutf16str\fR is encountered as a +character or until the number of 16-bit unsigned integers specified in +\fIutf16len\fR is read. The \fBUTF-16\fR characters that are read are converted +into \fBUTF-8\fR and the result is saved at \fIutf8str\fR. After the successful +conversion, \fIutf8len\fR contains the number of bytes saved at \fIutf8str\fR +as \fBUTF-8\fR characters. +.sp +.LP +The \fBuconv_u32tou16()\fR function reads the given \fIutf32str\fR in +\fBUTF-32\fR until \fBU+0000\fR (zero) in \fIutf32str\fR is encountered as a +character or until the number of 32-bit unsigned integers specified in +\fIutf32len\fR is read. The \fBUTF-32\fR characters that are read are converted +into \fBUTF-16\fR and the result is saved at \fIutf16str\fR. After the +successful conversion, \fIutf16len\fR contains the number of 16-bit unsigned +integers saved at \fIutf16str\fR as \fBUTF-16\fR characters. +.sp +.LP +The \fBuconv_u32tou8()\fR function reads the given \fIutf32str\fR in +\fBUTF-32\fR until \fBU+0000\fR (zero) in \fIutf32str\fR is encountered as a +character or until the number of 32-bit unsigned integers specified in +\fIutf32len\fR is read. The \fBUTF-32\fR characters that are read are converted +into \fBUTF-8\fR and the result is saved at \fIutf8str\fR. After the successful +conversion, \fIutf8len\fR contains the number of bytes saved at \fIutf8str\fR +as \fBUTF-8\fR characters. +.sp +.LP +The \fBuconv_u8tou16()\fR function reads the given \fIutf8str\fR in \fBUTF-8\fR +until the null ('\fB\e0\fR\&') byte in \fIutf8str\fR is encountered or until +the number of bytes specified in \fIutf8len\fR is read. The \fBUTF-8\fR +characters that are read are converted into \fBUTF-16\fR and the result is +saved at \fIutf16str\fR. After the successful conversion, \fIutf16len\fR +contains the number of 16-bit unsigned integers saved at \fIutf16str\fR as +\fBUTF-16\fR characters. +.sp +.LP +The \fBuconv_u8tou32()\fR function reads the given \fIutf8str\fR in \fBUTF-8\fR +until the null ('\fB\e0\fR\&') byte in \fIutf8str\fR is encountered or until +the number of bytes specified in \fIutf8len\fR is read. The \fBUTF-8\fR +characters that are read are converted into \fBUTF-32\fR and the result is +saved at \fIutf32str\fR. After the successful conversion, \fIutf32len\fR +contains the number of 32-bit unsigned integers saved at \fIutf32str\fR as +\fBUTF-32\fR characters. +.sp +.LP +During the conversion, the input and the output parameters are treated with +byte orderings specified in the \fIflag\fR parameter. When not specified, the +default byte ordering of the system is used. The byte ordering \fIflag\fR value +that is specified for \fBUTF-8\fR is ignored. +.sp +.LP +When \fBUCONV_IN_ACCEPT_BOM\fR is specified as the \fIflag\fR and the first +character of the string pointed to by the input parameter is the \fBBOM\fR +character, the value of the \fBBOM\fR character dictates the byte ordering of +the subsequent characters in the string pointed to by the input parameter, +regardless of the supplied input parameter byte ordering option \fIflag\fR +values. If the \fBUCONV_IN_ACCEPT_BOM\fR is not specified, the \fBBOM\fR as the +first character is treated as a regular Unicode character: Zero Width No Break +Space (\fBZWNBSP\fR) character. +.sp +.LP +When \fBUCONV_IGNORE_NULL\fR is specified, regardless of whether the input +parameter contains \fBU+0000\fR or null byte, the conversion continues until +the specified number of input parameter elements at \fIutf16len\fR, +\fIutf32len\fR, or \fIutf8len\fR are entirely consumed during the conversion. +.sp +.LP +As output parameters, \fIutf16len\fR, \fIutf32len\fR, and \fIutf8len\fR are not +changed if conversion fails for any reason. +.SH RETURN VALUES +.sp +.LP +Upon successful conversion, the functions return \fB0\fR. Upon failure, the +functions return one of the following \fBerrno\fR values: +.sp +.ne 2 +.mk +.na +\fB\fBEILSEQ\fR\fR +.ad +.RS 10n +.rt +The conversion detected an illegal or out of bound character value in the input +parameter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBE2BIG\fR\fR +.ad +.RS 10n +.rt +The conversion cannot finish because the size specified in the output parameter +is too small. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The conversion stops due to an incomplete character at the end of the input +string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +Conflicting byte-ordering option \fIflag\fR values are detected. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRConvert a \fBUTF-16\fR string in little-endian byte ordering +into \fBUTF-8\fR string. +.sp +.in +2 +.nf +#include <sys/types.h> +#include <sys/errno.h> +#include <sys/u8_textprep.h> +\&. +\&. +\&. +uint16_t u16s[MAXNAMELEN + 1]; +uchar_t u8s[MAXNAMELEN + 1]; +size_t u16len, u8len; +int ret; +\&. +\&. +\&. +u16len = u8len = MAXNAMELEN; +ret = uconv_u16tou8(u16s, &u16len, u8s, &u8len, + UCONV_IN_LITTLE_ENDIAN); +if (ret != 0) { + /* Conversion error occurred. */ + return (ret); +} +\&. +\&. +\&. +.fi +.in -2 + +.LP +\fBExample 2 \fRConvert a \fBUTF-32\fR string in big endian byte ordering into +little endian \fBUTF-16\fR. +.sp +.in +2 +.nf +#include <sys/types.h> +#include <sys/errno.h> +#include <sys/u8_textprep.h> +\&. +\&. +\&. +/* + * An UTF-32 character can be mapped to an UTF-16 character with + * two 16-bit integer entities as a "surrogate pair." + */ +uint32_t u32s[101]; +uint16_t u16s[101]; +int ret; +size_t u32len, u16len; +\&. +\&. +\&. +u32len = u16len = 100; +ret = uconv_u32tou16(u32s, &u32len, u16s, &u16len, + UCONV_IN_BIG_ENDIAN | UCONV_OUT_LITTLE_ENDIAN); +if (ret == 0) { + return (0); +} else if (ret == E2BIG) { + /* Use bigger output parameter and try just one more time. */ + uint16_t u16s2[201]; + + u16len = 200; + ret = uconv_u32tou16(u32s, &u32len, u16s2, &u16len, + UCONV_IN_BIG_ENDIAN | UCONV_OUT_LITTLE_ENDIAN); + if (ret == 0) + return (0); +} + +/* Otherwise, return -1 to indicate an error condition. */ +return (-1); +.fi +.in -2 + +.LP +\fBExample 3 \fRConvert a \fBUTF-8\fR string into \fBUTF-16\fR in little-endian +byte ordering. +.sp +.LP +Convert a \fBUTF-8\fR string into \fBUTF-16\fR in little-endian byte ordering +with a Byte Order Mark (BOM) character at the beginning of the output +parameter. + +.sp +.in +2 +.nf +#include <sys/types.h> +#include <sys/errno.h> +#include <sys/u8_textprep> +\&. +\&. +\&. +uchar_t u8s[MAXNAMELEN + 1]; +uint16_t u16s[MAXNAMELEN + 1]; +size_t u8len, u16len; +int ret; +\&. +\&. +\&. +u8len = u16len = MAXNAMELEN; +ret = uconv_u8tou16(u8s, &u8len, u16s, &u16len, + UCONV_IN_LITTLE_ENDIAN | UCONV_EMIT_BOM); +if (ret != 0) { + /* Conversion error occurred. */ + return (ret); +} +\&. +\&. +\&. +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBuconv_u16tou32\fR(9F) +.sp +.LP +The Unicode Standard (http://www.unicode.org) +.SH NOTES +.sp +.LP +Each \fBUTF-16\fR or \fBUTF-32\fR character maps to an \fBUTF-8\fR character +that might need one to maximum of four bytes. +.sp +.LP +One \fBUTF-32\fR or \fBUTF-8\fR character can yield two 16-bit unsigned +integers as a \fBUTF-16\fR character, which is a surrogate pair if the Unicode +scalar value is bigger than \fBU+FFFF\fR. +.sp +.LP +Ill-formed \fBUTF-16\fR surrogate pairs are seen as illegal characters during +the conversion. diff --git a/usr/src/man/man3c/ucred_get.3c b/usr/src/man/man3c/ucred_get.3c new file mode 100644 index 0000000000..9fe9387345 --- /dev/null +++ b/usr/src/man/man3c/ucred_get.3c @@ -0,0 +1,311 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ucred_get 3C "4 Apr 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +ucred_get, ucred_free, ucred_geteuid, ucred_getruid, ucred_getsuid, +ucred_getegid, ucred_getrgid, ucred_getsgid, ucred_getgroups, ucred_getprivset, +ucred_getpid, ucred_getprojid, ucred_getzoneid, ucred_getpflags, +ucred_getlabel, ucred_size \- user credential functions +.SH SYNOPSIS +.LP +.nf +#include <ucred.h> + +\fBucred_t *\fR\fBucred_get\fR(\fBpid_t\fR \fIpid\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBucred_free\fR(\fBucred_t *\fR\fIuc\fR); +.fi + +.LP +.nf +\fBuid_t\fR \fBucred_geteuid\fR(\fBconst ucred_t *\fR\fIuc\fR); +.fi + +.LP +.nf +\fBuid_t\fR \fBucred_getruid\fR(\fBconst ucred_t *\fR\fIuc\fR); +.fi + +.LP +.nf +\fBuid_t\fR \fBucred_getsuid\fR(\fBconst ucred_t *\fR\fIuc\fR); +.fi + +.LP +.nf +\fBgid_t\fR \fBucred_getegid\fR(\fBconst ucred_t *\fR\fIuc\fR); +.fi + +.LP +.nf +\fBgid_t\fR \fBucred_getrgid\fR(\fBconst ucred_t *\fR\fIuc\fR); +.fi + +.LP +.nf +\fBgid_t\fR \fBucred_getsgid\fR(\fBconst ucred_t *\fR\fIuc\fR); +.fi + +.LP +.nf +\fBint\fR \fBucred_getgroups\fR(\fBconst ucred_t *\fR\fIuc\fR, \fBconst gid_t **\fR\fIgroups\fR); +.fi + +.LP +.nf +\fBconst priv_set_t *\fR\fBucred_getprivset\fR(\fBconst ucred_t *\fR\fIuc\fR, + \fBpriv_ptype_t\fR \fIset\fR); +.fi + +.LP +.nf +\fBpid_t\fR \fBucred_getpid\fR(\fBconst ucred_t *\fR\fIuc\fR); +.fi + +.LP +.nf +\fBprojid_t\fR \fBucred_getprojid\fR(\fBconst ucred_t *\fR\fIuc\fR); +.fi + +.LP +.nf +\fBzoneid_t\fR \fBucred_getzoneid\fR(\fBconst ucred_t *\fR\fIuc\fR); +.fi + +.LP +.nf +\fBuint_t\fR \fBucred_getpflags\fR(\fBconst ucred_t *\fR\fIuc\fR, \fBuint_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBm_label_t *\fR\fBucred_getlabel\fR(\fBconst ucred_t *\fR\fIuc\fR); +.fi + +.LP +.nf +\fBsize_t\fR \fBucred_size\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions return or act on a user credential, \fBucred_t\fR. User +credentials are returned by various functions and describe the credentials of a +process. Information about the process can then be obtained by calling the +access functions. Access functions can fail if the underlying mechanism did not +return sufficient information. +.sp +.LP +The \fBucred_get()\fR function returns the user credential of the specified +\fIpid\fR or \fINULL\fR if none can be obtained. A \fIpid\fR value of +\fBP_MYID\fR returns information about the calling process. The return value is +dynamically allocated and must be freed using \fBucred_free()\fR. +.sp +.LP +The \fBucred_geteuid()\fR, \fBucred_getruid()\fR, \fBucred_getsuid()\fR, +\fBucred_getegid()\fR, \fBucred_getrgid()\fR, and \fBucred_getsgid()\fR +functions return the effective UID, real UID, saved UID, effective GID, real +GID, saved GID, respectively, or -1 if the user credential does not contain +sufficient information. +.sp +.LP +The \fBucred_getgroups()\fR function stores a pointer to the group list in the +\fBgid_t *\fR pointed to by the second argument and returns the number of +groups in the list. It returns -1 if the information is not available. The +returned group list is valid until \fBucred_free()\fR is called on the user +credential given as argument. +.sp +.LP +The \fBucred_getpid()\fR function returns the process ID of the process or -1 +if the process ID is not available. The process ID returned in a user +credential is only guaranteed to be correct in a very limited number of cases +when returned by \fBdoor_ucred\fR(3C) and \fBucred_get()\fR. In all other +cases, the process in question might have handed of the file descriptor, the +process might have exited or executed another program, or the process ID might +have been reused by a completely unrelated process after the original program +exited. +.sp +.LP +The \fBucred_getprojid()\fR function returns the project ID of the process or +-1 if the project ID is not available. +.sp +.LP +The \fBucred_getzoneid()\fR function returns the zone ID of the process or +\(mi1 if the zone ID is not available. +.sp +.LP +The \fBucred_getprivset()\fR function returns the specified privilege set +specified as second argument, or \fINULL\fR if either the requested information +is not available or the privilege set name is invalid. The returned privilege +set is valid until \fBucred_free()\fR is called on the specified user +credential. +.sp +.LP +The \fBucred_getpflags()\fR function returns the value of the specified +privilege flags from the \fBucred\fR structure, or (\fBuint_t\fR)-1 if none was +present. +.sp +.LP +The \fBucred_getlabel()\fR function returns the value of the label, or +\fINULL\fR if the label is not available. The returned label is valid until +\fBucred_free()\fR is called on the specified user credential. This function is +available only if the system is configured with Trusted Extensions. +.sp +.LP +The \fBucred_free()\fR function frees the memory allocated for the specified +user credential. +.sp +.LP +The \fBucred_size()\fR function returns \fBsizeof\fR(\fBucred_t\fR). This value +is constant only until the next boot, at which time it could change. The +\fBucred_size()\fR function can be used to determine the size of the buffer +needed to receive a credential option with \fBSO_RECVUCRED\fR. See +\fBsocket.h\fR(3HEAD). +.SH RETURN VALUES +.sp +.LP +See DESCRIPTION. +.SH ERRORS +.sp +.LP +The \fBucred_get()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +There is not enough memory available to allocate sufficient memory to hold a +user credential. The application can try again later. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 10n +.rt +The caller does not have sufficient privileges to examine the target process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.br +.na +\fB\fBENFILE\fR\fR +.ad +.RS 10n +.rt +The calling process cannot open any more files. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +The physical limits of the system are exceeded by the memory allocation needed +to hold a user credential. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBESRCH\fR\fR +.ad +.RS 10n +.rt +The target process does not exist. +.RE + +.sp +.LP +The \fBucred_getprivset()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The privilege set argument is invalid. +.RE + +.sp +.LP +The \fBucred_getlabel()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The label is not present. +.RE + +.sp +.LP +The \fBucred_geteuid()\fR, \fBucred_getruid()\fR, \fBucred_getsuid()\fR, +\fBucred_getegid()\fR, \fBucred_getrgid()\fR, \fBucred_getsgid()\fR, +\fBucred_getgroups()\fR, \fBucred_getpflags()\fR, \fBucred_getprivset()\fR, +\fBucred_getprojid()\fR, \fBucred_getpid()\fR, and \fBucred_getlabel()\fR +functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The requested user credential attribute is not available in the specified user +credential. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgetpflags\fR(2), \fBgetppriv\fR(2), \fBdoor_ucred\fR(3C), +\fBgetpeerucred\fR(3C), \fBpriv_set\fR(3C), \fBsocket.h\fR(3HEAD), +\fBattributes\fR(5), \fBlabels\fR(5), \fBprivileges\fR(5) diff --git a/usr/src/man/man3c/ungetc.3c b/usr/src/man/man3c/ungetc.3c new file mode 100644 index 0000000000..6a2a7c312e --- /dev/null +++ b/usr/src/man/man3c/ungetc.3c @@ -0,0 +1,78 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ungetc 3C "10 Sep 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +ungetc \- push byte back into input stream +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBint\fR \fBungetc\fR(\fBint\fR \fIc\fR, \fBFILE *\fR\fIstream\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBungetc()\fR function pushes the byte specified by \fIc\fR (converted to +an \fBunsigned char\fR) back onto the input stream pointed to by \fIstream\fR. +The pushed-back bytes will 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 \fIstream\fR) to a file-positioning function ( +\fBfseek\fR(3C), \fBfsetpos\fR(3C) or \fBrewind\fR(3C)) discards any +pushed-back bytes for the stream. The external storage corresponding to the +stream is unchanged. +.sp +.LP +Four bytes of push-back are guaranteed. If \fBungetc()\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. +.sp +.LP +If the value of \fIc\fR equals that of the macro \fBEOF\fR, the operation fails +and the input stream is unchanged. +.sp +.LP +A successful call to \fBungetc()\fR clears the end-of-file indicator for the +stream. The value of the file-position indicator for the stream after reading +or discarding all pushed-back bytes will be the same as it was before the bytes +were pushed back. The file-position indicator is decremented by each successful +call to \fBungetc()\fR; if its value was 0 before a call, its value is +indeterminate after the call. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBungetc()\fR returns the byte pushed back after +conversion. Otherwise it returns \fBEOF.\fR +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBread\fR(2), \fBIntro\fR(3), \fB__fsetlocking\fR(3C), \fBfseek\fR(3C), +\fBfsetpos\fR(3C), \fBgetc\fR(3C), \fBsetbuf\fR(3C), \fBstdio\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/ungetwc.3c b/usr/src/man/man3c/ungetwc.3c new file mode 100644 index 0000000000..ba326db86f --- /dev/null +++ b/usr/src/man/man3c/ungetwc.3c @@ -0,0 +1,94 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ungetwc 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +ungetwc \- push wide-character code back into input stream +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> +#include <wchar.h> + +\fBwint_t\fR \fBungetwc\fR(\fBwint_t\fR \fIwc\fR, \fBFILE *\fR\fIstream\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBungetwc()\fR function pushes the character corresponding to the wide +character code specified by \fIwc\fR back onto the input stream pointed to by +\fIstream\fR. The pushed-back characters will 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 \fIstream\fR) to a file-positioning +function ( \fBfseek\fR(3C), \fBfsetpos\fR(3C) or \fBrewind\fR(3C)) discards any +pushed-back characters for the stream. The external storage corresponding to +the stream is unchanged. +.sp +.LP +One character of push-back is guaranteed. If \fBungetwc()\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. +.sp +.LP +If the value of \fIwc\fR equals that of the macro \fBWEOF\fR, the operation +fails and the input stream is unchanged. +.sp +.LP +A successful call to \fBungetwc()\fR clears the end-of-file indicator for the +stream. The value of the file-position indicator for the stream after reading +or discarding all pushed-back characters will 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 \fBungetwc()\fR; if its value was 0 before +a call, its value is indeterminate after the call. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBungetwc()\fR returns the wide-character code +corresponding to the pushed-back character. Otherwise it returns \fBWEOF\fR. +.SH ERRORS +.sp +.LP +The \fBungetwc()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEILSEQ\fR\fR +.ad +.RS 10n +.rt +An invalid character sequence is detected, or a wide-character code does not +correspond to a valid character. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBread\fR(2), \fBfseek\fR(3C), \fBfsetpos\fR(3C), \fBrewind\fR(3C), +\fBsetbuf\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/unlockpt.3c b/usr/src/man/man3c/unlockpt.3c new file mode 100644 index 0000000000..d5194240cc --- /dev/null +++ b/usr/src/man/man3c/unlockpt.3c @@ -0,0 +1,90 @@ +'\" te +.\" Copyright (c) 1997, The Open Group. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH unlockpt 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +unlockpt \- unlock a pseudo-terminal master/slave pair +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBint\fR \fBunlockpt\fR(\fBint\fR \fIfildes\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBunlockpt()\fR function unlocks the slave pseudo-terminal device +associated with the master to which \fIfildes\fR refers. +.sp +.LP +Portable applications must call \fBunlockpt()\fR before opening the slave side +of a pseudo-terminal device. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBunlockpt()\fR returns \fB0\fR. Otherwise, it +returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBunlockpt()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIfildes\fR argument is not a file descriptor open for writing. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIfildes\fR argument is not associated with a master pseudo-terminal +device. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBopen\fR(2), \fBgrantpt\fR(3C), \fBptsname\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man3c/unsetenv.3c b/usr/src/man/man3c/unsetenv.3c new file mode 100644 index 0000000000..619e5527be --- /dev/null +++ b/usr/src/man/man3c/unsetenv.3c @@ -0,0 +1,79 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH unsetenv 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +unsetenv \- remove an environment variable +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBint\fR \fBunsetenv\fR(\fBconst char *\fR\fIname\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBunsetenv()\fR function removes an environment variable from the +environment of the calling process. The \fIname\fR argument points to a string +that is the name of the variable to be removed. The named argument cannot +contain an '=' character. If the named variable does not exist in the current +environment, the environment is unchanged and the function is considered to +have completed successfully. +.sp +.LP +If the application modifies \fIenviron\fR or the pointers to which it points, +the behavior of \fBunsetenv()\fR is undefined. The \fBunsetenv()\fR function +updates the list of pointers to which \fIenviron\fR points. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, 0 is returned. Otherwise, -1 is returned, +\fBerrno\fR set to indicate the error, and the environment is left unchanged. +.SH ERRORS +.sp +.LP +The \fBunsetenv()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIname\fR argument is a null pointer, points to an empty string, or points +to a string containing an '=' character. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgetenv\fR(3C), \fBsetenv\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/usleep.3c b/usr/src/man/man3c/usleep.3c new file mode 100644 index 0000000000..422ad7c30d --- /dev/null +++ b/usr/src/man/man3c/usleep.3c @@ -0,0 +1,74 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 1980 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. +.\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.TH usleep 3C "5 Feb 2008" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +usleep \- suspend execution for interval in microseconds +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> + +\fBint\fR \fBusleep\fR(\fBuseconds_t\fR \fIuseconds\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBusleep()\fR function suspends the caller from execution for the number +of microseconds specified by the \fIuseconds\fR argument. The actual suspension +time might be less than requested because any caught signal will terminate +\fBusleep()\fR following execution of that signal's catching routine. The +suspension time might be longer than requested by an arbitrary amount because +of the scheduling of other activity in the system. +.sp +.LP +If the value of \fIuseconds\fR is 0, then the call has no effect. +.sp +.LP +The use of the \fBusleep()\fR function has no effect on the action or blockage +of any signal. In a multithreaded process, only the invoking thread is +suspended from execution. +.SH RETURN VALUES +.sp +.LP +On completion, \fBusleep()\fR returns \fB0\fR. There are no error returns. +.SH ERRORS +.sp +.LP +No errors are returned. +.SH USAGE +.sp +.LP +The \fBusleep()\fR function is included for its historical usage. The +\fBnanosleep\fR(3C) function is preferred over this function. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelSafe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBnanosleep\fR(3C), \fBsleep\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/vfwprintf.3c b/usr/src/man/man3c/vfwprintf.3c new file mode 100644 index 0000000000..b9dfd8cfa7 --- /dev/null +++ b/usr/src/man/man3c/vfwprintf.3c @@ -0,0 +1,91 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH vfwprintf 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +vfwprintf, vswprintf, vwprintf \- wide-character formatted output of a stdarg +argument list +.SH SYNOPSIS +.LP +.nf +#include <stdarg.h> +#include <stdio.h> +#include <wchar.h> + +\fBint\fR \fBvfwprintf\fR(\fBFILE *restrict\fR \fIstream\fR, \fBconst wchar_t *restrict\fR \fIformat\fR, + \fBva_list\fR \fIarg\fR); +.fi + +.LP +.nf +\fBint\fR \fBvswprintf\fR(\fBwchar_t *restrict\fR \fIs\fR, \fBsize_t\fR \fIn\fR, + \fBconst wchar_t *restrict\fR \fIformat\fR, \fBva_list\fR \fIarg\fR); +.fi + +.LP +.nf +\fBint\fR \fBvwprintf\fR(\fBconst wchar_t *restrict\fR \fIformat\fR, \fBva_list\fR \fIarg\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBvwprintf()\fR, \fBvfwprintf()\fR, and \fBvswprintf()\fR functions are +the same as \fBwprintf()\fR, \fBfwprintf()\fR, and \fBswprintf()\fR +respectively, except that instead of being called with a variable number of +arguments, they are called with an argument list as defined by +<\fBstdarg.h\fR>. +.sp +.LP +These functions do not invoke the \fBva_end()\fR macro. However, as these +functions do invoke the \fBva_arg()\fR macro, the value of \fIap\fR after the +return is indeterminate. +.SH RETURN VALUES +.sp +.LP +Refer to \fBfwprintf\fR(3C). +.SH ERRORS +.sp +.LP +Refer to \fBfwprintf\fR(3C). +.SH USAGE +.sp +.LP +Applications using these functions should call \fBva_end(\fR\fIap\fR\fB)\fR +afterwards to clean up. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBfwprintf\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) +.SH NOTES +.sp +.LP +The \fBvwprintf()\fR, \fBvfwprintf()\fR, and \fBvswprintf()\fR functions can be +used safely in multithreaded applications, as long as \fBsetlocale\fR(3C) is +not being called to change the locale. diff --git a/usr/src/man/man3c/vlfmt.3c b/usr/src/man/man3c/vlfmt.3c new file mode 100644 index 0000000000..cbf989f5d7 --- /dev/null +++ b/usr/src/man/man3c/vlfmt.3c @@ -0,0 +1,108 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH vlfmt 3C "29 Dec 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +vlfmt \- display error message in standard format and pass to logging and +monitoring services +.SH SYNOPSIS +.LP +.nf +#include <pfmt.h> +#include <stdarg.h> + +\fBint\fR \fBvlfmt\fR(\fBFILE *\fR\fIstream\fR, \fBlong\fR \fIflag\fR, \fBconst char *\fR\fIformat\fR, \fBva_list\fR \fIap\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBvlfmt()\fR function is identical to \fBlfmt\fR(3C), except that it is +called with an argument list as defined by \fB<stdarg.h>\fR\&. +.sp +.LP +The <\fBstdarg.h\fR> header defines the type \fBva_list\fR and a set of macros +for advancing through a list of arguments whose number and types may vary. The +\fIap\fR argument is of type \fBva_list\fR. This argument is used with the +<\fBstdarg.h\fR> macros \fBva_start()\fR, \fBva_arg()\fR, and \fBva_end()\fR. +See \fBstdarg\fR(3EXT). The example in the \fBEXAMPLES\fR section below +demonstrates their use with \fBvlfmt()\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBvlfmt()\fR returns the number of bytes +transmitted. Otherwise, \fB\(mi1\fR is returned if there was a write error to +\fIstream\fR, or \fB\(mi2\fR is returned if unable to log and/or display at +console. +.SH EXAMPLES +.LP +\fBExample 1 \fRUse of \fBvlfmt()\fR to write an \fBerrlog()\fRroutine. +.sp +.LP +The following example demonstrates how \fBvlfmt()\fR could be used to write an +\fBerrlog()\fR routine. The \fBva_alist()\fR macro is used as the parameter +list in a function definition. The \fBva_start(\fR\fIap\fR, .\|.\|.) call, +where \fIap\fR is of type \fBva_list\fR, must be invoked before any attempt to +traverse and access unnamed arguments. Calls to \fBva_arg(\fR\fIap\fR\fB, +\fR\fIatype\fR\fB)\fR traverse the argument list. Each execution of +\fBva_arg()\fR expands to an expression with the value and type of the next +argument in the list \fIap\fR, which is the same object initialized by +\fBva_start()\fR. The \fIatype\fR argument is the type that the returned +argument is expected to be. The \fBva_end(\fR\fIap\fR\fB)\fR macro must be +invoked when all desired arguments have been accessed. The argument list in +\fIap\fR can be traversed again if \fBva_start()\fR is called again after +\fBva_end()\fR.) In the example below, \fBva_arg()\fR is executed first to +retrieve the format string passed to \fBerrlog()\fR. The remaining +\fBerrlog()\fR arguments (\fIarg1\fR, \fIarg2\fR, \fI\&...\fR) are passed to +\fBvlfmt()\fR in the argument \fIap\fR. + +.sp +.in +2 +.nf +\fB#include <pfmt.h> +#include <stdarg.h> +/* + * errlog should be called like + * errlog(log_info, format, arg1, ...); + */ +void errlog(long log_info, ...) +{ + va_list ap; + char *format; + va_start(ap, ); + format = va_arg(ap, char *); + (void) vlfmt(stderr, log_info|MM_ERROR, format, ap); + va_end(ap); + (void) abort(); +}\fR +.fi +.in -2 + +.SH USAGE +.sp +.LP +Since \fBvlfmt()\fR uses \fBgettxt\fR(3C), it is recommended that \fBvlfmt()\fR +not be used. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgettxt\fR(3C), \fBlfmt\fR(3C), \fBattributes\fR(5), \fBstdarg\fR(3EXT) diff --git a/usr/src/man/man3c/vpfmt.3c b/usr/src/man/man3c/vpfmt.3c new file mode 100644 index 0000000000..feb8d7a916 --- /dev/null +++ b/usr/src/man/man3c/vpfmt.3c @@ -0,0 +1,107 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH vpfmt 3C "29 Dec 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +vpfmt \- display error message in standard format and pass to logging and +monitoring services +.SH SYNOPSIS +.LP +.nf +#include <pfmt.h> +#include <stdarg.h> + +\fBint\fR \fBvpfmt\fR(\fBFILE *\fR\fIstream\fR, \fBlong\fR \fIflag\fR, \fBconst char *\fR\fIformat\fR, \fBva_list\fR \fIap\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBvpfmt()\fR function is identical to \fBpfmt\fR(3C), except that it is +called with an argument list as defined by <\fBstdarg.h\fR>. +.sp +.LP +The <\fBstdarg.h\fR> header defines the type \fBva_list\fR and a set of macros +for advancing through a list of arguments whose number and types may vary. The +\fIap\fR argument is of type \fBva_list\fR. This argument is used with the +<\fBstdarg.h\fR> macros \fBva_start()\fR, \fBva_arg()\fR, and \fBva_end()\fR. +See \fBstdarg\fR(3EXT). The example in the \fBEXAMPLES\fR section below +demonstrates their use with \fBvpfmt()\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBvpfmt()\fR returns the number of bytes +transmitted. Otherwise, \fB\(mi1\fR is returned if there was a write error to +\fIstream\fR. +.SH EXAMPLES +.LP +\fBExample 1 \fRUse of \fBvpfmt()\fR to write an error routine. +.sp +.LP +The following example demonstrates how \fBvpfmt()\fR could be used to write an +\fBerror()\fR routine. The \fBva_alist()\fR macro is used as the parameter list +in a function definition. The \fBva_start(\fR\fIap\fR, .\|.\|.) call, where +\fIap\fR is of type \fBva_list\fR, must be invoked before any attempt to +traverse and access unnamed arguments. Calls to \fBva_arg(\fR\fIap\fR\fB, +\fR\fIatype\fR\fB)\fR traverse the argument list. Each execution of +\fBva_arg()\fR expands to an expression with the value and type of the next +argument in the list \fIap\fR, which is the same object initialized by +\fBva_start()\fR. The \fIatype\fR argument is the type that the returned +argument is expected to be. The \fBva_end(\fR\fIap\fR\fB)\fR macro must be +invoked when all desired arguments have been accessed. The argument list in +\fIap\fR can be traversed again if \fBva_start()\fR is called again after +\fBva_end()\fR. In the example below, \fBva_arg()\fR is executed first to +retrieve the format string passed to \fBerror()\fR. The remaining \fBerror()\fR +arguments (\fIarg1\fR, \fIarg2\fR, ...) are passed to \fBvpfmt()\fR in the +argument \fIap\fR. + +.sp +.in +2 +.nf +#include <pfmt.h> +#include <stdarg.h> +/* + * error should be called like + * error(format, arg1, ...); + */ +void error(...) +{ + va_list ap; + char *format; + va_start(ap, ); + format = va_arg(ap, char *); + (void) vpfmt(stderr, MM_ERROR, format, ap); + va_end(ap); + (void) abort(); +} +.fi +.in -2 + +.SH USAGE +.sp +.LP +Since \fBvpfmt()\fR uses \fBgettxt\fR(3C), it is recommended that \fBvpfmt()\fR +not be used. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgettxt\fR(3C), \fBpfmt\fR(3C), \fBattributes\fR(5), \fBstdarg\fR(3EXT) diff --git a/usr/src/man/man3c/vprintf.3c b/usr/src/man/man3c/vprintf.3c new file mode 100644 index 0000000000..7736c8786e --- /dev/null +++ b/usr/src/man/man3c/vprintf.3c @@ -0,0 +1,172 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical +.\" and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH vprintf 3C "7 Jan 2009" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +vprintf, vfprintf, vsprintf, vsnprintf, vasprintf \- print formatted output of +a variable argument list +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> +#include <stdarg.h> + +\fBint\fR \fBvprintf\fR(\fBconst char *\fR\fIformat\fR, \fBva_list\fR \fIap\fR); +.fi + +.LP +.nf +\fBint\fR \fBvfprintf\fR(\fBFILE *\fR\fIstream\fR, \fBconst char *\fR\fIformat\fR, \fBva_list\fR \fIap\fR); +.fi + +.LP +.nf +\fBint\fR \fBvsprintf\fR(\fBchar *\fR\fIs\fR, \fBconst char *\fR\fIformat\fR, \fBva_list\fR \fIap\fR); +.fi + +.LP +.nf +\fBint\fR \fBvsnprintf\fR(\fBchar *\fR\fIs\fR, \fBsize_t\fR \fIn\fR, \fBconst char *\fR\fIformat\fR, \fBva_list\fR \fIap\fR); +.fi + +.LP +.nf +\fBint\fR \fBvasprintf\fR(\fBchar **\fR\fIret\fR, \fBconst char *\fR\fIformat\fR, \fBva_list\fR \fIap\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBvprintf()\fR, \fBvfprintf()\fR, \fBvsprintf()\fR, \fBvsnprintf()\fR, and +\fBvasprintf()\fR functions are the same as \fBprintf()\fR, \fBfprintf()\fR, +\fBsprintf()\fR, \fBsnprintf()\fR, and \fBasprintf()\fR, respectively, except +that instead of being called with a variable number of arguments, they are +called with an argument list as defined in the \fB<stdarg.h>\fR header. See +\fBprintf\fR(3C). +.sp +.LP +The \fB<stdarg.h>\fR header defines the type \fBva_list\fR and a set of macros +for advancing through a list of arguments whose number and types may vary. The +argument \fIap\fR to the \fBvprint\fR family of functions is of type +\fBva_list\fR. This argument is used with the <\fBstdarg.h\fR> header file +macros \fBva_start()\fR, \fBva_arg()\fR, and \fBva_end()\fR (see +\fBstdarg\fR(3EXT)). The \fBEXAMPLES\fR section below demonstrates the use of +\fBva_start()\fR and \fBva_end()\fR with \fBvprintf()\fR. +.sp +.LP +The macro \fBva_alist()\fR is used as the parameter list in a function +definition, as in the function called \fBerror()\fR in the example below. The +macro \fBva_start(\fR\fIap, name\fR\fB),\fR where \fIap\fR is of type +\fBva_list\fR and \fIname\fR is the rightmost parameter (just before +\|.\|.\|.), must be called before any attempt to traverse and access unnamed +arguments is made. The \fBva_end(\fR\fIap\fR\fB)\fR macro must be invoked when +all desired arguments have been accessed. The argument list in \fIap\fR can be +traversed again if \fBva_start()\fR is called again after \fBva_end()\fR. In +the example below, the \fBerror()\fR arguments (\fIarg1\fR, \fIarg2\fR, +\&.\|.\|.) are passed to \fBvfprintf()\fR in the argument \fIap\fR. +.SH RETURN VALUES +.sp +.LP +Refer to \fBprintf\fR(3C). +.SH ERRORS +.sp +.LP +The \fBvprintf()\fR and \fBvfprintf()\fR functions will fail if either the +\fIstream\fR is unbuffered or the \fIstream\fR's buffer needed to be flushed +and: +.sp +.ne 2 +.mk +.na +\fB\fBEFBIG\fR\fR +.ad +.RS 9n +.rt +The file is a regular file and an attempt was made to write at or beyond the +offset maximum. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBvprintf()\fR to write an error routine. +.sp +.LP +The following demonstrates how \fBvfprintf()\fR could be used to write an error +routine: + +.sp +.in +2 +.nf +#include <stdio.h> +#include <stdarg.h> +\&. . . +/* + * error should be called like + * error(function_name, format, arg1, \&.\|.\|.); + */ +void error(char *function_name, char *format, \&.\|.\|.) +{ + va_list ap; + va_start(ap, format); + /* print out name of function causing error */ + (void) fprintf(stderr, "ERR in %s: ", function_name); + /* print out remainder of message */ + (void) vfprintf(stderr, format, ap); + va_end(ap); + (void) abort(); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelSee below. +_ +StandardSee below. +.TE + +.sp +.LP +All of these functions can be used safely in multithreaded applications, as +long as \fBsetlocale\fR(3C) is not being called to change the locale. +.sp +.LP +See \fBstandards\fR(5) for the standards conformance of \fBvprintf()\fR, +\fBvfprintf()\fR, \fBvsprintf()\fR, and \fBvsnprintf()\fR. The +\fBvasprintf()\fR function is modeled on the one that appears in the FreeBSD, +NetBSD, and GNU C libraries. +.SH SEE ALSO +.sp +.LP +\fBprintf\fR(3C), \fBattributes\fR(5), \fBstdarg\fR(3EXT), \fBattributes\fR(5), +\fBstandards\fR(5) +.SH NOTES +.sp +.LP +The \fBvsnprintf()\fR return value when \fIn\fR = 0 was changed in the Solaris +10 release. The change was based on the SUSv3 specification. The previous +behavior was based on the initial SUSv2 specification, where \fBvsnprintf()\fR +when \fIn\fR = 0 returns an unspecified value less than 1. diff --git a/usr/src/man/man3c/vsyslog.3c b/usr/src/man/man3c/vsyslog.3c new file mode 100644 index 0000000000..e2149c4962 --- /dev/null +++ b/usr/src/man/man3c/vsyslog.3c @@ -0,0 +1,84 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH vsyslog 3C "30 Aug 2006" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +vsyslog \- log message with a stdarg argument list +.SH SYNOPSIS +.LP +.nf +#include <syslog.h> +#include <stdarg.h> + +\fBvoid\fR \fBvsyslog\fR(\fBint\fR \fIpriority\fR, \fBconst char *\fR\fImessage\fR, \fBva_list\fR \fIap\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBvsyslog()\fR function is identical to \fBsyslog\fR(3C), except that it +is called with an argument list as defined by <\fBstdarg.h\fR> rather than with +a variable number of arguments. +.SH EXAMPLES +.LP +\fBExample 1 \fRUse \fBvsyslog()\fR to write an error routine. +.sp +.LP +The following example demonstrates the use of \fBvsyslog()\fR in writing an +error routine. + +.sp +.in +2 +.nf +#include <syslog.h> +#include <stdarg.h> + +/* + * error should be called like: + * error(pri, function_name, format, arg1, arg2...); + */ + +void +error(int pri, char *function_name, char *format, ...) +{ + va_list args; + + va_start(args, format); + /* log name of function causing error */ + (void) syslog(pri, "ERROR in %s.", function_name); + /* log remainder of message */ + (void) vsyslog(pri, format, args); + va_end(args); + (void) abort( ); +} + +main() +{ + error(LOG_ERR, "main", "process %d is dying", getpid()); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBsyslog\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/wait.3c b/usr/src/man/man3c/wait.3c new file mode 100644 index 0000000000..3c2f6522ec --- /dev/null +++ b/usr/src/man/man3c/wait.3c @@ -0,0 +1,143 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH wait 3C "9 Jun 2004" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +wait \- wait for child process to stop or terminate +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/wait.h> + +\fBpid_t\fR \fBwait\fR(\fBint *\fR\fIstat_loc\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBwait()\fR function will suspend execution of the calling thread until +status information for one of its terminated child processes 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 +\fBwait()\fR, \fBwaitpid\fR(3C), or \fBwaitid\fR(2) awaiting termination of the +same process, exactly one thread will return the process status at the time of +the target process termination. If status information is available prior to the +call to \fBwait()\fR, return will be immediate. +.sp +.LP +If \fBwait()\fR returns because the status of a child process is available, it +returns the process \fBID\fR of the child process. If the calling process +specified a non-zero value for \fIstat_loc\fR, the status of the child process +is stored in the location pointed to by \fIstat_loc\fR. That status can be +evaluated with the macros described on the \fBwait.h\fR(3HEAD) manual page. +.sp +.LP +In the following, \fIstatus\fR is the object pointed to by \fIstat_loc\fR: +.RS +4 +.TP +.ie t \(bu +.el o +If the child process terminated due to an \fB_exit()\fR call, the low order 8 +bits of \fIstatus\fR will be 0 and the high order 8 bits will contain the low +order 7 bits of the argument that the child process passed to \fB_exit()\fR; +see \fBexit\fR(2). +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If the child process terminated due to a signal, the high order 8 bits of +\fIstatus\fR will be 0 and the low order 7bits will contain the number of the +signal that caused the termination. In addition, if \fBWCOREFLG\fR is set, a +"core image" will have been produced; see \fBsignal.h\fR(3HEAD) and +\fBwait.h\fR(3HEAD). +.RE +.sp +.LP +One instance of a \fBSIGCHLD\fR signal is queued for each child process whose +status has changed. If \fBwait()\fR returns because the status of a child +process is available, any pending \fBSIGCHLD\fR signal associated with the +process ID of that child process is discarded. Any other pending \fBSIGCHLD\fR +signals remain pending. +.sp +.LP +If the calling process has \fBSA_NOCLDWAIT\fR set or has \fBSIGCHLD\fR set to +\fBSIG_IGN\fR, and the process has no unwaited children that were transformed +into zombie processes, it will block until all of its children terminate, and +\fBwait()\fR will fail and set \fBerrno\fR to \fBECHILD\fR. +.sp +.LP +If a parent process terminates without waiting for its child processes to +terminate, the parent process \fBID\fR of each child process is set to 1, with +the initialization process inheriting the child processes; see \fBIntro\fR(2). +.SH RETURN VALUES +.sp +.LP +When \fBwait()\fR returns due to a terminated child process, the process +\fBID\fR of the child is returned to the calling process. Otherwise, +\fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBwait()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBECHILD\fR\fR +.ad +.RS 10n +.rt +The calling process has no existing unwaited-for child processes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 10n +.rt +The function was interrupted by a signal. +.RE + +.SH USAGE +.sp +.LP +Since \fBwait()\fR blocks on a stopped child, a calling process wanting to see +the return results of such a call should use \fBwaitpid\fR(3C) or +\fBwaitid\fR(2) instead of \fBwait()\fR. The \fBwait()\fR function is +implemented as a call to \fBwaitpid(-1, stat_loc, 0)\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelAsync-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(2), \fBexec\fR(2), \fBexit\fR(2), \fBfork\fR(2), \fBpause\fR(2), +\fBwaitid\fR(2), \fBptrace\fR(3C), \fBsignal\fR(3C), \fBsignal.h\fR(3HEAD), +\fBwaitpid\fR(3C), \fBwait.h\fR(3HEAD), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/wait3.3c b/usr/src/man/man3c/wait3.3c new file mode 100644 index 0000000000..bd724c6f60 --- /dev/null +++ b/usr/src/man/man3c/wait3.3c @@ -0,0 +1,241 @@ +'\" te +.\" Copyright (c) 1980 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved +.TH wait3 3C "4 Nov 2005" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +wait3, wait4 \- wait for process to terminate or stop +.SH SYNOPSIS +.LP +.nf +#include <sys/wait.h> +#include <sys/time.h> +#include <sys/resource.h> + +\fBpid_t\fR \fBwait3\fR(\fBint *\fR\fIstatusp\fR, \fBint\fR \fIoptions\fR, \fBstruct rusage *\fR\fIrusage\fR); +.fi + +.LP +.nf +\fBpid_t\fR \fBwait4\fR(\fBpid_t\fR \fIpid\fR, \fBint *\fR\fIstatusp\fR, \fBint\fR \fIoptions\fR, \fBstruct rusage *\fR\fIrusage\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBwait3()\fR function delays its caller until a signal is received or one +of its child processes terminates or stops due to tracing. If any child process +has died or stopped due to tracing and this has not already been reported, +return is immediate, returning the process \fBID\fR and status of one of those +children. If that child process has died, it is discarded. If there are no +children, \(mi1 is returned immediately. If there are only running or stopped +but reported children, the calling process is blocked. +.sp +.LP +If \fIstatusp\fR is not a null pointer, then on return from a successful +\fBwait3()\fR call, the status of the child process is stored in the integer +pointed to by \fIstatusp\fR. \fI*statusp\fR indicates the cause of termination +and other information about the terminated process in the following manner: +.RS +4 +.TP +.ie t \(bu +.el o +If the low-order 8 bits of \fI*statusp\fR are equal to 0177, the child process +has stopped; the 8 bits higher up from the low-order 8 bits of \fI*statusp\fR +contain the number of the signal that caused the process to stop. See +\fBsignal.h\fR(3HEAD). +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If the low-order 8 bits of \fI*statusp\fR are non-zero and are not equal to +0177, the child process terminated due to a signal; the low-order 7 bits of +\fI*statusp\fR contain the number of the signal that terminated the process. In +addition, if the low-order seventh bit of \fI*statusp\fR (that is, bit 0200) is +set, a ``core image'' of the process was produced; see \fBsignal.h\fR(3HEAD). +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Otherwise, the child process terminated due to an \fBexit()\fR call; the 8 bits +higher up from the low-order 8 bits of \fI*statusp\fR contain the low-order 8 +bits of the argument that the child process passed to \fBexit()\fR; see +\fBexit\fR(2). +.RE +.sp +.LP +The \fIoptions\fR argument is constructed from the bitwise inclusive \fBOR\fR +of zero or more of the following flags, defined in <\fBsys/wait.h\fR>: +.sp +.ne 2 +.mk +.na +\fB\fBWNOHANG\fR\fR +.ad +.RS 13n +.rt +Execution of the calling process is not suspended if status is not immediately +available for any child process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWUNTRACED\fR\fR +.ad +.RS 13n +.rt +The status of any child processes that are stopped, and whose status has not +yet been reported since they stopped, are also reported to the requesting +process. +.RE + +.sp +.LP +If \fIrusage\fR is not a null pointer, a summary of the resources used by the +terminated process and all its children is returned. Only the user time used +and the system time used are currently available. They are returned in the +\fBru_utime\fR and \fBru_stime\fR, members of the rusage structure, +respectively. +.sp +.LP +When the \fBWNOHANG\fR option is specified and no processes have status to +report, \fBwait3()\fR returns 0. The \fBWNOHANG\fR and \fBWUNTRACED\fR options +may be combined by the bitwise \fBOR\fR operation of the two values. +.sp +.LP +The \fBwait4()\fR function is an extended interface. If \fIpid\fR is 0, +\fBwait4()\fR is equivalent to \fBwait3()\fR. If \fIpid\fR has a nonzero value, +\fBwait4()\fR returns status only for the indicated process \fBID,\fR but not +for any other child processes. If \fIpid\fR has a negative value, \fBwait4()\fR +return status only for child processes whose process group ID is equal to the +absolute value of \fIpid\fR. The status can be evaluated using the macros +defined by \fBwait.h\fR(3HEAD). +.SH RETURN VALUES +.sp +.LP +If \fBwait3()\fR or \fBwait4()\fR returns due to a stopped or terminated child +process, the process \fBID\fR of the child is returned to the calling process. +Otherwise, \fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the +error. +.sp +.LP +If \fBwait3()\fR or \fBwait4()\fR return due to the delivery of a signal to the +calling process, \fB\(mi1\fR is returned and \fBerrno\fR is set to \fBEINTR\fR. +If \fBWNOHANG\fR was set in \fIoptions\fR, it has at least one child process +specified by \fIpid\fR for which status is not available, and status is not +available for any process specified by \fIpid\fR, \fB0\fR is returned. +Otherwise, \fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the +error. +.sp +.LP +The \fBwait3()\fR and \fBwait4()\fR functions return \fB0\fR if \fBWNOHANG\fR +is specified and there are no stopped or exited children, and return the +process \fBID\fR of the child process if they return due to a stopped or +terminated child process. Otherwise, they return \fB\(mi1\fR and set +\fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBwait3()\fR and \fBwait4()\fR functions will fail and return immediately +if: +.sp +.ne 2 +.mk +.na +\fB\fBECHILD\fR\fR +.ad +.RS 10n +.rt +The calling process has no existing unwaited-for child processes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +.rt +The \fIstatusp\fR or \fIrusage\fR arguments point to an illegal address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 10n +.rt +The function was interrupted by a signal. The value of the location pointed to +by \fIstatusp\fR is undefined. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of \fIoptions\fR is not valid. +.RE + +.sp +.LP +The \fBwait4()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBECHILD\fR\fR +.ad +.RS 10n +.rt +The process specified by \fIpid\fR does not exist or is not a child of the +calling process. +.RE + +.sp +.LP +The \fBwait3()\fRand \fBwait4()\fR functions will terminate prematurely, return +\fB\(mi1\fR, and set \fBerrno\fR to \fBEINTR\fR upon the arrival of a signal +whose \fBSA_RESTART\fR bit in its flags field is not set (see +\fBsigaction\fR(2)). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelAsync-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBkill\fR(1), \fBexit\fR(2), \fBwaitid\fR(2), \fBwaitpid\fR(3C), +\fBgetrusage\fR(3C), \fBsignal\fR(3C), \fBsignal.h\fR(3HEAD), \fBwait\fR(3C), +\fBwait.h\fR(3HEAD), \fBproc\fR(4), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +If a parent process terminates without waiting on its children, the +initialization process (process \fBID\fR = 1) inherits the children. +.sp +.LP +The \fBwait3()\fR and \fBwait4()\fR functions are automatically restarted when +a process receives a signal while awaiting termination of a child process, +unless the \fBSA_RESTART\fR bit is not set in the flags for that signal. diff --git a/usr/src/man/man3c/waitpid.3c b/usr/src/man/man3c/waitpid.3c new file mode 100644 index 0000000000..cdd9d73506 --- /dev/null +++ b/usr/src/man/man3c/waitpid.3c @@ -0,0 +1,227 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH waitpid 3C "7 Dec 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +waitpid \- wait for child process to change state +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/wait.h> + +\fBpid_t\fR \fBwaitpid\fR(\fBpid_t\fR \fIpid\fR, \fBint *\fR\fIstat_loc\fR, \fBint\fR \fIoptions\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBwaitpid()\fR function will suspend execution of the calling thread until +status information for one of its terminated child processes 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 +\fBwaitpid()\fR, \fBwait\fR(3C), or \fBwaitid\fR(2) awaiting termination of the +same process, exactly one thread will return the process status at the time of +the target process termination. If status information is available prior to the +call to \fBwaitpid()\fR, return will be immediate. +.sp +.LP +The \fIpid\fR argument specifies a set of child processes for which status is +requested, as follows: +.RS +4 +.TP +.ie t \(bu +.el o +If \fIpid\fR is less than \fB(pid_t)\(mi1\fR, status is requested for any child +process whose process group \fBID\fR is equal to the absolute value of +\fIpid\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If \fIpid\fR is equal to \fB(pid_t)\(mi1\fR, status is requested for any child +process. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If \fIpid\fR is equal to \fB(pid_t)0\fR status is requested for any child +process whose process group \fBID\fR is equal to that of the calling process. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If \fIpid\fR is greater than \fB(pid_t)0\fR, it specifies the process \fBID\fR +of the child process for which status is requested. +.RE +.sp +.LP +One instance of a \fBSIGCHLD\fR signal is queued for each child process whose +status has changed. If \fBwaitpid()\fR returns because the status of a child +process is available, and \fBWNOWAIT\fR was not specified in \fIoptions\fR, any +pending \fBSIGCHLD\fR signal associated with the process ID of that child +process is discarded. Any other pending \fBSIGCHLD\fR signals remain pending. +.sp +.LP +If the calling process has \fBSA_NOCLDWAIT\fR set or has \fBSIGCHLD\fR set to +\fBSIG_IGN\fR and the process has no unwaited children that were transformed +into zombie processes, it will block until all of its children terminate, and +\fBwaitpid()\fR will fail and set \fBerrno\fR to \fBECHILD\fR. +.sp +.LP +If \fBwaitpid()\fR returns because the status of a child process is available, +then that status may be evaluated with the macros defined by +\fBwait.h\fR(3HEAD) If the calling process had specified a non-zero value of +\fIstat_loc\fR, the status of the child process will be stored in the location +pointed to by \fIstat_loc\fR. +.sp +.LP +The \fIoptions\fR argument is constructed from the bitwise-inclusive OR of zero +or more of the following flags, defined in the header <\fBsys/wait.h\fR>: +.sp +.ne 2 +.mk +.na +\fB\fBWCONTINUED\fR\fR +.ad +.RS 14n +.rt +The status of any continued child process specified by \fIpid\fR, whose status +has not been reported since it continued, is also reported to the calling +process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWNOHANG\fR\fR +.ad +.RS 14n +.rt +The \fBwaitpid()\fR function will not suspend execution of the calling process +if status is not immediately available for one of the child processes specified +by \fIpid\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWNOWAIT\fR\fR +.ad +.RS 14n +.rt +Keep the process whose status is returned in \fIstat_loc\fR in a waitable +state. The process may be waited for again with identical results. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWUNTRACED\fR\fR +.ad +.RS 14n +.rt +The status of any child processes specified by \fIpid\fR that are stopped, and +whose status has not yet been reported since they stopped, is also reported to +the calling process. \fBWSTOPPED\fR is a synonym for \fBWUNTRACED\fR. +.RE + +.SH RETURN VALUES +.sp +.LP +If \fBwaitpid()\fR returns because the status of a child process is available, +it returns a value equal to the process \fBID\fR of the child process for which +status is reported. If \fBwaitpid()\fR returns due to the delivery of a signal +to the calling process, \fB\(mi1\fR is returned and \fBerrno\fR is set to +\fBEINTR\fR. If \fBwaitpid()\fR was invoked with \fBWNOHANG\fR set in +\fIoptions\fR, it has at least one child process specified by \fIpid\fR for +which status is not available, and status is not available for any process +specified by \fIpid\fR, then \fB0\fR is returned. Otherwise, \fB\(mi1\fR is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBwaitpid()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBECHILD\fR\fR +.ad +.RS 10n +.rt +The process or process group specified by \fIpid\fR does not exist or is not a +child of the calling process or can never be in the states specified by +\fIoptions\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 10n +.rt +The \fBwaitpid()\fR function was interrupted due to the receipt of a signal +sent by the calling process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +An invalid value was specified for \fIoptions.\fR +.RE + +.SH USAGE +.sp +.LP +With \fIoptions\fR equal to \fB0\fR and \fIpid\fR equal to \fB(pid_t)\(mi1\fR, +\fBwaitpid()\fR is identical to \fBwait\fR(3C). The \fBwaitpid()\fR function is +implemented as a call to the more general \fBwaitid\fR(2) function. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelAsync-Signal-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(2), \fBexec\fR(2), \fBexit\fR(2), \fBfork\fR(2), \fBpause\fR(2), +\fBsigaction\fR(2), \fBptrace\fR(3C), \fBsignal\fR(3C), \fBsiginfo.h\fR(3HEAD), +\fBwait\fR(3C), \fBwait.h\fR(3HEAD), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/walkcontext.3c b/usr/src/man/man3c/walkcontext.3c new file mode 100644 index 0000000000..2e1632afb7 --- /dev/null +++ b/usr/src/man/man3c/walkcontext.3c @@ -0,0 +1,245 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH walkcontext 3C "10 Apr 2007" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +walkcontext, addrtosymstr, printstack, backtrace, backtrace_symbols, +backtrace_symbols_fd \- walk stack pointed to by ucontext +.SH SYNOPSIS +.LP +.nf +#include <ucontext.h> + +\fBint\fR \fBwalkcontext\fR(\fBconst ucontext_t *\fR\fIuptr\fR, + \fBint (*\fR\fIoperate_func\fR)(uintptr_t, int, void *), \fBvoid *\fR\fIusrarg\fR); +.fi + +.LP +.nf +\fBint\fR \fBaddrtosymstr\fR(\fBuintptr_t\fR \fIaddr\fR, \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIlen\fR); +.fi + +.LP +.nf +\fBint\fR \fBprintstack\fR(\fBint\fR \fIfd\fR); +.fi + +.LP +.nf +#include <execinfo.h> + +\fBint\fR \fBbacktrace\fR(\fBvoid **\fR\fIbuffer\fR, \fBint\fR \fIsize\fR); +.fi + +.LP +.nf +\fBchar **\fR\fBbacktrace_symbols\fR(\fBvoid *const *\fR\fIbuffer\fR, \fBint\fR \fIsize\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBbacktrace_symbols_fd\fR(\fBvoid *const *\fR\fIbuffer\fR, \fBint\fR \fIsize\fR, \fBint\fR \fIfd\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBwalkcontext()\fR function walks the call stack pointed to by \fIuptr\fR, +which can be obtained by a call to \fBgetcontext\fR(2) or from a signal handler +installed with the \fBSA_SIGINFO\fR flag. The \fBwalkcontext()\fR function +calls the user-supplied function \fIoperate_func\fR for each routine found on +the call stack and each signal handler invoked. The user function is passed +three arguments: the PC at which the call or signal occurred, the signal number +that occurred at this PC (0 if no signal occurred), and the third argument +passed to \fBwalkcontext()\fR. If the user function returns a non-zero value, +\fBwalkcontext()\fR returns without completing the callstack walk. +.sp +.LP +The \fBaddrtosymstr()\fR function attempts to convert a PC into a symbolic +representation of the form +.sp +.in +2 +.nf +\fIobjname\fR'\fIfuncname\fR+0x\fIoffset\fR[0xPC] +.fi +.in -2 + +.sp +.LP +where \fIobjname\fR is the module in which the PC is located, \fIfuncname\fR is +the name of the function, and \fIoffset\fR is the offset from the beginning of +the function. The \fIobjname\fR, \fIfuncname\fR, and \fIoffset\fR values are +obtained from \fBdladdr\fR(3C) and might not always be present. The resulting +string is written to the user-supplied buffer. Should the length of the string +be larger than the user-supplied buffer, only the portion of the string that +will fit is written and null-terminated. +.sp +.LP +The \fBprintstack()\fR function uses \fBwalkcontext()\fR to print a symbolic +stack trace to the specified file descriptor. This is useful for reporting +errors from signal handlers. The \fBprintstack()\fR function uses +\fBdladdr1()\fR (see \fBdladdr\fR(3C)) to obtain symbolic symbol names. As a +result, only global symbols are reported as symbol names by \fBprintstack()\fR. +.sp +.LP +The \fBbacktrace()\fR function uses \fBwalkcontext()\fR to generate a stack's +program counter values for the calling thread and place these values into the +array specified by the buffer argument. The \fIsize\fR argument specifies the +maximum number of program counters that will be recorded. This function is +provided for compatibility with the GNU \fBlibc\fR used on Linux systems, +\fBglibc\fR. +.sp +.LP +The \fBbacktrace_symbols()\fR function translates the numerical program counter +values previously recorded by a call to \fBbacktrace()\fR in the \fIbuffer\fR +argument, and converts, where possible, each PC to a string indicating the +module, function and offset of each call site. The number of symbols present in +the array must be passed in with the \fIsize\fR argument. +.sp +.LP +The set of strings is returned in an array obtained from a call to +\fBmalloc\fR(3C). It is the responsibility of the caller to pass the returned +pointer to \fBfree()\fR. The individual strings must not be freed. Since +\fBmalloc()\fR is used to obtain the needed space, this function is MT-Safe +rather than Async-Signal-Safe and cannot be used reliably from a signal +handler. This function is provided for \fBglibc\fR compatibility. +.sp +.LP +The \fBbacktrace_symbols_fd()\fR function translates the numerical program +counter values previously recorded by a call to \fBbacktrace()\fR in the buffer +argument, and converts, where possible, each PC to a string indicating the +module, function, and offset of each call site. These strings are written to +the file descriptor specified in the \fIfd\fR argument. This function is +provided for \fBglibc\fR compatibility. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBwalkcontext()\fR and \fBprintstack()\fR return +0. If \fBwalkcontext()\fR cannot read the stack or the stack trace appears +corrupted, both functions return -1. +.sp +.LP +The \fBaddrtosymstr()\fR function returns the number of characters necessary to +hold the entire string representation of the passed in address, irrespective of +the size of the user-supplied buffer. +.sp +.LP +The \fBbacktrace()\fR function returns the number of stack frames captured. +.sp +.LP +The \fBbacktrace_symbols()\fR function returns a pointer to an array containing +string representations of the calling sequence. +.SH ERRORS +.sp +.LP +No error values are defined. +.SH USAGE +.sp +.LP +The \fBwalkcontext()\fR function is typically used to obtain information about +the call stack for error reporting, performance analysis, or diagnostic +purposes. Many library functions are not Async-Signal-Safe and should not be +used from a signal handler. If \fBwalkcontext()\fR is to be called from a +signal handler, careful programming is required. In particular, +\fBstdio\fR(3C) and \fBmalloc\fR(3C) cannot be used. +.sp +.LP +The \fBwalkstack()\fR, \fBaddrtosymstr()\fR, \fBprintstack()\fR, +\fBbacktrace()\fR, and \fBbacktrace_symbols_fd()\fR functions are +Async-Signal-Safe and can be called from a signal handler. The string +representation generated by \fBaddrtosymstr()\fR and displayed by +\fBprintstack()\fR, \fBbacktrace_symbols()\fR and \fBbacktrace_symbols_fd()\fR +is unstable and will change depending on the information available in the +modules that comprise the stack trace. +.sp +.LP +Tail-call optimizations on SPARC eliminate stack frames that would otherwise be +present. For example, if the code is of the form +.sp +.in +2 +.nf +#include <stdio.h> + +main() +{ + bar(); + exit(0); +} + +bar() +{ + int a; + a = foo(fileno(stdout)); + return (a); +} + +foo(int file) +{ + printstack(file); +} +.fi +.in -2 + +.sp +.LP +compiling without optimization will yield a stack trace of the form +.sp +.in +2 +.nf +/tmp/q:foo+0x8 +/tmp/q:bar+0x14 +/tmp/q:main+0x4 +/tmp/q:_start+0xb8 +.fi +.in -2 + +.sp +.LP +whereas with higher levels of optimization the output is +.sp +.in +2 +.nf +/tmp/q:main+0x10 +/tmp/q:_start+0xb8 +.fi +.in -2 + +.sp +.LP +since both the call to \fBfoo()\fR in main and the call to \fBbar()\fR in +\fBfoo()\fR are handled as tail calls that perform a return or restore in the +delay slot. For further information, see \fIThe SPARC Architecture Manual\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStable +_ +MT-LevelSee below. +.TE + +.sp +.LP +The \fBbacktrace_symbols()\fR function is MT-Safe. The remaining functions are +Async-Signal-Safe. +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(2), \fBgetcontext\fR(2), \fBsigaction\fR(2), \fBdladdr\fR(3C), +\fBsiginfo.h\fR(3HEAD), \fBattributes\fR(5) +.sp +.LP +Weaver, David L. and Tom Germond, eds. \fIThe SPARC Architecture Manual\fR, +Version 9. Santa Clara: Prentice Hall, 2000. diff --git a/usr/src/man/man3c/wcrtomb.3c b/usr/src/man/man3c/wcrtomb.3c new file mode 100644 index 0000000000..34c99702f7 --- /dev/null +++ b/usr/src/man/man3c/wcrtomb.3c @@ -0,0 +1,121 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH wcrtomb 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +wcrtomb \- convert a wide-character code to a character (restartable) +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> + +\fBsize_t\fR \fBwcrtomb\fR(\fBchar *restrict\fR \fIs\fR, \fBwchar_t\fR \fIwc\fR, \fBmbstate_t *restrict\fR \fIps\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +If \fIs\fR is a null pointer, the \fBwcrtomb()\fR function is equivalent to the +call: +.sp +.LP +wcrtomb(buf, L'\e0', ps) +.sp +.LP +where \fIbuf\fR is an internal buffer. +.sp +.LP +If \fIs\fR is not a null pointer, the \fBwcrtomb()\fR function determines the +number of bytes needed to represent the character that corresponds to the +wide-character given by \fIwc\fR (including any shift sequences), and stores +the resulting bytes in the array whose first element is pointed to by \fIs\fR. +At most \fBMB_CUR_MAX\fR bytes are stored. If \fIwc\fR is a null +wide-character, a null byte is stored, preceded by any shift sequence needed to +restore the initial shift state. The resulting state described is the initial +conversion state. +.sp +.LP +If \fIps\fR is a null pointer, the \fBwcrtomb()\fR function uses its own +internal \fBmbstate_t\fR object, which is initialized at program startup to the +initial conversion state. Otherwise, the \fBmbstate_t\fR object pointed to +by \fIps\fR is used to completely describe the current conversion state of the +associated character sequence. Solaris will behave as if no function defined in +the Solaris Reference Manual calls \fBwcrtomb()\fR. +.sp +.LP +The behavior of this function is affected by the \fBLC_CTYPE\fR category of the +current locale. See \fBenviron\fR(5). +.SH RETURN VALUES +.sp +.LP +The \fBwcrtomb()\fR function returns the number of bytes stored in the array +object (including any shift sequences). When \fIwc\fR is not a valid +wide-character, an encoding error occurs. In this case, the function stores +the value of the macros \fBEILSEQ\fR in \fBerrno\fR and returns +\fB(size_t)\(mi1\fR; the conversion state is undefined. +.SH ERRORS +.sp +.LP +The \fBwcrtomb()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIps\fR argument points to an object that contains an invalid conversion +state. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEILSEQ\fR\fR +.ad +.RS 10n +.rt +Invalid wide-character code is detected. +.RE + +.SH USAGE +.sp +.LP +If \fIps\fR is not a null pointer, \fBwcrtomb()\fR uses the \fBmbstate_t\fR +object pointed to by \fIps\fR and the function can be used safely in +multithreaded applications, as long as \fBsetlocale\fR(3C) is not being called +to change the locale. If \fIps\fR is a null pointer, \fBwcrtomb()\fR uses its +internal \fBmbstate_t\fR object and the function is Unsafe in multithreaded +applications. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSee NOTES below +.TE + +.SH SEE ALSO +.sp +.LP +\fBmbsinit\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5), \fBenviron\fR(5) diff --git a/usr/src/man/man3c/wcscoll.3c b/usr/src/man/man3c/wcscoll.3c new file mode 100644 index 0000000000..b7929291a8 --- /dev/null +++ b/usr/src/man/man3c/wcscoll.3c @@ -0,0 +1,103 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH wcscoll 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +wcscoll, wscoll \- wide character string comparison using collating information +.SH SYNOPSIS +.LP +.nf +#include <wchar.h> + +\fBint\fR \fBwcscoll\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR); +.fi + +.LP +.nf +\fBint\fR \fBwscoll\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBwcscoll()\fR and \fBwscoll()\fR functions compare the wide character +string pointed to by \fIws1\fR to the wide character string pointed to by +\fIws2\fR, both interpreted as appropriate to the \fBLC_COLLATE\fR category of +the current locale. +.sp +.LP +The \fBwcscoll()\fR and \fBwscoll()\fR functions do not change the setting of +\fBerrno\fR if successful. +.sp +.LP +An application wanting to check for error situations should set \fBerrno\fR to +0 before calling \fBwcscoll()\fR or \fBwscoll()\fR. If \fBerrno\fR is non-zero +on return, an error has occurred. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBwcscoll()\fR and \fBwscoll()\fR return an +integer greater than, equal to, or less than 0, depending upon whether the wide +character string pointed to by \fIws1\fR is greater than, equal to, or less +than the wide character string pointed to by \fIws2\fR, when both are +interpreted as appropriate to the current locale. On error, \fBwcscoll()\fR and +\fBwscoll()\fR may set \fBerrno\fR, but no return value is reserved to indicate +an error. +.SH ERRORS +.sp +.LP +The \fBwcscoll()\fR and \fBwscoll()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIws1\fR or \fIws2\fR arguments contain wide character codes outside the +domain of the collating sequence. +.RE + +.SH USAGE +.sp +.LP +The \fBwcsxfrm\fR(3C) and \fBwcscmp\fR(3C) functions should be used for sorting +large lists. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +CSIEnabled +_ +Interface Stability\fBwcscoll()\fR is Standard +_ +MT-LevelMT-Safe with exceptions +.TE + +.sp +.LP +The \fBwcscoll()\fR and \fBwscoll()\fR functions can be used safely in +multithreaded applications as long as \fBsetlocale\fR(3C) is not being called +to change the locale. +.SH SEE ALSO +.sp +.LP +\fBsetlocale\fR(3C), \fBwcscmp\fR(3C), \fBwcsxfrm\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/wcsftime.3c b/usr/src/man/man3c/wcsftime.3c new file mode 100644 index 0000000000..542953bb3f --- /dev/null +++ b/usr/src/man/man3c/wcsftime.3c @@ -0,0 +1,113 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH wcsftime 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +wcsftime \- convert date and time to wide character string +.SH SYNOPSIS +.LP +.nf +#include <wchar.h> +.fi + +.SS "XPG4 and SUS" +.LP +.nf +\fBsize_t\fR \fBwcsftime\fR(\fBwchar_t *\fR\fIwcs\fR, \fBsize_t\fR \fImaxsize\fR, \fBconst char *\fR\fIformat\fR, + \fBconst struct tm *\fR\fItimptr\fR); +.fi + +.SS "Default and other standards" +.LP +.nf +\fBsize_t\fR \fBwcsftime\fR(\fBwchar_t *restrict\fR \fIwcs\fR, \fBsize_t\fR \fImaxsize\fR, + \fBconst wchar_t *restrict\fR \fIformat\fR, + \fBconst struct tm *restrict\fR \fItimptr\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBwcsftime()\fR function is equivalent to the \fBstrftime\fR(3C) function, +except that: +.RS +4 +.TP +.ie t \(bu +.el o +The argument \fIwcs\fR points to the initial element of an array of +wide-characters into which the generated output is to be placed. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The argument \fImaxsize\fR indicates the maximum number of wide-characters to +be placed in the output array. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The argument \fIformat\fR is a wide-character string and the conversion +specifications are replaced by corresponding sequences of wide-characters. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The return value indicates the number of wide-characters placed in the output +array. +.RE +.sp +.LP +If copying takes place between objects that overlap, the behavior is undefined. +.SH RETURN VALUES +.sp +.LP +If the total number of resulting wide character codes (including the +terminating null wide-character code) is no more than \fImaxsize\fR, +\fBwcsftime()\fR returns the number of wide-character codes placed into the +array pointed to by \fIwcs\fR, not including the terminating null +wide-character code. Otherwise, \fB0\fR is returned and the contents of the +array are indeterminate. +.sp +.LP +The \fBwcfstime()\fR function uses \fBmalloc\fR(3C) and should \fBmalloc()\fR +fail, \fBerrno\fR will be set by \fBmalloc()\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +CSIEnabled +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBmalloc\fR(3C), \fBsetlocale\fR(3C), \fBstrftime\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) +.SH NOTES +.sp +.LP +The \fBwcsftime()\fR function can be used safely in multithreaded applications, +as long as \fBsetlocale\fR(3C) is not being called to change the locale. diff --git a/usr/src/man/man3c/wcsrtombs.3c b/usr/src/man/man3c/wcsrtombs.3c new file mode 100644 index 0000000000..ef11d82242 --- /dev/null +++ b/usr/src/man/man3c/wcsrtombs.3c @@ -0,0 +1,139 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH wcsrtombs 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +wcsrtombs \- convert a wide-character string to a character string +(restartable) +.SH SYNOPSIS +.LP +.nf +#include <wchar.h> + +\fBsize_t\fR \fBwcsrtombs\fR(\fBchar *restrict\fR \fIdst\fR, + \fBconst wchar_t **restrict\fR \fIsrc\fR, \fBsize_t\fR \fIlen\fR, + \fBmbstate_t *restrict\fR \fIps\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBwcsrtombs()\fR function converts a sequence of wide-characters from the +array indirectly pointed to by \fIsrc\fR into a sequence of corresponding +characters, beginning in the conversion state described by the object pointed +to by \fIps\fR. If \fIdst\fR is not a null pointer, the converted characters +are then stored into the array pointed to by \fIdst\fR. Conversion continues up +to and including a terminating null wide-character, which is also stored. +Conversion stops earlier in the following cases: +.RS +4 +.TP +.ie t \(bu +.el o +When a code is reached that does not correspond to a valid character. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +When the next character would exceed the limit of \fIlen\fR total bytes to be +stored in the array pointed to by \fIdst\fR (and \fIdst\fR is not a null +pointer). +.RE +.sp +.LP +Each conversion takes place as if by a call to the \fBwcrtomb()\fR function. +.sp +.LP +If \fIdst\fR is not a null pointer, the pointer object pointed to by \fIsrc\fR +is 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 is the initial +conversion state. +.sp +.LP +If \fIps\fR is a null pointer, the \fBwcsrtombs()\fR function uses its own +internal \fBmbstate_t\fR object, which is initialized at program startup to the +initial conversion state. Otherwise, the \fBmbstate_t\fR object pointed to by +\fIps\fR is used to completely describe the current conversion state of the +associated character sequence. Solaris will behave as if no function defined in +the Solaris Reference Manual calls \fBwcsrtombs()\fR. +.sp +.LP +The behavior of this function is affected by the \fBLC_CTYPE\fR category of the +current locale. See \fBenviron\fR(5). +.SH RETURN VALUES +.sp +.LP +If conversion stops because a code is reached that does not correspond to a +valid character, an encoding error occurs. In this case, the \fBwcsrtombs()\fR +function stores the value of the macro \fBEILSEQ\fR in \fBerrno\fR and returns +\fB(size_t)\(mi1\fR; the conversion state is undefined. Otherwise, it returns +the number of bytes in the resulting character sequence, not including the +terminating null (if any). +.SH ERRORS +.sp +.LP +The \fBwcsrtombs()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIps\fR argument points to an object that contains an invalid conversion +state. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEILSEQ\fR\fR +.ad +.RS 10n +.rt +A wide-character code does not correspond to a valid character. +.RE + +.SH USAGE +.sp +.LP +If \fIps\fR is not a null pointer, \fBwcsrtombs()\fR uses the \fBmbstate_t\fR +object pointed to by \fIps\fR and the function can be used safely in +multithreaded applications, as long as \fBsetlocale\fR(3C) is not being called +to change the locale. If \fIps\fR is a null pointer, \fBwcsrtombs()\fR uses its +internal \fBmbstate_t\fR object and the function is Unsafe in multithreaded +applications. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSee NOTES below +.TE + +.SH SEE ALSO +.sp +.LP +\fBmbsinit\fR(3C), \fBsetlocale\fR(3C), \fBwcrtomb\fR(3C), \fBattributes\fR(5), +\fBenviron\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/wcsstr.3c b/usr/src/man/man3c/wcsstr.3c new file mode 100644 index 0000000000..b7627f045b --- /dev/null +++ b/usr/src/man/man3c/wcsstr.3c @@ -0,0 +1,79 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH wcsstr 3C "14 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +wcsstr \- find a wide-character substring +.SH SYNOPSIS +.LP +.nf +#include <wchar.h> + +\fBwchar_t *\fR\fBwcsstr\fR(\fBconst wchar_t *restrict\fR \fIws1\fR, \fBconst wchar_t *restrict\fR \fIws2\fR); +.fi + +.SS "ISO C++" +.LP +.nf +#include <wchar.h> + +\fBconst wchar_t *\fR\fBwcsstr\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR); +.fi + +.LP +.nf +#include <cwchar> + +\fBwchar_t *std::\fR\fBwcsstr\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBwcsstr()\fR function locates the first occurrence in the wide-character +string pointed to by \fIws1\fR of the sequence of wide-characters (excluding +the terminating null wide-character) in the wide-character string pointed to by +\fIws2\fR. +.SH RETURN VALUES +.sp +.LP +On successful completion, \fBwcsstr()\fR returns a pointer to the located +wide-character string, or a null pointer if the wide-character string is not +found. +.sp +.LP +If \fIws2\fR points to a wide-character string with zero length, the function +returns \fIws1\fR. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBwschr\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/wcstod.3c b/usr/src/man/man3c/wcstod.3c new file mode 100644 index 0000000000..7f5d3ef01d --- /dev/null +++ b/usr/src/man/man3c/wcstod.3c @@ -0,0 +1,258 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH wcstod 3C "31 Mar 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +wcstod, wcstof, wcstold, wstod, watof \- convert wide character string to +floating-point number +.SH SYNOPSIS +.LP +.nf +#include <wchar.h> + +\fBdouble\fR \fBwcstod\fR(\fBconst wchar_t *restrict\fR \fInptr\fR, + \fBwchar_t **restrict\fR \fIendptr\fR); +.fi + +.LP +.nf +\fBfloat\fR \fBwcstof\fR(\fBconst wchar_t *restrict\fR \fInptr\fR, + \fBwchar_t **restrict\fR \fIendptr\fR); +.fi + +.LP +.nf +\fBlong double\fR \fBwcstold\fR(\fBconst wchar_t *restrict\fR \fInptr\fR, + \fBwchar_t **restrict\fR \fIendptr\fR); +.fi + +.LP +.nf +\fBdouble\fR \fBwstod\fR(\fBconst wchar_t *\fR\fInptr\fR, \fBwchar_t **\fR\fIendptr\fR); +.fi + +.LP +.nf +\fBdouble\fR \fBwatof\fR(\fBwchar_t *\fR\fInptr\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBwcstod()\fR, \fBwcstof()\fR, and \fBwcstold()\fR functions convert the +initial portion of the wide-character string pointed to by \fInptr\fR to +\fBdouble\fR, \fBfloat\fR, and \fBlong double\fR representation, respectively. +They first decompose the input wide-character string into three parts: +.RS +4 +.TP +1. +An initial, possibly empty, sequence of white-space wide-character codes (as +specified by \fBiswspace\fR(3C)) +.RE +.RS +4 +.TP +2. +A subject sequence interpreted as a floating-point constant or representing +infinity or NaN +.RE +.RS +4 +.TP +3. +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. +.RE +.sp +.LP +Then they attempt to convert the subject sequence to a floating-point number, +and return the result. +.sp +.LP +The expected form of the subject sequence is an optional plus or minus sign, +then one of the following: +.RS +4 +.TP +.ie t \(bu +.el o +A non-empty sequence of decimal digits optionally containing a radix character, +then an optional exponent part +.RE +.RS +4 +.TP +.ie t \(bu +.el o +A 0x or 0X, then a non-empty sequence of hexadecimal digits optionally +containing a radix character, then an optional binary exponent part +.RE +.RS +4 +.TP +.ie t \(bu +.el o +One of INF or INFINITY, or any other wide string equivalent except for case +.RE +.RS +4 +.TP +.ie t \(bu +.el o +One of NAN or NAN(\fIn-wchar-sequence\fR(\fIopt\fR)), or any other wide string +ignoring case in the NAN part, where: +.sp +.in +2 +.nf +n-wchar-sequence: + digit + nondigit + n-wchar-sequence digit + n-wchar-sequence nondigit +.fi +.in -2 + +.RE +.sp +.LP +In default mode for \fBwcstod()\fR, only decimal, INF/INFINITY, and +NAN/NAN(\fIn-char-sequence\fR) forms are recognized. In C99/SUSv3 mode, +hexadecimal strings are also recognized. +.sp +.LP +In default mode for \fBwcstod()\fR, the \fIn-char-sequence\fR in the +NAN(\fIn-char-equence\fR) form can contain any character except ')' (right +parenthesis) or '\e0' (null). In C99/SUSv3 mode, the \fIn-char-sequence\fR can +contain only upper and lower case letters, digits, and '_' (underscore). +.sp +.LP +The \fBwcstof()\fR and \fBwcstold()\fR functions always function in +C99/SUSv3-conformant mode. +.sp +.LP +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. +.sp +.LP +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) is interpreted as a floating constant +according to the rules of the C language, except that the radix character is +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 is +interpreted as negated. A wide-character sequence INF or INFINITY is +interpreted as an infinity. A wide-character sequence NAN or +NAN(\fIn-wchar-sequence\fR(\fIopt\fR)) is interpreted as a quiet NaN. A pointer +to the final wide string is stored in the object pointed to by \fIendptr\fR, +provided that \fIendptr\fR is not a null pointer. +.sp +.LP +If the subject sequence has either the decimal or hexadecimal form, the value +resulting from the conversion is rounded correctly according to the prevailing +floating point rounding direction mode. The conversion also raises floating +point inexact, underflow, or overflow exceptions as appropriate. +.sp +.LP +The radix character is defined in the program's locale (category +\fBLC_NUMERIC\fR). In the POSIX locale, or in a locale where the radix +character is not defined, the radix character defaults to a period ('.'). +.sp +.LP +If the subject sequence is empty or does not have the expected form, no +conversion is performed; the value of \fInptr\fR is stored in the object +pointed to by \fIendptr\fR, provided that \fIendptr\fR is not a null pointer. +.sp +.LP +The \fBwcstod()\fR function does not change the setting of \fBerrno\fR if +successful. +.sp +.LP +The \fBwstod()\fR function is identical to \fBwcstod()\fR. +.sp +.LP +The \fBwatof\fR(\fIstr\fR) function is equivalent to \fBwstod(\fR\fInptr\fR\fB, +(wchar_t **)NULL)\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, these functions return the converted value. If no +conversion could be performed, \fB0\fR is returned. +.sp +.LP +If the correct value is outside the range of representable values, +\fB\(+-HUGE_VAL\fR, \fB\(+-HUGE_VALF\fR, or \fB\(+-HUGE_VALL\fR is returned +(according to the sign of the value), a floating point overflow exception is +raised, and \fBerrno\fR is set to \fBERANGE\fR. +.sp +.LP +If the correct value would cause an underflow, the correctly rounded result +(which may be normal, subnormal, or zero) is returned, a floating point +underflow exception is raised, and \fBerrno\fR is set to \fBERANGE\fR. +.SH ERRORS +.sp +.LP +The \fBwcstod()\fR and \fBwstod()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBERANGE\fR\fR +.ad +.RS 10n +.rt +The value to be returned would cause overflow or underflow. +.RE + +.sp +.LP +The \fBwcstod()\fR and \fBwcstod()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +No conversion could be performed. +.RE + +.SH USAGE +.sp +.LP +Because 0 is returned on error and is also a valid return on success, an +application wishing to check for error situations should set \fBerrno\fR to 0 +call \fBwcstod()\fR, \fBwcstof()\fR, \fBwcstold()\fR, or \fBwstod()\fR, then +check \fBerrno\fR and if it is non-zero, assume an error has occurred. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityT{ +\fBwcstod()\fR, \fBwcstof()\fR, and \fBwcstold()\fR are Standard. +T} +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBiswspace\fR(3C), \fBlocaleconv\fR(3C), \fBscanf\fR(3C), \fBsetlocale\fR(3C), +\fBwcstol\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/wcstoimax.3c b/usr/src/man/man3c/wcstoimax.3c new file mode 100644 index 0000000000..9ff8c53a6b --- /dev/null +++ b/usr/src/man/man3c/wcstoimax.3c @@ -0,0 +1,106 @@ +'\" te +.\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved. Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH wcstoimax 3C "1 Dec 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +wcstoimax, wcstoumax \- convert wide-character string to integer type +.SH SYNOPSIS +.LP +.nf +#include <stddef.h> +#include <inttypes.h> + +\fBintmax_t\fR \fBwcstoimax\fR(\fBconst wchar_t *restrict\fR \fInptr\fR, + \fBwchar_t **restrict\fR \fIendptr\fR, \fBint\fR \fIbase\fR); +.fi + +.LP +.nf +\fBuintmax_t\fR \fBwcstoumax\fR(\fBconst wchar_t *restrict\fR \fInptr\fR, + \fBwchar_t **restrict\fR \fIendptr\fR, \fBint\fR \fIbase\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions are equivalent to the \fBwcstol\fR(3C), \fBwcstoll\fR(3C), +\fBwcstoul\fR(3C), and \fBwcstoull\fR(3C) functions, respectively, except that +the initial portion of the wide string is converted to \fBintmax_t\fR and +\fBuintmax_t\fR representation, respectively. +.SH RETURN VALUES +.sp +.LP +These functions return the converted value, if any. If no conversion could be +performed, 0 is returned. If the correct value is outside the range of +representable values, {\fBINTMAX_MAX\fR}, {\fBINTMAX_MIN\fR}, or +{\fBUINTMAX_MAX\fR} is returned (according to the return type and sign of the +value), and \fBerrno\fR is set to \fBERANGE\fR. +.SH ERRORS +.sp +.LP +These functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of \fIbase\fR is not supported. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBERANGE\fR\fR +.ad +.RS 10n +.rt +The value to be returned is not representable. +.RE + +.sp +.LP +These functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +No conversion could be performed. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBwcstol\fR(3C), \fBwcstoul\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/wcstol.3c b/usr/src/man/man3c/wcstol.3c new file mode 100644 index 0000000000..ef364e5204 --- /dev/null +++ b/usr/src/man/man3c/wcstol.3c @@ -0,0 +1,226 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH wcstol 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +wcstol, wcstoll, wstol, watol, watoll, watoi \- convert wide character string +to long integer +.SH SYNOPSIS +.LP +.nf +#include <wchar.h> + +\fBlong\fR \fBwcstol\fR(\fBconst wchar_t *restrict\fR \fInptr\fR, \fBwchar_t **restrict\fR \fIendptr\fR, + \fBint\fR \fIbase\fR); +.fi + +.LP +.nf +\fBlong long\fR \fBwcstoll\fR(\fBconst wchar_t *restrict\fR \fInptr\fR, \fBwchar_t **restrict\fR \fIendptr\fR, + \fBint\fR \fIbase\fR); +.fi + +.LP +.nf +#include <widec.h> + +\fBlong\fR \fBwstol\fR(\fBconst wchar_t *\fR\fInptr\fR, \fBwchar_t **\fR\fIendptr\fR, \fBint\fR \fIbase\fR); +.fi + +.LP +.nf +\fBlong\fR \fBwatol\fR(\fBwchar_t *\fR\fInptr\fR); +.fi + +.LP +.nf +\fBlong long\fR \fBwatoll\fR(\fBwchar_t *\fR\fInptr\fR); +.fi + +.LP +.nf +\fBint\fR \fBwatoi\fR(\fBwchar_t *\fR\fInptr\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBwcstol()\fR and \fBwcstoll()\fR functions convert the initial portion of +the wide character string pointed to by \fInptr\fR to \fBlong\fR and \fBlong +long\fR representation, respectively. They first decompose the input string +into three parts: +.RS +4 +.TP +1. +an initial, possibly empty, sequence of white-space wide-character codes (as +specified by \fBiswspace\fR(3C)) +.RE +.RS +4 +.TP +2. +a subject sequence interpreted as an integer represented in some radix +determined by the value of \fIbase\fR +.RE +.RS +4 +.TP +3. +a final wide character string of one or more unrecognised wide character +codes, including the terminating null wide-character code of the input wide +character string +.RE +.sp +.LP +They then attempt to convert the subject sequence to an integer, and return the +result. +.sp +.LP +If the value of \fIbase\fR is \fB0\fR, 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 `+' or `\(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 `0' optionally followed by a sequence of the +digits `0' to `7' only. A hexadecimal constant consists of the prefix `0x' or +`0X' followed by a sequence of the decimal digits and letters `a' (or `A') to +`f' (or `F') with values 10 to 15 respectively. +.sp +.LP +If the value of \fIbase\fR is between \fB2\fR and \fB36\fR, the expected form +of the subject sequence is a sequence of letters and digits representing an +integer with the radix specified by \fIbase\fR, optionally preceded by a `+' +or `\(mi' sign, but not including an integer suffix. The letters from `a' (or +`A') to `z' (or `Z') inclusive are ascribed the values 10 to 35; only letters +whose ascribed values are less than that of \fIbase\fR are permitted. If the +value of \fIbase\fR is \fB16\fR, the wide-character code representations of +`0x' or `0X' may optionally precede the sequence of letters and digits, +following the sign if present. +.sp +.LP +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. +.sp +.LP +If the subject sequence has the expected form and the value of \fIbase\fR is +\fB0\fR, the sequence of wide-character codes starting with the first digit is +interpreted as an integer constant. If the subject sequence has the expected +form and the value of \fIbase\fR is between \fB2\fR and \fB36\fR, it is 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 is negated. A pointer to the final wide character string is stored +in the object pointed to by \fIendptr\fR, provided that \fIendptr\fR is not a +null pointer. +.sp +.LP +If the subject sequence is empty or does not have the expected form, no +conversion is performed; the value of \fInptr\fR is stored in the object +pointed to by \fIendptr\fR, provided that \fIendptr\fR is not a null pointer. +.sp +.LP +These functions do not change the setting of \fBerrno\fR if successful. +.sp +.LP +Since 0, {\fBLONG_MIN\fR} or {\fBLLONG_MIN\fR}, and {\fBLONG_MAX\fR} or +{\fBLLONG_MAX\fR} are returned on error and are also valid returns on success, +an application wanting to check for error situations should set \fBerrno\fR to +0, call one of these functions, then check \fBerrno\fR. +.sp +.LP +The \fBwstol()\fR function is equivalent to \fBwcstol()\fR. +.sp +.LP +The \fBwatol()\fR function is equivalent to \fBwstol(\fR\fIstr\fR\fB,(wchar_t +**)NULL, 10)\fR\fI\&.\fR +.sp +.LP +The \fBwatoll()\fR function is the long-long (double long) version of +\fBwatol()\fR. +.sp +.LP +The \fBwatoi()\fR function is equivalent to \fB(int)watol(\|)\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, these functions return the converted value, if any. +If no conversion could be performed, 0 is returned and \fBerrno\fR may be set +to indicate the error. If the correct value is outside the range of +representable values, {\fBLONG_MIN\fR}, {\fBLONG_MAX\fR}, {\fBLLONG_MIN\fR}, or +{\fBLLONG_MAX\fR} is returned (according to the sign of the value), and +\fBerrno\fR is set to \fBERANGE\fR. +.SH ERRORS +.sp +.LP +These functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of \fIbase\fR is not supported. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBERANGE\fR\fR +.ad +.RS 10n +.rt +The value to be returned is not representable. +.RE + +.sp +.LP +These functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +No conversion could be performed. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface Stability\fBwcstol()\fR and \fBwcstoll()\fR are Standard. +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBiswalpha\fR(3C), \fBiswspace\fR(3C), \fBscanf\fR(3C), \fBwcstod\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +Truncation from \fBlong long\fR to \fBlong\fR can take place upon assignment or +by an explicit cast. diff --git a/usr/src/man/man3c/wcstoul.3c b/usr/src/man/man3c/wcstoul.3c new file mode 100644 index 0000000000..a03ec17f8d --- /dev/null +++ b/usr/src/man/man3c/wcstoul.3c @@ -0,0 +1,197 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH wcstoul 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +wcstoul, wcstoull \- convert wide-character string to unsigned long +.SH SYNOPSIS +.LP +.nf +#include <wchar.h> + +\fBunsigned long\fR \fBwcstoul\fR(\fBconst wchar_t *restrict\fR \fInptr\fR, + \fBwchar_t **restrict\fR \fIendptr\fR, \fBint\fR \fIbase\fR); +.fi + +.LP +.nf +\fBunsigned long long\fR \fBwcstoull\fR(\fBconst wchar_t *restrict\fR \fInptr\fR, + \fBwchar_t **restrict\fR \fIendptr\fR, \fBint\fR \fIbase\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBwcstoul()\fR and \fBwcstoull()\fR functions convert the initial portion +of the wide-character string pointed to by \fInptr\fR to \fBunsigned long\fR +and \fBunsigned long long\fR representation, respectively. First they decompose +the input wide-character string into three parts: +.RS +4 +.TP +1. +An initial, possibly empty, sequence of white-space wide-character codes (as +specified by the function \fBiswspace\fR(3C)) +.RE +.RS +4 +.TP +2. + Asubject sequence interpreted as an integer represented in some radix +determined by the value of \fIbase\fR +.RE +.RS +4 +.TP +3. +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 +.RE +.sp +.LP +They then attempt to convert the subject sequence to an unsigned integer and +return the result. +.sp +.LP +If the value of \fIbase\fR is 0, the expected form of the subject sequence is +that of a decimal constant, an octal constant, or a hexadecimal constant, any +of which may be preceded by a `+' or a `\(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 `0', optionally followed by a sequence of the +digits `0' to `7' only. A hexadecimal constant consists of the prefix `0x' or +`0X', followed by a sequence of the decimal digits and letters `a' (or `A') to +`f' (or `F'), with values 10 to 15, respectively. +.sp +.LP +If the value of \fIbase\fR 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 \fIbase\fR, optionally preceded by a `+' or a +`\(mi' sign, but not including an integer suffix. The letters from `a' (or `A') +to `z' (or `Z') inclusive are ascribed the values 10 to 35; only letters whose +ascribed values are less than that of \fIbase\fR are permitted. If the value of +\fIbase\fR is 16, the wide-character codes `0x' or `0X' may optionally precede +the sequence of letters and digits, following the sign, if present. +.sp +.LP +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 +a 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 a white space is other than a sign or a permissible letter or +digit. +.sp +.LP +If the subject sequence has the expected form and the value of \fIbase\fR is 0, +the sequence of wide-character codes starting with the first digit is +interpreted as an integer constant. If the subject sequence has the expected +form and the value of \fIbase\fR is between 2 and 36, it is 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 is negated. A pointer to the final wide character string is stored +in the object pointed to by \fIendptr\fR, provided that \fIendptr\fR is not a +null pointer. +.sp +.LP +If the subject sequence is empty or does not have the expected form, no +conversion is performed; the value of \fInptr\fR is stored in the object +pointed to by \fIendptr\fR, provided that \fIendptr\fR is not a null pointer. +.sp +.LP +The \fBwcstoul()\fR function does not change the setting of \fBerrno\fR if +successful. +.sp +.LP +Since 0, {\fBULONG_MAX\fR}, and {\fBULLONG_MAX\fR} are returned on error and 0 +is also a valid return on success, an application wanting to check for error +situations should set \fBerrno\fR to 0, then call \fBwcstoul()\fR or +\fBwcstoull()\fR, then check \fBerrno\fR. +.sp +.LP +The \fBwcstoul()\fR and \fBwcstoull()\fR functions do not change the setting of +\fBerrno\fR if successful. +.SH RETURN VALUE +.sp +.LP +Upon successful completion, \fBwcstoul()\fR and \fBwcstoull()\fR return the +converted value, if any. If no conversion could be performed, \fB0\fR is +returned and \fBerrno\fR may be set to indicate the error. If the correct value +is outside the range of representable values, {\fBULONG_MAX\fR} or +{\fBULLONG_MAX\fR}, respectively, is returned and \fBerrno\fR is set to +\fBERANGE\fR. +.SH ERRORS +.sp +.LP +The \fBwcstoul()\fR and \fBwcstoull()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of \fIbase\fR is not supported. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBERANGE\fR\fR +.ad +.RS 10n +.rt +The value to be returned is not representable. +.RE + +.sp +.LP +The \fBwcstoul()\fR and \fBwcstoull()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +No conversion could be performed. +.RE + +.SH USAGE +.sp +.LP +Unlike \fBwcstod\fR(3C) and \fBwcstol\fR(3C), \fBwcstoul()\fR and +\fBwcstoull()\fR must always return a non-negative number; using the return +value of \fBwcstoul()\fR for out-of-range numbers with \fBwcstoul()\fR or +\fBwcstoull()\fR could cause more severe problems than just loss of precision +if those numbers can ever be negative. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBisspace\fR(3C), \fBiswalpha\fR(3C), \fBscanf\fR(3C), \fBwcstod\fR(3C), +\fBwcstol\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/wcstring.3c b/usr/src/man/man3c/wcstring.3c new file mode 100644 index 0000000000..480768bac7 --- /dev/null +++ b/usr/src/man/man3c/wcstring.3c @@ -0,0 +1,433 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH wcstring 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +wcstring, wcscat, wscat, wcsncat, wsncat, wcscmp, wscmp, wcsncmp, wsncmp, +wcscpy, wscpy, wcsncpy, wsncpy, wcslen, wslen, wcschr, wschr, wcsrchr, wsrchr, +windex, wrindex, wcspbrk, wspbrk, wcswcs, wcsspn, wsspn, wcscspn, wscspn, +wcstok, wstok \- wide-character string operations +.SH SYNOPSIS +.LP +.nf +#include <wchar.h> + +\fBwchar_t *\fR\fBwcscat\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR); +.fi + +.LP +.nf +\fBwchar_t *\fR\fBwcsncat\fR(\fBwchar_t *restrict\fR \fIws1\fR, \fBconst wchar_t *restrict\fR \fIws2\fR, + \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +\fBint\fR \fBwcscmp\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR); +.fi + +.LP +.nf +\fBint\fR \fBwcsncmp\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR, \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +\fBwchar_t *\fR\fBwcscpy\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR); +.fi + +.LP +.nf +\fBwchar_t *\fR\fBwcsncpy\fR(\fBwchar_t *restrict\fR \fIws1\fR, \fBconst wchar_t *restrict\fR \fIws2\fR, + \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +\fBsize_t\fR \fBwcslen\fR(\fBconst wchar_t *\fR\fIws\fR); +.fi + +.LP +.nf +\fBwchar_t *\fR\fBwcschr\fR(\fBconst wchar_t *\fR\fIws\fR, \fBwchar_t\fR \fIwc\fR); +.fi + +.LP +.nf +\fBwchar_t *\fR\fBwcsrchr\fR(\fBconst wchar_t *\fR\fIws\fR, \fBwchar_t\fR \fIwc\fR); +.fi + +.LP +.nf +\fBwchar_t *\fR\fBwcspbrk\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR); +.fi + +.LP +.nf +\fBwchar_t *\fR\fBwcswcs\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR); +.fi + +.LP +.nf +\fBsize_t\fR \fBwcsspn\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR); +.fi + +.LP +.nf +\fBsize_t\fR \fBwcscspn\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR); +.fi + +.SS "XPG4, SUS, SUSv2, SUSv3" +.LP +.nf +\fBwchar_t *\fR\fBwcstok\fR(\fBwchar_t *restrict\fR \fIws1\fR, \fBconst wchar_t *restrict\fR \fIws2\fR); +.fi + +.SS "Default and other standards" +.LP +.nf +\fBwchar_t *\fR\fBwcstok\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR, \fBwchar_t **\fR\fIptr\fR); +.fi + +.LP +.nf +#include <widec.h> + +\fBwchar_t *\fR\fBwscat\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR); +.fi + +.LP +.nf +\fBwchar_t *\fR\fBwsncat\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR, \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +\fBint\fR \fBwscmp\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR); +.fi + +.LP +.nf +\fBint\fR \fBwsncmp\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR, \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +\fBwchar_t *\fR\fBwscpy\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR); +.fi + +.LP +.nf +\fBwchar_t *\fR\fBwsncpy\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR, \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +\fBsize_t\fR \fBwslen\fR(\fBconst wchar_t *\fR\fIws\fR); +.fi + +.LP +.nf +\fBwchar_t *\fR\fBwschr\fR(\fBconst wchar_t *\fR\fIws\fR, \fBwchat_t\fR \fIwc\fR); +.fi + +.LP +.nf +\fBwchar_t *\fR\fBwsrchr\fR(\fBconst wchar_t *\fR\fIws\fR, \fBwchat_t\fR \fIwc\fR); +.fi + +.LP +.nf +\fBwchar_t *\fR\fBwspbrk\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR); +.fi + +.LP +.nf +\fBsize_t\fR \fBwsspn\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR); +.fi + +.LP +.nf +\fBsize_t\fR \fBwscspn\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR); +.fi + +.LP +.nf +\fBwchar_t *\fR\fBwstok\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR); +.fi + +.LP +.nf +\fBwchar_t *\fR\fBwindex\fR(\fBconst wchar_t *\fR\fIws\fR, \fBwchar_t\fR \fIwc\fR); +.fi + +.LP +.nf +\fBwchar_t *\fR\fBwrindex\fR(\fBconst wchar_t *\fR\fIws\fR, \fBwchar_t\fR \fIwc\fR); +.fi + +.SS "ISO C++" +.LP +.nf +#include <wchar.h> + +\fBconst wchar_t *\fR\fBwcschr\fR(\fBconst wchar_t *\fR\fIws\fR, \fBwchar_t\fR \fIwc\fR); +.fi + +.LP +.nf +\fBconst wchar_t *\fR\fBwcspbrk\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR); +.fi + +.LP +.nf +\fBconst wchar_t *\fR\fBwcsrchr\fR(\fBconst wchar_t *\fR\fIws\fR, \fBwchar_t\fR \fIwc\fR); +.fi + +.LP +.nf +#include <cwchar> + +\fBwchar_t *std::\fR\fBwcschr\fR(\fBwchar_t *\fR\fIws\fR, \fBwchar_t\fR \fIwc\fR); +.fi + +.LP +.nf +\fBwchar_t *std::\fR\fBwcspbrk\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR); +.fi + +.LP +.nf +\fBwchar_t *std::\fR\fBwcsrchr\fR(\fBwchar_t *\fR\fIws\fR, \fBwchar_t\fR \fIwc\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions operate on wide-character strings terminated by \fBwchar_t\fR +\fINULL\fR characters. During appending or copying, these routines do not check +for an overflow condition of the receiving string. In the following, \fIws\fR, +\fIws1\fR, and \fIws2\fR point to wide-character strings terminated by a +\fBwchar_t NULL\fR. +.SS "wcscat(\|), wscat(\|)" +.sp +.LP +The \fBwcscat()\fR and \fBwscat()\fR functions append a copy of the +wide-character string pointed to by \fIws2\fR (including the terminating null +wide-character code) to the end of the wide-character string pointed to by +\fIws1\fR. The initial wide-character code of \fIws2\fR overwrites the null +wide-character code at the end of \fIws1\fR. If copying takes place between +objects that overlap, the behavior is undefined. Both functions return +\fIs1\fR; no return value is reserved to indicate an error. +.SS "wcsncat(\|), wsncat(\|)" +.sp +.LP +The \fBwcsncat()\fR and \fBwsncat()\fR functions append not more than \fIn\fR +wide-character codes (a null wide-character code and wide-character codes that +follow it are not appended) from the array pointed to by \fIws2\fR to the end +of the wide-character string pointed to by \fIws1\fR. The initial +wide-character code of \fIws2\fR overwrites the null wide-character code at the +end of \fIws1\fR. A terminating null wide-character code is always appended to +the result. Both functions return \fIws1\fR; no return value is reserved to +indicate an error. +.SS "wcscmp(\|), wscmp(\|)" +.sp +.LP +The \fBwcscmp()\fR and \fBwscmp()\fR functions compare the wide-character +string pointed to by \fIws1\fR to the wide-character string pointed to by +\fIws2\fR. The sign of a non-zero return value is 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. Upon completion, both functions return an +integer greater than, equal to, or less than zero, if the wide-character string +pointed to by \fIws1\fR is greater than, equal to, or less than the +wide-character string pointed to by \fIws2\fR. +.SS "wcsncmp(\|), wsncmp(\|)" +.sp +.LP +The \fBwcsncmp()\fR and \fBwsncmp()\fR functions compare not more than \fIn\fR +wide-character codes (wide-character codes that follow a null wide character +code are not compared) from the array pointed to by \fIws1\fR to the array +pointed to by \fIws2\fR. The sign of a non-zero return value is 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. Upon successful +completion, both functions return an integer greater than, equal to, or less +than zero, if the possibly null-terminated array pointed to by \fIws1\fR is +greater than, equal to, or less than the possibly null-terminated array pointed +to by \fIws2\fR. +.SS "wcscpy(\|), wscpy(\|)" +.sp +.LP +The \fBwcscpy()\fR and \fBwscpy()\fR functions copy the wide-character string +pointed to by \fIws2\fR (including the terminating null wide-character code) +into the array pointed to by \fIws1\fR. If copying takes place between objects +that overlap, the behavior is undefined. Both functions return \fIws1\fR; no +return value is reserved to indicate an error. +.SS "wcsncpy(\|), wsncpy(\|)" +.sp +.LP +The \fBwcsncpy()\fR and \fBwsncpy()\fR functions copy not more than \fIn\fR +wide-character codes (wide-character codes that follow a null wide character +code are not copied) from the array pointed to by \fIws2\fR to the array +pointed to by \fIws1\fR. If copying takes place between objects that overlap, +the behavior is undefined. If the array pointed to by \fIws2\fR is a +wide-character string that is shorter than \fIn\fR wide-character codes, null +wide-character codes are appended to the copy in the array pointed to by +\fIws1\fR, until a total \fIn\fR wide-character codes are written. Both +functions return \fI ws1\fR; no return value is reserved to indicate an error. +.SS "wcslen(\|), wslen(\|)" +.sp +.LP +The \fBwcslen()\fR and \fBwslen()\fR functions compute the number of +wide-character codes in the wide-character string to which \fIws\fR points, not +including the terminating null wide-character code. Both functions return +\fIws\fR; no return value is reserved to indicate an error. +.SS "wcschr(\|), wschr(\|)" +.sp +.LP +The \fBwcschr()\fR and \fBwschr()\fR functions locate the first occurrence of +\fIwc\fR in the wide-character string pointed to by \fIws\fR. The value of +\fIwc\fR must be a character representable as a type \fBwchar_t\fR and must be +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. Upon completion, both functions return a pointer to the +wide-character code, or a null pointer if the wide-character code is not found. +.SS "wcsrchr(\|), wsrchr(\|)" +.sp +.LP +The \fBwcsrchr()\fR and \fBwsrchr()\fR functions locate the last occurrence of +\fIwc\fR in the wide-character string pointed to by \fIws\fR. The value of +\fIwc\fR must be a character representable as a type \fBwchar_t\fR and must be +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. Upon successful completion, both functions return a +pointer to the wide-character code, or a null pointer if \fIwc\fR does not +occur in the wide-character string. +.SS "windex(\|), wrindex(\|)" +.sp +.LP +The \fBwindex()\fR and \fBwrindex()\fR functions behave the same as +\fBwschr()\fR and \fBwsrchr()\fR, respectively. +.SS "wcspbrk(\|), wspbrk(\|)" +.sp +.LP +The \fBwcspbrk()\fR and \fBwspbrk()\fR functions locate the first occurrence in +the wide character string pointed to by \fIws1\fR of any wide-character code +from the wide-character string pointed to by \fIws2\fR. Upon successful +completion, the function returns a pointer to the wide-character code, or a +null pointer if no wide-character code from \fIws2\fR occurs in \fIws1\fR. +.SS "wcswcs(\|)" +.sp +.LP +The \fBwcswcs()\fR function locates the first occurrence in the wide-character +string pointed to by \fIws1\fR of the sequence of wide-character codes +(excluding the terminating null wide-character code) in the wide-character +string pointed to by \fIws2\fR. Upon successful completion, the function +returns a pointer to the located wide-character string, or a null pointer if +the wide-character string is not found. If \fIws2\fR points to a wide-character +string with zero length, the function returns \fIws1\fR. +.SS "wcsspn(\|), wsspn(\|)" +.sp +.LP +The \fBwcsspn()\fR and \fBwsspn()\fR functions compute the length of the +maximum initial segment of the wide-character string pointed to by \fIws1\fR +which consists entirely of wide-character codes from the wide-character string +pointed to by \fIws2\fR. Both functions return the length \fIws1\fR; no return +value is reserved to indicate an error. +.SS "wcscspn(\|), wscspn(\|)" +.sp +.LP +The \fBwcscspn()\fR and \fBwscspn()\fR functions compute the length of the +maximum initial segment of the wide-character string pointed to by \fIws1\fR +which consists entirely of wide-character codes \fInot\fR from the +wide-character string pointed to by \fIws2\fR. Both functions return the length +of the initial substring of \fIws1\fR; no return value is reserved to indicate +an error. +.SS "wcstok(\|), wstok(\|)" +.sp +.LP +A sequence of calls to the \fBwcstok()\fR and \fBwstok()\fR functions break the +wide-character string pointed to by \fIws1\fR into a sequence of tokens, each +of which is delimited by a wide-character code from the wide-character string +pointed to by \fIws2\fR. +.SS "Default and other standards" +.sp +.LP +The third argument points to a caller-provided \fBwchar_t\fR pointer into which +the \fBwcstok()\fR function stores information necessary for it to continue +scanning the same wide-character string. This argument is not available with +the XPG4 and SUS versions of \fBwcstok()\fR, nor is it available with the +\fBwstok()\fR function. See \fBstandards\fR(5). +.sp +.LP +The first call in the sequence has \fIws1\fR as its first argument, and is +followed by calls with a null pointer as their first argument. The separator +string pointed to by \fIws2\fR may be different from call to call. +.sp +.LP +The first call in the sequence searches the wide-character string pointed to by +\fIws1\fR for the first wide-character code that is \fInot\fR contained in the +current separator string pointed to by \fIws2\fR. If no such wide-character +code is found, then there are no tokens in the wide-character string pointed to +by \fIws1\fR, and \fBwcstok()\fR and \fBwstok()\fR return a null pointer. If +such a wide-character code is found, it is the start of the first token. +.sp +.LP +The \fBwcstok()\fR and \fBwstok()\fR functions then search from that point for +a wide-character code that \fIis\fR 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 \fIws1\fR, and subsequent searches +for a token will return a null pointer. If such a wide-character code is found, +it is overwritten by a null wide character, which terminates the current token. +The \fBwcstok()\fR and \fBwstok()\fR functions save a pointer to the following +wide-character code, from which the next search for a token will start. +.sp +.LP +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. +.sp +.LP +Upon successful completion, both functions return a pointer to the first +wide-character code of a token. Otherwise, if there is no token, a null pointer +is returned. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +CSIEnabled +_ +Interface StabilitySee NOTES. +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBmalloc\fR(3C), \fBstring\fR(3C), \fBwcswidth\fR(3C), \fBwcwidth\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) +.SH NOTES +.sp +.LP +The \fBwcscat()\fR, \fBwcsncat()\fR, \fBwcscmp()\fR, \fBwcsncmp()\fR, +\fBwcscpy()\fR, \fBwcsncpy()\fR, \fBwcslen()\fR, \fBwcschr()\fR, +\fBwcsrchr()\fR, \fBwcspbrk()\fR, \fBwcswcs()\fR, \fBwcsspn()\fR, +\fBwcscspn()\fR, and \fBwcstok()\fR functions are Standard. The \fBwscat()\fR, +\fBwsncat()\fR, \fBwscmp()\fR, \fBwsncmp()\fR, \fBwscpy()\fR, \fBwsncpy()\fR, +\fBwslen()\fR, \fBwschr()\fR, \fBwsrchr()\fR, \fBwspbrk()\fR, \fBwsspn()\fR, +\fBwstok()\fR, \fBwindex()\fR, and \fBwrindex()\fR functions are Stable. diff --git a/usr/src/man/man3c/wcswidth.3c b/usr/src/man/man3c/wcswidth.3c new file mode 100644 index 0000000000..01cf902139 --- /dev/null +++ b/usr/src/man/man3c/wcswidth.3c @@ -0,0 +1,66 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH wcswidth 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +wcswidth \- number of column positions of a wide-character string +.SH SYNOPSIS +.LP +.nf +#include <wchar.h> + +\fBint\fR \fBwcswidth\fR(\fBconst wchar_t *\fR\fIpwcs\fR, \fBsize_t\fR \fIn\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBwcswidth()\fR function determines the number of column positions +required for \fIn\fR wide-character codes (or fewer than \fIn\fR wide-character +codes if a null wide-character code is encountered before \fIn\fR +wide-character codes are exhausted) in the string pointed to by \fIpwcs\fR. +.SH RETURN VALUES +.sp +.LP +The \fBwcswidth()\fR function either returns \fB0\fR (if \fIpwcs\fR points to a +null wide-character code), or returns the number of column positions to be +occupied by the wide-character string pointed to by \fIpwcs\fR, or returns +\fB\(mi1\fR (if any of the first \fIn\fR wide-character codes in the +wide-character string pointed to by \fIpwcs\fR is not a printing wide-character +code). +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +CSIEnabled +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBsetlocale\fR(3C), \fBwcwidth\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/wcsxfrm.3c b/usr/src/man/man3c/wcsxfrm.3c new file mode 100644 index 0000000000..33a62d09dd --- /dev/null +++ b/usr/src/man/man3c/wcsxfrm.3c @@ -0,0 +1,119 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH wcsxfrm 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +wcsxfrm, wsxfrm \- wide character string transformation +.SH SYNOPSIS +.LP +.nf +#include <wchar.h> + +\fBsize_t\fR \fBwcsxfrm\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR, \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +\fBsize_t\fR \fBwsxfrm\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR, \fBsize_t\fR \fIn\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBwcsxfrm()\fR and \fBwcsxfrm()\fR functions transform the wide character +string pointed to by \fIws2\fR and place the resulting wide character string +into the array pointed to by \fIws1\fR. The transformation is such that if +either the \fBwcscmp\fR(3C) or \fBwscmp\fR(3C) functions are applied to two +transformed wide strings, they return a value greater than, equal to, or less +than 0, corresponding to the result of the \fBwcscoll\fR(3C) or +\fBwscoll\fR(3C) function applied to the same two original wide character +strings. No more than \fIn\fR wide-character codes are placed into the +resulting array pointed to by \fIws1\fR, including the terminating null +wide-character code. If \fIn\fR is 0, \fIws1\fR is permitted to be a null +pointer. If copying takes place between objects that overlap, the behavior is +undefined. +.sp +.LP +The \fBwcsxfrm()\fR and \fBwsxfrm()\fR functions do not change the setting of +\fBerrno\fR if successful. +.sp +.LP +Since no return value is reserved to indicate an error, an application wishing +to check for error situations should set \fBerrno\fR to 0, then call +\fBwcsxfrm()\fR or \fBwsxfrm()\fR, then check \fBerrno\fR. +.SH RETURN VALUES +.sp +.LP +The \fBwcsxfrm()\fR and \fBwsxfrm()\fR functions return the length of the +transformed wide character string (not including the terminating null +wide-character code). If the value returned is \fIn\fR or more, the contents of +the array pointed to by \fIws1\fR are indeterminate. +.sp +.LP +On error, \fBwcsxfrm()\fR and \fBwsxfrm()\fR may set \fBerrno\fR but no return +value is reserved to indicate an error. +.SH ERRORS +.sp +.LP +The \fBwcsxfrm()\fR and \fBwsxfrm()\fR functions may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The wide character string pointed to by \fIws2\fR contains wide-character codes +outside the domain of the collating sequence. +.RE + +.SH USAGE +.sp +.LP +The transformation function is such that two transformed wide character +strings can be ordered by the \fBwcscmp()\fR or \fBwscmp()\fR functions as +appropriate to collating sequence information in the program's locale (category +\fBLC_COLLATE\fR). +.sp +.LP +The fact that when \fIn\fR is 0, \fIws1\fR is permitted to be a null pointer, +is useful to determine the size of the \fIws1\fR array prior to making the +transformation. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +CSIEnabled +_ +Interface Stability\fBwcsxfrm()\fR is Standard +_ +MT-LevelMT-Safe with exceptions +.TE + +.sp +.LP +The \fBwcsxfrm()\fR and \fBwsxfrm()\fR functions can be used safely in +multithreaded applications as long as \fBsetlocale\fR(3C) is not being called +to change the locale. +.SH SEE ALSO +.sp +.LP +\fBsetlocale\fR(3C), \fBwcscmp\fR(3C), \fBwcscoll\fR(3C), \fBwscmp\fR(3C), +\fBwscoll\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/wctob.3c b/usr/src/man/man3c/wctob.3c new file mode 100644 index 0000000000..d445d8e512 --- /dev/null +++ b/usr/src/man/man3c/wctob.3c @@ -0,0 +1,70 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH wctob 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +wctob \- wide-character to single-byte conversion +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> +#include <wchar.h> + +\fBint\fR \fBwctob\fR(\fBwint_t\fR \fIc\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBwctob()\fR function determines whether \fIc\fR corresponds to a member +of the extended character set whose character representation is a single byte +when in the initial shift state. +.sp +.LP +The behavior of this function is affected by the \fBLC_CTYPE\fR category of the +current locale. See \fBenviron\fR(5) +.SH RETURN VALUES +.sp +.LP +The \fBwctob()\fR function returns \fBEOF\fR if \fIc\fR does not correspond to +a character with length one in the initial shift state. Otherwise, it returns +the single-byte representation of that character. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBbtowc\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5), \fBenviron\fR(5), +\fBstandards\fR(5) +.SH NOTES +.sp +.LP +The \fBwctob()\fR function can be used safely in multithreaded applications, as +long as \fBsetlocale\fR(3C) is not being called to change the locale. diff --git a/usr/src/man/man3c/wctomb.3c b/usr/src/man/man3c/wctomb.3c new file mode 100644 index 0000000000..aed022ce0d --- /dev/null +++ b/usr/src/man/man3c/wctomb.3c @@ -0,0 +1,79 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH wctomb 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +wctomb \- convert a wide-character code to a character +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBint\fR \fBwctomb\fR(\fBchar *\fR\fIs\fR, \fBwchar_t\fR \fIwchar\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBwctomb()\fR function determines the number of bytes needed to represent +the character corresponding to the wide-character code whose value is +\fIwchar\fR. It stores the character representation (possibly multiple bytes) +in the array object pointed to by \fIs\fR (if \fIs\fR is not a null pointer). +At most \fBMB_CUR_MAX\fR bytes are stored. +.sp +.LP +A call with \fIs\fR as a null pointer causes this function to return \fB0\fR. +The behavior of this function is affected by the \fBLC_CTYPE\fR category of the +current locale. +.SH RETURN VALUES +.sp +.LP +If \fIs\fR is a null pointer, \fBwctomb()\fR returns \fB0\fR value. If \fIs\fR +is not a null pointer, \fBwctomb()\fR returns \fB\(mi1\fR if the value of +\fIwchar\fR does not correspond to a valid character, or returns the number of +bytes that constitute the character corresponding to the value of \fIwchar\fR. +.sp +.LP +In no case will the value returned be greater than the value of the +\fBMB_CUR_MAX\fR macro. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH USAGE +.sp +.LP +The \fBwctomb()\fR function can be used safely in a multithreaded application, +as long as \fBsetlocale\fR(3C) is not being called to change the locale. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +CSIEnabled +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBmblen\fR(3C), \fBmbstowcs\fR(3C), \fBmbtowc\fR(3C), \fBsetlocale\fR(3C), +\fBwcstombs\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/wctype.3c b/usr/src/man/man3c/wctype.3c new file mode 100644 index 0000000000..e80056bbac --- /dev/null +++ b/usr/src/man/man3c/wctype.3c @@ -0,0 +1,86 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH wctype 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +wctype \- define character class +.SH SYNOPSIS +.LP +.nf +#include <wchar.h> + +\fBwctype_t\fR \fBwctype\fR(\fBconst char *\fR\fIcharclass\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBwctype()\fR function is defined for valid character class names as +defined in the current locale. The \fIcharclass\fR is a string identifying a +generic character class for which codeset-specific type information is +required. The following character class names are defined in all locales: +.sp + +.sp +.TS +tab(); +lw(1.83i) lw(1.83i) lw(1.83i) +lw(1.83i) lw(1.83i) lw(1.83i) +. +alnumalphablank +cntrldigitgraph +lowerprintpunct +spaceupperxdigit +.TE + +.sp +.LP +Additional character class names defined in the locale definition file +(category \fBLC_CTYPE\fR) can also be specified. +.sp +.LP +The function returns a value of type \fBwctype_t\fR, which can be used as the +second argument to subsequent calls of \fBiswctype\fR(3C). \fBwctype()\fR +determines values of \fBwctype_t\fR according to the rules of the coded +character set defined by character type information in the program's locale +(category \fBLC_CTYPE\fR). The values returned by \fBwctype()\fR are valid +until a call to \fBsetlocale\fR(3C) that modifies the category \fBLC_CTYPE\fR. +.SH RETURN VALUES +.sp +.LP +The \fBwctype()\fR function returns \fB0\fR if the given character class name +is not valid for the current locale (category \fBLC_CTYPE\fR); otherwise it +returns an object of type \fBwctype_t\fR that can be used in calls to +\fBiswctype()\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +CSIEnabled +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBiswctype\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/wcwidth.3c b/usr/src/man/man3c/wcwidth.3c new file mode 100644 index 0000000000..5fa3084812 --- /dev/null +++ b/usr/src/man/man3c/wcwidth.3c @@ -0,0 +1,65 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH wcwidth 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +wcwidth \- number of column positions of a wide-character code +.SH SYNOPSIS +.LP +.nf +#include <wchar.h> + +\fBint\fR \fBwcwidth\fR(\fBwchar_t\fR \fIwc\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBwcwidth()\fR function determines the number of column positions required +for the wide character \fIwc\fR. The value of \fIwc\fR must be a character +representable as a \fBwchar_t\fR, and must be a wide-character code +corresponding to a valid character in the current locale. +.SH RETURN VALUES +.sp +.LP +The \fBwcwidth()\fR function either returns \fB0\fR (if \fIwc\fR is a null +wide-character code), or returns the number of column positions to be occupied +by the wide-character code \fIwc\fR, or returns \fB\(mi1\fR (if \fIwc\fR does +not correspond to a printing wide-character code). +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +CSIEnabled +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe with exceptions +.TE + +.SH SEE ALSO +.sp +.LP +\fBsetlocale\fR(3C), \fBwcswidth\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3c/wmemchr.3c b/usr/src/man/man3c/wmemchr.3c new file mode 100644 index 0000000000..a6d2c9856e --- /dev/null +++ b/usr/src/man/man3c/wmemchr.3c @@ -0,0 +1,80 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH wmemchr 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +wmemchr \- find a wide-character in memory +.SH SYNOPSIS +.LP +.nf +#include <wchar.h> + +\fBwchar_t *\fR\fBwmemchr\fR(\fBconst wchar_t *\fR\fIws\fR, \fBwchar_t\fR \fIwc\fR, \fBsize_t\fR \fIn\fR); +.fi + +.SS "ISO C++" +.LP +.nf +#include <wchar.h> + +\fBconst wchar_t *\fR\fBwmemchr\fR(\fBconst wchar_t *\fR\fIws\fR, \fBwchar_t\fR \fIwc\fR, \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +#include <cwchar> + +\fBwchar_t *std::\fR\fBwmemchr\fR(\fBwchar_t *\fR\fIws\fR, \fBwchar_t\fR \fIwc\fR, \fBsize_t\fR \fIn\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBwmemchr()\fR function locates the first occurrence of \fIwc\fR in the +initial \fIn\fR wide-characters of the object pointed to be \fIws\fR. This +function is not affected by locale and all \fBwchar_t\fR values are treated +identically. The null wide-character and \fBwchar_t\fR values not +corresponding to valid characters are not treated specially. +.sp +.LP +If \fIn\fR is 0, \fIws\fR must be a valid pointer and the function behaves as +if no valid occurrence of \fIwc\fR is found. +.SH RETURN VALUES +.sp +.LP +The \fBwmemchr()\fR function returns a pointer to the located wide-character, +or a null pointer if the wide-character does not occur in the object. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBwmemcmp\fR(3C), \fBwmemcpy\fR(3C), \fBwmemmove\fR(3C), \fBwmemset\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/wmemcmp.3c b/usr/src/man/man3c/wmemcmp.3c new file mode 100644 index 0000000000..42c9f07dde --- /dev/null +++ b/usr/src/man/man3c/wmemcmp.3c @@ -0,0 +1,67 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH wmemcmp 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +wmemcmp \- compare wide-characters in memory +.SH SYNOPSIS +.LP +.nf +#include <wchar.h> + +\fBint\fR \fBwmemcmp\fR(\fBconst wchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR, \fBsize_t\fR \fIn\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBwmemcmp()\fR function compares the first \fIn\fR wide-characters of the +object pointed to by \fIws1\fR to the first \fIn\fR wide-characters of the +object pointed to by \fIws2\fR. This function is not affected by locale and all +\fBwchar_t\fR values are treated identically. The null wide-character and +\fBwchar_t\fR values not corresponding to valid characters are not treated +specially. +.sp +.LP +If \fIn\fR is zero, \fIws1\fR and \fIws2\fR must be a valid pointers and the +function behaves as if the two objects compare equal. +.SH RETURN VALUES +.sp +.LP +The \fBwmemcmp()\fR function returns an integer greater than, equal to, or less +than 0, accordingly as the object pointed to by \fIws1\fR is greater than, +equal to, or less than the object pointed to by \fIws2\fR. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBwmemchr\fR(3C), \fBwmemcpy\fR(3C), \fBwmemmove\fR(3C), \fBwmemset\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/wmemcpy.3c b/usr/src/man/man3c/wmemcpy.3c new file mode 100644 index 0000000000..4b777bc5cb --- /dev/null +++ b/usr/src/man/man3c/wmemcpy.3c @@ -0,0 +1,64 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH wmemcpy 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +wmemcpy \- copy wide-characters in memory +.SH SYNOPSIS +.LP +.nf +#include <wchar.h> + +\fBwchar_t *\fR\fBwmemcpy\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR, \fBsize_t\fR \fIn\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBwmemcpy()\fR function copies \fIn\fR wide-characters from the object +pointed to by \fIws2\fR to the object pointed to be \fIws1\fR. This function is +not affected by locale and all \fBwchar_t\fR values are treated identically. +The null wide-character and \fBwchar_t\fR values not corresponding to valid +characters are not treated specially. +.sp +.LP +If \fIn\fR is zero, \fIws1\fR and \fIws2\fR must be a valid pointers, and the +function copies zero wide-characters. +.SH RETURN VALUES +.sp +.LP +The \fBwmemcpy()\fR function returns the value of \fIws1\fR. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBwmemchr\fR(3C), \fBwmemcmp\fR(3C), \fBwmemmove\fR(3C), \fBwmemset\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/wmemmove.3c b/usr/src/man/man3c/wmemmove.3c new file mode 100644 index 0000000000..a998397b2a --- /dev/null +++ b/usr/src/man/man3c/wmemmove.3c @@ -0,0 +1,71 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH wmemmove 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +wmemmove \- copy wide-characters in memory with overlapping areas +.SH SYNOPSIS +.LP +.nf +#include <wchar.h> + +\fBwchar_t *\fR\fBwmemmove\fR(\fBwchar_t *\fR\fIws1\fR, \fBconst wchar_t *\fR\fIws2\fR, \fBsize_t\fR \fIn\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBwmemmove()\fR function copies \fIn\fR wide-characters from the object +pointed to by \fIws2\fR to the object pointed to by \fIws1\fR. Copying takes +place as if the \fIn\fR wide-characters from the object pointed to by \fIws2\fR +are first copied into a temporary array of \fIn\fR wide-characters that does +not overlap the objects pointed to by \fIws1\fR or \fIws2\fR, and then the +\fIn\fR wide-characters from the temporary array are copied into the object +pointed to by \fIws1.\fR +.sp +.LP +This function is not affected by locale and all \fBwchar_t\fR values are +treated identically. The null wide-character and \fBwchar_t\fR values not +corresponding to valid characters are not treated specially. +.sp +.LP +If \fIn\fR is 0, \fIws1\fR and \fIws2\fR must be a valid pointers, and the +function copies zero wide-characters. +.SH RETURN VALUES +.sp +.LP +The \fBwmemmove()\fR function returns the value of \fIws1\fR. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBwmemchr\fR(3C), \fBwmemcmp\fR(3C), \fBwmemcpy\fR(3C), \fBwmemset\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/wmemset.3c b/usr/src/man/man3c/wmemset.3c new file mode 100644 index 0000000000..9e3505418c --- /dev/null +++ b/usr/src/man/man3c/wmemset.3c @@ -0,0 +1,64 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH wmemset 3C "14 Aug 2002" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +wmemset \- set wide-characters in memory +.SH SYNOPSIS +.LP +.nf +#include <wchar.h> + +\fBwchar_t *\fR\fBwmemset\fR(\fBwchar_t *\fR\fIws\fR, \fBwchar_t\fR \fIwc\fR, \fBsize_t\fR \fIn\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBwmemset()\fR function copies the value of \fIwc\fR into each of the +first \fIn\fR wide-characters of the object pointed to by \fIws\fR. This +function is not affected by locale and all \fBwchar_t\fR values are treated +identically. The null wide-character and \fBwchar_t\fR values not +corresponding to valid characters are not treated specially. +.sp +.LP +If \fIn\fR is 0, \fIws\fR must be a valid pointer and the function copies zero +wide-characters. +.SH RETURN VALUES +.sp +.LP +The \fBwmemset()\fR functions returns the value of \fIws\fR. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBwmemchr\fR(3C), \fBwmemcmp\fR(3C), \fBwmemcpy\fR(3C), \fBwmemmove\fR(3C), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/wordexp.3c b/usr/src/man/man3c/wordexp.3c new file mode 100644 index 0000000000..8df5772228 --- /dev/null +++ b/usr/src/man/man3c/wordexp.3c @@ -0,0 +1,384 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers 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 in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH wordexp 3C "1 Nov 2003" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +wordexp, wordfree \- perform word expansions +.SH SYNOPSIS +.LP +.nf +#include <wordexp.h> + +\fBint\fR \fBwordexp\fR(\fBconst char *restrict\fR \fIwords\fR, \fBwordexp_t *restrict\fR \fIpwordexp\fR, + \fBint\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBwordfree\fR(\fBwordexp_t *\fR\fIpwordexp\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBwordexp()\fR function performs word expansions, subject to quoting, and +places the list of expanded words into the structure pointed to by +\fIpwordexp\fR. +.sp +.LP +The \fBwordfree()\fR function frees any memory allocated by \fBwordexp()\fR +associated with \fIpwordexp\fR. +.SS "\fIwords\fR Argument" +.sp +.LP +The \fIwords\fR argument is a pointer to a string containing one or more words +to be expanded. The expansions will be the same as would be performed by the +shell if \fIwords\fR were the part of a command line representing the arguments +to a utility. Therefore, \fIwords\fR must not contain an unquoted \fBNEWLINE\fR +or any of the unquoted shell special characters: +.sp +.LP +\fB | & ; < >\fR +.sp +.LP +except in the context of command substitution. It also must not contain +unquoted parentheses or braces, except in the context of command or variable +substitution. If the argument \fIwords\fR contains an unquoted comment +character (number sign) that is the beginning of a token, \fBwordexp()\fR may +treat the comment character as a regular character, or may interpret it as a +comment indicator and ignore the remainder of \fIwords\fR. +.SS "\fIpwordexp\fR Argument" +.sp +.LP +The structure type \fBwordexp_t\fR is defined in the header <\fBwordexp.h\fR> +and includes at least the following members: +.sp +.ne 2 +.mk +.na +\fB\fBsize_t we_wordc\fR\fR +.ad +.RS 19n +.rt +Count of words matched by \fIwords\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBchar **we_wordv\fR\fR +.ad +.RS 19n +.rt +Pointer to list of expanded words. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsize_t we_offs\fR\fR +.ad +.RS 19n +.rt +Slots to reserve at the beginning of \fIpwordexp\(mi>\fR\fBwe_wordv\fR. +.RE + +.sp +.LP +The \fBwordexp()\fR function stores the number of generated words into +\fIpwordexp\(mi>\fR\fBwe_wordc\fR and a pointer to a list of pointers to words +in \fIpwordexp\(mi>\fR\fBwe_wordv.\fR Each individual field created during +field splitting is a separate word in the \fIpwordexp\(mi>\fR\fBwe_wordv\fR +list. The words are in order. The first pointer after the last word pointer +will be a null pointer. +.sp +.LP +It is the caller's responsibility to allocate the storage pointed to by +\fIpwordexp\fR. The \fBwordexp()\fR function allocates other space as needed, +including memory pointed to by \fIpwordexp\(mi>\fR\fBwe_wordv\fR. The +\fBwordfree()\fR function frees any memory associated with \fIpwordexp\fR from +a previous call to \fBwordexp()\fR. +.SS "\fIflags\fR Argument" +.sp +.LP +The \fIflags\fR argument is used to control the behavior of \fBwordexp()\fR. +The value of \fIflags\fR is the bitwise inclusive \fBOR\fR of zero or more of +the following constants, which are defined in \fB<wordexp.h>\fR: +.sp +.ne 2 +.mk +.na +\fB\fBWRDE_APPEND\fR\fR +.ad +.RS 16n +.rt +Append words generated to the ones from a previous call to \fBwordexp()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWRDE_DOOFFS\fR\fR +.ad +.RS 16n +.rt +Make use of \fIpwordexp\(mi>\fR\fBwe_offs.\fR If this flag is set, +\fIpwordexp\(mi>\fR\fBwe_offs\fR is used to specify how many \fINULL\fR +pointers to add to the beginning of \fIpwordexp\(mi>\fR\fBwe_wordv.\fR In other +words, \fIpwordexp\(mi>\fR\fBwe_wordv\fR will point to +\fIpwordexp\(mi>\fR\fBwe_offs\fR \fINULL\fR pointers, followed by +\fIpwordexp\(mi>\fR\fBwe_wordc\fR word pointers, followed by a \fINULL\fR +pointer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWRDE_NOCMD\fR\fR +.ad +.RS 16n +.rt +Fail if command substitution is requested. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWRDE_REUSE\fR\fR +.ad +.RS 16n +.rt +The \fIpwordexp\fR argument was passed to a previous successful call to +\fBwordexp()\fR, and has not been passed to \fBwordfree()\fR. The result will +be the same as if the application had called \fBwordfree()\fR and then called +\fBwordexp()\fR without \fBWRDE_REUSE\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWRDE_SHOWERR\fR\fR +.ad +.RS 16n +.rt +Do not redirect \fBstderr\fR to \fB/dev/null\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWRDE_UNDEF\fR\fR +.ad +.RS 16n +.rt +Report error on an attempt to expand an undefined shell variable. +.RE + +.sp +.LP +The \fBWRDE_APPEND\fR flag can be used to append a new set of words to those +generated by a previous call to \fBwordexp()\fR. The following rules apply when +two or more calls to \fBwordexp()\fR are made with the same value of +\fIpwordexp\fR and without intervening calls to \fBwordfree()\fR: +.RS +4 +.TP +1. +The first such call must not set \fBWRDE_APPEND\fR. All subsequent calls +must set it. +.RE +.RS +4 +.TP +2. +All of the calls must set \fBWRDE_DOOFFS\fR, or all must not set it. +.RE +.RS +4 +.TP +3. +After the second and each subsequent call, \fIpwordexp\(mi>\fR\fBwe_wordv\fR +will point to a list containing the following: +.RS +4 +.TP +a. +zero or more \fINULL\fR pointers, as specified by \fBWRDE_DOOFFS\fR and +\fIpwordexp\(mi>\fR\fBwe_offs.\fR +.RE +.RS +4 +.TP +b. +pointers to the words that were in the \fIpwordexp\(mi>\fR\fBwe_wordv\fR +list before the call, in the same order as before. +.RE +.RS +4 +.TP +c. +pointers to the new words generated by the latest call, in the specified +order. +.RE +.RE +.RS +4 +.TP +4. +The count returned in \fIpwordexp\(mi>\fR\fBwe_wordc\fR will be the total +number of words from all of the calls. +.RE +.RS +4 +.TP +5. +The application can change any of the fields after a call to +\fBwordexp()\fR, but if it does it must reset them to the original value before +a subsequent call, using the same \fIpwordexp\fR value, to \fBwordfree()\fR or +\fBwordexp()\fR with the \fBWRDE_APPEND\fR or \fBWRDE_REUSE\fR flag. +.RE +.sp +.LP +If \fIwords\fR contains an unquoted: +.sp +.LP +\fBNEWLINE\fR \fB| & ; < > ( ) { }\fR +.sp +.LP +in an inappropriate context, \fBwordexp()\fR will fail, and the number of +expanded words will be zero. +.sp +.LP +Unless \fBWRDE_SHOWERR\fR is set in \fIflags\fR, \fBwordexp()\fR will redirect +\fBstderr\fR to \fB/dev/null\fR for any utilities executed as a result of +command substitution while expanding \fIwords\fR. +.sp +.LP +If \fBWRDE_SHOWERR\fR is set, \fBwordexp()\fR may write messages to +\fIstderr\fR if syntax errors are detected while expanding \fIwords\fR. If +\fBWRDE_DOOFFS\fR is set, then \fIpwordexp\(mi>\fR\fB we_offs\fR must have the +same value for each \fBwordexp()\fR call and \fBwordfree()\fR call using a +given \fIpwordexp\fR. +.sp +.LP +The following constants are defined as error return values: +.sp +.ne 2 +.mk +.na +\fB\fBWRDE_BADCHAR\fR\fR +.ad +.RS 16n +.rt +One of the unquoted characters: +.sp +\fBNEWLINE\fR \fB| & ; < > ( ) { }\fR +.sp +appears in \fIwords\fR in an inappropriate context. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWRDE_BADVAL\fR\fR +.ad +.RS 16n +.rt +Reference to undefined shell variable when \fBWRDE_UNDEF\fR is set in +\fIflags\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWRDE_CMDSUB\fR\fR +.ad +.RS 16n +.rt +Command substitution requested when \fBWRDE_NOCMD\fR was set in flags. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWRDE_NOSPACE\fR\fR +.ad +.RS 16n +.rt +Attempt to allocate memory failed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWRDE_SYNTAX\fR\fR +.ad +.RS 16n +.rt +Shell syntax error, such as unbalanced parentheses or unterminated string. +.RE + +.SH RETURN VALUES +.sp +.LP +On successful completion, \fBwordexp()\fR returns \fB0\fR. +.sp +.LP +Otherwise, a non-zero value as described in \fB<wordexp.h>\fR is returned to +indicate an error. If \fBwordexp()\fR returns the value \fBWRDE_NOSPACE\fR, +then \fIpwordexp\(mi>\fR\fBwe_wordc\fR and \fIpwordexp\(mi>\fR\fBwe_wordv\fR +will be updated to reflect any words that were successfully expanded. In other +cases, they will not be modified. +.sp +.LP +The \fBwordfree()\fR function returns no value. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH USAGE +.sp +.LP +This 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 filename (or list of filenames) and then uses +\fBwordexp()\fR to process the input, the user could respond with anything that +would be valid as input to the shell. +.sp +.LP +The \fBWRDE_NOCMD\fR flag is provided for applications that, for security or +other reasons, want to prevent a user from executing shell command. Disallowing +unquoted shell special characters also prevents unwanted side effects such as +executing a command or writing a file. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfnmatch\fR(3C), \fBglob\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3c/wsprintf.3c b/usr/src/man/man3c/wsprintf.3c new file mode 100644 index 0000000000..a6d97b1f9c --- /dev/null +++ b/usr/src/man/man3c/wsprintf.3c @@ -0,0 +1,56 @@ +'\" te +.\" Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH wsprintf 3C "29 Dec 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +wsprintf \- formatted output conversion +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> +#include <widec.h> + +\fBint\fR \fBwsprintf\fR(\fBwchar_t *\fR\fIs\fR, \fBconst char *\fR\fIformat\fR, \fB/*\fR \fIarg\fR */ ... );); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBwsprintf()\fR function outputs a Process Code string ending with a +Process Code (\fBwchar_t\fR) null character. It is the user's responsibility +to allocate enough space for this \fBwchar_t\fR string. +.sp +.LP +This returns the number of Process Code characters (excluding the null +terminator) that have been written. The conversion specifications and behavior +of \fBwsprintf()\fR are the same as the regular \fBsprintf\fR(3C) function +except that the result is a Process Code string for \fBwsprintf(\|),\fR and on +Extended Unix Code (EUC) character string for \fBsprintf()\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBwsprintf()\fR returns the number of characters +printed. Otherwise, a negative value is returned. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBwsscanf\fR(3C), \fBprintf\fR(3C), \fBscanf\fR(3C), \fBsprintf\fR(3C), +\fBattributes\fR(5) diff --git a/usr/src/man/man3c/wsscanf.3c b/usr/src/man/man3c/wsscanf.3c new file mode 100644 index 0000000000..958af48ef4 --- /dev/null +++ b/usr/src/man/man3c/wsscanf.3c @@ -0,0 +1,58 @@ +'\" te +.\" Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH wsscanf 3C "29 Dec 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +wsscanf \- formatted input conversion +.SH SYNOPSIS +.LP +.nf +#include<stdio.h> +#include <widec.h> + +\fBint\fR \fBwsscanf\fR(\fBwchar_t *\fR\fIs\fR, \fBconst char *\fR\fIformat\fR, \fB/*\fR \fIpointer\fR */ ... ); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBwsscanf()\fR function reads Process Code characters from the Process +Code string \fIs\fR, interprets them according to the \fIformat\fR, and stores +the results in its arguments. It expects, as arguments, a control string +\fIformat\fR, and a set of \fIpointer\fR arguments indicating where the +converted input should be stored. The results are undefined if there are +insufficient \fIarg\fRs for the format. If the format is exhausted while +\fIarg\fRs remain, the excess \fIarg\fRs are simply ignored. +.sp +.LP +The conversion specifications and behavior of \fBwsscanf()\fR are the same as +the regular \fBsscanf\fR(3C) function except that the source is a Process Code +string for \fBwsscanf()\fR and on Extended Unix Code (EUC) character string for +\fBsscanf\fR(3C). +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBwsscanf()\fR returns the number of characters +matched. Otherwise, it returns a negative value. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBwsprintf\fR(3C), \fBprintf\fR(3C), \fBscanf\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/wstring.3c b/usr/src/man/man3c/wstring.3c new file mode 100644 index 0000000000..61a7c4508c --- /dev/null +++ b/usr/src/man/man3c/wstring.3c @@ -0,0 +1,81 @@ +'\" te +.\" Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH wstring 3C "29 Dec 1996" "SunOS 5.11" "Standard C Library Functions" +.SH NAME +wstring, wscasecmp, wsncasecmp, wsdup, wscol \- Process Code string operations +.SH SYNOPSIS +.LP +.nf +#include <widec.h> + +\fBint\fR \fBwscasecmp\fR(\fBconst wchar_t *\fR\fIs1\fR, \fBconst wchar_t *\fR\fIs2\fR); +.fi + +.LP +.nf +\fBint\fR \fBwsncasecmp\fR(\fBconst wchar_t *\fR\fIs1\fR, \fBconst wchar_t *\fR\fIs2\fR, \fBint\fR \fIn\fR); +.fi + +.LP +.nf +\fBwchar_t *\fR\fBwsdup\fR(\fBconst wchar_t *\fR\fIs\fR); +.fi + +.LP +.nf +\fBint\fR \fBwscol\fR(\fBconst wchar_t *\fR\fIs\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions operate on Process Code strings terminated by \fBwchar_t\fR +null characters. During appending or copying, these routines do not check for +an overflow condition of the receiving string. In the following, \fIs\fR, +\fIs1\fR, and \fIs2\fR point to Process Code strings terminated by a +\fBwchar_t\fR null. +.SS "wscasecmp(\|), wsncasecmp(\|)" +.sp +.LP +The \fBwscasecmp()\fR function compares its arguments, ignoring case, and +returns an integer greater than, equal to, or less than 0, depending upon +whether \fIs1\fR is lexicographically greater than, equal to, or less than +\fIs2\fR. It makes the same comparison but compares at most \fIn\fR Process +Code characters. The four Extended Unix Code (EUC) codesets are ordered from +lowest to highest as 0, 2, 3, 1 when characters from different codesets are +compared. +.SS "wsdup(\|)" +.sp +.LP +The \fBwsdup()\fR function returns a pointer to a new Process Code string, +which is a duplicate of the string pointed to by \fIs\fR. The space for the new +string is obtained using \fBmalloc\fR(3C). If the new string cannot be created, +a null pointer is returned. +.SS "wscol(\|)" +.sp +.LP +The \fBwscol()\fR function returns the screen display width (in columns) of the +Process Code string \fIs\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBmalloc\fR(3C), \fBstring\fR(3C), \fBwcstring\fR(3C), \fBattributes\fR(5) |