1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
|
Appendix G. Environment Variables and .RC files QuickStart {#nc_env_quickstart}
==============================
[TOC]
The netCDF-c library provides several parameterization mechanisms to
control its behavior at run-time. The term _run-time_ means that the
library's behavior can be changed every time the library is initialized
The most commonly used parameterization mechanisms are:
1. Environment Variables -- accessed by the getenv() function.
2. .RC files -- accessed from the file system.
## Environment Variables {#nc_env_vars}
The following table describes (most of) the environment variables
used by the netcdf-c library. There are some not listed that are only
used for specialized debugging.
<table>
<tr><th>Name<th>Description
<tr><td>ALLUSERSPROFILE<td>This is more-or-less the Windows equivalent of "HOME"
<tr><td>AWS_ACCESS_KEY_ID<td>Used by the aws access libraries; overrides ${HOME}/.aws/config entries.
<tr><td>AWS_CONFIG_FILE<td>Used by the aws access libraries; specifies absolute path to the config file.
<tr><td>AWS_DEFAULT_REGION<td>Used by the aws access libraries; specifies default S3 region.
<tr><td>AWS_PROFILE<td>Used by the aws access libraries; specifies default AWS profile.
<tr><td>AWS_REGION<td>Used by the aws access libraries; specifies specific region to use.
<tr><td>AWS_SECRET_ACCESS_KEY<td>Used by the aws access libraries; overrides ${HOME}/.aws/config entries.
<tr><td>CURLOPT_VERBOSE<td>Causes libcurl to produce verbose output.
<tr><td>HOME<td>The user's home directory.
<tr><td>MSYS2_PREFIX<td>If platform is MSYS2, then specify the root prefix.
<tr><td>NC_DEFAULT_CREATE_PERMS<td>For NCZarr, specify the default creation permissions for a file.
<tr><td>NC_DEFAULT_DIR_PERMS<td>For NCZarr, specify the default creation permissions for a directory.
<tr><td>NCLOGGING<td>Specify the log level: one of "OFF","ERR","WARN","NOTE","DEBUG".
<tr><td>NCPATHDEBUG<td>Causes path manager to output debugging information.
<tr><td>NCRCENV_HOME<td>Overrides ${HOME} as the location of the .rc file.
<tr><td>NCRCENV_IGNORE<td>Causes any .rc files to be ignored.
<tr><td>NCRCENV_RC<td>The absolute path to use for the .rc file.
<tr><td>NCTRACING<td>Specify the level of tracing detail.
<tr><td>NCZARRFORMAT<td>Force use of a specific Zarr format version: 2 or 3.
<tr><td>NETCDF_LOG_LEVEL<td>Specify the log level for HDF5 logging (separate from e.g. NCLOGGING).
<tr><td>TEMP<td>For Windows platform, specifies the location of a directory to store temporary files.
<tr><td>USERPROFILE<td>For Windows platform, overrides ${HOME}.
</table>
## Resource Control (.rc) Files {#nc_env_rc}
In addition to using environment variables,
the netcdf-c library supports run-time configuration
of the library using the so-called ".rc" file mechanism.
This means that as part of its initialization, the netcdf-c
library will search for and process a set of files where
these files contain entries specifying (key,value) pairs.
These pairs are compiled into a single internal database
that can be queried by other parts of the netcdf-c library.
### Locating The _.rc_ Files
For historical reasons, multiple .rc files are allowed.
### Search Order
The netcdf-c library searches for, and loads from, the following files,
in this order:
1. $HOME/.ncrc
2. $HOME/.dodsrc
3. $CWD/.ncrc
4. $CWD/.dodsrc
*$HOME* is the user's home directory and *$CWD* is the current working directory.
Entries in later files override any of the earlier files
It is strongly suggested that you pick a uniform location and a uniform name
and use them always. Otherwise you may observe unexpected results
when the netcdf-c library loads an rc file you did not expect.
### RC File Format
The rc file format is a series of lines of the general form:
````
[<URL>]<key>=<value>
````
where the bracket-enclosed URL is optional. Note that the brackets
are part of the line.
### URL Constrained RC File Entries
Each line of the rc file can begin with a URL enclosed in
square brackets. The parts of the URL that are used for choosing
an entry are the host, the port, and the URL path.
Note that the host+port is the only part used when searching for
libcurl related entries. This is because libcurl's authorization grain is not
any finer than host+port level.
The URL path may be used for non-curl related entries.
Also note that the protocol is ignored.
Here are some examples.
````
[https://remotetest.unidata.ucar.edu/thredds]HTTP.VERBOSE=1
or
[https://fake.ucar.edu:9090]HTTP.VERBOSE=0
````
For selection purposes, the host+port+path is used when the path argument
for _nc_open()_ or _nc_create()_ takes the form of a URL.
If the url request from, say, the _netcdf_open_ method
has a host,port, and path matching one of the prefixes in the rc file, then
the corresponding entry will be used, otherwise ignored.
This means that an entry with a matching host+port+path will take
precedence over an entry without a host+port+path.
For example, passing this URL to _nc_open_
````
http://remotetest.unidata.ucar.edu/thredds/dodsC/testdata/testData.nc
````
will have HTTP.VERBOSE set to 1 because its host and path match the example above.
Similarly, using this path
````
http://fake.ucar.edu:9090/dts/test.01
````
will have HTTP.VERBOSE set to 0 because its host+port matches the example above.
### Programmatic Access to .rc File
It is possible for client programs to query and modify the internal .rc database
through the following API.
* ````char* nc_rc_get(const char* key);````
Get the value corresponding to key or return NULL if not defined. The caller must free the resulting value.
* ````int nc_rc_set(const char* key, const char* value);````
Set/overwrite the value corresponding to the specified key.
Note that this API does not (currently) support URL prefixed keys, so the client will need to take this into account.
### Defined .rc file keys
There a a number of keys used by the netcdf-c library. Most of them
are authorization-related. The file "auth.md" describes these keys.
Other keys are as follows:
* libdap4/d4curlfunctions.c and oc2/ocinternal.c
- HTTP.READ.BUFFERSIZE -- set the read buffer size for DAP2/4 connection
- HTTP.KEEPALIVE -- turn on keep-alive for DAP2/4 connection
* libdispatch/ds3util.c
- AWS.PROFILE -- alternate way to specify the default AWS profile
- AWS.REGION -- alternate way to specify the default AWS region
* libnczarr/zinternal.c
- ZARR.DIMENSION_SEPARATOR -- alternate way to specify the Zarr dimension separator character
* oc2/occurlfunctions.c
- HTTP.NETRC -- alternate way to specify the path of the .netrc file
## History {#nc_env_history}
__Author__: Dennis Heimbigner<br>
__Email__: dmh at ucar dot edu<br>
__Initial Version__: 01/09/2023<br>
__Last Revised__: 07/30/2024
|
