Netscape NETSCAPE ENTERPRISE SERVER 6.1 - NSAPI PROGRAMMER... User manual

NSAPI Programmer’s Guide
Netscape Enterprise Server
Version 6.1
April 2002 (Draft)

Netscape Communications Corporation ("Netscape") and its licensors retain all ownership rights to the software programs offered by
Netscape (referred to herein as "Software") and related documentation. Use of the Software and related documentation is governed
by the license agreement for the Software and applicable copyright law.
Your right to copy this documentation is limited by copyright law.Making unauthorized copies, adaptations or compilation works is
prohibited and constitutes a punishable violation of the law. Netscape may revise this documentation from time to time without
notice.
THIS DOCUMENTATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN NO EVENT SHALL NETSCAPE BE
LIABLE FOR INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY KIND ARISING FROM ANY
ERROR IN THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION ANY LOSS OR INTERRUPTION OF BUSINESS,
PROFITS, USE, OR DATA.
The Software and documentation are copyright © 2001 Sun Microsystems, Inc. Portions copyright 1999, 2002 Netscape
Communications Corporation. All rights reserved.
This product includes software developed by Apache Software Foundation (http://www.apache.org/). Copyright (c) 1999 The
Apache Software Foundation. All rights reserved.
This product includes software developed by the University of California, Berkeley and its contributors. Copyright (c) 1990, 1993,
1994 The Regents of the University of California. All rights reserved.
Netscape and the Netscape N logo are registered trademarks of Netscape Communications Corporation in the United States and
other countries. Other Netscape logos, product names and service names are also trademarks of Netscape and may be registered in
some countries. Sun, Sun Microsystems, and the Sun logo, iPlanet, and the iPlanet logo are trademarks or registered trademarks of
Sun Microsystems, Inc. in the United States and other countries. Other product and brand names are trademarks of their respective
owners.
The downloading, exporting, or reexporting of Netscape software or any underlying information or technology must be in full
compliance with all United States and other applicable laws and regulations. Any provision of Netscape software or documentation
to the U.S. government is with restricted rights as described in the license agreement for that Software.

3
Contents
AboutThisBook ...............................................................15
WheretoFindRelatedInformation ....................................................... 17
Chapter 1 BasicsofServerOperation............................................19
ConfigurationFiles..................................................................... 20
magnus.conf ........................................................................ 20
server.xml .......................................................................... 20
obj.conf ............................................................................ 21
mime.types ......................................................................... 21
DynamicReconfiguration ............................................................... 22
HowtheServerHandlesRequestsfromClients ............................................ 22
HTTPBasics ........................................................................ 22
StepsintheRequestHandlingProcess ................................................. 24
DirectivesforHandlingRequests ...................................................... 25
WritingNewServerApplicationFunctions ................................................ 25
Chapter 2 SyntaxandUseofobj.conf............................................27
ServerInstructionsinobj.conf............................................................ 27
SummaryoftheDirectives............................................................ 28
The<Object>Tagandthe<Client>Tag ................................................... 31
TheObjectTag ...................................................................... 31
ObjectsthatUsethenameAttribute ................................................. 32
ObjectthatUsetheppathAttribute.................................................. 32
TheClientTag ...................................................................... 33
VariablesDefinedinserver.xml .......................................................... 34
FlowofControlinobj.conf .............................................................. 35
AuthTrans.......................................................................... 35

4 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
NameTrans ......................................................................... 35
HowtheServerKnowstoProcessOtherObjects ...................................... 36
PathCheck.......................................................................... 37
ObjectType ......................................................................... 38
SettingtheTypeByFileExtension .................................................. 38
ForcingtheType.................................................................. 39
Service ............................................................................. 40
ServiceExamples ................................................................. 40
DefaultServiceDirective........................................................... 42
AddLog . . . ......................................................................... 43
Error............................................................................... 43
SyntaxRulesforEditingobj.conf ......................................................... 44
OrderofDirectives .................................................................. 44
Parameters ......................................................................... 44
CaseSensitivity ..................................................................... 44
Separators .......................................................................... 45
Quotes ............................................................................. 45
Spaces ............................................................................. 45
LineContinuation ................................................................... 45
PathNames......................................................................... 45
Comments.......................................................................... 45
Aboutobj.confDirectiveExamples ....................................................... 46
Chapter 3 Predefined SAFs and the Request Handling Process ..................... 47
ThebucketParameter................................................................... 49
AuthTransStage ....................................................................... 50
basic-auth .......................................................................... 51
basic-ncsa .......................................................................... 53
get-sslid ............................................................................ 54
qos-handler......................................................................... 54
NameTransStage ...................................................................... 55
assign-name ........................................................................ 56
document-root ...................................................................... 57
home-page ......................................................................... 58
pfx2dir............................................................................. 59
redirect ............................................................................ 61
strip-params ........................................................................ 63
unix-home.......................................................................... 64
PathCheckStage ....................................................................... 65
check-acl ........................................................................... 65
deny-existence ...................................................................... 66
find-index .......................................................................... 67
find-links........................................................................... 67

5
find-pathinfo ....................................................................... 68
get-client-cert ....................................................................... 69
load-config ......................................................................... 70
nt-uri-clean ......................................................................... 73
ntcgicheck .......................................................................... 74
require-auth ........................................................................ 74
set-virtual-index..................................................................... 75
ssl-check ........................................................................... 76
ssl-logout........................................................................... 77
unix-uri-clean....................................................................... 77
ObjectTypeStage....................................................................... 78
force-type .......................................................................... 78
set-default-type ..................................................................... 79
shtml-hacktype...................................................................... 80
type-by-exp......................................................................... 81
type-by-extension ................................................................... 82
ServiceStage .......................................................................... 83
add-footer .......................................................................... 86
add-header ......................................................................... 87
append-trailer....................................................................... 88
imagemap .......................................................................... 89
index-common ...................................................................... 90
index-simple........................................................................ 92
key-toosmall........................................................................ 93
list-dir ............................................................................. 94
make-dir ........................................................................... 95
query-handler....................................................................... 95
remove-dir ......................................................................... 96
remove-file ......................................................................... 97
rename-file ......................................................................... 98
send-cgi ............................................................................ 99
send-file........................................................................... 101
send-range ........................................................................ 103
send-shellcgi....................................................................... 103
send-wincgi ....................................................................... 104
service-dump ...................................................................... 105
shtml_send ........................................................................ 106
stats-xml .......................................................................... 107
upload-file......................................................................... 108
AddLog Stage . . . ..................................................................... 109
common-log ....................................................................... 109
flex-log............................................................................ 110
record-useragent ................................................................... 111

6 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
ErrorStage ........................................................................... 112
send-error ......................................................................... 112
qos-error .......................................................................... 113
Chapter 4 CreatingCustomSAFs ............................................. 115
TheSAFInterface ..................................................................... 116
SAFParameters....................................................................... 116
pb(parameterblock)................................................................ 116
sn(session) ........................................................................ 117
rq(request) ........................................................................ 117
ResultCodes ......................................................................... 119
CreatingandUsingCustomSAFs ....................................................... 119
WritetheSourceCode .............................................................. 120
CompileandLink .................................................................. 121
IncludeDirectoryandnsapi.hFile.................................................. 121
Libraries ........................................................................ 121
LinkerCommandsandOptionsforGeneratingaSharedObject........................ 122
AdditionalLinkerFlags........................................................... 122
CompilerFlags .................................................................. 123
LoadandInitializetheSAF .......................................................... 124
InstructtheServertoCalltheSAFs ................................................... 124
ReconfiguretheServer .............................................................. 126
TesttheSAF ....................................................................... 126
OverviewofNSAPICFunctions ........................................................ 127
ParameterBlockManipulationRoutines ............................................... 127
Protocol Utilities for Service SAFs . . .................................................. 128
MemoryManagement............................................................... 128
FileI/O ........................................................................... 129
NetworkI/O ...................................................................... 129
Threads ........................................................................... 129
Enterprise ServerUtilities . . . ......................................................... 130
VirtualServer ...................................................................... 131
RequiredBehaviorofSAFsforEachDirective............................................. 131
InitSAFs .......................................................................... 132
AuthTransSAFs.................................................................... 133
NameTransSAFs................................................................... 134
PathCheckSAFs.................................................................... 134
ObjectTypeSAFs ................................................................... 134
ServiceSAFs ....................................................................... 134
ErrorSAFs......................................................................... 135
AddLog SAFs . . .................................................................... 135
CGItoNSAPIConversion.............................................................. 135

7
Chapter 5 NSAPI Function Reference . . .........................................139
NSAPIFunctions(inAlphabeticalOrder) ................................................ 139
CALLOC .......................................................................... 140
cinfo_find ......................................................................... 140
condvar_init ....................................................................... 141
condvar_notify..................................................................... 142
condvar_terminate ................................................................. 142
condvar_wait ...................................................................... 143
crit_enter .......................................................................... 143
crit_exit ........................................................................... 144
crit_init ........................................................................... 144
crit_terminate ...................................................................... 145
daemon_atrestart................................................................... 145
fc_open ........................................................................... 146
fc_close ........................................................................... 147
filebuf_buf2sd ..................................................................... 147
filebuf_close ....................................................................... 148
filebuf_getc ........................................................................ 148
filebuf_open ....................................................................... 149
filebuf_open_nostat................................................................. 149
FREE ............................................................................. 150
func_exec.......................................................................... 151
func_find.......................................................................... 151
log_error .......................................................................... 152
MALLOC ......................................................................... 153
net_ip2host ........................................................................ 154
net_read........................................................................... 154
net_write.......................................................................... 155
netbuf_buf2sd ..................................................................... 155
netbuf_close ....................................................................... 156
netbuf_getc ........................................................................ 156
netbuf_grab........................................................................ 157
netbuf_open ....................................................................... 157
param_create ...................................................................... 158
param_free ........................................................................ 158
pblock_copy ....................................................................... 159
pblock_create ...................................................................... 159
pblock_dup........................................................................ 160
pblock_find........................................................................ 160
pblock_findval ..................................................................... 161
pblock_free ........................................................................ 161
pblock_nninsert .................................................................... 162
pblock_nvinsert .................................................................... 162

8 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
pblock_pb2env..................................................................... 163
pblock_pblock2str .................................................................. 163
pblock_pinsert ..................................................................... 164
pblock_remove..................................................................... 165
pblock_str2pblock .................................................................. 165
PERM_CALLOC ................................................................... 166
PERM_FREE....................................................................... 166
PERM_MALLOC................................................................... 167
PERM_REALLOC .................................................................. 168
PERM_STRDUP.................................................................... 168
prepare_nsapi_thread............................................................... 169
protocol_dump822.................................................................. 170
protocol_set_finfo .................................................................. 170
protocol_start_response ............................................................. 171
protocol_status..................................................................... 172
protocol_uri2url.................................................................... 173
protocol_uri2url_dynamic ........................................................... 173
REALLOC......................................................................... 174
request_get_vs ..................................................................... 175
request_header..................................................................... 175
request_stat_path................................................................... 176
request_translate_uri................................................................ 177
session_dns........................................................................ 177
session_maxdns .................................................................... 178
shexp_casecmp..................................................................... 179
shexp_cmp ........................................................................ 179
shexp_match....................................................................... 180
shexp_valid........................................................................ 181
STRDUP .......................................................................... 181
system_errmsg ..................................................................... 182
system_fclose ...................................................................... 182
system_flock....................................................................... 183
system_fopenRO ................................................................... 183
system_fopenRW................................................................... 184
system_fopenWA .................................................................. 184
system_fread ...................................................................... 185
system_fwrite ...................................................................... 185
system_fwrite_atomic............................................................... 186
system_gmtime .................................................................... 187
system_localtime ................................................................... 187
system_lseek....................................................................... 188
system_rename .................................................................... 189
system_ulock ...................................................................... 189

9
system_unix2local .................................................................. 189
systhread_attach ................................................................... 190
systhread_current .................................................................. 190
systhread_getdata .................................................................. 191
systhread_newkey.................................................................. 191
systhread_setdata .................................................................. 192
systhread_sleep .................................................................... 192
systhread_start..................................................................... 193
systhread_timerset ................................................................. 193
util_can_exec ...................................................................... 194
util_chdir2path..................................................................... 194
util_chdir2path..................................................................... 195
util_cookie_find .................................................................... 195
util_env_find ...................................................................... 196
util_env_free....................................................................... 196
util_env_replace.................................................................... 197
util_env_str........................................................................ 197
util_getline ........................................................................ 198
util_hostname...................................................................... 198
util_is_mozilla ..................................................................... 199
util_is_url ......................................................................... 199
util_itoa ........................................................................... 200
util_later_than ..................................................................... 200
util_sh_escape ..................................................................... 201
util_snprintf ....................................................................... 201
util_sprintf ........................................................................ 202
util_strcasecmp .................................................................... 202
util_strftime ....................................................................... 203
util_strncasecmp ................................................................... 204
util_uri_escape ..................................................................... 204
util_uri_is_evil ..................................................................... 205
util_uri_parse ...................................................................... 205
util_uri_unescape .................................................................. 206
util_vsnprintf ...................................................................... 206
util_vsprintf ....................................................................... 207
vs_alloc_slot ....................................................................... 208
vs_get_data........................................................................ 208
vs_get_default_httpd_object ......................................................... 209
vs_get_doc_root.................................................................... 209
vs_get_httpd_objset................................................................. 210
vs_get_id.......................................................................... 210
vs_get_mime_type.................................................................. 211
vs_lookup_config_var............................................................... 211

10 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
vs_register_cb...................................................................... 212
vs_set_data ........................................................................ 212
vs_translate_uri .................................................................... 213
Chapter 6 ExamplesofCustomSAFs .......................................... 215
ExamplesintheBuild.................................................................. 216
AuthTransExample ................................................................... 217
Installing the Example . ............................................................. 217
SourceCode ....................................................................... 218
NameTransExample .................................................................. 219
Installing the Example . ............................................................. 220
SourceCode ....................................................................... 221
PathCheckExample ................................................................... 223
Installing the Example . ............................................................. 223
SourceCode ....................................................................... 224
ObjectTypeExample................................................................... 226
Installing the Example . ............................................................. 227
SourceCode ....................................................................... 227
ServiceExample ...................................................................... 228
Installing the Example . ............................................................. 229
SourceCode ....................................................................... 229
MoreComplexServiceExample ...................................................... 231
AddLog Example . .................................................................... 232
Installing the Example . ............................................................. 232
SourceCode ....................................................................... 232
QualityofServiceExamples ............................................................ 234
Installing the Example . ............................................................. 234
SourceCode ....................................................................... 234
Chapter 7 SyntaxandUseofmagnus.conf...................................... 241
InitSAFs............................................................................. 242
cindex-init......................................................................... 243
define-perf-bucket .................................................................. 245
dns-cache-init ...................................................................... 246
flex-init ........................................................................... 246
flex-rotate-init...................................................................... 251
init-cgi ............................................................................ 253
init-clf............................................................................. 254
init-uhome ........................................................................ 255
load-modules ...................................................................... 255
nt-console-init...................................................................... 256
perf-init ........................................................................... 257