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

setenv.3p (4918B)

    

  1. '\" et
  2. .TH SETENV "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. setenv
  12. \(em add or change environment variable
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <stdlib.h>
  17. .P
  18. int setenv(const char *\fIenvname\fP, const char *\fIenvval\fP, int \fIoverwrite\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIsetenv\fR()
  23. function shall update or add a variable in the environment of the
  24. calling process. The
  25. .IR envname
  26. argument points to a string containing the name of an environment
  27. variable to be added or altered. The environment variable shall be set
  28. to the value to which
  29. .IR envval
  30. points. The function shall fail if
  31. .IR envname
  32. points to a string which contains an
  33. .BR '=' 
  34. character. If the environment variable named by
  35. .IR envname
  36. already exists and the value of
  37. .IR overwrite
  38. is non-zero, the function shall return success and the environment
  39. shall be updated. If the environment variable named by
  40. .IR envname
  41. already exists and the value of
  42. .IR overwrite
  43. is zero, the function shall return success and the environment shall
  44. remain unchanged.
  45. .P
  46. The
  47. \fIsetenv\fR()
  48. function shall update the list of pointers to which
  49. .IR environ
  50. points.
  51. .P
  52. The strings described by
  53. .IR envname
  54. and
  55. .IR envval
  56. are copied by this function.
  57. .P
  58. The
  59. \fIsetenv\fR()
  60. function need not be thread-safe.
  61. .SH "RETURN VALUE"
  62. Upon successful completion, zero shall be returned. Otherwise, \-1
  63. shall be returned,
  64. .IR errno
  65. set to indicate the error, and the environment shall be unchanged.
  66. .SH ERRORS
  67. The
  68. \fIsetenv\fR()
  69. function shall fail if:
  70. .TP
  71. .BR EINVAL
  72. The
  73. .IR envname
  74. argument points to an empty string or points to a string containing an
  75. .BR '=' 
  76. character.
  77. .TP
  78. .BR ENOMEM
  79. Insufficient memory was available to add a variable or its value to the
  80. environment.
  81. .LP
  82. .IR "The following sections are informative."
  83. .SH EXAMPLES
  84. None.
  85. .SH "APPLICATION USAGE"
  86. See
  87. \fIexec\fR()
  88. for restrictions on changing the environment in multi-threaded
  89. applications.
  90. .SH RATIONALE
  91. Unanticipated results may occur if
  92. \fIsetenv\fR()
  93. changes the external variable
  94. .IR environ .
  95. In particular, if the optional
  96. .IR envp
  97. argument to
  98. \fImain\fR()
  99. is present, it is not changed, and thus may point to an obsolete copy
  100. of the environment (as may any other copy of
  101. .IR environ ).
  102. However, other than the aforementioned restriction, the standard
  103. developers intended that the traditional method of walking through
  104. the environment by way of the
  105. .IR environ
  106. pointer must be supported.
  107. .P
  108. It was decided that
  109. \fIsetenv\fR()
  110. should be required by this version because it addresses a piece of
  111. missing functionality, and does not impose a significant burden on the
  112. implementor.
  113. .P
  114. There was considerable debate as to whether the System V
  115. \fIputenv\fR()
  116. function or the BSD
  117. \fIsetenv\fR()
  118. function should be required as a mandatory function. The
  119. \fIsetenv\fR()
  120. function was chosen because it permitted the implementation of the
  121. \fIunsetenv\fR()
  122. function to delete environmental variables, without specifying an
  123. additional interface. The
  124. \fIputenv\fR()
  125. function is available as part of the XSI option.
  126. .P
  127. The standard developers considered requiring that
  128. \fIsetenv\fR()
  129. indicate an error when a call to it would result in exceeding
  130. {ARG_MAX}.
  131. The requirement was rejected since the condition might be temporary,
  132. with the application eventually reducing the environment size. The
  133. ultimate success or failure depends on the size at the time of a call
  134. to
  135. .IR exec ,
  136. which returns an indication of this error condition.
  137. .P
  138. See also the RATIONALE section in
  139. .IR "\fIgetenv\fR\^(\|)".
  140. .SH "FUTURE DIRECTIONS"
  141. None.
  142. .SH "SEE ALSO"
  143. .IR "\fIexec\fR\^",
  144. .IR "\fIgetenv\fR\^(\|)",
  145. .IR "\fIputenv\fR\^(\|)",
  146. .IR "\fIunsetenv\fR\^(\|)"
  147. .P
  148. The Base Definitions volume of POSIX.1\(hy2017,
  149. .IR "\fB<stdlib.h>\fP",
  150. .IR "\fB<sys_types.h>\fP",
  151. .IR "\fB<unistd.h>\fP"
  152. .\"
  153. .SH COPYRIGHT
  154. Portions of this text are reprinted and reproduced in electronic form
  155. from IEEE Std 1003.1-2017, Standard for Information Technology
  156. -- Portable Operating System Interface (POSIX), The Open Group Base
  157. Specifications Issue 7, 2018 Edition,
  158. Copyright (C) 2018 by the Institute of
  159. Electrical and Electronics Engineers, Inc and The Open Group.
  160. In the event of any discrepancy between this version and the original IEEE and
  161. The Open Group Standard, the original IEEE and The Open Group Standard
  162. is the referee document. The original Standard can be obtained online at
  163. http://www.opengroup.org/unix/online.html .
  164. .PP
  165. Any typographical or formatting errors that appear
  166. in this page are most likely
  167. to have been introduced during the conversion of the source files to
  168. man page format. To report such errors, see
  169. https://www.kernel.org/doc/man-pages/reporting_bugs.html .