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 .Dd February 21, 2008
  33 .Dt VARSYM 2
  34 .Os
  35 .Sh NAME
  36 .Nm varsym_get ,
  37 .Nm varsym_set ,
  38 .Nm varsym_list
  39 .Nd variant symlink variables
  40 .Sh LIBRARY
  41 .Lb libc
  42 .Sh SYNOPSIS
  43 .In unistd.h
  44 .In sys/varsym.h
  45 .Ft int
  46 .Fn varsym_get "int mask" "const char *wild" "char *buf" "int bufsize"
  47 .Ft int
  48 .Fn varsym_set "int level" "const char *name" "const char *data"
  49 .Ft int
  50 .Fn varsym_list "int level" "char *buf" "int maxsize" "int *marker"
  51 .Sh DESCRIPTION
  52 The
  53 .Fn varsym_get
  54 system call retrieves the value of the first variable whose left side matches
  55 .Fa wild
  56 and return the value in
  57 .Fa buf .
  58 .Fa Bufsize
  59 specifies the length of the buffer and
  60 .Fa mask
  61 can be used to further restrict the search to variables of certain type.
  62 A value of
  63 .Dv VARSYM_ALL_MASK
  64 will search all variables (see below for other mask definitions).
  65 .Pp
  66 .Fn Varsym_set
  67 sets the variable
  68 .Fa name
  69 of type
  70 .Fa level
  71 to the value pointed to by
  72 .Fa data .
  73 .Pp
  74 The
  75 .Fn varsym_list
  76 system call fills the buffer
  77 .Fa buf
  78 with variable settings for the specified
  79 .Fa level .
  80 A maximum of
  81 .Fa maxsize
  82 bytes of settings are returned and
  83 .Fa marker
  84 is set to the actual number of name/value pairs read, or -1 if no more
  85 remain.
  86 .Fn Varsym_list
  87 must be called repeatedly until
  88 .Fa marker
  89 is -1 if all settings are to be retrieved.
  90 The format of the buffer is
  91 .Dq \e000name\e000value\e000name\e000value... .
  92 .Pp
  93 The following
  94 .Nm varsym
  95 levels (and masks) are defined in
  96 .In sys/varsym.h :
  97 .Bl -tag -width indent
  98 .It Dv VARSYM_PROC Pq Dv VARSYM_PROC_MASK
  99 Per-process variables.
 100 .\".It Dv VARSYM_USER Pq Dv VARSYM_USER_MASK
 101 .\"Per-user variables.
 102 .It Dv VARSYM_SYS Pq Dv VARSYM_SYS_MASK
 103 System wide variables.
 104 .It Dv VARSYM_PRISON
 105 Used internally.
 106 .El
 107 .Sh RETURN VALUES
 108 .Rv -std varsym_get varsym_set
 109 .Pp
 110 The
 111 .Fn varsym_list
 112 function returns the number of bytes read if successful;
 113 otherwise the value -1 is returned and the global variable
 114 .Fa errno
 115 is set to indicate the error.
 116 .Sh ERRORS
 117 The
 118 .Nm varsym
 119 system calls will fail when one of the following occurs:
 120 .Bl -tag -width Er
 121 .It Bq Er EINVAL
 122 An invalid
 123 .Fa level
 124 was specified.
 125 .It Bq Er ENOENT
 126 A variable could not be found.
 127 .It Bq Er EOVERFLOW
 128 Insufficient space for storing variable values was specified.
 129 .El
 130 .Sh SEE ALSO
 131 .Xr varsym 1
 132 .Sh HISTORY
 133 The
 134 .Nm varsym
 135 system calls first appeared in
 136 .Dx 1.0 .
 137 .Sh AUTHORS
 138 .An -nosplit
 139 The
 140 .Nm varsym
 141 system calls were written by
 142 .An Matthew Dillon
 143 and this manual page was written by
 144 .An Sascha Wildner .