logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

putenv.3p (4124B)

    

  1. '\" et
  2. .TH PUTENV "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. putenv
  12. \(em change or add a value to an environment
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <stdlib.h>
  17. .P
  18. int putenv(char *\fIstring\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIputenv\fR()
  23. function shall use the
  24. .IR string
  25. argument to set environment variable values. The
  26. .IR string
  27. argument should point to a string of the form "\c
  28. .IR name =\c
  29. .IR value \c
  30. \&".
  31. The
  32. \fIputenv\fR()
  33. function shall make the value of the environment variable
  34. .IR name
  35. equal to
  36. .IR value
  37. by altering an existing variable or creating a new one. In either
  38. case, the string pointed to by
  39. .IR string
  40. shall become part of the environment, so altering the string shall
  41. change the environment.
  42. .P
  43. The
  44. \fIputenv\fR()
  45. function need not be thread-safe.
  46. .SH "RETURN VALUE"
  47. Upon successful completion,
  48. \fIputenv\fR()
  49. shall return 0; otherwise, it shall return a non-zero value and set
  50. .IR errno
  51. to indicate the error.
  52. .SH ERRORS
  53. The
  54. \fIputenv\fR()
  55. function may fail if:
  56. .TP
  57. .BR ENOMEM
  58. Insufficient memory was available.
  59. .LP
  60. .IR "The following sections are informative."
  61. .SH EXAMPLES
  62. .SS "Changing the Value of an Environment Variable"
  63. .P
  64. The following example changes the value of the
  65. .IR HOME
  66. environment variable to the value
  67. .BR /usr/home .
  68. .sp
  69. .RS 4
  70. .nf
  72. #include <stdlib.h>
  73. \&...
  74. static char *var = "HOME=/usr/home";
  75. int ret;
  76. .P
  77. ret = putenv(var);
  78. .fi
  79. .P
  80. .RE
  81. .SH "APPLICATION USAGE"
  82. The
  83. \fIputenv\fR()
  84. function manipulates the environment pointed to by
  85. .IR environ ,
  86. and can be used in conjunction with
  87. \fIgetenv\fR().
  88. .P
  89. See
  90. \fIexec\fR()
  91. for restrictions on changing the environment in multi-threaded
  92. applications.
  93. .P
  94. This routine may use
  95. \fImalloc\fR()
  96. to enlarge the environment.
  97. .P
  98. A potential error is to call
  99. \fIputenv\fR()
  100. with an automatic variable as the argument, then return from the
  101. calling function while
  102. .IR string
  103. is still part of the environment.
  104. .P
  105. Although the space used by
  106. .IR string
  107. is no longer used once a new string which defines
  108. .IR name
  109. is passed to
  110. \fIputenv\fR(),
  111. if any thread in the application has used
  112. \fIgetenv\fR()
  113. to retrieve a pointer to this variable, it should not be freed by calling
  114. \fIfree\fR().
  115. If the changed environment variable is one known by the system (such as
  116. the locale environment variables) the application should never free the
  117. buffer used by earlier calls to
  118. \fIputenv\fR()
  119. for the same variable.
  120. .P
  121. The
  122. \fIsetenv\fR()
  123. function is preferred over this function. One reason is that
  124. \fIputenv\fR()
  125. is optional and therefore less portable. Another is that using
  126. \fIputenv\fR()
  127. can slow down environment searches, as explained in the RATIONALE
  128. section for
  129. .IR "\fIgetenv\fR\^(\|)".
  130. .SH RATIONALE
  131. Refer to the RATIONALE section in
  132. .IR "\fIsetenv\fR\^(\|)".
  133. .SH "FUTURE DIRECTIONS"
  134. None.
  135. .SH "SEE ALSO"
  136. .IR "\fIexec\fR\^",
  137. .IR "\fIfree\fR\^(\|)",
  138. .IR "\fIgetenv\fR\^(\|)",
  139. .IR "\fImalloc\fR\^(\|)",
  140. .IR "\fIsetenv\fR\^(\|)"
  141. .P
  142. The Base Definitions volume of POSIX.1\(hy2017,
  143. .IR "\fB<stdlib.h>\fP"
  144. .\"
  145. .SH COPYRIGHT
  146. Portions of this text are reprinted and reproduced in electronic form
  147. from IEEE Std 1003.1-2017, Standard for Information Technology
  148. -- Portable Operating System Interface (POSIX), The Open Group Base
  149. Specifications Issue 7, 2018 Edition,
  150. Copyright (C) 2018 by the Institute of
  151. Electrical and Electronics Engineers, Inc and The Open Group.
  152. In the event of any discrepancy between this version and the original IEEE and
  153. The Open Group Standard, the original IEEE and The Open Group Standard
  154. is the referee document. The original Standard can be obtained online at
  155. http://www.opengroup.org/unix/online.html .
  156. .PP
  157. Any typographical or formatting errors that appear
  158. in this page are most likely
  159. to have been introduced during the conversion of the source files to
  160. man page format. To report such errors, see
  161. https://www.kernel.org/doc/man-pages/reporting_bugs.html .