Index: head/share/man/man9/Makefile =================================================================== --- head/share/man/man9/Makefile (revision 69991) +++ head/share/man/man9/Makefile (revision 69992) @@ -1,183 +1,195 @@ # $FreeBSD$ MAN9= CONDSPLASSERT.9 DELAY.9 KASSERT.9 MD5.9 SPLASSERT.9 \ VFS.9 VFS_FHTOVP.9 VFS_INIT.9 VFS_MOUNT.9 VFS_QUOTACTL.9 \ VFS_ROOT.9 VFS_START.9 VFS_STATFS.9 VFS_SYNC.9 VFS_UNMOUNT.9 \ VFS_VGET.9 VFS_VPTOFH.9 VFS_CHECKEXP.9 \ VOP_ACCESS.9 VOP_ADVLOCK.9 VOP_ATTRIB.9 \ VOP_BWRITE.9 VOP_CREATE.9 VOP_FSYNC.9 VOP_LEASE.9 \ VOP_GETPAGES.9 VOP_INACTIVE.9 VOP_IOCTL.9 VOP_LINK.9 \ VOP_LOCK.9 VOP_LOOKUP.9 VOP_MMAP.9 VOP_OPENCLOSE.9 \ VOP_PATHCONF.9 VOP_PRINT.9 VOP_RDWR.9 VOP_READDIR.9 \ VOP_READLINK.9 VOP_REALLOCBLKS.9 VOP_REMOVE.9 VOP_RENAME.9 \ VOP_STRATEGY.9 \ accf_data.9 accf_http.9 at_exit.9 at_fork.9 atomic.9 \ bios.9 boot.9 buf.9 \ cd.9 copy.9 \ devfs_add_devswf.9 devfs_link.9 devfs_remove_dev.9 devstat.9 \ devtoname.9 \ fetch.9 \ get_cyclecounter.9 \ ifnet.9 inittodr.9 intro.9 \ kernacc.9 kthread.9 \ malloc.9 make_dev.9 mbuf.9 microseq.9 microtime.9 microuptime.9 \ mi_switch.9 mutex.9 \ namei.9 \ panic.9 pfil.9 physio.9 posix4.9 psignal.9 \ random.9 resettodr.9 rtalloc.9 rtentry.9 \ sleep.9 spl.9 store.9 style.9 suser.9 swi.9 \ time.9 timeout.9 tvtohz.9 \ uio.9 \ vget.9 vnode.9 vput.9 vref.9 vrele.9 vslock.9 MAN9+= device.9 device_add_child.9 device_delete_child.9 device_enable.9 \ device_find_child.9 device_get_children.9 \ device_get_devclass.9 device_get_driver.9 \ device_get_ivars.9 device_get_softc.9 device_get_state.9 \ device_get_unit.9 device_probe_and_attach.9 device_quiet.9 \ device_set_desc.9 device_set_flags.9 driver.9 \ devclass.9 devclass_add_driver.9 devclass_find.9 \ devclass_get_device.9 devclass_get_devices.9 devclass_get_maxunit.9 \ devclass_get_name.9 devclass_get_softc.9 \ DEVICE_ATTACH.9 DEVICE_DETACH.9 DEVICE_PROBE.9 DEVICE_SHUTDOWN.9 \ DRIVER_MODULE.9 BUS_PRINT_CHILD.9 BUS_SETUP_INTR.9 \ BUS_READ_IVAR.9 \ bus_generic_attach.9 bus_generic_detach.9 bus_generic_map_intr.9 \ bus_generic_print_child.9 bus_generic_read_ivar.9 \ bus_generic_shutdown.9 \ bus_alloc_resource.9 bus_release_resource.9 \ VOP_ACLCHECK.9 VOP_GETACL.9 VOP_GETEXTATTR.9 VOP_SETACL.9 \ VOP_SETEXTATTR.9 acl.9 extattr.9 kobj.9 taskqueue.9 accept_filter.9 \ + sbuf.9 \ sysctl_add_oid.9 sysctl_ctx_init.9 MLINKS+=MD5.9 MD5Init.9 MD5.9 MD5Transform.9 MLINKS+=VOP_ATTRIB.9 VOP_GETATTR.9 MLINKS+=VOP_ATTRIB.9 VOP_SETATTR.9 MLINKS+=VOP_CREATE.9 VOP_MKDIR.9 MLINKS+=VOP_CREATE.9 VOP_MKNOD.9 MLINKS+=VOP_CREATE.9 VOP_SYMLINK.9 MLINKS+=VOP_GETPAGES.9 VOP_PUTPAGES.9 MLINKS+=VOP_INACTIVE.9 VOP_RECLAIM.9 MLINKS+=VOP_LOCK.9 VOP_ISLOCKED.9 MLINKS+=VOP_LOCK.9 VOP_UNLOCK.9 MLINKS+=VOP_LOCK.9 vn_lock.9 MLINKS+=VOP_OPENCLOSE.9 VOP_CLOSE.9 MLINKS+=VOP_OPENCLOSE.9 VOP_OPEN.9 MLINKS+=VOP_RDWR.9 VOP_READ.9 MLINKS+=VOP_RDWR.9 VOP_WRITE.9 MLINKS+=VOP_REMOVE.9 VOP_RMDIR.9 MLINKS+=atomic.9 atomic_add.9 MLINKS+=atomic.9 atomic_clear.9 MLINKS+=atomic.9 atomic_cmpset.9 MLINKS+=atomic.9 atomic_load.9 MLINKS+=atomic.9 atomic_readandclear.9 MLINKS+=atomic.9 atomic_set.9 MLINKS+=atomic.9 atomic_subtract.9 MLINKS+=atomic.9 atomic_store.9 MLINKS+=at_exit.9 rm_at_exit.9 MLINKS+=at_fork.9 rm_at_fork.9 MLINKS+=copy.9 copyin.9 copy.9 copyinstr.9 copy.9 copyout.9 copy.9 copystr.9 MLINKS+=devfs_link.9 devfs_makelink.9 MLINKS+=devstat.9 devicestat.9 devstat.9 devstat_add_entry.9 MLINKS+=devstat.9 devstat_remove_entry.9 devstat.9 devstat_start_transaction.9 MLINKS+=devstat.9 devstat_end_transaction.9 MLINKS+=fetch.9 fubyte.9 fetch.9 fuswintr.9 fetch.9 fusword.9 fetch.9 fuword.9 MLINKS+=ifnet.9 if_data.9 ifnet.9 ifaddr.9 ifnet.9 ifqueue.9 MLINKS+=kernacc.9 useracc.9 MLINKS+=kthread.9 kproc_start.9 kthread.9 kproc_suspend_loop.9 MLINKS+=kthread.9 kthread_create.9 kthread.9 kthread_exit.9 MLINKS+=kthread.9 resume_kproc.9 kthread.9 shutdown_kproc.9 MLINKS+=kthread.9 suspend_kproc.9 MLINKS+=make_dev.9 destroy_dev.9 MLINKS+=malloc.9 FREE.9 malloc.9 MALLOC.9 malloc.9 free.9 MLINKS+=mi_switch.9 cpu_switch.9 MLINKS+=namei.9 NDINIT.9 MLINKS+=namei.9 NDFREE.9 MLINKS+=pfil.9 pfil_hook_get.9 pfil.9 pfil_add_hook.9 pfil.9 pfil_remove_hook.9 MLINKS+=posix4.9 p1003_1b.9 MLINKS+=psignal.9 gsignal.9 psignal.9 pgsignal.9 MLINKS+=random.9 srandom.9 random.9 arc4random.9 random.9 read_random.9 MLINKS+=rtalloc.9 rtalloc1.9 rtalloc.9 rtalloc_ign.9 MLINKS+=sleep.9 tsleep.9 sleep.9 wakeup.9 sleep.9 wakeup_one.9 MLINKS+=sleep.9 asleep.9 sleep.9 await.9 sleep.9 msleep.9 MLINKS+=buf.9 bp.9 MLINKS+=spl.9 spl0.9 MLINKS+=spl.9 splbio.9 spl.9 splclock.9 spl.9 splhigh.9 spl.9 splimp.9 MLINKS+=spl.9 splnet.9 spl.9 splsoftclock.9 spl.9 splsofttty.9 MLINKS+=spl.9 splstatclock.9 spl.9 spltty.9 spl.9 splvm.9 spl.9 splx.9 MLINKS+=store.9 subyte.9 store.9 suswintr.9 store.9 susword.9 store.9 suword.9 MLINKS+=swi.9 sched_swi.9 swi.9 sinthand_add.9 MLINKS+=time.9 boottime.9 time.9 mono_time.9 time.9 runtime.9 MLINKS+=timeout.9 untimeout.9 MLINKS+=timeout.9 callout_handle_init.9 timeout.9 callout_init.9 MLINKS+=timeout.9 callout_stop.9 timeout.9 callout_reset.9 MLINKS+=uio.9 uiomove.9 MLINKS+=vref.9 VREF.9 MLINKS+=vslock.9 vsunlock.9 MLINKS+=device_add_child.9 device_add_child_ordered.9 MLINKS+=device_enable.9 device_disable.9 MLINKS+=device_enable.9 device_is_enabled.9 MLINKS+=device_get_state.9 device_busy.9 MLINKS+=device_get_state.9 device_unbusy.9 MLINKS+=device_get_state.9 device_is_alive.9 MLINKS+=device_quiet.9 device_verbose.9 MLINKS+=device_quiet.9 device_is_quiet.9 MLINKS+=device_set_desc.9 device_get_desc.9 MLINKS+=device_set_desc.9 device_set_desc_copy.9 MLINKS+=device_set_flags.9 device_get_flags.9 MLINKS+=devclass_add_driver.9 devclass_delete_driver.9 MLINKS+=devclass_add_driver.9 devclass_find_driver.9 MLINKS+=BUS_READ_IVAR.9 BUS_WRITE_IVAR.9 MLINKS+=bus_generic_read_ivar.9 bus_generic_write_ivar.9 MLINKS+=microtime.9 getmicrotime.9 microtime.9 nanotime.9 MLINKS+=microtime.9 getnanotime.9 MLINKS+=microuptime.9 getmicrouptime.9 microuptime.9 nanouptime.9 MLINKS+=microuptime.9 getnanouptime.9 MLINKS+=mutex.9 MUTEX_DECLARE.9 MLINKS+=mutex.9 mtx_init.9 MLINKS+=mutex.9 mtx_enter.9 MLINKS+=mutex.9 mtx_try_enter.9 MLINKS+=mutex.9 mtx_exit.9 MLINKS+=mutex.9 mtx_destroy.9 MLINKS+=mutex.9 mtx_owned.9 MLINKS+=mutex.9 mtx_assert.9 MLINKS+=kobj.9 kobj_class_compile.9 MLINKS+=kobj.9 kobj_class_compile_static.9 MLINKS+=kobj.9 kobj_class_free.9 MLINKS+=kobj.9 kobj_create.9 MLINKS+=kobj.9 kobj_init.9 MLINKS+=kobj.9 kobj_delete.9 MLINKS+=kobj.9 DEFINE_CLASS.9 MLINKS+=taskqueue.9 taskqueue_create.9 MLINKS+=taskqueue.9 taskqueue_free.9 MLINKS+=taskqueue.9 taskqueue_find.9 MLINKS+=taskqueue.9 taskqueue_enqueue.9 MLINKS+=taskqueue.9 taskqueue_run.9 MLINKS+=taskqueue.9 TASK_INIT.9 MLINKS+=taskqueue.9 TASKQUEUE_DECLARE.9 MLINKS+=taskqueue.9 TASKQUEUE_DEFINE.9 MLINKS+=suser.9 suser_xxx.9 MLINKS+=sysctl_add_oid.9 sysctl_remove_oid.9 MLINKS+=sysctl_add_oid.9 SYSCTL_ADD_OID.9 MLINKS+=sysctl_add_oid.9 SYSCTL_ADD_NODE.9 MLINKS+=sysctl_add_oid.9 SYSCTL_ADD_STRING.9 MLINKS+=sysctl_add_oid.9 SYSCTL_ADD_INT.9 MLINKS+=sysctl_add_oid.9 SYSCTL_ADD_UINT.9 MLINKS+=sysctl_add_oid.9 SYSCTL_ADD_LONG.9 MLINKS+=sysctl_add_oid.9 SYSCTL_ADD_ULONG.9 MLINKS+=sysctl_add_oid.9 SYSCTL_ADD_OPAQUE.9 MLINKS+=sysctl_add_oid.9 SYSCTL_ADD_STRUCT.9 MLINKS+=sysctl_add_oid.9 SYSCTL_ADD_PROC.9 MLINKS+=sysctl_ctx_init.9 sysctl_ctx_free.9 MLINKS+=sysctl_ctx_init.9 sysctl_ctx_entry_add.9 MLINKS+=sysctl_ctx_init.9 sysctl_ctx_entry_del.9 MLINKS+=sysctl_ctx_init.9 sysctl_ctx_entry_find.9 + +MLINKS+=sbuf.9 sbuf_new.9 +MLINKS+=sbuf.9 sbuf_setpos.9 +MLINKS+=sbuf.9 sbuf_cat.9 +MLINKS+=sbuf.9 sbuf_cpy.9 +MLINKS+=sbuf.9 sbuf_printf.9 +MLINKS+=sbuf.9 sbuf_putc.9 +MLINKS+=sbuf.9 sbuf_finish.9 +MLINKS+=sbuf.9 sbuf_data.9 +MLINKS+=sbuf.9 sbuf_len.9 +MLINKS+=sbuf.9 sbuf_delete.9 .include Index: head/share/man/man9/sbuf.9 =================================================================== --- head/share/man/man9/sbuf.9 (nonexistent) +++ head/share/man/man9/sbuf.9 (revision 69992) @@ -0,0 +1,233 @@ +.\"- +.\" Copyright (c) 2000 Poul Henning Kamp and Dag-Erling Coïdan Smørgrav +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd December 10, 2000 +.Dt sbuf 9 +.Os FreeBSD +.Sh NAME +.Nm sbuf_new , +.Nm sbuf_setpos , +.Nm sbuf_cat , +.Nm sbuf_cpy , +.Nm sbuf_printf , +.Nm sbuf_putc , +.Nm sbuf_finish , +.Nm sbuf_data , +.Nm sbuf_len , +.Nm sbuf_delete +.Nd safe string formatting +.Sh SYNOPSIS +.Fd #include +.Ft int +.Fn sbuf_new "struct sbuf *s" "char *buf" "size_t length" "int flags" +.Ft int +.Fn sbuf_setpos "struct sbuf *s" "size_t pos" +.Ft int +.Fn sbuf_cat "struct sbuf *s" "char *str" +.Ft int +.Fn sbuf_cpy "struct sbuf *s" "char *str" +.Ft int +.Fn sbuf_printf "struct sbuf *s" "char *fmt" "..." +.Ft int +.Fn sbuf_putc "struct sbuf *s" "int c" +.Ft int +.Fn sbuf_finish "struct sbuf *s" +.Ft char * +.Fn sbuf_data "struct sbuf *s" +.Ft size_t +.Fn sbuf_len "struct sbuf *s" +.Ft void +.Fn sbuf_delete "struct sbuf *s" +.Sh DESCRIPTION +The +.Nm sbuf +family of functions allow one to safely allocate, construct and +release bounded null-terminated strings in kernel space. +Instead of arrays of characters, these functions operate on structures +called +.Fa sbufs , +defined in +.Aq Pa sys/sbuf.h . +.Pp +The +.Fn sbuf_new +function initializes the +.Fa sbuf +pointed to by its first argument. +The +.Fa buf +argument is a pointer to a buffer in which to store the actual string; +if it is +.Dv NULL , +.Fn sbuf_new +will allocate one using +.Xr malloc 9 . +The +.Fa length +is the intended size of the storage buffer. +The fourth argument, +.Fa flags , +is currently unused and should always be set to zero. +.Pp +Note that if +.Fa buf +is not +.Dv NULL , +it must point to an array of at least +.Fa length +characters. +.Pp +The +.Fn sbuf_setpos +function sets the +.Fa sbuf Ns 's +current position to +.Fa pos , +which is a value between zero and one less than the size of the +storage buffer. +.Pp +The +.Fn sbuf_cat +function appends the string +.Fa str +to the +.Fa sbuf +at the current position. +.Pp +The +.Fn sbuf_cpy +function replaces the contents of the +.Fa sbuf +with those of the string +.Fa str . +This is equivalent to calling +.Fn sbuf_cat +with a fresh +.Fa sbuf +or one which position has been reset to zero with +.Fn sbuf_setpos . +.Pp +The +.Fn sbuf_printf +function formats its arguments according to the format string pointed +to by +.Fa fmt +and appends the resulting string to the +.Fa sbuf +at the current position. +.Pp +The +.Fn sbuf_putc +function appends the character +.Fa c +to the +.Fa sbuf +at the current position. +.Pp +The +.Fn sbuf_finish +function null-terminates the +.Fa sbuf +and marks it as finished, which means that it may no longer be +modified using +.Fn sbuf_setpos , +.Fn sbuf_cat , +.Fn sbuf_cpu , +.Fn sbuf_printf +or +.Fn sbuf_putc . +.Pp +The +.Fn sbuf_data +and +.Fn sbuf_len +functions return the actual string and its length, respectively, and +only work on a finished and non-overflowed +.Fa sbuf . +.Pp +Finally, the +.Fn sbuf_delete +function clears the +.Fa sbuf +and frees its storage buffer if it was allocated by +.Fn sbuf_new . +.Sh NOTES +If an operation caused an +.Fa sbuf +to overflow, most subsequent operations (including +.Fn sbuf_finish ) +on it will fail until the +.Fa sbuf Ns 's +position is reset to a value between 0 and one less than the size of +its storage buffer using +.Fn sbuf_setpos , +or it is reinitialized to a sufficiently short string using +.Fn sbuf_cpy . +.Sh RETURN VALUES +.Fn sbuf_new +returns \-1 if it failed to allocate a storage buffer, and zero +otherwise. +.Pp +.Fn sbuf_setpos +returns \-1 if +.Fa pos +was invalid, and zero otherwise. +.Pp +.Fn sbuf_cat , +.Fn sbuf_cpy , +.Fn sbuf_printf , +.Fn sbuf_putc , +and +.Fn sbuf_finish +all return \-1 if the buffer overflowed, and zero otherwise. +.Pp +.Fn sbuf_data +and +.Fn sbuf_len +return +.Dv NULL +and 0, respectively, if the buffer overflowed. +.Sh SEE ALSO +.Xr printf 3 , +.Xr strcat 3 , +.Xr strcpy 3 +.Sh HISTORY +The +.Nm sbuf +family of functions first appeared in +.Fx 4.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm sbuf +family of functions was designed by +.An Poul-Henning Kamp Aq phk@FreeBSD.org +and implemented by +.An Dag-Erling Co\(:idan Sm\(/orgrav Aq des@FreeBSD.org . +.Pp +This manual page was written by +.An Dag-Erling Co\(:idan Sm\(/orgrav . Property changes on: head/share/man/man9/sbuf.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property