.\"
.\" Copyright (c) 2008
.\"	The DragonFly Project.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\" 3. Neither the name of The DragonFly Project nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific, prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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
.\" COPYRIGHT HOLDERS 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.
.\"
.\" $DragonFly: src/lib/libc/sys/varsym.2,v 1.3 2008/02/24 19:46:47 swildner Exp $
.\"
.Dd February 21, 2008
.Os
.Dt VARSYM 2
.Sh NAME
.Nm varsym_get ,
.Nm varsym_set ,
.Nm varsym_list
.Nd variant symlink variables
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In unistd.h
.In sys/varsym.h
.Ft int
.Fn varsym_get "int mask" "const char *wild" "char *buf" "int bufsize"
.Ft int
.Fn varsym_set "int level" "const char *name" "const char *data"
.Ft int
.Fn varsym_list "int level" "char *buf" "int maxsize" "int *marker"
.Sh DESCRIPTION
The
.Fn varsym_get
system call retrieves the value of the first variable whose left side matches
.Fa wild
and return the value in
.Fa buf .
.Fa Bufsize
specifies the length of the buffer and
.Fa mask
can be used to further restrict the search to variables of certain type.
A value of
.Dv VARSYM_ALL_MASK
will search all variables (see below for other mask definitions).
.Pp
.Fn Varsym_set
sets the variable
.Fa name
of type
.Fa level
to the value pointed to by
.Fa data .
.Pp
The
.Fn varsym_list
system call fills the buffer
.Fa buf
with variable settings for the specified
.Fa level .
A maximum of
.Fa maxsize
bytes of settings are returned and
.Fa marker
is set to the actual number of name/value pairs read, or -1 if no more
remain.
.Fn Varsym_list
must be called repeatedly until
.Fa marker
is -1 if all settings are to be retrieved.
The format of the buffer is
.Dq \e000name\e000value\e000name\e000value... .
.Pp
The following
.Nm varsym
levels (and masks) are defined in
.In sys/varsym.h :
.Bl -tag -width indent
.It Dv VARSYM_PROC Pq Dv VARSYM_PROC_MASK
Per-process variables.
.\".It Dv VARSYM_USER Pq Dv VARSYM_USER_MASK
.\"Per-user variables.
.It Dv VARSYM_SYS Pq Dv VARSYM_SYS_MASK
System wide variables.
.It Dv VARSYM_PRISON
Used internally.
.El
.Sh RETURN VALUES
.Rv -std varsym_get varsym_set
.Pp
The
.Fn varsym_list
function returns the number of bytes read if successful;
otherwise the value -1 is returned and the global variable
.Fa errno
is set to indicate the error.
.Sh ERRORS
The
.Nm varsym
system calls will fail when one of the following occurs:
.Bl -tag -width Er
.It Bq Er EINVAL
An invalid
.Fa level
was specified.
.It Bq Er ENOENT
A variable could not be found.
.It Bq Er EOVERFLOW
Insufficient space for storing variable values was specified.
.El
.Sh SEE ALSO
.Xr varsym 1
.Sh HISTORY
The
.Nm varsym
system calls first appeared in
.Dx 1.0 .
.Sh AUTHORS
.An -nosplit
The
.Nm varsym
system calls were written by
.An Matthew Dillon
and this manual page was written by
.An Sascha Wildner .