lib/libc/sys/varsym.2

   1 .\"
   2 .\" Copyright (c) 2008
   3 .\"     The DragonFly Project.  All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\"
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in
  13 .\"    the documentation and/or other materials provided with the
  14 .\"    distribution.
  15 .\" 3. Neither the name of The DragonFly Project nor the names of its
  16 .\"    contributors may be used to endorse or promote products derived
  17 .\"    from this software without specific, prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  22 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  23 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  24 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  25 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  26 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  27 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  28 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  29 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\" $DragonFly: src/lib/libc/sys/varsym.2,v 1.3 2008/02/24 19:46:47 swildner Exp $
  33 .\"
  34 .Dd February 21, 2008
  35 .Os
  36 .Dt VARSYM 2
  37 .Sh NAME
  38 .Nm varsym_get ,
  39 .Nm varsym_set ,
  40 .Nm varsym_list
  41 .Nd variant symlink variables
  42 .Sh LIBRARY
  43 .Lb libc
  44 .Sh SYNOPSIS
  45 .In unistd.h
  46 .In sys/varsym.h
  47 .Ft int
  48 .Fn varsym_get "int mask" "const char *wild" "char *buf" "int bufsize"
  49 .Ft int
  50 .Fn varsym_set "int level" "const char *name" "const char *data"
  51 .Ft int
  52 .Fn varsym_list "int level" "char *buf" "int maxsize" "int *marker"
  53 .Sh DESCRIPTION
  54 The
  55 .Fn varsym_get
  56 system call retrieves the value of the first variable whose left side matches
  57 .Fa wild
  58 and return the value in
  59 .Fa buf .
  60 .Fa Bufsize
  61 specifies the length of the buffer and
  62 .Fa mask
  63 can be used to further restrict the search to variables of certain type.
  64 A value of
  65 .Dv VARSYM_ALL_MASK
  66 will search all variables (see below for other mask definitions).
  67 .Pp
  68 .Fn Varsym_set
  69 sets the variable
  70 .Fa name
  71 of type
  72 .Fa level
  73 to the value pointed to by
  74 .Fa data .
  75 .Pp
  76 The
  77 .Fn varsym_list
  78 system call fills the buffer
  79 .Fa buf
  80 with variable settings for the specified
  81 .Fa level .
  82 A maximum of
  83 .Fa maxsize
  84 bytes of settings are returned and
  85 .Fa marker
  86 is set to the actual number of name/value pairs read, or -1 if no more
  87 remain.
  88 .Fn Varsym_list
  89 must be called repeatedly until
  90 .Fa marker
  91 is -1 if all settings are to be retrieved.
  92 The format of the buffer is
  93 .Dq \e000name\e000value\e000name\e000value... .
  94 .Pp
  95 The following
  96 .Nm varsym
  97 levels (and masks) are defined in
  98 .In sys/varsym.h :
  99 .Bl -tag -width indent
 100 .It Dv VARSYM_PROC Pq Dv VARSYM_PROC_MASK
 101 Per-process variables.
 102 .\".It Dv VARSYM_USER Pq Dv VARSYM_USER_MASK
 103 .\"Per-user variables.
 104 .It Dv VARSYM_SYS Pq Dv VARSYM_SYS_MASK
 105 System wide variables.
 106 .It Dv VARSYM_PRISON
 107 Used internally.
 108 .El
 109 .Sh RETURN VALUES
 110 .Rv -std varsym_get varsym_set
 111 .Pp
 112 The
 113 .Fn varsym_list
 114 function returns the number of bytes read if successful;
 115 otherwise the value -1 is returned and the global variable
 116 .Fa errno
 117 is set to indicate the error.
 118 .Sh ERRORS
 119 The
 120 .Nm varsym
 121 system calls will fail when one of the following occurs:
 122 .Bl -tag -width Er
 123 .It Bq Er EINVAL
 124 An invalid
 125 .Fa level
 126 was specified.
 127 .It Bq Er ENOENT
 128 A variable could not be found.
 129 .It Bq Er EOVERFLOW
 130 Insufficient space for storing variable values was specified.
 131 .El
 132 .Sh SEE ALSO
 133 .Xr varsym 1
 134 .Sh HISTORY
 135 The
 136 .Nm varsym
 137 system calls first appeared in
 138 .Dx 1.0 .
 139 .Sh AUTHORS
 140 .An -nosplit
 141 The
 142 .Nm varsym
 143 system calls were written by
 144 .An Matthew Dillon
 145 and this manual page was written by
 146 .An Sascha Wildner .