draft/man3/envz_add.3

   1 .\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de)
   2 .\" Distributed under GPL
   3 .\" based on the description in glibc source and infopages
   4 .\"
   5 .\" Corrections and additions, aeb
   6 .\"
   7 .\" Japanese Version Copyright (c) 2002 Akihiro MOTOKI, all rights reserved.
   8 .\" Translated Mon Feb  2 2003 by Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
   9 .\"
  10 .TH ENVZ_ADD 3 2007-05-18 "" "Linux Programmer's Manual"
  11 .\"O .SH NAME
  12 .SH Ì¾Á°
  13 .\"O envz_add, envz_entry, envz_get, envz_merge,
  14 .\"O envz_remove, envz_strip \- environment string support
  15 envz_add, envz_entry, envz_get, envz_merge,
  16 envz_remove, envz_strip \- ´Ä¶ÊÑ¿ôÊ¸»úÎó¤ÎÁàºî
  17 .\"O .SH SYNOPSIS
  18 .SH ½ñ¼°
  19 .nf
  20 .B "#include <envz.h>"
  21
  22 .BI "error_t envz_add(char **" envz ", size_t *" envz_len ,
  23 .ti 20n
  24 .BI "const char *" name ", const char *" value );
  25
  26 .BI "char *envz_entry(const char *" envz ", size_t *" envz_len \
  27 ", const char *" name );
  28
  29 .BI "char *envz_get(const char *" envz ", size_t *" envz_len \
  30 ", const char *" name );
  31
  32 .BI "error_t envz_merge(char **" envz ", size_t *" envz_len ,
  33 .ti 20n
  34 .BI "const char *" envz2 ", size_t " envz2_len ", int " override );
  35
  36 .BI "void envz_remove(char **" envz ", size_t *" envz_len \
  37 ", const char *" name );
  38
  39 .BI "void envz_strip(char **" envz ", size_t *" envz_len );
  40 .fi
  41 .\"O .SH DESCRIPTION
  42 .SH ÀâÌÀ
  43 .\"O These functions are glibc-specific.
  44 ¤³¤ì¤é¤Î´Ø¿ô glibc ¸ÇÍ¤Ç¤¢¤ë¡£
  45 .LP
  46 .\"O An argz vector is a pointer to a character buffer together with a length,
  47 .\"O see
  48 .\"O .BR argz_add (3).
  49 .\"O An envz vector is a special argz vector, namely one where the strings
  50 .\"O have the form "name=value".
  51 .\"O Everything after the first \(aq=\(aq is considered
  52 .\"O to be the value.
  53 .\"O If there is no \(aq=\(aq, the value is taken to be NULL.
  54 .\"O (While the value in case of a trailing \(aq=\(aq is the empty string "".)
  55 argz vector ¤ÏÄ¹¤µ¾ðÊóÉÕ¤¤ÎÊ¸»ú¥Ð¥Ã¥Õ¥¡¤Ø¤Î¥Ý¥¤¥ó¥¿¤Ç¤¢¤ë¡£
  56 .BR argz_add (3)
  57 ¤ò»²¾È¤Î¤³¤È¡£
  58 envz vector ¤Ï¡¢Ê¸»úÎó¤¬ "name=value (Ì¾Á°=ÃÍ)" ¤Î·Á¼°¤Ë¤Ê¤Ã¤Æ¤¤¤ëÆÃÊÌ¤Ê
  59 argz vector ¤Ç¤¢¤ë¡£
  60 ºÇ½é¤Î \(aq=\(aq °Ê¹ß¤Ï¤¹¤Ù¤ÆÃÍ¤È¤ß¤Ê¤µ¤ì¤ë¡£\(aq=\(aq ¤¬¤Ê¤±¤ì¤Ð¡¢
  61 ÃÍ¤Ï NULL ¤È²ò¼á¤µ¤ì¤ë¡£(Ê¸»úÎó¤Î°ìÈÖºÇ¸å¤ÎÊ¸»ú¤¬ \(aq=\(aq ¤Î¾ì¹ç¡¢ÃÍ¤Ï¶õÊ¸»úÎó
  62 "" ¤È²ò¼á¤µ¤ì¤ë¡£)
  63 .LP
  64 .\"O These functions are for handling envz vectors.
  65 ¤³¤ì¤é¤Î´Ø¿ô¤Ï envz vector ¤òÁàºî¤¹¤ë¤¿¤á¤Î¤â¤Î¤Ç¤¢¤ë¡£
  66 .LP
  67 .\"O .BR envz_add ()
  68 .\"O adds the string
  69 .\"O .RI \&" name = value \&"
  70 .\"O (in case
  71 .\"O .I value
  72 .\"O is non-NULL) or
  73 .\"O .RI \&" name \&"
  74 .\"O (in case
  75 .\"O .I value
  76 .\"O is NULL) to the envz vector
  77 .\"O .RI ( *envz ,\  *envz_len )
  78 .\"O and updates
  79 .\"O .I *envz
  80 .\"O and
  81 .\"O .IR *envz_len .
  82 .\"O If an entry with the same
  83 .\"O .I name
  84 .\"O existed, it is removed.
  85 .BR envz_add ()
  86 ¤Ï¡¢Ê¸»úÎó
  87 .RI \&" name = value \&"
  88 .RI ( value
  89 ¤¬ NULL ¤Ç¤Ê¤¤¾ì¹ç) ¤Þ¤¿¤Ï
  90 .RI \&" name \&"
  91 .RI ( value
  92 ¤¬ NULL ¤Î¾ì¹ç) ¤ò
  93 envz vector
  94 .RI ( *envz ,\  *envz_len )
  95 ¤ËÄÉ²Ã¤·¡¢
  96 .I *envz
  97 ¤È
  98 .I *envz_len
  99 ¤ò¹¹¿·¤¹¤ë¡£
 100 .I name
 101 ¤ÈÆ±¤¸Ì¾Á°¤ò»ý¤Ä¥¨¥ó¥È¥ê¤¬¤¢¤Ã¤¿¾ì¹ç¡¢¸µ¤Î¥¨¥ó¥È¥ê¤Ïºï½ü¤µ¤ì¤ë¡£
 102 .LP
 103 .\"O .BR envz_entry ()
 104 .\"O looks for
 105 .\"O .I name
 106 .\"O in the envz vector
 107 .\"O .RI ( envz ,\  envz_len )
 108 .\"O and returns the entry if found, or NULL if not.
 109 .BR envz_entry ()
 110 ¤Ï¡¢envz vector
 111 .RI ( envz ,\  envz_len )
 112 ¤«¤éÌ¾Á°¤¬
 113 .I name
 114 ¤Î¥¨¥ó¥È¥ê¤ò¸¡º÷¤¹¤ë¡£
 115 ¸«¤Ä¤«¤Ã¤¿¾ì¹ç¤Ï¤½¤Î¥¨¥ó¥È¥ê¤òÊÖ¤·¡¢¸«¤Ä¤«¤é¤Ê¤«¤Ã¤¿¾ì¹ç¤Ï NULL ¤òÊÖ¤¹¡£
 116 .LP
 117 .\"O .BR envz_get ()
 118 .\"O looks for
 119 .\"O .I name
 120 .\"O in the envz vector
 121 .\"O .RI ( envz ,\  envz_len )
 122 .\"O and returns the value if found, or NULL if not.
 123 .\"O (Note that the value can also be NULL, namely when there is
 124 .\"O an entry for
 125 .\"O .I name
 126 .\"O without \(aq=\(aq sign.)
 127 .BR envz_get ()
 128 ¤Ï¡¢envz vector
 129 .RI ( envz ,\  envz_len )
 130 ¤«¤éÌ¾Á°¤¬
 131 .I name
 132 ¤Î¥¨¥ó¥È¥ê¤ò¸¡º÷¤¹¤ë¡£
 133 ¸«¤Ä¤«¤Ã¤¿¾ì¹ç¤Ï¥¨¥ó¥È¥ê¤ÎÃÍ¤òÊÖ¤·¡¢¸«¤Ä¤«¤é¤Ê¤«¤Ã¤¿¾ì¹ç¤Ï NULL ¤òÊÖ¤¹¡£
 134 (ÃÍ¤Ï NULL ¤Î¾ì¹ç¤â¤¢¤ë¤³¤È¤ËÃí°Õ¤¹¤ë¤³¤È¡£Ì¾Á°¤¬
 135 .I name
 136 ¤Î¥¨¥ó¥È¥ê¤Ë \(aq=\(aq Éä¹æ¤¬¤Ê¤¤¾ì¹ç¤¬³ºÅö¤¹¤ë¡£)
 137 .LP
 138 .\"O .BR envz_merge ()
 139 .\"O adds each entry in
 140 .\"O .I envz2
 141 .\"O to
 142 .\"O .IR *envz ,
 143 .\"O as if with
 144 .\"O .BR envz_add ().
 145 .\"O If
 146 .\"O .I override
 147 .\"O is true, then values in
 148 .\"O .I envz2
 149 .\"O will supersede those with the same name in
 150 .\"O .IR *envz ,
 151 .\"O otherwise not.
 152 .BR envz_merge ()
 153 ¤Ï¡¢
 154 .BR envz_add ()
 155 ¤ÈÆ±¤¸¤è¤¦¤Ë
 156 .I envz2
 157 ¤Î³Æ¥¨¥ó¥È¥ê¤ò
 158 .I *envz
 159 ¤ËÄÉ²Ã¤¹¤ë¡£
 160 .I override
 161 ¤¬¿¿¤Î¾ì¹ç¡¢
 162 .I envz2
 163 ¤ÎÃÍ¤Ç
 164 .I *envz
 165 Æâ¤ÎÆ±¤¸Ì¾Á°¤ò¤â¤ÄÃÍ¤Ï¾å½ñ¤¤µ¤ì¤ë¡£
 166 µ¶¤Î¾ì¹ç¤Ï¾å½ñ¤¤µ¤ì¤Ê¤¤¡£
 167 .LP
 168 .\"O .BR envz_remove ()
 169 .\"O removes the entry for
 170 .\"O .I name
 171 .\"O from
 172 .\"O .RI ( *envz ,\  *envz_len )
 173 .\"O if there was one.
 174 .BR envz_remove ()
 175 ¤Ï¡¢Ì¾Á°¤¬
 176 .I name
 177 ¤Î¥¨¥ó¥È¥ê¤¬¤¢¤ì¤Ð
 178 .RI ( *envz ,\  *envz_len )
 179 ¤«¤éºï½ü¤¹¤ë¡£
 180 .LP
 181 .\"O .BR envz_strip ()
 182 .\"O removes all entries with value NULL.
 183 .BR envz_strip ()
 184 ¤Ï¡¢ÃÍ¤¬ NULL ¤Î¥¨¥ó¥È¥ê¤ò¤¹¤Ù¤Æºï½ü¤¹¤ë¡£
 185 .\"O .SH "RETURN VALUE"
 186 .SH ÊÖ¤êÃÍ
 187 .\"O All envz functions that do memory allocation have a return type of
 188 .\"O \fIerror_t\fP, and return 0 for success, and \fBENOMEM\fP
 189 .\"O if an allocation error occurs.
 190 ¥á¥â¥ê³ä¤êÅö¤Æ¤ò¹Ô¤¦ envz ´Ø¿ô·²¤Ï¤¹¤Ù¤Æ \fIerror_t\fP ·¿¤ÎÊÖ¤êÃÍ¤ò»ý¤Ä¡£
 191 À®¸ù¤·¤¿¾ì¹ç¤Ï 0 ¤òÊÖ¤·¡¢³ä¤êÅö¤Æ¥¨¥é¡¼¤¬È¯À¸¤·¤¿¾ì¹ç¤Ï
 192 \fBENOMEM\fP ¤òÊÖ¤¹¡£
 193 .\"O .SH "CONFORMING TO"
 194 .SH ½àµò
 195 .\"O These functions are a GNU extension.
 196 .\"O Handle with care.
 197 ¤³¤ì¤é¤Î´Ø¿ô¤Ï GNU ¤Ë¤è¤ë³ÈÄ¥¤Ç¤¢¤ë¡£Ãí°Õ¤·¤Æ»ÈÍÑ¤¹¤ë¤³¤È¡£
 198 .\"O .SH EXAMPLE
 199 .SH Îã
 200 .nf
 201 #include <stdio.h>
 202 #include <stdlib.h>
 203 #include <envz.h>
 204
 205 int
 206 main(int argc, char *argv[], char *envp[])
 207 {
 208     int i, e_len = 0;
 209     char *str;
 210
 211     for (i = 0; envp[i] != NULL; i++)
 212         e_len += strlen(envp[i]) + 1;
 213
 214     str = envz_entry(*envp, e_len, "HOME");
 215     printf("%s\en", str);
 216     str = envz_get(*envp, e_len, "HOME");
 217     printf("%s\en", str);
 218     exit(EXIT_SUCCESS);
 219 }
 220 .fi
 221 .\"O .SH "SEE ALSO"
 222 .SH ´ØÏ¢¹àÌÜ
 223 .BR argz_add (3)