curl/docs/libcurl/curl_getenv.3

.\" **************************************************************************
.\" *                                  _   _ ____  _
.\" *  Project                     ___| | | |  _ \| |
.\" *                             / __| | | | |_) | |
.\" *                            | (__| |_| |  _ <| |___
.\" *                             \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" **************************************************************************
.TH curl_getenv 3 "30 April 2004" "libcurl 7.12" "libcurl Manual"
.SH NAME
curl_getenv - return value for environment name
.SH SYNOPSIS
.B #include <curl/curl.h>
.sp
.BI "char *curl_getenv(const char *" name ");"
.ad
.SH DESCRIPTION
curl_getenv() is a portable wrapper for the getenv() function, meant to
emulate its behavior and provide an identical interface for all operating
systems libcurl builds on (including win32).

You must \fIcurl_free(3)\fP the returned string when you're done with it.
.SH AVAILABILITY
This function will be removed from the public libcurl API in a near future. It
will instead be made "available" by source code access only, and then as
curlx_getenv().
.SH RETURN VALUE
A pointer to a null-terminated string or NULL if it failed to find the
specified name.
.SH NOTE
Under unix operating systems, there isn't any point in returning an allocated
memory, although other systems won't work properly if this isn't done. The
unix implementation thus has to suffer slightly from the drawbacks of other
systems.
.SH "SEE ALSO"
.BR getenv "(3C), "
source header: added to more files 2011-03-12 07:14:32 +08:00			`.\" **************************************************************************`
			`.\" * _ _ ____ _`
			`.\" * Project ___\| \| \| \| _ \\| \|`
			`.\" * / __\| \| \| \| \|_) \| \|`
			`.\" * \| (__\| \|_\| \| _ <\| \|___`
			`.\" * \___\|\___/\|_\| \_\_____\|`
			`.\" *`
language: s/behaviour/behavior/g We currently use both spellings the british "behaviour" and the american "behavior". However "behavior" is more used in the project so I think it's worth dropping the british name. Closes #6395 2020-12-31 17:11:49 +08:00			`.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.`
source header: added to more files 2011-03-12 07:14:32 +08:00			`.\" *`
			`.\" * This software is licensed as described in the file COPYING, which`
			`.\" * you should have received as part of this distribution. The terms`
curl.se: new home Closes #6172 2020-11-04 21:02:01 +08:00			`.\" * are also available at https://curl.se/docs/copyright.html.`
source header: added to more files 2011-03-12 07:14:32 +08:00			`.\" *`
			`.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell`
			`.\" * copies of the Software, and permit persons to whom the Software is`
			`.\" * furnished to do so, under the terms of the COPYING file.`
			`.\" *`
			`.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY`
			`.\" * KIND, either express or implied.`
			`.\" *`
			`.\" **************************************************************************`
these functions are marked to get removed from the public API "soon" 2004-04-30 16:38:08 +08:00			`.TH curl_getenv 3 "30 April 2004" "libcurl 7.12" "libcurl Manual"`
ripped out from ../ and put in its own directory now 2002-03-04 18:09:48 +08:00			`.SH NAME`
			`curl_getenv - return value for environment name`
			`.SH SYNOPSIS`
			`.B #include <curl/curl.h>`
			`.sp`
formatting update to produce better links with the new roffit version 2004-02-27 23:34:06 +08:00			`.BI "char curl_getenv(const char " name ");"`
ripped out from ../ and put in its own directory now 2002-03-04 18:09:48 +08:00			`.ad`
			`.SH DESCRIPTION`
			`curl_getenv() is a portable wrapper for the getenv() function, meant to`
language: s/behaviour/behavior/g We currently use both spellings the british "behaviour" and the american "behavior". However "behavior" is more used in the project so I think it's worth dropping the british name. Closes #6395 2020-12-31 17:11:49 +08:00			`emulate its behavior and provide an identical interface for all operating`
ripped out from ../ and put in its own directory now 2002-03-04 18:09:48 +08:00			`systems libcurl builds on (including win32).`
curl_getenv.3: Fix the memory handling description - Tell the user to call curl_free() to free the pointer returned by curl_getenv(). Prior to this change the user was directed to call free(), but that would not work in cases where the library and application use separate C runtimes and therefore have separate heap memory management. Closes https://github.com/curl/curl/pull/5016 2020-03-02 15:59:40 +08:00
			`You must \fIcurl_free(3)\fP the returned string when you're done with it.`
these functions are marked to get removed from the public API "soon" 2004-04-30 16:38:08 +08:00			`.SH AVAILABILITY`
			`This function will be removed from the public libcurl API in a near future. It`
			`will instead be made "available" by source code access only, and then as`
			`curlx_getenv().`
ripped out from ../ and put in its own directory now 2002-03-04 18:09:48 +08:00			`.SH RETURN VALUE`
terminology: call them null-terminated strings Updated terminology in docs, comments and phrases to refer to C strings as "null-terminated". Done to unify with how most other C oriented docs refer of them and what users in general seem to prefer (based on a single highly unscientific poll on twitter). Reported-by: coinhubs on github Fixes #5598 Closes #5608 2020-06-25 17:38:25 +08:00			`A pointer to a null-terminated string or NULL if it failed to find the`
curl_getenv.3: Fix the memory handling description - Tell the user to call curl_free() to free the pointer returned by curl_getenv(). Prior to this change the user was directed to call free(), but that would not work in cases where the library and application use separate C runtimes and therefore have separate heap memory management. Closes https://github.com/curl/curl/pull/5016 2020-03-02 15:59:40 +08:00			`specified name.`
ripped out from ../ and put in its own directory now 2002-03-04 18:09:48 +08:00			`.SH NOTE`
			`Under unix operating systems, there isn't any point in returning an allocated`
			`memory, although other systems won't work properly if this isn't done. The`
Anthony Bryan's man page cleanup in language and spelling 2008-12-29 05:56:56 +08:00			`unix implementation thus has to suffer slightly from the drawbacks of other`
ripped out from ../ and put in its own directory now 2002-03-04 18:09:48 +08:00			`systems.`
			`.SH "SEE ALSO"`
			`.BR getenv "(3C), "`