env.html (6237B)
1 <html> 2 <head> 3 <meta name="viewport" content="width=device-width, initial-scale=1.0" /> 4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 5 <meta http-equiv="Content-Language" content="en" /> 6 <title>skalibs: the env header</title> 7 <meta name="Description" content="skalibs: the env header" /> 8 <meta name="Keywords" content="skalibs header env environ environment char**" /> 9 <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> 10 </head> 11 <body> 12 13 <p> 14 <a href="index.html">libstddjb</a><br /> 15 <a href="../libskarnet.html">libskarnet</a><br /> 16 <a href="../index.html">skalibs</a><br /> 17 <a href="//skarnet.org/software/">Software</a><br /> 18 <a href="//skarnet.org/">skarnet.org</a> 19 </p> 20 21 <h1> The <tt>skalibs/env.h</tt> header </h1> 22 23 <p> 24 The following functions are declared in the <tt>skalibs/env.h</tt> header, 25 and implemented in the <tt>libskarnet.a</tt> or <tt>libskarnet.so</tt> library. 26 </p> 27 28 <h2> General information </h2> 29 30 <p> 31 <tt>env.h</tt> contains functions that help shape the environment of programs 32 before spawning or executing them, without affecting the environment of the 33 main program. 34 </p> 35 36 <p> 37 Unless otherwise noted, all functions in this header return 1 on success or 38 0 (and set errno) on failure. 39 </p> 40 41 42 <h3> Bytestrings for environment modifications </h3> 43 44 <p> 45 A few functions in <tt>env.h</tt> (and many in <a href="exec.html">exec.h</a>) 46 have arguments named <tt>modifs</tt> and <tt>modiflen</tt>. A <em>modif</em> 47 is a byte-string that encodes a series of instructions to set/override 48 environment variables, or to remove them from the environment. 49 </p> 50 51 <h2> Functions </h2> 52 53 <h3> Fetching variables </h3> 54 55 <p> 56 <code>char const *env_get (char const *s)</code><br> 57 Deprecated alias of 58 <a href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/getenv.html">getenv()</a>. 59 </p> 60 61 <p> 62 <code>char const *ucspi_get (char const *s)</code><br> 63 Prepends the current <a href="//cr.yp.to/proto/ucspi.txt">UCSPI</a> protocol 64 to <em>s</em> and returns that environment variable. For instance, 65 <tt>uscpi_get("REMOTEEUID")</tt> would return the contents of the environment 66 variable <tt>IPCREMOTEEUID</tt> under <tt>s6-ipcserver</tt>. Returns NULL 67 EINVAL if it detects the program is not being run under UCSPI, or NULL ENOENT 68 if the variable that was specifically requested is not found. 69 </p> 70 71 <p> 72 <code>char const *env_get2 (char const *const *envp, char const *s)</code><br> 73 Similar to getenv(), but searches in <em>envp</em> instead of the current 74 process's environment. 75 </p> 76 77 <h3> Serialization </h3> 78 79 <p>Despite the name, these functions also work for <tt>argv</tt>s.</p> 80 81 <p> 82 <code>size_t env_len (char const *const* envp)</code><br> 83 Returns the number of elements in the array of strings <em>envp</em> up to, but 84 not including, the first null pointer. 85 </p> 86 87 <p> 88 <code>int env_string (stralloc *sa, char const *const *envp, size_t envlen)</code><br> 89 Serializes the array of NUL-terminated strings <em>envp</em> with <em>envlen</em> 90 elements into a series of contiguous NUL-terminated strings in the stralloc 91 *<em>sa</em>. 92 </p> 93 94 <p> 95 <code>int env_make (char const **v, size_t n, char const *s, size_t len)</code></br> 96 Deserializes the result of <tt>env_string</tt>: pointers to the first 97 <em>n</em> contiguous NUL-terminated strings contained in the byte-string 98 <em>s</em> of length <em>len</em> are written to <em>v</em>. Returns 1 on 99 success, or 0 EINVAL if <em>s</em> does not end in a NUL. <br> 100 Note that this function does not write NULL to the final value of <em>v</em>. 101 </p> 102 103 <h3> Environment modification </h3> 104 105 <p> 106 <code>int env_addmodif (stralloc *sa, char const *s, char const *t)</code><br> 107 Adds an instruction to the modif contained in *<em>sa</em>. If <em>t</em> is 108 null, add an instruction to remove the variable <em>s</em> from the 109 environment. If <em>t</em> is not null, add an instruction to always set the 110 variable <em>s</em> to <em>t</em>. 111 </p> 112 113 <p> 114 <code>size_t env_merge (char const **v, size_t vmax, char const *const *envp, size_t envlen, char const *modifs, size_t modiflen)</code><br> 115 Takes the environment with <em>envlen</em> variables contained in <em>envp</em>, 116 applies the modifications encoded in the modif <em>modifs</em> of length 117 <em>modiflen</em>, and stores the result in <em>v</em> with a terminating NULL. 118 It only tries to store up to <em>vmax-1</em> variables, which makes <em>vmax</em> 119 entries after the terminating NULL. Returns the number of elements now in 120 <em>v</em>, or 0 if the resulting <em>v</em> would be larger than <em>vmax</em>. 121 </p> 122 123 <p> 124 <code>size_t env_merg (char const **v, size_t vmax, char const *const *envp, char const *modifs, size_t modiflen)</code><br> 125 Similar to the above function, but <em>envp</em> is assumed to be NULL 126 terminated. 127 </p> 128 129 <h3> Envdir functions </h3> 130 131 <p> 132 <code>int envdir_internal (char const *path, stralloc *modifs, unsigned int options, char nullis)</code><br> 133 Essentially <a href="/software/s6/s6-envdir.html">s6-envdir</a> as library. 134 <em>options</em> is a bitwise OR of <tt>SKALIBS_ENVDIR_VERBATIM</tt>, 135 <tt>SKALIBS_ENVDIR_NOCHOMP</tt> and <tt>SKALIBS_ENVDIR_NOCLAMP</tt>, which 136 correspond to s6-envdir's <tt>-f</tt>, <tt>-n</tt> and <tt>-L</tt> options, 137 respectively.<br /> 138 It adds instructions to <em>modifs</em> that replicate the effect 139 <tt>s6-envdir [-f] [-n] [-L] -c <em>nullis</em> <em>path</em></tt> would have on 140 the program it executes. 141 </p> 142 143 <p> 144 <code>int envdir_chomp (char const *path, stralloc *modifs)</code><br> 145 A macro that calls 146 <tt>envdir_internal(path, modifs, SKALIBS_ENVDIR_NOCHOMP, '\n')</tt>. 147 </p> 148 149 <p> 150 <code>int envdir (char const *path, stralloc *modifs)</code><br /> 151 <code>int envdir_verbatim (char const *path, stralloc *modifs)</code><br> 152 <code>int envdir_verbatim_chomp (char const *path, stralloc *modifs)</code><br> 153 Macros that call <tt>envdir_internal(path, modifs, options, '\n')</tt>, with 154 <em>options</em> set to self-explanatory values. 155 </p> 156 157 <p> 158 <code>int env_dump (char const *dir, mode_t mode, char const *const *envp)</code><br> 159 Turns the contents of the NULL terminated environment in <em>envp</em> into an 160 envdir located at <em>dir</em>. Files are created with mode <em>mode</em>. 161 </p> 162 163 </body> 164 </html>